# 前端真实接口联调与阶段收口：真人接手清单

所属工单：[前端真实接口联调与阶段收口](../issues/18-frontend-real-integration-gate.md)。本清单提供真人必须亲自完成的步骤；首次接手准备后，用户已明确要求同步取证。当前实测与版本记录见[当前预检报告](t18-current-preflight.md)。

**当前尚未就绪：请先保持候选工单状态，不开始最终验收。** 实际页面入口为 `http://127.0.0.1:8000/#/cockpit`；18个只读接口预检通过，WS订阅通过，但地图因调色shader编译失败停止渲染，监测三个端点仍缺createdAt，交付运行基线尚未锁定。先由对应执行票修复与协调版本；代理复验通过、重新开启WS窗口并明确通知后，再执行下表。

## 为什么需要真人

判定类别：**需人工测试**，附带外部业务系统的操作权限和最终业务判断。驾驶舱只读；真实报警及工单的创建、派单、接单、处理、提交验收、结案由业务人员在外部业务系统执行。代理不能代替业务人员作真实处置，也不能替真人团队给出验收结论。技术取证、版本核对、证据整理和基线回写由代理承担。

工单已认领，15 项已登记前置依赖均已关闭。关闭执行票不等于阶段已通过；本票保持 `ready-for-human` / `claimed`，目前没有新的完整真人验收结论。

## 开始真人操作前：由代理或对应执行票处理

这些是技术准备，不是交给用户的实施步骤：

- 核定前后端仓库、分支、精确提交、Gogs 推送状态、运行产物和页面实际地址；锁定 `DATA_SOURCE.REAL`、后端 `http://192.168.110.96:8301`、REST `/api/cockpit/v1/**`、WS `/ws/deviceStatus` 与只读快照。源码 HEAD 不能单独证明服务运行的是该版本。
- 核对[刷新引发抖动的修复交付](../issues/33-33-jitter-fix.md)是否已提交推送。地图和该票仍有“修复留在工作树”的记录；完成版本核对前，只能称其历史走查通过，不能当作已交付基线。
- 复核监测三端点 `createdAt` 缺口。最新已读历史审计为 140/143，余 3 项未通过；空值的合法性与字段缺失须分开核对。若真实缺口仍存在，回到对应规格/执行票补齐，不能用验收签字绕过。
- 用户已在当前对话明确要求真实只读接口、WS和浏览器取证。本轮已做GET/订阅/页面进入预检，结果和限制见[当前预检报告](t18-current-preflight.md)；未运行build，未启动/重启服务，未做真人业务操作。复验和长时间同步取证继续由代理承担，不要求真人手工分析JSON、运行脚本或维护基线。
- 同一轮取证须记录时间范围、快照与筛选参数。现有基线卡片按历史版本保留；新版本追加卡片并注明替代关系，不覆盖历史证据、不提前升级状态。

## 仅需真人执行的实施步骤

技术准备期间可以进行预走查；其结果须标注“预走查”，满足完整版本与证据门槛后才能作为最终验收。

| 顺序 | 真人操作 | 每步检查点与验证方法 | 留给代理的结果 |
| --- | --- | --- | --- |
| 1 | 在代理确认的 real 页面，依次切换总体概览、基础设施、运行监测、预警处置，检查全部 16 个面板 | 数字、名称与业务认识一致；真实空态能理解；没有 `undefined`、明显空白或错误被显示成正常数据。发现不符，记录模式、面板名、可见现象和时刻；代理核对同次请求 | 每个模式通过/未通过/待验及异常现象 |
| 2 | 走查一张图，切换行业（含窨井）、片区（含未分区）、状态多选，查看监测点、未关联设备、设施与管线，打开有位置和无位置对象的详情 | 筛选与对象身份符合业务语义；无设备点位仍在统计/台账；无位置对象不伪造位置且有原因。管网条数与设施总数不同，不混比。代理核对八桶、分页 token、计数和同次响应 | 可读性、定位、图层及筛选的真人结论 |
| 3 | 在实际使用的有 GPU 电脑保持画面静置至少 90 秒，再做一次手动刷新、筛选和模式切换 | 目视覆盖至少两个 30s freshness tick，确认没有周期性抽搐、标记闪失、选择对象串位或面板失联。若有问题，记发生时刻与当时操作；代理做刷新窗口与性能证据对照 | 电脑/浏览器环境、观察时长、是否再现抖动 |
| 4 | 在代理已确认取证窗口开启后，由业务人员选定一个真实报警，在外部系统创建并关联工单；按实际流程派单、接单、处理、提交验收，最终由有验收权限的人结案 | 不跳过业务必经环节。记录设备编码、报警单号、工单编号及每次动作时刻；每个阶段在驾驶舱检查同一报警、工单状态和时间线。代理同步核对 REST 与 `cockpitWorkOrderStateDelta`，真人不用解析帧 | 同一条真实链路的动作记录、页面可见结果 |
| 5 | 由真人验收团队对本轮完整结果给出结论 | 逐模式与完整闭环分别标“通过/未通过/待验”，说明原因和可见结果。无样本、无结案权限或尚未走完的步骤一律待验；最终业务结论不能由代理代签 | 参与角色、时间、场景、结论及阻断项 |

外部系统如需分角色操作，由具有相应权限的业务人员继续；不要求当前用户代行全部角色。记录角色即可，不要求实名。

## 样本与当前口径

