# 驾驶舱设施点位与管线几何读模型：实施与验收记录

本记录承接[后端执行票 —— 驾驶舱设施点位与管线几何读模型](../issues/30-untitled.md)。最终两轴审查见[几何读模型最终审查](geometry-read-model-review.md)。

## 基线与范围

- 后端仓库：`E:\pipe-ner-server`，分支 `master`，本轮起始 `HEAD=7fb7c2c`；初查工作区干净。
- 前端已有大量并行工作；本票只改本票记录与后端新增文件，不收取其它改动。
- 端点：`GET /api/cockpit/v1/infrastructure/geometry`。沿用现有 `AjaxResult` 信封，`data` 是 GeoJSON `FeatureCollection`；GET 继承既有 `/api/cockpit/v1/**` 免鉴权规则，无写入口、无新增鉴权例外。
- 从 `PipeNetworkBaseService.list()` / `GasPipePointService.list()` / `ManholeBaseService.list()` 读取；实体的 MyBatis-Plus `@TableLogic` 排除删除数据。事务标记只读，三源任一异常整体返回 HTTP 500 + `SERVER_ERROR`，不伪装为部分成功或空集合。

## 响应契约

- 顶层：`type=FeatureCollection`、`generatedAt`、`features[]`、`coverage[]`。
- `generatedAt` 只代表响应生成时间，不冒充可重读的一致性快照 token。
- `Feature.id`：`来源表:来源主键`，跨表不碰撞。
- `geometry`：真实两端点 `LineString` 或真实 `Point`；坐标顺序始终 `[longitude, latitude]`。任何端点缺失、越界或为 `(0,0)`，该对象 `geometry=null`，对象保留。
- `properties`：`source/sourceId/code/name/industry/typeCode/networkType/pointType/networkId/sourceCoordinates/coordinateValidation/coordinateValidations`。
- 管段与燃气构件 `networkId` 原样关联，窨井关联原样保留；没有关系时显式 null，不通过距离或共享坐标生成关系。
- `pointType` 原样透传，不把设施构件类型与监测点类型/设备类型编码混用，不填充不存在的构件。
- `coordinateValidation` 与 map-snapshot 同形：`state/reason/renderable/crs`。先按已有 validator 检测结构错误；数值合法之后仍因无校核来源返回 `UNVERIFIED/UNVERIFIED_COORDINATE/renderable=false`。**范围合法不能升格为已校核**。
- `coordinateValidations` 按源顺序提供逐坐标校验（点一个，管段起终点两个），避免终点非法被起点未校核掩盖。`sourceCoordinates` 保留原始值（含 null），供无地图位置清单解释。
- 未分类管网仍保留，`industry=UNKNOWN/typeCode=PIPE_UNCLASSIFIED` 并透传 `networkType`，不静默归入其它行业。

## 覆盖语义

每个 coverage 条目包含 `industry/source/geometryType/state/reason/recordCount/geometryCount/renderableCount`；数量来自本次响应，未硬编码现场规模。

| 行业 | LineString | Point |
| --- | --- | --- |
| GAS | pipe_network_base：真实两端点，TWO_ENDPOINTS_ONLY | gas_pipe_point：全部实际构件，pointType/networkId 原样 |
| WATER_SUPPLY | pipe_network_base：真实两端点，TWO_ENDPOINTS_ONLY | UNAVAILABLE / NO_COMPONENT_SOURCE |
| DRAINAGE | pipe_network_base：真实两端点，TWO_ENDPOINTS_ONLY | UNAVAILABLE / NO_TYPED_COMPONENT_SOURCE |
| MANHOLE | UNAVAILABLE / NO_PIPELINE_SOURCE | manhole_base：真实窨井点，NO_COMPONENT_TYPE |
| UNKNOWN | 未分类管网原样保留，UNKNOWN_NETWORK_TYPE | 无独立来源 |

`AVAILABLE` 表示已读取到源记录，`EMPTY` 表示支持的数据源本次没有记录，`UNAVAILABLE` 表示本端点没有该几何来源。`geometryCount` 是具有结构合法几何的对象数，**不等于可上图数**；可上图只能看 `renderableCount` / 对象的 `coordinateValidation.renderable`。

## 对抗式自查计划

- 三行业类型映射和设施命名空间；未知类型不丢弃。
- 真实两端点/Point、坐标顺序、跨表 ID、不生成拓扑。
- 所有原始燃气构件类型（包括缺失和未知）保留，networkId 不臆造。
- 缺经纬度、正负越界、零坐标；特别检查“起点未校核 + 终点非法”整线不可渲染且有具体错误。
- 三类来源都不能凭坐标合法升级为 VALID；边界值不误判越界。
- 空源与无来源覆盖状态区分；数量与实际 features 自洽。
- 任何源失败/返回 null：HTTP 500，无私有错误泄漏、无部分成功。
- JSON 信封、geometry=null、只读 GET/POST 405；真实安全链仍须实测，无头的 standalone MockMvc 不作为免鉴权证据。

## 验收状态

- 提交 `33ca0b6`（feat(cockpit): add read-only facility geometry model，5 文件 +631 行）已推送 `origin/master`（`60a0e9a..33ca0b6`，快进）。
- 针对性测试 **22/22**：几何 Service 14、Controller 6（含真实 Service→MVC 非空 Point/LineString 序列化与事务异常脱敏 500 回归）、免鉴权配置 2。
- 全量 `*Cockpit*Test` **463/463**：在仅含 `33ca0b6` 的隔离副本（`implementation/t30/validation-checkout`）通过；主工作树因另一并行会话未提交的设施统计构造器改动无法编译测试，未动其工作。
- 实施中独立两轴审查发现并修复：事务代理异常绕过稳定失败响应（控制器局部 RuntimeException handler 统一脱敏 500）、合法非空几何缺实际 JSON 序列化回归（已补）。最终复核 Standards 0 / Spec 0，见[几何读模型最终审查](geometry-read-model-review.md)。
- MockMvc 为 standalone，不作为真实安全链证据；真实免鉴权 GET 验收（无 Authorization 只读请求）在 `192.168.110.96:8301` 实例加载 `33ca0b6` 后执行：探针 `implementation/t30/live-acceptance.py`（当前仍 404，实例未重启，结果落 `live-acceptance.json`）。
- 2026-10-12 本轮用户明确授权 Maven 测试（含编译）与由用户在 IDE 重启实例；未运行浏览器调试。