KSP_project/docs/timeline_page_retest_report_2026-05-31.md

时间线页面复测报告

日期：2026-05-31

结论

其他团队的修改有部分推进，但时间线页面还不能算完成。已改善的点包括：scale=day 时下拉框能正确显示 Day、segment 外层宽度开始使用 track_width_pct、asset 名称已具备链接、_partial=1 从 HTML 改成了 JSON，单次响应体从上一轮约 315 KB 降到当前约 128 KB。

但复测发现新的关键回归：页面加载后客户端 JS 会直接替换 #tl-canvas.innerHTML，把时间刻度行清掉；滚轮/按钮缩放没有可靠生效；Auto scale 在手动范围下仍然错误；事件点仍然只是无文字小点；资产筛选仍不是需求里的“type/location 筛选后资产多选默认全选”。

测试环境

• 本地服务：http://127.0.0.1:9000
• 页面：/mission-preview/timeline
• 自动化：Codex in-app Browser + 现有 tests/test_e2e.py
• 当前工作区包含大量未提交改动，本报告只做复测与记录，不修改业务代码。

执行的检查

HTTP / 路由检查

1. GET /mission-preview/timeline

   • HTTP 200
   • 响应体约 512 KB
   • 包含 tl-viewport / tl-canvas

2. GET /mission-preview/timeline?_partial=1

   • HTTP 200
   • Content-Type: application/json
   • 响应体约 128 KB
   • scale=year
   • bucket_count=15
   • rows=14

3. GET /mission-preview/timeline?scale=auto&start=2057-04-24&end=2057-07-21&range_mode=manual&_partial=1

   • HTTP 200
   • range_start=2057-04-24T00:00
   • range_end=2057-07-21T00:00
   • 实际 scale=year
   • 实际 bucket_count=1
   • 这是错误结果。88 天范围应该自动进入 Day 或至少 Month。

4. GET /mission-preview/timeline?scale=day&start=2057-04-24&end=2057-07-21&range_mode=manual&_partial=1

   • HTTP 200
   • scale=day
   • bucket_count=89
   • 说明显式 Day 路径可工作。

浏览器 DOM 检查

初始打开 /mission-preview/timeline 后，等待 JS 执行完成：

• #tl-canvas.children.length = 14
• DOM 中 asset 行数 = 14
• segment 数 = 116
• event 数 = 238
• timeline_json.scale = year
• timeline_json.bucket_count = 15
• select[name=scale].value = year
• window.tlZoom = undefined
• window.tlResetView = undefined

重要现象：客户端渲染后，#tl-canvas 的第一个子元素已经是 Europa Outpost 的资产行，不再是时间刻度行。也就是说，服务端首屏渲染出来的刻度行被 JS 清掉了。

现有 E2E

执行命令：

python tests\test_e2e.py

结果：

• 总计 36 项
• 通过 34 项
• 失败 2 项
• 失败项均为时间线：
  • 8.1 渲染
  • 8.2 数据 -- 0 rows

说明：现有 E2E 仍在找旧 DOM 选择器 #tls / .tl-r，已经与当前实现失配。这个失败不等价于页面完全不可用，但说明测试套件没有跟随时间线重构更新，无法作为时间线验收依据。

逐项复测结果

1. 滚轮缩放卡顿

状态：部分改善，但未通过。

改善点：

• _partial=1 改成 JSON 后，单次 partial 数据量下降到约 128 KB。
• 新实现意图是在客户端用 timeline_json 直接重绘，理论上可以避免上一版每次 wheel 都请求后端。

仍存在的问题：

• 实测滚轮操作没有改变 hidden start/end，也没有改变 segment 位置。
• Zoom + / Zoom - / Reset View 按钮仍然存在，但模板里没有定义 tlZoom() 和 tlResetView()。
• 客户端 zoom 逻辑只调整 bucket_count，没有按新的 range_start/range_end 重新计算每个 segment/event 相对位置。即使 wheel 触发成功，也会出现“缩放但不按新窗口重定位”的问题。

证据：

• window.tlZoom 为 undefined
• window.tlResetView 为 undefined
• 点击按钮对应的 inline handler 是 tlZoom(1.3) / tlResetView()

2. 滚轮缩放丢失日志/资产

状态：旧丢参问题缓解，但新实现仍有风险。

已改善：

• 客户端缩放不再发 AJAX，因此上一版 wheel AJAX 丢 asset_ids / record_scope 的问题不再以同样形式出现。
• URL 手动传 2 个 asset_ids 时，DOM 确实只渲染这 2 个 asset。

仍存在的问题：

• 默认资产多选框没有任何选中项，但页面渲染 14 个 asset。UI 表达仍然是“未选择”，实际语义却是“全部显示”。
• 客户端缩放数据来自初始 timeline_json，如果后续改为 partial 更新，需要重新验证所有 filter 参数是否同步。

证据：

• 默认打开时：asset options = 14，selected count = 0，timeline rows = 14。
• 加 asset_ids=A&B 打开时：selected count = 2，timeline rows = 2。

3. 缩放时自动切换年/月/日

状态：未通过。

显式 scale=day 已经可以显示 Day，并且 JSON 返回 bucket_count=89。但 scale=auto 或不传 scale 且传入 88 天手动范围时，后端仍返回 scale=year、bucket_count=1。

根因判断：

