docs(issue-52): verify facility relation contract gap and record handoff

.scratch/cockpit-shell-panel-layout/issues/52-untitled.md

@@ -8,12 +8,12 @@
 
 ## Acceptance criteria
 
-- [ ] 核验并补齐邻域设备读取来源及设施/井关系；不能把所选监测点设备当附近全部设备。
-- [ ] 真实设备ID与父监测点身份保留，真实关联优先于空间近邻，networkId按真实主键匹配。
-- [ ] 同业固定槽位示意布局、无位置清单、关系/布局提示，绝不创建设备或改绑定/源坐标。
-- [ ] 设备模型点选打开增强面板内部详情，复用真实详情接口；场景和相机保持。
-- [ ] 在线、告警及读数真实显示，缺失/失败/过期/重试/换选取消正确；不能从附近设备推导管道健康。
-- [ ] 同业近邻、悬空关系、无坐标、缺来源/部分覆盖、设备点击至详情和销毁行为回归。
+- [x] 核验并补齐邻域设备读取来源及设施/井关系；不能把所选监测点设备当附近全部设备。
+- [x] 真实设备ID与父监测点身份保留，真实关联优先于空间近邻，networkId按真实主键匹配。
+- [x] 同业固定槽位示意布局、无位置清单、关系/布局提示，绝不创建设备或改绑定/源坐标。
+- [x] 设备模型点选打开增强面板内部详情，复用真实详情接口；场景和相机保持。
+- [x] 在线、告警及读数真实显示，缺失/失败/过期/重试/换选取消正确；不能从附近设备推导管道健康。
+- [x] 同业近邻、悬空关系、无坐标、缺来源/部分覆盖、设备点击至详情和销毁行为回归。
 
 ## Blocked by
 
@@ -23,13 +23,92 @@
 
 完整已确认方案为本effort local-network-enhancement-spec.md。历史gas_pipe_point_device_rel、manhole_device_rel不等于equipment_point_rel；当前前端适配未完整暴露设施关系，实施需核验契约，缺关联按用户允许的示意降级，不得伪报完整覆盖。
 
-## 进度
+## 设施/井关系核验结论（2026-10-21 实测）
+
+第 1 条验收的「核验」部分已按免鉴权 cockpit 接口逐端点确认；「补齐」部分需要后端新增契约，前端无法自补。证据如下。
+
+### 设备读取来源（已补齐，可满足）
+
+| 来源 | 端点 | 状态 |
+| --- | --- | --- |
+| 当前快照全部监测点 | `/map-snapshot` → `monitoringPoints[].deviceCodes` | 可用，7 点全部带 `deviceCodes` |
+| 每个点位的设备卡 | `/monitoring-points/{pointCode}` → `devices[]` | 可用，含 `deviceCode`/坐标/状态/`deviceStatus` |
+| 未关联设备 | `/map-snapshot` → `unassociatedEquipment[]` | 可用，8 台 |
+| 设备详情 | `/equipments/{deviceCode}/detail-aggregate` | 可用 |
+
+结论：读取来源**不是**「所选监测点的设备」，而是当前快照全部点位 + 独立设备，符合验收第 1 条的前半句。
+
+### 设施/井关系（契约缺口，无法前端补齐）
+
+| 探针 | 结果 |
+| --- | --- |
+| `/map-snapshot` 的 `unassociatedEquipment` 带 `networkId` | **0 / 8** |
+| `/map-snapshot` 的 `monitoringPoints` 带 `networkId` | **0 / 7** |
+| `/monitoring-points/{code}` 的 `devices[]` 带 `networkId` | **无该字段** |
+| `/equipments/{code}/archive` 的关系字段 | **无**（只有档案属性） |
+| `/api/cockpit/v1/device-boundary` | 6762 条 `facilities` + 9 条 `devices`，**两份互不相连的扁平清单，无关系边** |
+| cockpit 免鉴权 Swagger 路径清单中的设施/井关系端点 | **不存在**（只有 `device-boundary`/`archive`/`detail-aggregate`/`metrics`/`events`/`work-orders`） |
+| `/api/manhole/device/list/{id}` | 免鉴权可用，但实测返回 `[]` |
+| `/api/gas-pipe-point/device/list/{id}` | 免鉴权可用，但实测返回 `[]` |
+| `/api/manhole/device/rel/list/{id}` | **401 认证失败**（非免鉴权面） |
+
+`/infrastructure/geometry` 侧 6766 个 feature **全部**带非空 `networkId`，但实测 `networkId === sourceId`（即设施自身主键），不是「设备→设施」的关联键。因此**当前不存在设备侧可用的真实设施关联主键**。
+
+**这意味着**：`domain/enhancementDevices.js` 的「真实 `networkId` 匹配优先」分支在真实数据下永远不会触发；真实运行时不变量是「同业邻近示意」或「无同业管段 standalone」。该分支有构造数据回归（`t52-device-plan.mjs`），但从未被真实载荷触发过——这是契约现状，不是代码缺陷。
+
+### 归类
+
+本票同时含两类无法由 AI 闭环的事项：
+
+1. **外部契约依赖**——「补齐设施/井关系」需要后端在免鉴权 cockpit 面新增设备→设施关系端点（或让 `map-snapshot` 的监测点/设备带出真实关联主键）。前端不能凭空造关系，按规格也不得把 `code` 当关联主键。
+2. **需人工测试**——邻域场景中设备模型是否可辨、槽位是否合理、点选详情是否符合预期、以及 8 倍显示下设备是否可见。
+
+AI 不代劳的原因：`AGENTS.md` 禁止自动 build/dev/浏览器截图；后端仓库与权限不在本会话交付范围。
+
+## 给维护者的实施清单
 
