KSP_project/docs/test_plan_v2.md

KSP 管理后台重构测试计划 v2

生成日期：2026-05-31

1. 项目与重构摘要

本项目是一个 Flask + SQLAlchemy 的 KSP 数据管理后台，数据来源包括引擎/通信/燃料箱/载具 Excel，以及任务资产日志。早期能力集中在数据中心：引擎目录、通信部件、燃料箱规格、载具成本、燃料换算和导入脚本。

draft_board.md 描述的重构重点是“任务运营”：

• 资产当前位置、当前任务、当前状态由 AssetLogEntry 按 simulation_time 派生，不应直接编辑位置结果。
• 资产列表、任务总览、状态板、任务列表、时间线和地点板都应围绕同一套资产日志快照计算。
• 日志支持 state interval / event point，并支持 state nodes；节点应按时间排序。
• 对接关系应是时间敏感模型，需求中规划了 docking_events 表，并要求已有资产对接时双向写入日志。
• 地点板应提供 Canvas 星图、天体层级导航、缩放/拖拽和 scope 面板。
• 时间线应提供只读时间轴、搜索、预设、类型/位置/状态/日期范围/资产选择等筛选。
• 数据中心保持现有结构，重构不应破坏 CRUD、筛选、排序和详情页。

当前实现与 draft_board.md 的明显差距：

• 模型和迁移中尚未实现 docking_events 表；当前 /api/v1/assets/<id>/dock 只给当前资产新增一条 state 日志，没有真实父子对接关系、分离流程或双向日志。
• Location 仍是日志自由文本字段，尚未落成结构化层级选项。
• 地点板已接入 Canvas 和轨道数据，但当前模板使用程序绘制的渐变天体，没有使用 demo/textures/ 的真实纹理。
• 时间线模板渲染了筛选控件，但未发现 tlPreset、搜索/筛选控件事件处理脚本；这些控件需要被测试明确捕获。
• 资产详情日志搜索/类型筛选控件存在 DOM，但未发现对应前端过滤脚本。

2. 对现有 docs/test_plan.md 的评估

现有计划覆盖面大体方向正确，但不能直接作为验收依据：

• 文档称“12 个测试模块”，实际只写了 10 个模块。
• 大量断言只验证元素存在，例如按钮、表格、canvas，而没有验证数据来源、交互结果、URL 参数、数据库派生逻辑或副作用。
• 多个用例与当前实现不一致：日志编辑实际是跳转到编辑页，不是打开 modal；对接功能没有 docking_events；时间线筛选控件缺少脚本；地点板没有真实纹理切换。
• 测试脚本 tests/test_e2e.py 只有 36 个轻量断言，且结果名称编码损坏；它没有执行关键 CRUD 写入、分离、双向日志、时间敏感对接、筛选功能有效性，也没有隔离数据库。
• 测试环境写“真实 PostgreSQL”，但计划包含新增/删除/对接写入，这会污染生产式数据。写入类测试必须切换到隔离测试库或事务回滚。

3. 测试策略

测试分三层执行。

A. 非破坏性冒烟回归

目标：确认服务可达、页面主结构存在、关键数据表可渲染、API 基本可用。

适用环境：当前真实 PostgreSQL 或只读数据环境。

执行方式：

• HTTP GET 页面检查。
• API GET/错误输入检查。
• 静态模板/脚本契约检查。
• 不新增、不编辑、不删除、不调用会持久写入的对接接口。

B. 浏览器交互回归

目标：确认 JS 交互真的工作，而不是只存在 DOM。

适用环境：可运行 Playwright/Browser 的本地环境。

执行方式：

• 点击主题切换、时间 modal、侧边栏、地点板 canvas、时间线筛选控件。
• 检查 URL、DOM、canvas 像素和 console error。
• 只执行不写库的交互，除非已切到测试库。

C. 写入与业务验收

目标：验证重构核心的业务正确性。

适用环境：隔离 PostgreSQL/SQLite 测试库，或每个测试事务回滚。

执行方式：

• 使用固定 fixture 创建资产、日志、节点、对接事件。
• 测试完成后清理或回滚。
• 严禁在真实数据环境直接执行新增/删除/对接/导入。

4. v2 测试矩阵

