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

## 进度

### 本次接手核对（当前状态，优先于后文历史记录）

**2026-10-13 当前结论：尚未完整验收就绪。** 用户已明确选择同步取证，代理完成当前版本/Gogs只读查询、18端点GET预检、30s WS订阅和实际浏览器进入系统检查；18个端点HTTP200/code200/readOnly=true，21项检查18过/3失败（监测createdAt缺字段）。WS订阅成功但窗口已结束，无真实工单动作，无新增量通过结论。实际入口为 `http://127.0.0.1:8000/#/cockpit`。地图在real页面因调色片元shader编译失败停止渲染，已留[截图](../verify/artifacts/t18/takeover-browser-20261013/rendering-stopped.jpg)。

新增两个技术阻断：[监测三端点createdAt真实契约缺失](35-createdat.md)、[调色shader编译失败使地图停止渲染](36-untitled.md)，均已建为地图子票并接入本票Blocked by；待执行会话分诊/修复，不要求用户手工修代码。详细实测、版本、证据限制和启动条件见[当前预检报告](../handoff/t18-current-preflight.md)，真人测试步骤见[接手清单](../handoff/t18-human-takeover.md)。本轮未运行build、未启动/重启服务、未修改功能代码或真实业务数据；没有新真人验收结论。

前端HEAD=`5a83ab9b`、真实远端master=`a6fbbea9`，本地ahead12且驾驶舱36个已跟踪源码文件有差异；后端HEAD=`a96091ce`、真实远端master=`3e448568`，缓存origin/master已落后，不依据缓存ahead1推断实际推送状态。当前运行产物与干净提交尚未绑定，不能升级正式基线。候选真实工单 `WO202610121103507623` / 设备 `21119740` 仍为0/待派单、报警关联true；请保持状态，等新的取证窗口就绪后再推进。

- 已读全正文、全部评论、标签、认领与阻塞关系，并读所属地图 Destination/Notes/Decisions so far。工单已认领，保留 `@me`；15 项登记前置依赖均已关闭。本票仍为开放、`claimed` / `ready-for-human`，**未完成完整阶段验收，不得宣称收口**。
- **人工介入判定成立：需人工测试**，附带外部业务系统操作权限与最终业务判断。真实报警及工单创建、派单、接单、处理、提交验收、结案须由具有相应角色的真人在外部业务系统完成；驾驶舱仅只读呈现。AI 可做版本/接口/WS/浏览器技术取证与证据整理，但不能代替真人处置或代签最终业务结论。本轮未发现需要重新裁定的设计问题，不转 `ready-for-agent`。
- 工单后文的“真人走查结论（5 项，均未通过）”“下一步”及旧 WS 窗口属于历史记录，不再是当前待修清单。预警事件故障、信封消费、管网映射、分页八桶、图层接线、台账分母、抖动诊断与修复的关联票已关闭；旧结论不得用于判定当前运行版本。
- 尚有技术证据门槛：地图与抖动修复票仍记“已关闭但改动未提交”；最新已读历史真实审计 140/143，余 3 项为监测 `createdAt` 缺口；现有基线卡片跨多个版本，缺一张覆盖当前前后端提交/推送/运行实例的完整阶段基线。以上须由代理或对应执行票核对，不能交给真人签字豁免，也不能推定现在接口仍失败。
- 当前设施口径以[设施总数三处口径一致性修复](31-5278-5276-5273.md)为准；旧 5278/5276/5273 分域期望已被统一目录取代，历史三端同为 5283，管网集合 5268。数字只对应历史快照。坐标按[坐标自动准入裁定](34-coordinate-auto-admission.md)核验，不要求人工寻找坐标校核入口。

### 给真人的实施方案与检查点

已产出[真人接手清单](../handoff/t18-human-takeover.md)：仅列真人业务走查、真实有 GPU 环境目视稳定性、外部报警—工单全流程及最终验收结论；每步含验证方法。版本核对、探针、WS 捕获、浏览器断言与基线回写由代理承担。清单同时覆盖合法空态、失败分区、坐标边界、未分区、无关联工单、零分母和刷新/筛选/模式切换回归，缺样本项记待验。

### 当前下一步

**维护者最新指示：先保留移交，其他会话正在修改相关内容，等待正常后继续。** 本会话暂停进一步执行和功能修改，不认领新建的两张执行票，不代提交并行改动，也不开启真人工单流转；已有真实只读取证授权保留，用户要求继续时先核对稳定版本和运行基线再复验。

1. 在[监测数据时间修复](35-createdat.md)与[调色shader修复](36-untitled.md)中处理技术阻断；本票不修改功能代码。前端并行改动需协调并形成限定提交/推送，由代理补运行绑定。
2. 修复后代理在稳定版本重做受影响的GET、WS和浏览器预检，补四模式/边界/筛选分页证据。当前用户已授权同步取证，无需重复询问同一验证授权；需扩展到功能修复时按对应执行票范围处理。
3. 代理确认新的WS捕获窗口已订阅后通知用户开始，给出测试样本、页面入口、步骤与逐项检查点。真人负责真实报警—工单业务流程、90秒目视稳定性与团队验收，程序证据由代理同步记录。
4. 对照实际结果完成自查，按版本追加基线；全部条件满足才发resolution comment、关闭并完成上报，在地图Decisions so far追加名称链接及一句结论。目前保持claimed/ready-for-human/open、未就绪/未收口，不要求真人代修代码或用签字豁免缺口。

