Halaman utama Jelajahi Bantuan
Daftar Masuk
ChenJZ
/
City-Lifeline-Cockpit
1
0
Fork 0
Berkas Masalah 0 Permintaan Tarik 0 Wiki
Pohon: 7183d131a8
Ranting Tag
City-Lifelin...
/
.scratch
/
cockpit-shell-panel-layout
/
issues
/
52-untitled.md

52-untitled.md 9.7 KB
Riwayat Mentahan

邻域设备示意挂载与增强面板内部详情

What to build

在邻域增强场景显示真实监测设备模型，按行业在管道固定示意槽位摆放并可点击查看内部设备详情。真实设施关系优先；无关系但合法坐标的邻近设备可挂同业最近管段，标“邻近设备·示意安装”。无合适管段独立显示，无坐标无关联仅列清单。

Acceptance criteria

  • 核验并补齐邻域设备读取来源及设施/井关系；不能把所选监测点设备当附近全部设备。
  • 真实设备ID与父监测点身份保留，真实关联优先于空间近邻，networkId按真实主键匹配。
  • 同业固定槽位示意布局、无位置清单、关系/布局提示，绝不创建设备或改绑定/源坐标。
  • 设备模型点选打开增强面板内部详情，复用真实详情接口；场景和相机保持。
  • 在线、告警及读数真实显示，缺失/失败/过期/重试/换选取消正确；不能从附近设备推导管道健康。
  • 同业近邻、悬空关系、无坐标、缺来源/部分覆盖、设备点击至详情和销毁行为回归。

Blocked by

51

Context

完整已确认方案为本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/浏览器截图；后端仓库与权限不在本会话交付范围。

给维护者的实施清单

A. 现场视觉验收（只需你本人执行）

  1. 你启动 yarn dev，打开 http://127.0.0.1:8000/#/cockpit。
  2. 拾取一条管道进入「地下管线详情视图」。
  3. 逐项目检：
    • 右侧「监测设备」区是否与「附近管道状态」分离显示、不被长列表挤走；
    • 场景中是否有可辨的设备图标/模型，点击后是否打开内部设备详情面板；
    • 设备清单点击是否聚焦到场景设备并打开同一详情；
    • 设备标注是否明确写「邻近设备 · 示意安装」（而非暗示真实安装位置）；
    • 无坐标设备是否只出现在清单、没有被摆到伪造位置。
  4. 检查点：图标大小是否合适、密集时是否互相遮挡、详情面板是否遮挡关键信息、关闭详情后场景是否保持。
  5. 边界与回归：换选管道、切换 25/50/100 米、切换全局行业筛选——确认设备清单随之变化且旧详情被取消。

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，已关闭）、窨井剖切（53）、真实管径与材质（54）、场景设备图标细化（58）、按设备类型取指标（56）。

可复跑的离线证据

  • 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 Type: task Blocked by: #51 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 代劳：① 维护者在正式入口目检设备图标/槽位/内部详情；② 后端补齐「设备→设施」关系契约后，真实关联分支才会在真实数据上生效（当前按已批准的邻近示意降级，不伪报完整覆盖）。