模块	优先级	用例	类型	预期
服务/API	P0	/api/v1/health	冒烟	HTTP 200，status=ok，service 名正确
服务/API	P0	燃料列表 API	冒烟	返回 8 个燃料因子
服务/API	P1	燃料换算 API mode=volume/mass	冒烟	返回每种燃料的换算结果
服务/API	P1	燃料换算非法输入	冒烟	HTTP 400，错误信息明确
基础框架	P0	首页可达	冒烟	HTTP 200，显示任务总览
基础框架	P0	侧边栏	冒烟	显示任务运营、数据中心、燃料换算、API 健康检查
基础框架	P1	主题切换	浏览器	data-theme 在 dark/light 间切换，localStorage 持久化
基础框架	P1	模拟时间 modal	浏览器	可打开/关闭/ESC 关闭，Apply 后 URL 写入 sim_time
任务总览	P0	指标与状态板渲染	冒烟	Tracked Assets / Active Missions / Upcoming / Status Board 存在
任务总览	P1	模拟时间影响	业务	同一 fixture 在不同 sim_time 下派生状态和 upcoming 变化正确
资产列表	P0	/assets 可达	冒烟	表格有数据行，显示当前位置/当前事件/日志数
资产列表	P0	搜索路由	冒烟	q=ST-01 返回匹配资产
资产列表	P1	类型/排序	浏览器	下拉改变后请求参数正确，结果排序/过滤正确
资产列表	P1	退役资产默认隐藏	业务	默认不显示 retired，显式开关后显示
资产详情	P0	从列表进入详情	冒烟	显示信息卡、Docking Target、Docked Vehicles、Log Entries
资产详情	P1	当前状态/位置派生	业务	state interval 覆盖当前时间时取 active state；无 active 时取最近日志或 home_region
资产详情	P1	日志分页	浏览器	多页日志翻页后保留 sim_time
资产详情	P2	日志搜索/类型筛选	浏览器	输入/选择后列表实际收缩；若控件无脚本应失败
日志 CRUD	P0	新增 state interval	写入	写入后列表出现，state nodes 按 at_time 升序
日志 CRUD	P0	新增 event point	写入	event 无 end/state/nodes 字段要求，保存后可见
日志 CRUD	P0	编辑日志页	写入	GET 预填原值，POST 修改后持久化，失败时保留输入并显示 validation dialog
日志 CRUD	P1	删除日志	写入	删除后 entries 计数减少，关联 nodes 级联删除
对接功能	P0	需求级数据模型	静态/迁移	存在 docking_events 表和模型字段；当前应失败
对接功能	P0	已有资产对接	写入	parent/child 关系可按时间查询，双方日志/节点按需求写入
对接功能	P0	custom name 对接	写入	只影响当前 asset，保留 child_label
对接功能	P0	分离	写入	undocked_at 写入，当前时间晚于分离时不再显示 docked
状态板	P0	/mission-preview/status-board 可达	冒烟	显示状态分组、筛选栏、upcoming
状态板	P1	筛选	浏览器	资产类型/地点/记录范围筛选后卡片数量和 URL 参数正确
任务列表	P1	/missions 可达	冒烟	显示任务/日志聚合列表
任务列表	P1	筛选	浏览器	类型/地点/记录范围筛选正确
地点板	P0	/mission-preview/location-board 可达	冒烟	canvas、Scope、Assets in Scope、Ongoing Missions 存在
地点板	P0	canvas 非空	浏览器	截图或像素采样证明非空，console 无错误
地点板	P1	层级导航	浏览器	点击 Jupiter 进入 Jupiter System，点击 Io 进入 Io，Back 返回
地点板	P1	缩放/拖拽	浏览器	wheel 改变缩放，拖拽改变视图偏移
地点板	P1	资产 scope	业务	不同 scope 下 Assets in Scope 与日志 location 派生一致
地点板	P2	真实纹理	视觉/静态	使用真实纹理资源或明确降级；当前实现应标记未达 draft 目标
时间线	P0	/mission-preview/timeline 可达	冒烟	时间线行和刻度渲染
时间线	P1	scale 切换	浏览器	Year/Month/Day 改变 URL 或刻度
时间线	P1	搜索/类型/地点/状态筛选	浏览器	控件实际改变可见行；当前缺少脚本时应失败
时间线	P1	日期范围	浏览器/业务	手动范围生效，segment 裁切百分比正确
数据中心	P0	四个列表页	冒烟	/engines /communications /tanks /vehicles 均 HTTP 200 且有数据
数据中心	P1	筛选/排序	浏览器	查询参数生效，表格结果正确
数据中心	P1	CRUD	写入	新增/编辑/删除后数据库一致，失败时 validation 明确
导入	P1	workbook inspect/import dry run	业务	能识别表结构、自然键冲突、导入统计
可访问性/前端质量	P1	console error	浏览器	主路径无 JS error
可访问性/前端质量	P2	响应式	视觉	1440x900、390x844 下无严重重叠

5. 自动化建议

• 保留一个 smoke 套件：只读、可在真实库跑，覆盖 P0 冒烟项。
• 新增一个 e2e 套件：Playwright + 测试库，覆盖 P1 浏览器交互。
• 新增一个 business 套件：Flask test client + fixture + 事务回滚，覆盖日志派生、对接、时间敏感状态。
• 测试报告必须输出 Markdown 与机器可读 JSON；失败项保留 URL、参数、截图或最小复现步骤。
• 所有写入测试统一使用唯一前缀，例如 TEST_E2E_20260531_，并在 teardown 校验清理完成。

6. 本轮建议的验收门槛

• P0 冒烟：100% 通过。
• P0 业务：对接模型完成前允许标记为“未实现”，但不能误报通过。
• P1 浏览器交互：主路径无 console error，地点板 canvas 非空，时间线筛选可实际生效。
• 写入测试：只允许在隔离库执行；真实库环境下报告为 skipped，而不是 pass。