148 lines
24 KiB
Markdown
148 lines
24 KiB
Markdown
# 调查任务展示与 Dev 测试
|
||
|
||
“调查测试”顶部的“全屏爆管视觉警告”区域提供持续预览、三档强度和“模拟事件处理结束”。默认使用标准档；关闭按钮位于屏幕底部状态提示右上角。真实警告随监测事件持续至处理结束，查看调查后继续显示；手动关闭按项目与事件在当前标签页记忆。预览操作只改变本地视觉状态。
|
||
|
||
可直接打开顶部 Dev 入口载入、编辑、校验并执行本地测试案例，无需先选择调查或开启实时跟随。纯数据和界面块可独立预览，包含地图或图表展示指令时需等待地图就绪。验证实际调查联动时，在“工况任务 → 调查任务”选择一项任务，再打开 Dev。Dev 默认打开“调查测试”页签，保留当前选择，显示调查代次、实时图表数、已保存报告中的图表/表格/地图入口数，以及最近的展示动作。上一轮报告会明确标注，不当成本轮新成果。
|
||
|
||
Dev 分为“调查测试”“通知测试”和“地图调试”三个页签：调查测试按“准备数据 → 校验与执行 → 检查结果”组织 JSONL 流程；通知测试提供五种状态、报告与任务入口、长文本和连续六条通知；地图调试保留要素定位、水流、图层和标注工具。切换页签保留输入与展示状态，不清除当前预览。地图重置操作仅显示在地图调试页。
|
||
|
||
通知测试中的信息、成功提示默认 3.2 秒后关闭；警告和错误可手动关闭，加载状态通过“模拟加载完成”更新为成功提示。带操作入口的通知持续保留，点击查看仍保留，正文显示“保留至手动关闭”；多条通知沿用原有堆叠，关闭当前通知后可继续查看其余通知。报告和任务按钮仅记录本地点击反馈。“清除测试通知”只移除本页测试样例，不影响真实通知。
|
||
|
||
## 当前识别链路
|
||
|
||
| 内容 | 来源和行为 |
|
||
| --- | --- |
|
||
| 实时地图、图表和覆盖层 | 从工作台事件流读取 `operational.presentation.requested`，核对所选 task、run 和 generation，验证命令后使用调查展示控制器执行 |
|
||
| 已保存的结构化界面 | 任务报告的 `ui_blocks` 使用既有 `answer-ui@1` 校验及 json-render 组件；未知或不合法的内容不作为可执行界面 |
|
||
| JSONL 数据 | Dev 中显式载入、校验后在展示面板预览；调查数据行仅展示，只有受控展示指令行会在点击“执行本地预览”后操作地图或图表 |
|
||
|
||
选中调查任务时，通过只读 `GET /api/v1/operational-tasks/{task_id}/presentation-events` 分页读取该任务保存的展示事件，并载入左下列表；同时载入本轮最新报告中已保存的有效界面块。已完成任务、关闭实时跟随时也可读取。历史报告仍在任务详情可读。开启跟随或重连时先建立固定事件游标，载入不超过该游标的历史，期间到达的新事件暂存，历史完成后再顺序消费，避免间隙或重复。“载入当前报告”加载该任务最新保存的报告界面块，供本地检查，不重新发布报告。
|
||
|
||
Dev 与工况详情共用右侧工具位置，切换调查时先关闭 Dev 回到任务列表，再打开 Dev 检查新的选择。实时展示面板位于地图左下方，打开 Dev 后仍可看见。新图表进入其滚动区时会滚动到图表，保留标题；手动收起面板后仍接收指令，展开再查看。切换项目、调查或执行代次会清理临时效果并取消未完成的本地预览。上述清理保留本次页面会话内的动作快照，只有切换项目会同时清空历史。已绑定调查时关闭跟随也会清理该调查的当前临时展示；未选择调查的本地预览不受跟随开关影响。面板外仍可操作地图，手动拖拽或滚轮暂停镜头自动跟随。
|
||
|
||
## 图表和窗口管理
|
||
|
||
调查、本地预览与对话展示面板提供“图表窗口”入口，在一个可拖动、缩放、最大化的总窗口中集中查看所有子图表，包括 open_chart 形成的对象图组与报告中的 Chart。每张子图表保留自身的独立弹窗放大入口，可同时打开多个放大窗口；关闭总窗口收起其内部开启的放大窗口，关闭子窗口只收起该放大视图。普通趋势总览、柱状图和报告 Chart 保持各自的图表语义。
|
||
|
||
总窗口使用固定槽位布局，提供“单图布局”“左右布局”“四宫格布局”，每行分别显示 1、2、2 个固定位置，单图与左右布局每行约占一个可视区高度，四宫格每个可视区约显示两行。全部图表沿纵向连续排列，通过滚动查看；图表随槽位尺寸适配，末行按列数补齐空槽。窄窗口使用单图布局，调宽后恢复先前选择的布局。头部定位、布局和重置控件置于同一条浅底工具栏，控件保持等高，窄窗口允许自然换行。“快速定位图表”列出全部图表，选择后滚动到对应位置并聚焦目标；目标的位置栏短暂显示淡色背景和“已定位”，不使用整卡外框，避免高亮被滚动区域裁切。
|
||
|
||
槽内图表使用紧凑控件，绘图区下方的图例独立滚动，筛选、详情与依据通过入口展开。多对象图在宽槽右侧显示对象按钮，窄槽使用对象选择器；独立放大后使用完整控件。
|
||
|
||
整条图表位置栏均为拖拽手柄，悬停反馈覆盖整栏；在目标位置释放后交换两处内容，拖到空槽则移动到空槽，其他位置不推移。悬停时整张卡片显示轻量浅色高亮，拖动源与目标位置保留整卡浅色提示；位置栏使用柔和浅底和深色文字，不使用深色横幅。图表保持原有清晰度，目标位置使用细线提示，轻量标题预览沿用中性边框。原图表留在原位，不克隆或随指针重绘。不再提供“移动到”下拉菜单，下方图表通过纵向滚动和快速定位查看。
|
||
|
||
槽位映射依据稳定的子图表标识：同一图表实时更新时保留位置，删除图表后保留中间空槽并移除末尾空行，新图优先填补空槽，再追加位置与行。同一次任务查看期间，关闭并重新打开总窗口保留槽位与布局；任务、项目或执行代次切换后重新建立当前内容。交换位置不改变图表数据、对象选择或服务端的展示事件顺序。
|
||
|
||
工作台顶部的窗口列表入口列出已打开的总图表窗口、独立子图表和表格窗口，选择条目可将对应窗口置顶并定位到标题栏。列表中的“关闭全部窗口”统一收起当前打开的窗口，不删除已加载的图表、表格或任务结果；图表窗口可从原展示入口重新打开。
|
||
|
||
总窗口与子图表使用同一缩放交互：指针拖动窗口边缘时，图表按窗口实际尺寸适配，保持已有图表实例与筛选、序列显隐和对象选择；松开后确认最终尺寸。拖动期间按 Escape 或发生 pointercancel 时取消调整、恢复原尺寸；标题栏的 Shift 加方向键继续用于逐步调整大小。
|
||
|
||
只有正在跟随的运行中调查新收到 open_chart 时，才自动弹出一次总窗口，不自动弹出各子图表，不抢走键盘焦点；后续指令按 chart_id 更新其中的数据。打开、切换、刷新任务、SSE 重连补载、历史回看和回到当前都只恢复内容，已完成任务也不弹窗。用户关闭总窗口后，本次任务查看期间的后续更新不使其再次弹出；手动收起展示面板期间的新指令也不请求弹窗。总窗口已经打开时，历史回看只更新其中的快照，实时数据不覆盖正在查看的历史。切换任务、项目或执行代次关闭原窗口并重新静默载入，返回之前看过的任务也不重放自动弹出意图。Chat 与本地 Dev 预览使用手动入口。
|
||
|
||
open_chart 仍只提交 chart_id/chart/evidence_refs，close_chart 仍按 chart_id 移除对象；不新增 display 或 objects 字段。排列、布局与窗口打开意图仅存在当前浏览器中，不进入保存的展示快照或事件。displayed 回执表示展示内容已加载，不保证弹出了独立窗口。
|
||
|
||
## 本地测试步骤
|
||
|
||
1. 在默认展开的“调查测试”页签准备数据。“载入合成样例”在当前地图中心生成合成空间展示、压力曲线、候选表格和一条候选数据；所选调查进度存在地图目标时，另加入该目标的高亮测试。所有合成结果均有明确标记。
|
||
2. 可选：点击“校验 JSONL”单独查看识别出的展示指令、界面块、调查数据数量。也可直接执行本地预览，执行入口会自动校验当前全部内容。
|
||
3. 点击“执行本地预览”，自动校验通过后对照地图和左下展示面板中的图表、结构化界面与数据摘要；手动打开“图表窗口”，核对单图、左右、四宫格的固定槽位、拖放交换、末行空槽与纵向滚动，再检查快速定位和子图表独立放大，并从顶部窗口列表切换已打开的窗口。Dev 的“原始数据检查”可点击对象查看原始行内容。动作记录区分“实时指令”和“本地测试”，显示应用或失败结果。
|
||
4. 按需“下载测试 JSONL”保存当前已校验输入；“清除临时展示”清除当前浏览器的高亮、图表和覆盖层。测试不改变服务端事件游标，不发起调查、审批、工单或设备写入。
|
||
|
||
样例与导出仅存在当前页面或用户下载的文件中，不写 Agent 工作区，不伪造已保存证据。Dev 不会自动枚举 Agent 生成的本地文件；要检查已有 JSONL，可将通过受控入口取得的文件内容粘贴到编辑区。当前最多 200 KB、40 行、8 个界面块；地图与图表继续遵守原展示协议的数量、几何及序列约束。
|
||
|
||
## 可切换测试案例
|
||
|
||
“JSONL 测试案例”选择框不依赖调查选择；地图就绪后即可切换并载入内容，显示该案例的预期结果。本地预览无需选择调查或开启跟随，表格、卡片、数据摘要、图表与范围统一在地图左下方的“本地预览展示”中显示，Dev 只保留输入、校验、原始数据检查与执行记录；“载入合成样例”重新生成当前案例，尚未选择时载入组合联动。修改输入会重置案例选择与校验状态，仍可继续手工测试。“载入当前报告”继续加载所选任务已保存的界面块。
|
||
|
||
| 案例 | 核对内容 |
|
||
| --- | --- |
|
||
| 组合联动 | 合成空间点、压力曲线、候选表格与数据；定位和高亮在地图调试页签操作 |
|
||
| 复杂调查：多图多表联动 | 8 个压力点、4 个管段的同期复合图聚合为 2 个子图表，另有方案柱状图、2 个表格与合成覆盖面 |
|
||
| 复杂图表：多测点与长时序 | 每个对象包含 96 个时刻、1 条当前曲线和 7 组稀疏历史散点；右侧切换对象，下方显隐序列 |
|
||
| 复杂表格：宽表、长文本与边界数据 | 50 行 8 列宽表、空结果、零值、负数、重复值及缺口 |
|
||
| 压力趋势对比 | 两条合成压力曲线、时间轴、单位与图例 |
|
||
| 影响用户统计 | 合成用户数柱状图，不作为真实停水统计 |
|
||
| 合成影响范围 | 当前地图中心附近的合成 Polygon |
|
||
| 投诉热力分布 | 三个具有非负权重的合成投诉点 |
|
||
| 候选管段对比 | 合成候选表格及两条 candidate 数据，不查询虚拟管段 |
|
||
| 隔离阀门清单 | 合成阀门表格及两条 valve 数据，不执行关阀 |
|
||
| 纯 JSONL 数据 | 只显示数据；内嵌 action 字段不作为动作执行 |
|
||
| 错误：JSON 语法 | 第二行语法错误时整批拒绝，不执行第一行合法动作 |
|
||
| 错误：不支持的动作 | 拒绝协议未支持的动作 |
|
||
| 错误：图表数据不齐 | 拒绝时间轴和序列长度不一致的图表 |
|
||
| 错误：同期时刻错位 | 拒绝历史时间与横轴槽位不一致的复合图，整批不执行 |
|
||
|
||
切换前若执行过本地预览，会先清除它的当前临时地图、图表和业务结果，保留动作历史供回看；仅选择或编辑 JSONL 不执行新指令。有内容时即可点击“执行本地预览”，无需先点单独校验；每次执行都会重新校验当前全部输入。任何一行错误都会拦截整批，显示具体错误，不执行部分指令；地图尚未就绪时也显示原因。仅空输入或正在执行时禁用按钮，不以调查选择或实时跟随作为本地执行前提。测试不会写入 Server、重启调查或发送 Agent 对话。案例定义位于 [investigation-dev-cases.ts](../src/features/workbench/utils/investigation-dev-cases.ts)。
|
||
|
||
## JSONL 格式
|
||
|
||
以下每行都是独立对象。第一行只在点击执行后清理本地高亮；第二行预览合成说明；第三行仅为候选数据，不触发高亮、定位或计算。
|
||
|
||
```jsonl
|
||
{"record_type":"presentation","command":{"action":"clear_highlights"}}
|
||
{"record_type":"ui_block","evidence_refs":[],"block":{"version":"answer-ui@1","block_id":"dev-note","fallback_text":"本地合成格式示例","spec":{"root":"note","elements":{"note":{"type":"Text","props":{"text":"本地合成格式示例，不代表调查成果。","tone":"warning"},"children":[]}}}}}
|
||
{"record_type":"candidate","origin":"synthetic","source_evidence_refs":[],"element_id":"DEMO-PIPE-01","status":"example_only"}
|
||
```
|
||
|
||
仓库内的可复制数据示例为 [unified-presentation.jsonl](../tests/fixtures/unified-presentation.jsonl)，覆盖十种 command、两个可聚合的对象复合图、一个 `phase: final` 界面块和带来源的普通数据行；`P1` 是浏览器测试夹具中的测点，业务项目应使用已核实的实际编号。内置案例从同一个记录生成器输出，并在生成时通过当前校验器。错误案例单独保留，专门验证拒绝行为。
|
||
|
||
每行必须显式使用 `record_type: presentation`、`record_type: ui_block`，或带来源的调查数据类型。裸 command、裸 `answer-ui@1` block 和旧 chat 的 name/params 格式均拒绝。展示指令统一接受 `locate_features/zoom_to_map/highlight_features/clear_highlights/open_chart/close_chart/set_overlay/clear_overlay/render_scada_analysis/clear_scada_analysis`，不能加入项目、运行身份、URL、脚本或任意命令。Dev 的覆盖层样例直接提供合成几何，仅用于本地渲染测试；任务 Agent 的 `set_overlay` 可只传证据编号，由 Server 提取几何；传入 data 时必须与保存的证据快照一致。Chat 和 Dev 执行已提供并校验的 data。不能把 Dev 格式当成 Server 写入接口。
|
||
|
||
数据行需要 `record_type`、`origin`、`source_evidence_refs`，其余字段按实际内容保留。`origin` 接受 system_data、synthetic、derived、human_input，仅说明本地数据来源，不构成 Server 证据认证。显示合成表格不等于运行过定位或完成现场处置。
|
||
|
||
## 验证范围
|
||
|
||
聚焦测试：
|
||
|
||
```bash
|
||
pnpm exec vitest run src/features/workbench/utils/investigation-dev-preview.test.ts src/features/workbench/components/map-dev-panel.test.tsx src/features/workbench/hooks/investigation-presentation-follower.test.ts
|
||
PLAYWRIGHT_PORT=5194 pnpm exec playwright test tests/browser/investigation-dev-tools.e2e.ts tests/browser/floating-panel-pointer.e2e.ts --workers=1 --reporter=line
|
||
PLAYWRIGHT_PORT=5195 pnpm exec playwright test tests/browser/investigation-chart-manager.e2e.ts tests/browser/investigation-chart-groups.e2e.ts tests/browser/investigation-chart-layout.e2e.ts tests/browser/investigation-chart-resize.e2e.ts --workers=1 --reporter=line
|
||
```
|
||
|
||
浏览器用隔离 API/SSE fixture 验证所选任务到真实 MapLibre/React 展示的消费链、Dev 开启与收起、JSONL 校验和下载、任务静默恢复、任务切换清理、子图表管理、紧凑窗口、实际尺寸适配及面板外地图输入；不调用付费模型或真实工单、设备接口。真实 Agent 是否发布了正确的事件、报告或 JSONL 文件，仍需按实际项目运行记录核对。
|
||
|
||
## 统一展示动作
|
||
|
||
Chat 使用 `present_view({command, reason})`，在线通过 SSE 的 `tjwater.frontend_action` 承载 `frontend-action@2`，动作字段为 command，不再接收 name/params。浏览器回传 `frontend-action-result@2`。任务事件和 Dev JSONL 的 command 使用相同结构，并进入同一执行器。Chat、调查和 Dev 预览分别拥有地图源、SCADA 图层及图表状态；清理、切换会话和切换任务不会误清其他入口。Chat 动作按接收顺序执行，切换会话取消正在执行及排队动作；过期动作不会执行。任务仍只记录发布状态，不等待浏览器。查看历史回答不会重放动作。
|
||
|
||
动作 schema 的维护源是 `src/features/agent/presentation/command-schema.ts`。修改后在前端仓库运行 `node scripts/export-view-command-contract.mjs`，同步 Agent 主机/原生工具共用的 TypeScript schema、Agent/Server JSON Schema，以及两端 tests/fixtures 下的统一 JSONL 示例与图表正反例；运行同一命令加 `--check` 检查内容一致性。JSON Schema 表达字段和数量约束，跨字段的时间语义由运行时校验和共享测试矩阵保证。Server 任务入口继续执行证据归属和快照校验。
|
||
|
||
## 已有案例与示例迁移
|
||
|
||
仓库内正向示例统一使用以下格式；测试输入中的旧格式仅用于明确的拒绝用例。
|
||
|
||
| 内容 | 当前格式 |
|
||
| --- | --- |
|
||
| 地图、图表和 SCADA 动作 | `{"record_type":"presentation","command":{"action":"动作名",…}}` |
|
||
| 图表动作 | `open_chart`，图表数据位于 `command.chart`，明确提供 `chart_id` 和 `evidence_refs` |
|
||
| 结构化界面 | `{"record_type":"ui_block","block":{"version":"answer-ui@1","block_id":"…","phase":"final",…},"evidence_refs":[]}` |
|
||
| 调查数据 | 保留 `record_type/origin/source_evidence_refs`，不把内嵌 action 提升为指令 |
|
||
| Chat 调用 | `present_view({command, reason})`，不再调用旧的独立展示工具 |
|
||
|
||
迁移覆盖内置复杂案例、可复制 JSONL、跨端校验夹具及文档，不修改历史会话、数据库或外部下载文件。旧的已保存图表仍按结构校验读取；新输入与发布按下述规则校验。
|
||
|
||
|
||
## 对象复合图与验证规则
|
||
|
||
协议继续使用 `open_chart`，每个对象有独立稳定的 `chart_id`；不增加 `objects` 字段。多对象同期对比使用 `chart_type: time_comparison`。标题写为 `<对象ID> <同组标题>`，每条序列名以同一 `<对象ID> ` 开头，建议后接 `当前 YYYY-MM-DD` 或历史日期。对象 ID 以字母或数字开头，仅使用字母、数字、下划线、点或短横线。图例显示在绘图区下方；宽槽右侧的对象按钮单选切换数据集，窄槽使用对象选择器；独立放大的窄窗口把对象按钮移到下方。
|
||
|
||
仅 `open_chart` 中带历史 scatter 的明确对象图自动聚合。同组标题、chart_type、横纵轴名称、横轴槽位及当前序列名称去掉对象前缀后的部分、当前 sample_times 必须完全一致；不同单位或窗口分开。普通 line/bar 图和结构化回答中的独立 Chart 保持各自图表，统一在总窗口管理。关闭子窗口只收起放大视图，关闭聚合卡片移除组内所有对象；按原 chart_id 的 close_chart 仅移除该对象。
|
||
|
||
历史读取还兼容已保存的 `测点 <对象ID> <同组标题>`、`压力测点 <对象ID> <描述>` 和 `流量测点 <对象ID> <描述>` 标题；后两种以指标名称连接描述作为同组标题，压力和流量分开。对象归属仍要求序列名带同一对象前缀。历史 scatter 仅写 `MM-DD` 的旧图，只有在标题与唯一当前 line 明确指向同一对象，且每条日期序列至少有一个有效采样时间、有效值与时间一一对应、时间换算为 UTC+8 后均为同一完整日期并与日期名相符时，才兼容日期型历史图例；缺失时间、日期不符、跨对象序列或歧义标题保持单图。这些兼容只影响显示聚合，保留原指令、标题、序列、采样时间和证据，不修改保存的数据，也不放宽新发布的同期规则。
|
||
|
||
当前与历史共用 UTC+8 的 HH:mm 或 HH:mm:ss 槽位，时刻精度一致，窗口按顺序且短于一天，允许跨午夜。每对象最多 100 个槽位、8 组序列，包含当前 line 和历史 scatter，不能混入 bar。每组 sample_times 与 data 等长，有效值保留带时区的真实采样时间；缺测值和时间均为 null，零值保留。采样时间换算为 UTC+8 后须落在对应槽位；当前曲线共享同一窗口，每组历史来自此前某个对应日期，不能混入当天、未来或不同日期。普通 line/bar 不套用这些同期语义，但不能用 line 冒充 line 与历史 scatter 复合图。
|
||
|
||
Dev 的 presentation 与 ui_block.Chart、新的 Chat open_chart（Agent 主机与原生工具）及任务图表发布使用相同的同期规则。历史读取的结构校验不追溯拒绝旧混合图。Server 在任务展示和报告发布时另外校验证据归属与同期语义，错误码为 TIME_COMPARISON_INVALID；本地预览不证明证据有效或业务发布成功。共享正反例的维护源为 [chart-publication-cases.json](../tests/fixtures/chart-publication-cases.json)，随导出脚本同步到 Agent 与 Server，并在各仓库独立运行测试。
|
||
|
||
|
||
## 展示动作历史
|
||
|
||
调查实时展示按所选任务读取 Server 已保存的展示动作，各任务的历史在浏览器中分别保留、切换时按任务展示。对话展示和本地预览展示继续保留当前项目、本次页面会话内收到的动作。清除类动作不纳入历史。展示面板的“切换展示动作”以最新优先倒序排列，“当前（最新）”始终置顶，动作编号保留发生顺序。可选择任一已完成、未完成或取消的动作，也可用上一步/下一步逐步回看；进行中的动作显示状态但不可选择。“回到当前”恢复最新展示。 当前结果与最后一条已完成动作相同时，合并显示为“当前（最新）”，下拉和前后导航不再重复这一项。清理后当前结果与最后快照不同，最后一条仍作为历史结果可选。切换任务、切换案例、关闭图表和清除当前展示都会保留历史；切换项目或刷新页面后清空浏览器缓存，重新选择调查任务可再次读取 Server 保存的事件。不设最近若干条的截断。载入和回看不向 Server 发布事件，不重启调查、审批或现场操作；重复选择同一任务按任务编号和事件序号去重。
|
||
|
||
本地快照保存图表、界面块、数据、证据摘要、地图几何及镜头。Server 历史保留原发布指令和空间证据快照；只有要素编号的旧定位指令在首次载入时按当前项目读取可访问几何，不声称这些是历史时刻的资产位置。载入后回看使用本地快照，不重复查询。上一轮结果可作为历史查看，不混入本轮当前状态。单条过期或不合法指令显示失败记录，其他有效结果继续载入。历史导航直接渲染快照，不重新查询资产、执行原指令或发送调查请求。关闭图表、显示/隐藏及定位覆盖层、界面块关联要素定位等操作会产生记录；清除临时展示、清除地图展示，以及 `clear_highlights/clear_overlay/clear_scada_analysis` 指令只更新当前状态，不创建历史条目，已有结果快照仍保留；地图手动拖拽和证据展开属于查看操作，不逐帧记录。记录不是完整底图或外部实时数据的离线副本。
|
||
|
||
回看期间，新动作继续更新“当前”，面板保留正在查看的历史并提示后续动作数。“回到当前”恢复这些最新结果。历史画面禁止关闭图表、修改覆盖层和发起新的关联要素查询，仍可查看依据、检查表格并定位已有覆盖层。地图与界面使用已有过渡，并尊重减少动画设置。Dev 原始数据检查对应编辑器最近一次执行的输入，不随展示历史切换；历史结果及快照以展示面板为准。
|
||
|
||
|
||
历史接口按 `after`、`through` 游标和 `limit` 分页，返回 `task_id/event_cursor/items/next_after`；客户端固定首次授权游标，不截断为最近一页。Server 按项目、任务及展示事件类型读取现有事件日志，不需要新增数据表。新接口需与前端一起发布；测试覆盖的是当前源码的服务/仓储/API 单元检查与浏览器模拟 API 联动，未替代真实项目验收。
|