- 历史正向样本：设备 `21119740`、报警 `BJ202610121103101791`、工单 `WO202610121103507623`；[关联一致性最终验收](../issues/21-21-vs.md)记录三端关联 true，状态为当时的 0/待派单。本轮须先由代理只读核对其当前状态和关联，再决定能否继续用于真实闭环。
- 历史负向样本 `WO202610101511303516` 在后续验收时为未关联 false/null，不能沿用早期 true 记录，把它当作当前正向闭环。
- 设施统一口径以[设施总数一致性修复](../issues/31-5278-5276-5273.md)为准：当时三端设施总数为 5283，管网集合为 5268。这些数字只属于历史快照；新一轮按同范围、同时间数据核对一致性。旧[管网人工核验说明](manual-verify-pipe-type-namespace.md)的 5278/5276/5273 分域期望已经被新裁定取代。
- 坐标按[自动准入裁定](../issues/34-coordinate-auto-admission.md)验证：合法且在主场景区内才能上图；非法或区外保留清单及原因。取消人工校核前置后，不再要求用户寻找不存在的坐标校核入口。旧“全量 UNVERIFIED”是历史结果。
- **状态序变化属预期（2026-10-23，票 71 收口）**：后端单设备状态序已改为「未转工单的报警 > 工单处置 > 预警」并部署复验通过（10/10，脚本 `../verify/artifacts/t71/verify-after-deploy.mjs`）。走查预期读数：未关联设备业务轴 预警 **3→1**、工单处置 **3→5**；`41010500001320000002`、`TEST-CBYL5432168` 两台由「预警」变「工单处置」（特效 blink → spin，属两态动效切换）；`TEST-TCLLJ002215` 仍预警；`21119740` 点位仍报警。另一处必须解释、**不能当缺陷**：同一台设备可能「地图/设备卡=工单处置、运行监测异常设备清单=预警/离线」——这是票 71 裁定 Q3=A 的结果（situation 按设备事实判、不跟随业务序，也没有 `WORK_ORDER` 桶）。

## 完成实施后的自查：代理逐项对照，真人确认业务结果

| 验收与回归项 | 必须保留的证据 / 判定 |
| --- | --- |
| real 生命周期 | 地图、16 面板、WS、freshness 自动初始化；实际请求指向锁定后端；失败不回退 mock |
| 地图筛选与快照 | 状态多选 OR；八桶全局计数与饼图同源；逐页携带同一个 `snapshotAt`；行业/片区/状态组合与同次响应一致 |
| 业务词汇与时间 | MANHOLE 显“窨井”；未分区不伪造归属；`createdAt` 与 `sampledAt` 分开；监测三端点缺口真正消除或如实记未达标 |
| 合法空态 | 无设备点位仍计数；无关联工单明确提示；分母 0 显示不适用；空列表不输出 `undefined` 或伪造数字 |
| 坐标边界 | 缺失/非法/区外对象不上图但保留记录与原因；不补默认坐标；坐标准入不改变对象是否计入统计 |
| 分区失败与恢复 | 真实失败只影响对应分区，不能显示为空态或正常数据；恢复后回到真实数据。若本轮没有自然故障，测试方安排受控验证；代理辅助取证，不要求用户制造业务故障 |
| 报警—工单一致性 | 同一真实链路在设备、ALARM、时间线的关联与状态一致；创建到结案的动作与真人记录对应；处置率为状态 5 / 状态 0–6，状态 7 排除 |
| WS 正反向 | 状态实际变化时核对对应工单增量帧和页面更新；记录实际 `scanIntervalMs` 和延迟。观察覆盖至少两个扫描周期；无帧时先核对是否真的发生状态码变化，不能仅凭“处置”动作或 `update_time` 判断故障 |
| 状态序与观感（票 71） | 两台设备显示「工单处置」而非「预警」、业务轴 预警 1 / 工单 5；同一设备在地图与运行监测异常清单状态不同属裁定结果（Q3），不记缺陷；动效由闪烁变旋转属预期 |
| 交互回归 | 刷新/模式切换/筛选后详情、锚点、选择对象仍一致，未复现周期性抽搐；既有 mock 回归单独记录，不算真实验收证据 |
| 基线与最终结论 | 前后端精确版本及推送/运行证明、请求与 WS 证据、freshness、浏览器 `data-*` 断言、真人结论齐备；缺任一关键项保持未收口 |

未找到真实边界样本的项标“待验”，不能从正常路径通过推断边界通过。发现功能缺陷回对应执行票修复，本票不承接代码修改。

## 真人结果记录模板

- 页面与设备环境：
- 观察时间范围 / 参与角色：
- 总体概览：通过 / 未通过 / 待验；现象：
- 基础设施：通过 / 未通过 / 待验；现象：
- 运行监测：通过 / 未通过 / 待验；现象：
- 预警处置：通过 / 未通过 / 待验；现象：
- 地图、筛选、无地图位置、刷新稳定性：
- 设备编码 / 报警单号 / 工单编号：
- 动作记录（动作、时刻、前后状态、页面结果）：
- 已结案：是 / 否；若否，原因与接手角色：
- 最终业务结论：通过 / 未通过 / 待验；剩余阻断：

## 不在本票范围内

前后端功能开发或修复、驾驶舱写操作、替真人执行外部工单处置、目标环境 `192.168.110.30:8301` 部署、管线 glTF 素材制作和并行白模素材工作。它们不能夹入本次联调交付，但实际改变运行版本或界面时应登记基线，复验受影响项。

## 收尾纪律

代理收到真人结果后对照上表整理程序证据，追加基线卡片；全部条件满足才写“真实数据联调完成”，全部首阶段模式和闭环均获真人通过才写“模式整体收口”。届时在工单发 resolution comment、关闭工单、调用 `deck_issue_report` 完成上报，并在地图 Decisions so far 追加工单名称链接与一句结论。当前只完成接手准备，保持开放，不记完成决策。