后端执行票 —— 驾驶舱设施点位与管线几何读模型

进度

Type: task Status: resolved Blocked by: Labels: ready-for-agent, backend-execution, wayfinder:task Category: backend-execution

背景与来源

票 24（前端设施点位与管线真实几何图层接线）范围第 1 项要求先定「权威读取路径」；维护者 2026-10-12 裁定：新开后端驾驶舱几何读模型，不在前端复用业务 GIS 端点。

已核实的事实（一手来源，2026-10-12）

驾驶舱侧没有任何几何端点：zksy-admin 下 24 个 Cockpit*Controller 中无一产出几何。/api/cockpit/v1/map-snapshot 只返回 monitoringPoints + unassociatedEquipment；/infrastructure/base-archives 只有聚合统计。
全后端只有两处几何产出：WaterSupplyGisMapController（/waterSupply/gis/map/features）与 gasbasic/GisController。两者都在 /api/cockpit/v1/** 之外。
两者都要鉴权：实测 GET /waterSupply/gis/map/features 返回 HTTP 200 + 业务 code=401 认证失败。ADR 0005 明文规定免鉴权范围「不扩展到后端其他业务路径」，故前端不可直接复用。
数据底座按行业不均（决定建模口径的关键事实）：

| 行业 | 管线几何 | 构件属性 | | --- | --- | --- | | 燃气 | pipe_network_base（network_type='0'）每条仅 2 个端点（startLongitude/startLatitude/endLongitude/endLatitude），直线段 | ✅ gas_pipe_point：经纬度 + pointType（阀门/调压/计量/阴极保护/弯头/三通/其它）+ networkId 关联所属管线 | | 供水 | 同表 network_type='2'，同为 2 端点直线段 | ❌ 无管点构件表 | | 排水 | 同表 network_type='1'，同为 2 端点直线段 | ⚠️ 有 drainage.domain.PipeNetworkInfo（管线/管点/排口），未见构件类型字段 | | 窨井 | 无管线；ManholeBase 有经纬度 | ❌ |

规模：pipe_network_base 共 5268 条（燃气 537 / 供水 996 / 排水 3735），管线总长 67.6 km。

交付物

新增免鉴权几何端点，挂在 /api/cockpit/v1/** 下（继承 ADR 0005 的免鉴权口径与只读语义），返回 GeoJSON FeatureCollection：
- 管段 LineString（沿用现有两点的 [lon, lat] 坐标顺序约定）；
- 管点/构件 Point，带 pointType 与所属 networkId。
跨行业覆盖如实呈现：哪些行业有几何、哪些没有，必须由响应本身表达，不得让前端猜。燃气按裁定出全套构件；供水/排水只有真实 2 点直线段就只给直线段；窨井给点位。
坐标校核纪律与决策票 07 一致：范围校验、零坐标、未校验坐标一律不得静默渲染，须随几何一并给出可判定的状态（与 map-snapshot 的 coordinateValidation 同形），由前端决定进「无地图位置」清单还是上图。
不做坐标臆造：不得为缺坐标的记录生成默认点或吸附推断节点。管段目前无共享端点拓扑，不得据此推断弯头/三通连接关系。

验收

只读 GET 实测：免鉴权可取到真实几何；坐标缺失/非法的对象带明确状态；燃气构件类型齐全、供水/排水/窨井的覆盖缺口在响应中如实可判；Cockpit*Test 全绿并推送提交（基点写进票内）。

关联

由票 24 范围第 1 项派生；票 24 的真实几何验收依赖本票落地。

进度

已实施并审查：新增 GET /api/cockpit/v1/infrastructure/geometry（免鉴权、只读、AjaxResult 信封内 GeoJSON FeatureCollection）。三源只读：pipe_network_base 真实两端点直线、gas_pipe_point 全部构件（pointType/networkId 原样）、manhole_base 点位；未分类管网保留（UNKNOWN/PIPE_UNCLASSIFIED）；不生成坐标、不推断拓扑。坐标纪律：结构非法（缺失/越界/零坐标）→ geometry=null + 具体 reason + sourceCoordinates 保留；数值合法但无校核来源 → UNVERIFIED/不可渲染；coverage 9 条显式区分 AVAILABLE/EMPTY/UNAVAILABLE 与各行业缺口。
提交 33ca0b6 已推 origin/master（60a0e9a..33ca0b6 快进）。针对性 22/22（几何 Service 14、Controller 6、免鉴权配置 2）；全量 *Cockpit*Test 463/463（在仅含该提交的隔离副本 validation-checkout 上通过；主工作树因另一并行会话未提交的设施统计改动无法编译测试，未动其工作）。两轴审查发现并修复事务异常绕过脱敏 500、非空几何 JSON 序列化回归，最终复核 Standards 0 / Spec 0。
详情：实施与验收记录、最终审查、真实验收结果。
真实免鉴权 GET 验收通过（2026-10-12 07:11，用户重启 IDE 实例加载 33ca0b6 后执行）：无 Authorization 请求 GET /api/cockpit/v1/infrastructure/geometry → HTTP 200 + 业务 code 200；13/13 检查全绿。实测 5272 个 feature（燃气管线 537 / 供水 996 / 排水 3735 / 燃气构件 1 / 窨井 3）；5270 条 UNVERIFIED_COORDINATE（数值合法但无校核来源）+ 2 条 INVALID LONGITUDE_OUT_OF_RANGE（窨井越界）；坐标纪律完整执行（geometry=null 对非法、合法不冒充已校核）；燃气构件 pointType=valve 原样透传、networkId 关联保留；供水/排水构件缺口 NO_COMPONENT_SOURCE / NO_TYPED_COMPONENT_SOURCE、窨井管线缺口 NO_PIPELINE_SOURCE 均如实标注 UNAVAILABLE。探针：implementation/t30/live-acceptance.py。

Answer

已收口（2026-10-12）：免鉴权只读几何端点 GET /api/cockpit/v1/infrastructure/geometry 实施、审查、测试、真实验收全链路完成。提交 33ca0b6 已推 origin/master。契约：AjaxResult.data 为 GeoJSON FeatureCollection，三源真实几何（pipe_network_base 两端点直线 / gas_pipe_point 构件原样 pointType+networkId / manhole_base 点位），坐标纪律与 map-snapshot 同形（非法→geometry=null+reason；合法但无校核来源→UNVERIFIED/不可渲染），coverage 9 条如实区分 AVAILABLE/EMPTY/UNAVAILABLE 与各行业缺口。真实验收：无 Authorization GET → 200，5272 feature，5270 UNVERIFIED + 2 INVALID，行业覆盖缺口全如实标注。详见进度区与关联 handoff。

Comments

local — 2026-10-12T07:21:30.258Z

真实免鉴权GET验收通过（2026-10-12 07:11，用户重启实例后），13/13全绿：5272 feature、5270 UNVERIFIED + 2 INVALID（越界窨井）、燃气构件pointType/networkId原样、各行业覆盖缺口如实UNAVAILABLE。提交33ca0b6已推origin/master，全量*Cockpit*Test 463/463。票收口。

30-untitled.md 6.9 KB Riwayat Mentahan