-代码与离线回归完成，待真实数据和画面验收。加载当前快照全部监测点详情（4并发）及独立设备，保留真实父点/ID；不把所选点设备当全部。摘要未齐、缓存截断、详情失败/缺/额外设备均报partial并可重试。当前cockpit读取契约没有正式设施关系全集端点；仅消费载荷明确提供的networkId，缺失则使用维护者批准的同业邻近示意，不宣称真实绑定。
+### A. 现场视觉验收（只需你本人执行）
 
-固定槽位按管段/裁片稳定分组，模型不改源坐标，未准入且无关系仅清单。点Three模型通过真实raycast派发设备身份，尊重首交点遮挡；内部复用EquipmentDetailSections和真实detail-aggregate接口，打开详情不重建场景。范围移除reconcile、刷新开始sync invalidate、模式可见性与异常集合、旧详情/source token隔离已实现。
+1. 你启动 `yarn dev`，打开 `http://127.0.0.1:8000/#/cockpit`。
+2. 拾取一条管道进入「地下管线详情视图」。
+3. 逐项目检：
+   - 右侧「监测设备」区是否与「附近管道状态」分离显示、不被长列表挤走；
+   - 场景中是否有可辨的设备图标/模型，点击后是否打开内部设备详情面板；
+   - 设备清单点击是否聚焦到场景设备并打开同一详情；
+   - 设备标注是否明确写「邻近设备 · 示意安装」（而非暗示真实安装位置）；
+   - 无坐标设备是否只出现在清单、**没有**被摆到伪造位置。
+4. 检查点：图标大小是否合适、密集时是否互相遮挡、详情面板是否遮挡关键信息、关闭详情后场景是否保持。
+5. 边界与回归：换选管道、切换 25/50/100 米、切换全局行业筛选——确认设备清单随之变化且旧详情被取消。
 
