18: 前端真实接口联调与阶段收口

Labels: ready-for-human, wayfinder:task

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

目标

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

前置条件

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

验收范围

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

非目标

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

证据

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

进度

用户反馈的监测点丢失已核实并定位到行（票28）：6 个真实监测点在 map-snapshot 正确返回，但 monitoring/overview 与 monitoring/distribution 均报 0，且被静默丢弃（excluded 各计数皆不含它们）。根因是点位循环按 devices.size() 计入排除桶，无设备点位计 0。剩余阻断 19/20/21/23/24/25/26/27/28。

真人闭环证据（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 项，均未通过）

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

新发现（契约不一致）

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

下一步

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

票 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（部署不自动执行）。
后端基线更新：远端 master 已从 a151183 前进到 94971b5，含预警重构两次提交。此前「远端 a151183」记录作废。
WS 增量取证第一轮：干净的负向观察。捕获窗口 15:36:15–15:43:15，订阅成功，0 帧增量。双向核对：工单仍为 stateCode=1（待接单）、updateTime=15:12:49、时间线仍 2 条 —— 窗口内确实没有状态变化，因此「无帧」不构成链路故障。证据 ws-order-advance-1512.json。已开启 15 分钟新窗口等待真人推进状态。
新的部署后核对项：927fad2 同时删除了预警经纬度，预警类事件将不再有坐标（用户提供的真实报警记录本身即 longitude/latitude = null）。需确认驾驶舱对无坐标预警的呈现，不得伪造坐标。

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

local — 2026-10-10T07:59:30.566Z

面板逐项复核 + 一处自我更正（2026-10-10 15:58）

1. 更正我早前的错误结论。 我此前判定「前端把真实数据读成空、把业务失败读成成功」，该结论不成立，票 22 已撤销。三重复核：独立进程调用适配层返回 success/1006；四种前置顺序下均正常；浏览器真实渲染出真实读数。前端确实正确地把后端 code=500 判为失败分区（界面如实显示「数据加载失败 · 数据源暂不可用 · 该面板加载失败（其它分区不受影响）」）。原三项失败探针检查是我脚本自身的缺陷。

2. 四模式 16 个面板逐项实测（DATA_SOURCE.REAL，真实后端）

模式	面板	实测结果
总体概览	态势总览	通过：设施底数 8、智能设备 7、在线率 14.3%（在线 1/7）
总体概览	基础设施	通过：设施 8、设备 7、管线里程 18.81943 km、片区「未分区」1006
总体概览	运行监测	通过：在线率 14.3%、在线 1／离线 6、类型分布真实
总体概览	预警设置	失败（后端 `code=500`）
基础设施	基础档案	通过：1006、供水 1004／排水 2、片区 1006、建成年限 1002/4
基础设施	运行信息	通过（当前行业燃气为 0，故如实「后端未提供该类指标」）
基础设施	管理信息	通过：1001 + 片区×行业 7 行真实计数
基础设施	应急保障	失败（后端 `code=500`）
运行监测	监测概览	通过：设备 7、在线 0／离线 7、类型分布真实
运行监测	监测分布	真实空态（13 个对象坐标全部 `UNVERIFIED`，按契约不得上图）—— 符合契约
运行监测	运行概况	失败（后端 `code=500`）
运行监测	监测点台账	真实空态，但显示 `undefined` 条 → 新票 27
预警处置	当前预警／历史分析／预警效率／预警分析	四项全部失败（后端 `code=500`）

结论：16 个面板中 8 个真实数据通过、7 个因同一后端根因失败、1 个真实空态且呈现缺陷。 用户「四个面板全失败」的观察准确 —— 失败项恰好集中在总体概览-预警设置、基础设施-应急保障、运行监测-运行概况、预警处置整体，全部同源于票 19 的部署时序问题，重新部署预计可一次性恢复。

3. 地图状态更新：已加载 13 个对象、可上图 0、无地图位置 13（全部未校验）。分页未再出现 snapshotAt 丢失（上次故障未复现），但 pointStatus 八桶计数仍全为「—」。

4. 缺陷票调整：22 撤销为「前提不成立」；新增 27 监测点台账渲染 undefined。票 18 前置相应调整为 19/20/21/23/24/25/26/27。

local — 2026-10-10T08:18:13.765Z

用户反馈核实：监测点丢失，已定位到行（2026-10-10 16:15）

用户指出「当前监测点也没有获取到正确的接口，后端一共有六个未关联设备点监测点」。核实成立，且比反馈更严重。

事实对照

端点	监测点数
`GET /map-snapshot`	6（`GS001`/`GS002`/`PS001`/`PS002`/`RQ001`/`RQ002`，均 `pointStatus=EMPTY`、`deviceCodes=[]`）
`GET /monitoring/overview`	0
`GET /monitoring/distribution`	0（`pagination.total=0`，`pointStatusDistribution.EMPTY=0`）

并且是静默丢弃：excluded 中 unknownTypeCount=0、typeKindMismatchCount=0、invalidCoordinateCount=7（只记了 7 台未关联设备），6 个监测点既未计入总数，也未计入任何排除桶，彻底消失。

根因（已定位到具体行）

CockpitMonitoringDistributionService 点位循环（约 258–270 行）：

int amount = devices.size();   // 这 6 个点位 devices.size() = 0
if (UNKNOWN_TYPE.equals(mismatch)) {
    unknownTypeCount += amount;  // 加 0 —— 等于没记录
}
continue;                        // 被丢弃

同文件设备循环（约 326–334 行）同样分支却是 unknownTypeCount += 1（按设备自身计 1）。点位按设备数计、设备按自身计，口径不对称 —— 无设备点位因此被抹掉。

连锁效应：hasResolved = !deviceCodes.isEmpty()（约 444 行），而 deviceCodes 仅在坐标校验通过后收集；坐标全未校验 → 报 NO_RESOLVED_DEVICES，但真实原因是「设备坐标未校验」而非「无设备」，两种语义被混为一谈。

另一处矛盾：后端自己在 map-snapshot 已判定这 6 个点位为 EMPTY，而 monitoring/distribution 的 EMPTY 桶却是 0 —— 同一后端两处判定不自洽。

结论：适配器层（BusinessCockpitMonitoringDistributionAdapter）正确构建了 6 个点位，是 Service 层的排除计数丢弃了它们。已建票 28，与票 20 同族（未分类对象静默丢弃）。

18-frontend-real-integration-gate.md 15 KB Historique Raw