fix(workbench): stabilize investigation presentation rendering
Keep investigation graphs stable during updates, defer expensive chart rendering, and prevent stale results when switching tasks. Adopt reference annotations and consolidate frontend documentation.
This commit is contained in:
@@ -0,0 +1,117 @@
|
||||
# 非地图面板整理
|
||||
|
||||
> 历史记录：2026 年 9 月的面板整理过程，当前规范见 [样式设计指南](../style-design-guide.md)。测试数量、失败列表与未提交状态只对应原记录时间，不代表当前回归结果。
|
||||
|
||||
2026-09-17，范围限供水前端，不改变地图业务、OpenCode、数据库表或环境配置。
|
||||
|
||||
## 视觉与交互
|
||||
|
||||
沿用现有浅色阅读面、Noto Sans SC 中文字体、蓝色操作强调和状态徽标。优先修复可读性、对齐和窄屏裁切，不引入第二套主题、字体或组件库。
|
||||
|
||||
- `FieldSelect` 复用现有 Radix Select：统一标签、40px 最小高度、长选项换行、禁用态、键盘选择和弹层层级。清空受控值后回到占位提示，不触发额外业务动作。
|
||||
- `Checkbox` 保留原生输入与标签语义，统一勾选、焦点和禁用样式。反馈确认仍须用户主动勾选。
|
||||
- `Disclosure` 保留原生 details/summary 语义，统一展开箭头、焦点和点击区域。
|
||||
- 调查目标和外围历史回放的日期字段单列展示，避免窄面板内日期与时分被裁切。两处均已使用共享自定义日期时间弹窗，保留各自本地时间/UTC 的业务语义。
|
||||
- 手机端 Agent 欢迎区改为紧凑横排，避免被底部输入区遮挡。
|
||||
- 桌面成果专注视图为 Agent 折叠栏预留空间，标题不再被覆盖，仍可重新展开助手。
|
||||
- 成果图表显式使用页面的中文字体栈。此前 ECharts 画布仍以 `11px sans-serif` 绘制中文图例，在测试环境显示方框；浏览器画布探针已验证修复前失败、修复后在 1280/375px 通过，截图可见完整“调度下限”。源码只有这一处 ReactECharts 入口。
|
||||
|
||||
## 检查覆盖
|
||||
|
||||
| 面板 | 本次检查 |
|
||||
| --- | --- |
|
||||
| 调查任务、生命周期、运行与历史结果 | 表单、确认区、折叠内容、长标识、320/375/1280px |
|
||||
| 已保存比较结论、Evidence 查看 | 四分支、加载/空/错误态、只读重试、键盘下拉、320/375/1280px |
|
||||
| 外围样板、模拟数据、历史回放 | 下拉、日期、状态徽标、任务历史、375px |
|
||||
| 反馈关联、人工复核 | 确认勾选、展开内容、禁用与只读边界、窄屏 |
|
||||
| Agent 对话与历史 | 桌面抽屉、320/375px 欢迎区与滚动容器边界 |
|
||||
| 工况列表与详情 | 375px 抽屉布局 |
|
||||
| 成果预览与文档 | 1280/375px，桌面标题与折叠栏几何边界 |
|
||||
| 图层、测量、标注、更多、开发面板 | 非地图浮层边界，开发面板表单控件统一 |
|
||||
|
||||
实际要素详情使用地图上的 `FeaturePopover`；未接入运行入口的 `FeatureInsightPanel` 已在冗余清理中移除。
|
||||
|
||||
## 验证与限制
|
||||
|
||||
最终代码检查：`pnpm typecheck`、`pnpm lint`、全量 68 文件 / 350 项 Vitest、`pnpm build` 通过。生产构建仍提示部分 chunk 超过 500kB，本次未扩展打包优化范围。调查/反馈/外围/比较/生命周期的 29 项与非地图布局的 5 项专项浏览器用例通过，比较区新增的弹层不透明度和背景色检查另行重跑 6 项通过。非地图布局用例同时覆盖开发面板键盘选项和成果图表画布字体。
|
||||
|
||||
浏览器用例使用显式模拟接口，不代表真实账号、Agent 和 PG 的全链路验收。主要回归在 `tests/browser/non-map-panels-layout.e2e.ts`、`run-comparison.e2e.ts` 及既有调查、反馈、外围与生命周期测试中；截图保存在忽略的 `test-results/non-map-panels/`、`test-results/run-comparison/` 等目录，不作为发布资源。
|
||||
|
||||
本次也运行了完整浏览器套件，当次为 66 通过、33 失败，不能宣称全量通过。已确认的失败包括旧用例依赖 Agent 初始展开或已不存在的“工作台导航”、旧截图基线，以及新移动用例当时选择器不唯一。后者已改为语义化 `role=log` 并在专项回归中通过；其他旧用例与真实地图依赖仍需单独梳理，不通过修改产品默认行为或批量更新截图掩盖失败。
|
||||
|
||||
运行内容来自现有接口，无需手动替换界面占位数据。人工验收时请在桌面全宽与 375px 下检查长任务名称、日期输入、下拉键盘操作和成果标题。
|
||||
|
||||
## 后续交互回归
|
||||
|
||||
继续核查旧失败用例时发现并修复了两处真实缺陷：
|
||||
|
||||
- 窄桌面展开工况详情会自动收起 Agent；此前聊天草稿存在被卸载的面板内部，重新展开时丢失。现在由稳定的工作台 hook 持有草稿，桌面和手机面板共享受控值，新建会话仍清空。此状态只在当前页面内保留，不是刷新后的持久化草稿，也没有新增存储层。面板仍可卸载，避免为了保留文字让隐藏的语音控件继续活动。
|
||||
- 新增调查/外围入口后，1536px 顶栏的异常处置与调查按钮发生重叠。现在保留按钮宽度、收紧组间距，仅在 1800px 以上展开次要按钮文字；较窄桌面省略模型只读提示，完整操作名称仍通过无障碍标签提供。手机标题显示短称“供水”，而不是省略号。
|
||||
|
||||
`workspace-main-frame.e2e.ts` 现在验证默认收起、主动展开后的相邻布局、收起恢复、成果 split/focus 切换，并检查 320/375/1024/1280/1440/1536/1600/1800/1920px 顶栏按钮不重叠、标题不截断。顶栏几何断言修复前失败，修复后通过。截图位于 `test-results/workspace-regression/`。
|
||||
|
||||
`agent-voice-hydration.e2e.ts` 与 `agent-panel-resize.e2e.ts` 改为先通过真实按钮打开助手，再检查语音、几何和草稿状态；不再假定 Agent 初始展开或折叠后保留旧版 72px 导航宽度。工况自动收起场景使用其实际适用的 1280px 宽度，保留了未发送草稿不丢失的断言。布局测试按实时几何等待入场动画完成，不固定动画中途的坐标，也没有加入固定 sleep。
|
||||
|
||||
该轮完整浏览器套件为 79 通过、21 失败，共 100 项。仍有旧导航/默认展开假设、截图基线与动画时机相关失败，不能宣称全量通过，也未批量更新基线。
|
||||
|
||||
## 调查任务日期时间补充
|
||||
|
||||
根因是原先只统一了 `datetime-local` 输入框外观，其日历和时间弹窗仍由浏览器绘制。调查任务的开始、结束时窗已替换为共享 `DateTimeField`：沿用浅色面板、蓝色选中态和现有 Radix 弹层/下拉，不引入新依赖。
|
||||
|
||||
- 日历、月份、年份、小时和分钟均在应用内绘制，窄屏弹窗限制宽高并允许纵向滚动。
|
||||
- 点击确认才更新值，取消或 Esc 放弃草稿并将焦点返回字段；日历支持方向键和 PageUp/PageDown。
|
||||
- 年份编辑保持输入焦点，支持闰年和真实月份天数；无效源值不会被静默截断后保存。
|
||||
- 已关闭任务不可编辑。组件仍输出本地 `YYYY-MM-DDTHH:mm`，原有目标保存逻辑负责转换 UTC，不改变业务时区语义。
|
||||
- `date-time-field.test.tsx` 覆盖组件边界。
|
||||
|
||||
调查任务两个日期字段均已替换；同类的外围历史回放已在后续批次统一，见下节。
|
||||
|
||||
补充后的验证：`pnpm typecheck`、`pnpm lint`、69 文件 / 357 项单元测试和 `pnpm build` 全部通过；日期时间、调查面板、非地图布局、运行控制及任务生命周期的 20 项浏览器回归通过。生产构建仍有既有大 chunk 提示。上述浏览器检查使用模拟接口，不替代真实系统验收。
|
||||
|
||||
日期回归用例做过红绿验证：临时将调查时窗重新接回原生 `datetime-local`，确认/提交用例因缺少自定义字段入口失败；恢复 `DateTimeField` 后重新运行全部 3 项日期用例通过。代码未提交。
|
||||
|
||||
按用户要求，每轮 Playwright 结束后检查其浏览器和临时 Vite 服务是否退出，不关闭用户已有的 5173 开发服务。
|
||||
|
||||
## 外围历史回放日期补充
|
||||
|
||||
外围面板的 `HistoryTime` 同样仍由浏览器绘制日期时间弹窗，已删除该包装并复用 `DateTimeField`。保留“开始（UTC）/结束（UTC）”标签和原来的 UTC 查询拼接，不套用调查任务的本地时间转换。扫描 `src/` 已无原生 date/time/datetime-local 输入入口。
|
||||
|
||||
`peripheral-sample-panel.e2e.ts` 新增实际交互断言：修改起止日期时间后只有点击“读取历史读数”才发送 GET；浏览器为 Asia/Shanghai 时，08:15 仍按 08:15Z 查询；取消不改值、不发查询，也没有任何外围写请求。320/375/1280px 弹窗边界与无横向溢出通过，截图位于忽略的 `test-results/peripheral-datetime/`。
|
||||
|
||||
红绿验证：替换前该用例因缺少自定义日期入口失败，替换后外围面板、调查日期时间、反馈导入共 14 项浏览器测试通过。类型检查、Lint、69 文件 / 357 项单元测试与生产构建通过，构建仍提示既有大 chunk。仍使用模拟接口，不代表真实外围服务验收；完整浏览器套件的失败不因本轮专项通过而视为消除。
|
||||
|
||||
## 问答与流式测试入口修订
|
||||
|
||||
重新运行确认旧问答/流式用例默认寻找尚未展开的 Agent 输入框；显式展开后还暴露了授权项目模拟缺失。请求失败探针记录 `/api/v1/projects` 连接拒绝，Agent 客户端因此未进入回复与模型查询。现在使用明确的测试运行配置和已有项目/SCADA mock，不改产品授权流程；临时日志已移除。
|
||||
|
||||
流式用例另外仍断言旧浮动简报和浮动输入区。当前 `desktop-dock` 分支将简报和输入区放入正常布局，已改为验证简报在对话区上方、输入框在滚动区域下方、分析中操作禁用及区域不重叠；进度窗口几何采样、计划卡片、结束滚动、保持展开、选中文本朗读等原断言仍保留。问答回复的精确请求号与 payload 断言未放宽。两个文件共 3 项重跑通过，其中问答桌面和流式用例此前失败。
|
||||
|
||||
本轮最终完整浏览器套件：103 项中 85 通过、18 失败，耗时 2.7 分钟。失败分布为 `app.e2e.ts` 4 项、`agent-acrylic.e2e.ts` 4 项、开发面板/地图通知/移动转桌面/窄桌面工况/地图相机稳定性各 1 项、视觉基线 5 项。不得将全部失败归因于旧断言，仍需逐项核查实际行为。此前工况动画时机失败在本轮未复现，未作修复，仍作为时序风险保留；问答与流式是本轮明确修订后通过的两项。完整结果与失败上下文位于忽略的 `test-results/non-map-followup-full/`。
|
||||
|
||||
## 历史菜单、Esc 分层与全量回归收尾
|
||||
|
||||
继续核查上述 18 个失败后，确认并修复了以下真实行为问题：
|
||||
|
||||
- 手机 Agent 内的 Radix 模型菜单和权限模式菜单已处理 Esc，并将事件标记为 `defaultPrevented`，但外层 `MobileWorkbenchSheet` 的 window 监听仍无条件关闭抽屉。外层现在只处理未被内层消费的 Esc。模型和权限菜单各自关闭后，焦点返回原触发按钮；没有内层菜单时，Esc 仍关闭抽屉。
|
||||
- Dev Panel 有相同的事件分层缺陷。`FieldSelect` 打开时第一次 Esc 只关闭选择菜单并返回焦点，第二次 Esc 才关闭开发面板。
|
||||
- 手机端已打开 Agent 时跨越 1024px 进入桌面，原逻辑先清空移动抽屉状态，导致用户打开 Agent 的意图丢失。现在先将移动 Agent 状态迁移为桌面展开状态，再清空移动抽屉。
|
||||
- Dev Panel 打开时，地图工具栏仍在面板下面渲染。现在开发面板显示期间不挂载桌面地图工具栏与其工具面板。
|
||||
- 1024px 下展开工况任务会自动折叠 Agent，但 880px 工况面板与 72px 折叠栏重叠 4px。布局变量现显式记录折叠栏宽度，工况面板在该宽度下收敛到 852px，二者保留 24px 间距。
|
||||
|
||||
同时修正了三类失真的回归断言。地图容器变宽或变窄时，MapLibre 的 `resize()` 会发出 `movestart`，但经纬度、缩放、方位角和俯仰并未改变；相机稳定性用例现在直接比较这五项参数。地图通知位置测试改用确定会生成通知的“操作参考”入口。工况材质测试等待入场动画结束后再读取 transform 和 will-change，不再采样动画中间帧。焦点、几何和业务请求断言均保留。
|
||||
|
||||
320px 与 375px 的模型菜单截图位于 `test-results/agent-history-ui/320-model-menu.png` 和 `375-model-menu.png`，长标题重命名截图位于同一目录。模型名称、说明和菜单边界完整，权限模式、模型、语音和发送控件没有重叠。五张过期的工作台视觉基线经逐张检查后更新，覆盖桌面浅色/卫星底图、1920px Agent 收起状态、手机启动器和手机 Agent 半屏；手机工况卫星图无需更新。视觉用例更新后再次无更新参数运行，6/6 通过。
|
||||
|
||||
最终验证结果：`pnpm typecheck`、`pnpm lint`、69 文件 / 357 项 Vitest、`pnpm build` 全部通过。构建继续报告既有的 500kB 以上 chunk 提示，CSS 校验和 TTS bundle 通过。完整 Playwright 套件为 104/104 通过，耗时 2.4 分钟，结果位于忽略的 `test-results/non-map-followup-final-green/`。这些浏览器用例仍使用模拟接口，不替代真实账号、Agent、PG 和外围服务的全链路验收。
|
||||
|
||||
## 新增业务组件统一设计
|
||||
|
||||
2026-09-18 对调查任务与外围样板的新组件完成统一重构。现行规则见 [样式设计指南](../style-design-guide.md)，视觉方向是浅色专业调度台，保留地图为主工作区，并将侧栏内容稳定为“定位、状态、下一步、证据”的阅读顺序。
|
||||
|
||||
- 新增 `WorkbenchSection`、`WorkbenchNotice` 和 `WorkbenchEmptyState`，统一标题、状态、提示和空态，减少同级彩色卡片与大面积空白。
|
||||
- 生命周期确认、定时计划、目标编译、运行控制、运行对比、人工复核和 Evidence 导入统一状态语言与操作层级。
|
||||
- 外围样板将连接与场景、历史回放、待提交来源、已有任务放在前面；测试工单、测试数据和 request_id 查询移到辅助区并默认折叠。外围工单统一按系统数据处理。
|
||||
- `FieldSelect`、`Checkbox`、`Disclosure` 和 `DateTimeField` 统一焦点、hover、按压和禁用反馈。日期时间弹层继续支持 Esc 取消并返回焦点。
|
||||
- 数据表使用等宽数字并将数值右对齐；320、375 和 1280px 下均无横向溢出。
|
||||
|
||||
本轮最终检查为 `pnpm typecheck`、`pnpm lint`、76 文件 / 395 项 Vitest 和 `pnpm build` 通过。新增组件相关的 17 文件 / 118 项单测通过，核心业务面板 Playwright 为 31/31 通过。完整浏览器套件共 110 项，并发运行 108 项通过；2 项在等待 Toast 退出时超过 15 秒，随后单进程精确复跑 2/2 通过。截图位于忽略的 `test-results/task-lifecycle/`、`run-control/`、`run-comparison/`、`peripheral-datetime/` 和 `/tmp/feedback-*.png`。
|
||||
Reference in New Issue
Block a user