• mission_timeline_preview() 在解析 range_start/range_end 之前先调用 _resolve_timeline_scale(request.args.get("scale"), initial_range_start, initial_range_end)。
• 这导致 auto scale 使用的是默认全量时间范围，而不是用户当前手动范围。
• 此外 <option value="auto"> 永远不会保持 Auto selected，因为后端最后传给模板的是解析后的 year/month/day，不是原始 scale mode。

4. Type/location 筛选后资产多选默认全选

状态：未通过。

当前行为：

• Type 和 Location 仍是普通单选下拉。
• Assets 仍是原生 <select multiple>。
• 默认 selected count = 0，但页面显示全部资产。
• 没有 checkbox dropdown、Select All、Clear、已选数量展示。
• 没有 State 筛选。

需求目标是“先根据 type 和 location 进行筛选，筛选结果进入下拉多选框，默认全选，仅展示选中的 asset”。当前仍是“空 asset_ids 表示全部”，没有做到视觉和语义一致。

5. Event point 显示效果

状态：未通过。

当前 DOM：

• .tl-evt 数量 = 238
• 有可见文本的 .tl-evt 数量 = 0
• connector 数量 = 0
• state node 与普通 event 没有稳定的 class/data 区分

后端仍然计算了事件 label 宽度、label side、track、connector height，但当前客户端渲染没有使用这些字段。页面仍然只是 7px 小圆点，不能扫描事件内容。

6. 点击 asset 跳转到 asset 页面

状态：基本通过，但还需要人工点击验收。

当前 asset label 已渲染为链接：

/assets/fba95050-ca89-4e67-b796-66b7e1c40764?sim_time=2060-08-11T10:00

这比上一版 plain div 有明显改善。需要注意的是当前 simulation_time 来自 DB/session，复测时已变成 2060-08-11T10:00，不是原本默认的 2060-03-12T09:00。这不是时间线链接本身的问题，但全局 simulation time 被写 DB 后会影响所有页面和测试基线，建议测试报告里固定 sim_time。

新发现的问题

A. 时间刻度行被客户端渲染清除

模板服务端先渲染了刻度行：

<div id="tl-canvas">
  <div>scale labels...</div>
  ...
</div>

但脚本执行：

if (tlCanvas) tlCanvas.innerHTML = buildHTML(tlData);

buildHTML() 只生成 asset rows，不生成 scale labels。因此用户最终看到的 DOM 没有时间刻度行。

B. 缩放按钮是坏控件

页面底部仍显示：

• Zoom +
• Zoom -
• Reset View

但没有定义对应函数：

• window.tlZoom === undefined
• window.tlResetView === undefined

这些按钮应删除、接入同一套 zoom controller，或改成有效按钮。

C. 客户端缩放算法不完整

当前 wheel handler 更新：

tlData.range_start = fmtDate(newFrom)
tlData.range_end = fmtDate(newTo)
tlData.bucket_count = Math.round(scale)

但 segment/event 的 start_position、display_end_position、position 都是后端基于旧 range 计算出的 bucket position。只改 bucket_count 无法正确表达新 range。缩放后必须重新按时间戳计算位置，或向后端请求基于新 range 的 JSON。

D. _partial=1 合约已变，但旧 partial 模板仍在仓库

当前路由 _partial=1 返回 JSON，不再使用 mission_timeline_partial.html。但该模板仍存在且是旧 HTML 片段。建议清理或明确废弃，避免后续维护者误用。

E. 现有 E2E 已过期

tests/test_e2e.py 仍验证旧选择器：

• #tls
• .tl-r

当前实现已经没有这些节点，所以时间线测试失败。需要更新测试，让它验证当前关键行为，而不是旧 DOM 名称。

建议修复优先级

P0

1. 恢复最终 DOM 的时间刻度行，或让客户端 buildHTML() 同时渲染刻度。
2. 修复 auto scale：先确定手动 range，再基于最终 range 解析 scale。
3. 删除或实现 tlZoom() / tlResetView()。
4. 让 wheel zoom 要么真正按时间戳重新计算位置，要么改回请求 _partial=1 JSON 并完整替换数据。
5. 更新 E2E 时间线选择器和断言。

P1

1. 实现资产 checkbox dropdown，默认全选筛选后的候选资产。
2. 增加 State 筛选。
3. 让 selected count、URL 参数、实际 rows 三者一致。
4. 渲染 event labels、state-node/event 区分和 connector。

P2

1. 清理废弃的 mission_timeline_partial.html。
2. 固定测试用 sim_time，避免 DB 全局 simulation time 污染测试基线。
3. 给 timeline JSON 增加 schema/契约测试。

建议验收用例

1. 打开 /mission-preview/timeline?sim_time=2060-03-12T09:00，确认有时间刻度行，首行不是 asset 文本。
2. 默认打开后，asset dropdown 显示所有候选 asset 已选，rows 数等于 selected count。
3. 选择 type/location 后，asset dropdown 只包含筛选结果，并默认全选。
4. 取消一个 asset，确认该 asset row 立即消失或提交后消失。
5. 传 start=2057-04-24&end=2057-07-21&range_mode=manual&scale=auto，确认 scale 解析为 Day 或预期精度。
6. 使用滚轮缩放，确认 hidden start/end、刻度标签、segment/event 位置一起变化。
7. 点击 Zoom + / Zoom - / Reset View，确认没有 JS error 且视图变化符合按钮含义。
8. 点击 asset 名称，确认跳到 /assets/<id>?sim_time=...。
9. Hover event point，确认 tooltip 有 title/time；肉眼可见的事件标签或聚合提示存在。
10. 执行更新后的 E2E，时间线模块不再依赖旧 #tls / .tl-r。