Labels: ready-for-human, wayfinder:task

Type: integration
Status: claimed
Assignee: @me
Label: ready-for-human
Blocked by: #14, #15, #16, #17, #19, #20, #21, #22, #23, #24, #25, #26, #27, #28, #33, #35, #36
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-*` 断言和真人验收结论；缺任一关键证据则不得宣称阶段收口。

## 历史进度（2026-10-10）

方案A裁定已入票28与CONTEXT.md。发现我的严重推理错误：用修复后代码的复核结果否定修复前已证实的缺陷（票22），已恢复为「已修复待验证」并记录纪律。另发现存在并行工作正在修改票22/24/27相关源码，我已将其移出暂存区未代提交，需在改动稳定后复验所有结论。

## 真人闭环证据（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)

## 历史下一步（2026-10-10，已被本次接手进度取代）

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

### 管网映射后端交付回写（2026-10-12）

[管网编码与设施命名空间](20-20-0-1.md)已完成。主修复740d896已部署实测；燃气537、供水996、排水3735合计5268；基础档案总数5278、概览5276、管理信息5273为不同对象域。设施不再误标监测设备类型。审查P2/P3补齐29d1ae2经复核并合入0a6b108推送，整合后管网专项29/29通过；远端新增报警生命周期顺序断言有1项全量失败，相关文件本次未改，如实见[审查报告](../handoff/review-pipe-type-namespace.md)。

维护者粗验未发现问题，完整界面核验仍由本票承载；按[人工核验步骤](../handoff/manual-verify-pipe-type-namespace.md)清空筛选并核对real请求与页面响应，不把接口验证替代完整浏览器验收。


### 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）放大了故障，必须独立修复。①（地图不显示）中「预警事件无坐标」也是成因之一，与坐标校核来源缺失同族。

### 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](27-27.md) |
| 预警处置 | 当前预警／历史分析／预警效率／预警分析 | **四项全部失败**（后端 `code=500`） |

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

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

**4. 缺陷票调整**：[22](22-22.md) 撤销为「前提不成立」；新增 [27](27-27.md) 监测点台账渲染 `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 行）：

```java
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](28-28.md)，与 [票 20](20-20-0-1.md) 同族（未分类对象静默丢弃）。

### local — 2026-10-10T08:39:30.828Z
**我的推理错误更正 + 并行工作发现（2026-10-10 16:40）**

**1. 我撤销票 22 的判断是错的，已恢复。**

时间线揭示了真相：

| 时刻 | 事件 |
| --- | --- |
| 10:25 | 探针报告写入，三项 `frontend-*` 检查**失败** —— 此时 `cockpitApi.js` 尚未修复 |
| **14:38** | **并行改动修复了 `cockpitApi.js` 的信封拆解** |
| 15:50 | 我复核 → 通过（**但跑的是已修复的代码**） |
| 15:58 | 我据此撤销票 22 —— **错误** |

我的错误在于：**用修复后的通过，否定修复前已证实的缺陷**。修复后的代码正确，不能证明缺陷从未存在。正确处置是标记「已修复待验证」而非撤销。

票 22 已恢复为 `fixed-pending-verification`，并写明待验证项（重跑探针、浏览器确认 500 显示为失败分区、确认 mock 分支未被误伤）。沉淀一条纪律：**验证缺陷必须确认被测代码版本与复现时版本一致**。

**2. 存在并行工作，正在修改我这张票涉及的文件。**

工作区（**非我改动，已原样保留未提交**）：

| 文件 | 修改时间 | 可能对应 |
| --- | --- | --- |
| `src/modules/cockpit/services/cockpitApi.js` | 14:38 | 票 22（信封拆解） |
| `src/modules/cockpit/domain/modeLayerPlan.js` | 15:50 | 票 24（设施/管线图层） |
| `src/modules/cockpit/stores/deviceLayerStore.js` | 16:26 | 票 27 或设备图层 |
| `src/modules/cockpit/CockpitShell.vue` | 16:35 | 票 24/27 |
| `.scratch/cockpit-shell-panel-layout/**`（票 41/42/47/48、t48 验证脚本） | — | 另一 effort 的联动质量收口 |

**我已把它们从暂存区移出，未替他人提交**（`git reset` 保留工作区内容）。我的提交只含 `CONTEXT.md` 与本 effort 的票面。

**这带来两个后果，需注意**：

1. **票 24/27 可能正在被实现** —— 我此前基于「图层未接线」「渲染 undefined」建的票，其对应文件已有改动，实施完成后应改为待验证而非待实现。
2. **我此前的浏览器取证（15:55–15:58）与这些并行改动存在时间交叠** —— 当时观测到的界面状态可能已不是当前代码的行为，任何结论都需在改动稳定后复验。

**3. 本轮新增确认**：票 28 口径决策（方案 A）已写入，`CONTEXT.md` 的「点位状态」「无地图位置」两条术语已就地澄清，并新增「无设备点位」条目（显式区别于「未关联设备」—— 两者方向相反，不是同一类对象）。