# 18: 前端真实接口联调与阶段收口
Labels: ready-for-human, wayfinder:task

Type: integration
Status: claimed
Label: ready-for-human
Blocked by: 14, 15, 16, 17, 19, 20, 21, 22, 23, 24, 25, 26
Category: integration

## 目标

把前端执行票 14–16 的契约/mock 实现切换到真实后端，完成第一阶段真实数据联调与业务可见性收口。该票是**真实联调验收门**，不是前端功能开发票。

## 前置条件

- 前端实现票 14–16 已完成逻辑闸门和 mock/契约验证。
- 后端执行票 11–13 已分别完成其代码、编译、契约测试，并由滚动复验票 17 在本地联调环境 `http://192.168.110.96:8301` 复验；本地联调通过后代码提交并推送 Gogs。
- 已锁定前端与后端提交哈希、分支、Gogs 推送状态和联调环境，登记到基线卡片。

## 验收范围

1. `DATA_SOURCE.REAL` + 本地真实 baseUrl 启动 `/cockpit`，验证 real 生命周期与 mock 同构：地图、四模式面板、WS、freshness。
2. 验证地图摘要状态筛选、district 片区、MANHOLE/窨井、`createdAt`、报警—工单读模型和实时同步。
3. 验证空数据、失败分区、坐标未校验、未分区、无关联工单、分母为 0 等真实边界，不用 mock 填补真实缺口。
4. 完成浏览器/人工走查；报警—工单闭环的最终业务结论由真人团队确认。
5. 更新对应基线卡片：四态至少达到「真实数据联调完成」；所有首阶段模式和闭环通过后才能写「模式整体收口」。

## 非目标

- 不在本票修改后端代码或前端功能代码；发现问题回到对应执行票修复。
- 不把目标部署 `192.168.110.30:8301` 纳入本阶段门槛。
- 不提供驾驶舱工单写操作。

## 证据

保留前后端提交哈希、实际请求结果、WS 事件、新鲜度结果、浏览器 `data-*` 断言和真人验收结论；缺任一关键证据则不得宣称阶段收口。

## 进度

真人闭环已取证：工单侧三项通过（关联标记/状态推进/时间线），报警侧不可见。走查 5 项均未通过，已拆为 19–26 并接为前置。票 19 根因更正为「部署时序错位」（DB 迁移领先于旧构建，修复已在 origin/master=94971b5），转为部署动作待人工执行。后端远端基线由 a151183 更新为 94971b5。WS 订阅通过；工单增量帧第一轮为干净负向观察（窗口内无状态变化），新窗口已开启待真人推进。

## 真人闭环证据（2026-10-10）

业务人员操作记录：报警 `BJ202610101504570793`，设备 `21119740`（测试环境监测设备01），`warningCode=WARN-SUSPENDED-SOLIDS`，实测值 `60.78`／阈值上限 `60`，四级报警，触发时间 `15:04:57`；据此创建工单 `WO202610101511303516`（`15:11:30`）；随后派单给超级管理员（`15:12:49`）。

驾驶舱只读接口对同一次操作的实测回应：

| 检查 | 实测 | 判定 |
| --- | --- | --- |
| 工单可见性 | `GET /equipments/21119740/work-orders` → `WO202610101511303516`，`stateCode=1`，`eventAssociation={ALARM, cd57be42bd18d02f7d3390fb98539b93, 15:11:30}`，`associatedWithCurrentEvent=true` | **通过**：报警→工单关系真实可读 |
| 工单状态推进 | 创建时 `orderStatus=0`（待派单）→ 派单后 `stateCode=1`（待接单） | **通过**：状态流转真实落到读模型 |
| 时间线 | 两条真实动作：待派单「由报警单[BJ202610101504570793]创建工单…」`15:11:30`；待接单「派单给责任人：超级管理员」`15:12:49` | **通过**：动作轨迹与真人操作一致 |
| 报警本体可见性 | `GET /equipments/21119740/events/current`、`GET /events/current?mode=ALARM`、`GET /monitoring/situation` 均业务 `code=500`（`early_warning.warning_name` 列不存在） | **失败**：驾驶舱看不到这条报警，闭环在「报警」一端断开 |
| 设备地图呈现 | `21119740` 仍在地图 `unassociatedEquipment` 中，`coordinateValidation.renderable=false` | **失败**：有数据但不上图 |

**结论**：报警—工单闭环的「工单侧」已用真实数据验证通过；「报警侧」因后端事件族故障未通过。因此本票**不得**宣称阶段收口。

## 实时增量证据（WS）

- 订阅链路：**通过**。`ws://192.168.110.96:8301/ws/deviceStatus` 直订后收到 `cockpitSubscribed`（`scope=all`，`serverUpdatedAt=2026-10-10T10:58:41+08:00`），免鉴权、无 `authenticate` 帧，浏览器顶栏同步显示「状态推送已连接」。证据：`verify/artifacts/t18/ws-observation.json`。
- 工单增量帧：**待取证**。上表订阅窗口结束于 `10:59`，早于本次 `15:04` 报警与 `15:12` 派单，因此**尚未**覆盖任何真实状态变化。已开启 7 分钟捕获窗口（覆盖两个 60s 扫描周期），需真人再推进一次工单状态（接单或处置）才能取得 `cockpitWorkOrderStateDelta` 帧。证据落 `ws-order-advance-1512.json`。
- 纪律：未收到增量帧不等于链路故障，必须同时复查工单状态确有变化（历史票 17 的负向观察纪律）。