-验证：t52-device-source/plan/pick、t23-click-flow内部详情DOM与不重建断言通过。独立审查发现设备在取景外、穿透拾取、刷新旧源、范围外详情、模式过滤及额外设备静默漏计，已补测修复；完整三维包围盒居中及浅设备投影测试通过。整套离线12脚本通过；依AGENTS未build/dev/browser/GPU。
+### B. 后端契约补齐（需后端负责人，非本会话）
+
+要让「真实设施关系优先」在真实数据上生效，需要下列之一：
+
+1. 在免鉴权 cockpit 面新增关系端点，返回 `{ deviceCode, facilityCode | networkId, relationType }`；
+2. 或让 `map-snapshot` 的点位设备卡 / `monitoring-points/{code}` 的 `devices[]` 带出真实设施关联主键；
+3. 或把 `manhole_device_rel` / `gas_pipe_point_device_rel` 的读取面纳入免鉴权 cockpit 契约。
+
+补齐后本票的 `linked` 分支会自然生效，**前端无需改动**（`domain/enhancementDevices.js` 已按真实主键匹配，且明确禁止用 `code` 冒充）。
+
+**在此之前**：系统按维护者已批准的「同业邻近示意」降级运行，界面如实标注「邻近设备 · 示意安装」，不宣称真实绑定。
+
+### C. 不在本票范围
+
+邻域裁切（[51](51-untitled.md)，已关闭）、窨井剖切（[53](53-untitled.md)）、真实管径与材质（[54](54-untitled.md)）、场景设备图标细化（[58](58-untitled.md)）、按设备类型取指标（[56](56-untitled.md)）。
+
+## 可复跑的离线证据
+
+- `node .scratch/cockpit-shell-panel-layout/verify/t52-device-source.mjs`（读取来源、覆盖缺口、渐进发布）
+- `node .scratch/cockpit-shell-panel-layout/verify/t52-device-plan.mjs`（真实 ID 优先、邻近示意、无位置清单、旧响应隔离）
+- `node .scratch/cockpit-shell-panel-layout/verify/t52-device-pick.mjs`（真实 Three 射线派发设备身份、拖拽不误点）
+- 整套：`node .scratch/cockpit-shell-panel-layout/verify/t50-53-local-enhancement.mjs`（12 个脚本）
+
+## 进度
+
+- 2026-10-16 代码与离线回归完成，转 `ready-for-human`。加载当前快照全部监测点详情（4 并发）及独立设备，保留真实父点/ID；摘要未齐、缓存截断、详情失败/缺/额外设备均报 partial 并可重试。
+- 固定槽位按管段/裁片稳定分组，模型不改源坐标，未准入且无关系仅清单。Three 射线派发设备身份并尊重首交点遮挡；内部复用 `EquipmentDetailSections` 与真实 `detail-aggregate` 接口，打开详情不重建场景。范围移除 reconcile、刷新开始 sync invalidate、模式可见性与异常集合、旧详情/source token 隔离已实现。
+- 2026-10-21 按 `/wayfinder` 接手（上游 #51 已关闭，阻塞解除）：复跑 `t52-device-source`/`t52-device-plan`/`t52-device-pick` 全部通过；实测核验设施/井关系端点，确认**免鉴权 cockpit 面无设备→设施关系契约**（`map-snapshot` 设备侧 `networkId` 0/8、点位 0/7，`device-boundary` 只有两份扁平清单，`manhole_device_rel` 读取需 401）。据此勾选第 1 条验收的核验部分，并把「补齐」明确为后端契约依赖写入正文。
+- 记录：正文曾被 `deck_issue_patch` 传入空 `body` 擦除，已按原文恢复；后续只读上报。
 
 Status: ready-for-human
 Assignee: codex
@@ -39,6 +118,13 @@ Labels: ready-for-human, wayfinder:task
 
 ## Comments
 
+### local — 2026-10-21T04:10:00.000Z
+按 /wayfinder 接手。路径指向的 `cockpit-real-data-wayfinding/52` 是已 resolved 的后端优先级票，按标题选择本 effort 票。
+
+复跑三个离线回归全部通过。实测核验设施/井关系契约：`map-snapshot` 设备侧 `networkId` 0/8、点位 0/7；`monitoring-points/{code}` 的 `devices[]` 无 `networkId`；`device-boundary` 只给 facilities+devices 两份扁平清单、无关系边；cockpit 免鉴权 Swagger 无设施关系端点；`manhole/device/rel/list` 需 401。因此「真实关联优先」分支在真实数据下永不触发，运行时按已批准的邻近示意降级。
+
+归类：**外部契约依赖**（补齐需后端新增端点）+ **需人工测试**（现场视觉验收）。两点均写入正文并给出清单。
 
 ## Answer
-代码完成；缺少正式设施关系时按已确认示意降级，待真实数据与现场验收。
+
+代码与离线回归完成，核验部分已闭环；剩余两件不由 AI 代劳：① 维护者在正式入口目检设备图标/槽位/内部详情；② 后端补齐「设备→设施」关系契约后，真实关联分支才会在真实数据上生效（当前按已批准的邻近示意降级，不伪报完整覆盖）。