<!-- DSH-IDEMPOTENCY-KEY: t24-backend-geometry-read-model -->
<!-- parentKey: 00 -->
# 后端执行票 —— 驾驶舱设施点位与管线几何读模型


## 进度

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

## 背景与来源

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

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

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

   | 行业 | 管线几何 | 构件属性 |
   | --- | --- | --- |
   | 燃气 | `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。

## 交付物

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

## 验收

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

## 关联

由[票 24](../cockpit-real-data-wayfinding/issues/24-24.md) 范围第 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。
- 详情：[实施与验收记录](../handoff/geometry-read-model.md)、[最终审查](../handoff/geometry-read-model-review.md)、[真实验收结果](../implementation/t30/live-acceptance.json)。
- **真实免鉴权 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

<!-- 里程碑以进度区为准；deck chain 记录处理轨迹 -->

### 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。票收口。