## 真人走查结论（5 项，均未通过）

1. **地图未正确显示**：监测点、设备、设施、管道在地图上都没有正确显示。已知成因分层：全部真实坐标为 `UNVERIFIED`／不可上图；设施与管线图层未接线（`modeLayerPlan` 恒传 `facilities:null`、`pipelines:null`）；地图分页第 2 页曾漏带 `snapshotAt` 被后端拒绝。→ [24](24-24.md)、[23](23-23-token-pointstatus.md)
2. **四个面板全部加载失败**：总体概览-预警设置、基础设施-应急保障、运行监测-运行概况、预警处置四个面板均数据加载失败。已知成因：后端业务 `code=500`；前端还存在业务错误被适配为 success、真实数据被显示为空。→ [19](19-19-early-warning-warning-name.md)、[22](22-22.md)
3. **主场景抖动**：等待一段时间后整个画面进入抽搐状态。**尚未诊断**，按纪律不猜成因。→ [26](26-26.md)
4. **设施总数不符**：界面显示 `1001`，实际 `5268`。→ [20](20-20-0-1.md)
5. **Cesium 水印**：左下角存在 `https://cesium.com/` 署名，引擎未关闭 `creditContainer`。→ [25](25-25-cesium-ion-data-attribution.md)

## 新发现（契约不一致）

同一张工单 `WO202610101511303516`：`/equipments/{code}/work-orders` 返回 `associatedWithCurrentEvent=true` 且 `eventAssociation` 完整，`/work-orders/{code}/timeline` 却返回 `associatedWithCurrentEvent=false` 且 `eventAssociation=null`。两处口径不一致。→ [21](21-21-vs.md)

## 下一步

1. 修复 [19](19-19-early-warning-warning-name.md)（预警/事件族结构漂移）与 [20](20-20-0-1.md)（管网映射与设施类型命名空间），这两项解锁最多面板与统计。
2. 修复 [22](22-22.md)（前端信封与业务错误）、[23](23-23-token-pointstatus.md)（分页 token 与八桶契约）、[25](25-25-cesium-ion-data-attribution.md)（署名）。
3. [26](26-26.md) 先出诊断结论，再决定修复票；[24](24-24.md) 依赖 [20](20-20-0-1.md) 的真实映射。
4. 真人再推进一次工单状态，取得 `cockpitWorkOrderStateDelta` 帧。
5. 修复完成后重新部署并锁定运行提交哈希，重跑 `verify/t18-real-audit.mjs`，补齐非空指标、事件族与四模式面板真实数据。
6. 复做完整真人闭环（推进到已接单／处理中／待验收／已结案），确认报警侧与工单侧同时呈现。
7. 全部阻断清零且人工验收完成后，才更新基线卡片到「真实数据联调完成」；所有首阶段模式与闭环通过后才写「模式整体收口」，并追加地图 Decisions so far。

## 关联证据

- 真实探针：`.scratch/cockpit-real-data-wayfinding/verify/t18/live-audit-results.json`、矩阵报告 `real-integration-gate-report.md`、端点快照 `initial-live-endpoints.json`、WS 订阅 `ws-observation.json`、WS 增量 `ws-order-advance-1512.json`（待生成）。
- 项目规则要求的 build/debug 验证未自动运行；本次只执行用户明确授权的真实只读接口与浏览器联调。

## Comments

### local — 2026-10-10T07:46:20.363Z
**根因更正 + 新证据（2026-10-10 15:44）**

1. **票 19 的根因已确证，不是「缺列要补」**：数据库迁移领先于运行构建。上游 `927fad2 refactor(warning): 重构预警系统数据结构和业务逻辑`（2026-10-10 11:43 +0800）已从 `EarlyWarning` 删除 `warningName`/`longitude`/`latitude` 映射并动了库结构；运行实例（PID 37792，启动于 08:28:52，基线 `d8a6b03`）仍按旧映射 SELECT 被删列。**修复已在远端**：`927fad2` 与 `94971b5` 均在 `origin/master`（远端现为 `94971b5`）。票 19 因此从「写代码」改为「用 `origin/master` 重新构建并部署」，已转 `ready-for-human`（部署不自动执行）。

2. **后端基线更新**：远端 `master` 已从 `a151183` 前进到 `94971b5`，含预警重构两次提交。此前「远端 a151183」记录作废。

3. **WS 增量取证第一轮：干净的负向观察**。捕获窗口 `15:36:15–15:43:15`，订阅成功，0 帧增量。双向核对：工单仍为 `stateCode=1`（待接单）、`updateTime=15:12:49`、时间线仍 2 条 —— 窗口内确实没有状态变化，因此「无帧」不构成链路故障。证据 `ws-order-advance-1512.json`。已开启 15 分钟新窗口等待真人推进状态。

4. **新的部署后核对项**：`927fad2` 同时删除了预警经纬度，预警类事件将不再有坐标（用户提供的真实报警记录本身即 `longitude/latitude = null`）。需确认驾驶舱对无坐标预警的呈现，不得伪造坐标。

**对本票判定的影响**：②（四个面板加载失败）中相当一部分很可能随重新部署即可恢复，不全是前端缺陷；但前端把 `code=500` 读成 success（票 22）放大了故障，必须独立修复。①（地图不显示）中「预警事件无坐标」也是成因之一，与坐标校核来源缺失同族。