<!-- DSH-IDEMPOTENCY-KEY: t18-defect-facility-mapping -->
<!-- parentKey: 00 -->
# 20: 后端执行票 —— 管网编码 0/1 映射与设备边界设施类型命名空间


## 进度

已完成：主修复740d896现场复验通过；P2/P3补齐29d1ae2经复核并合入0a6b108推送；最终管网专项29/29。最新远端报警旁路存在1项全量失败，如实见审查报告，不属于本次管网交付。

Type: task
Status: resolved
Label: ready-for-agent
Category: backend-execution

## 来源

票 18 真实数据口径核对（2026-10-10），并由真人走查第 4 项佐证（界面设施总数 1001，实际 5268）。

## 状态

**已 resolved（2026-10-10 实施 / 2026-10-12 复验）**：诊断 + 2 项维护者裁定 + 实施 + 契约测试 + 变异检验 + 提交推送 + **真实环境复验七项全通过**。提交 `740d896` 已推 `origin/master`（`94971b5..740d896`）。验证：全量 8 模块 **439/439**（新增 17 例）+ 变异检验两处确认有牙齿。基线卡片：[管网编码 0/1 映射与命名空间隔离](../handoff/baselines/pipe-network-type-namespace.md)（**状态 ③**）。人工核验步骤：[人工核验步骤说明](../handoff/manual-verify-pipe-type-namespace.md)。

维护者 2026-10-12 重启后已做一次粗验，**未发现问题**；随后按人工核验说明完成核验，并明确要求提交推送。本轮记录依据维护者直接反馈，不额外推定整个真实联调阶段全部通过。逐项接口复验如下。

### 真实环境复验（2026-10-12，实例 PID 25880 @ 08:39:37 加载 `740d896`）

| 复验项 | 实测 | 期望 | 判定 |
| --- | --- | --- | --- |
| `base-archives` 管网计数 | 排水管线 **3735**、供水管线 **996**、燃气管线 **537**；合计 **5268** | `537+3735+996=5268` | **通过** |
| `base-archives` 排除统计 | `unknownTypeCount=0`，无「未分类管网」条目 | 0 | **通过** |
| 设施总数自洽 | `facilityCount=5278`（5268 管网+3 水厂+5 泵站+2 排水工程设施） | 修复前 1001 | **通过** |
| `overview/infrastructure` | `unknownTypeCount` **5268 → 0**；行业 GAS **537** / WATER_SUPPLY **1004** / DRAINAGE **3735** | 管网进入正式统计 | **通过** |
| `device-boundary` 命名空间 | 设施类型仅「燃气/供水/排水管线」三类；**无管网被标成「供水设备/排水设备/燃气设备」**；行业 gas **537** / waterSupply **996** / drainage **3735**；`unknownTypeCount=0` | 命名空间隔离 | **通过** |
| `management-information` | `unknownIndustryCount=0`；管网归未分区桶 DRAINAGE **3735** / GAS **537** / WATER_SUPPLY **998**（996 管网+2 水源地） | 全部纳入且不冒充片区 | **通过** |
| `operating-information` | `unknownIndustryCount=0`；管网长度指标燃气 **537** 条 / 供水 **996** 条 / 排水 **3735** 条 | 三组齐全 | **通过** |

**自洽校验**：各端点管网条数一致 = 537+996+3735 = **5268**，与真实库 `network_type` 分布精确吻合。

诊断手段：只读源码核实 + 真实库只读探针（凭据经环境变量注入，探针放 `%TEMP%` 用完即删）+ 联调环境 `http://192.168.110.96:8301` 实测。

## 现象

1. **管网数字编码漏计**：业务 GIS 既有规则为 `pipe_network_base.network_type` `0=燃气 / 1=排水 / 2=供水`（见 `zksy-admin` 的 GIS 控制器）。但基础档案、管理信息、运行信息、总体概览四个适配器只兼容 `2=供水`、`3=燃气` 与行业文字，`0`/`1` 被直接跳过。真实分组 `0=537、1=3735、2=996` → **4272 条管网未进入任何正式统计**。因过滤发生在适配器内，响应 `excluded=0` 不能作为完整性证据。
2. **设施类型命名空间误用**：设备边界只用 `equipment_type`（监测设备类型）建字典，却用同一编码去解释设施 `network_type`，导致真实 3735 条排水设施被标为「供水设备 / WATER_SUPPLY」、996 条供水设施被标为「排水设备 / DRAINAGE」。
3. **概览强制置空**：`overview/infrastructure` 把所有管网设施行业置 `null`，正式行业统计只得到 `8`（水厂 3 + 供水泵站 5），`excluded.unknownTypeCount=5268`。

## 诊断（2026-10-10）

诊断手段：只读源码核实 + 真实库只读探针（凭据走环境变量、探针放 `%TEMP%` 用完即删）。

### 后端基线

| 项 | 值 |
| --- | --- |
| 仓库 / 分支 / 提交 | `origin/master` / `master` / `d8a6b03`（票 13 收口后的基线） |
| 联调环境 | `http://192.168.110.96:8301` 可达 |

### 数据事实（真实库实测）

| 项 | 实测值 |
| --- | --- |
| `pipe_network_base.network_type` 分布 | `0`=537、`1`=3735、`2`=996，**总数 5268**（与票面声称一致） |
| 权威编码规则 | `GisController.getPipeLines` L43 注释与分支：**`0`=燃气、`1`=排水、`2`=供水**（另兼容 `gas/drainage/water` 等历史串） |
| `equipment_type` 主键命名空间 | id=`1`→**供水设备**、id=`2`→**排水设备**、id=`3`→燃气设备（parent 均为 0） |
| `network_type="3"` 实际存在？ | **不存在**（分布仅 `0/1/2`）；且生产代码无任何 `setNetworkType` 写入路径 |

### 现象逐条核实（票面三个现象均成立）

**现象 1 — 管网数字编码漏计（4272 条丢失）**：三处**各自复制**的映射函数都只认 `2`/`3` 与中文串，遇到 `0`/`1` 返回 `null`，调用方随即 `continue` 静默丢弃：

| 位置 | 函数 | 缺 `0`/`1` 的后果 |
| --- | --- | --- |
| `BusinessCockpitInfrastructureBaseArchivesAdapter.pipeType` L149 | 返回 `WATER_PIPE`/`GAS_PIPE`/`DRAINAGE_PIPE` | `addPipes` L123 `typeCode==null` → `continue`，5268 条只剩 996 条进入响应 |
| `BusinessCockpitInfrastructureManagementInformationAdapter.pipeIndustry` L154 | 返回行业码 | 4272 条 `industry=null` |
| `BusinessCockpitInfrastructureOperatingInformationAdapter.pipeIndustry` L191 | 返回行业码 | 4272 条 `industry=null` |

三份逻辑重复且同源同错——这正是「单一权威来源」要消除的对象。

**现象 2 — 命名空间碰撞（类型名与行业系统性错位）**：`BusinessCockpitDeviceBoundaryAdapter` L85 把**原始 `network_type`** 当作设施类型码上报，服务层 `mapFacility` L78 用 `types.get(...)` 去查 **`equipment_type` 字典**。两套编码数值域重叠而语义不同，于是：

| `network_type` | 真实含义 | 误查 `equipment_type` | 对外结果 |
| --- | --- | --- | --- |
| `1` | 排水（**3735 条**） | id=1 = 供水设备 | 被标「供水设备 / WATER_SUPPLY」 |
| `2` | 供水（**996 条**） | id=2 = 排水设备 | 被标「排水设备 / DRAINAGE」 |
| `0` | 燃气（537 条） | 无 id=0 | 类型解析失败 → `UNKNOWN_TYPE` |

适配器类注释 L29-30 声称「管网设施 `network_type` 是自由文本、与 `equipment_type.id` 无对应关系」——**该前提为假**：它不是自由文本，而是有权威编码的字段；「无对应关系」被误实现为「透传原始码」，结果不是隔离而是碰撞。

**现象 3 — 概览强制置空**：`BusinessCockpitOverviewInfrastructureAdapter` L123 构造设施 `SourceType(code, name, industry, drainageScope, objectKind)` 时传 `industry=null, drainageScope=null`，5268 条管网全部落入非正式范围，正式行业统计只剩水厂 3 + 泵站 5。

### 修复方向（单一权威来源）

新增单源持有**管网命名空间**的类型码 / 中文名 / 行业，四处适配器共用；设备边界的设施类型改用该命名空间（不再借用 `equipment_type` 主键），未识别值仍显式 `null` 计入 `UNKNOWN_TYPE`，不静默丢弃。

## 待裁定问题（已裁定，2026-10-10）

1. ~~**设备边界的设施类型身份如何表示**~~ —— **裁定：设施改用管网命名空间码**（`GAS_PIPE/WATER_PIPE/DRAINAGE_PIPE`，由适配器注入、`objectKind=FACILITY`），与 `equipment_type` 主键彻底隔离。
2. ~~**旧映射 `"3"`→燃气 如何处置**~~ —— **裁定：删除**，严格执行 GIS 权威规则 `0/1/2`；外部若真写入 `3`，归未识别并计入 `unknownTypeCount`。

## 维护者裁定（2026-10-10）

1. **命名空间隔离方式**：设施类型改用管网命名空间码（`GAS_PIPE/WATER_PIPE/DRAINAGE_PIPE`，与 base-archives 既有字典一致），由适配器注入这三条 `SourceType`（`objectKind=FACILITY`）；不再借用 `equipment_type` 主键，也不再两套命名空间共用一张 map。
2. **旧映射 `"3"`**：**删除**，严格执行 GIS 权威规则 `0/1/2`；若外部真写入 `3`，归未识别（`industry=null`、计入 `unknownTypeCount`），不静默丢弃。

## 实施结果（2026-10-10）

共 13 个文件（1 新增主类 + 3 新增测试 + 9 修改）：

| 交付 | 内容 |
| --- | --- |
| **单一权威来源** | 新增 `cockpit/foundation/CockpitPipeNetworkType`（仿票 12 的 `CockpitDistrict`）：类型码/中文名/行业三合一，覆盖 `0/1/2` 与历史串；无法映射归非空哨兵 `PIPE_UNCLASSIFIED` |
| **base-archives** | 删本地 `pipeType()`；`0/1/2` 全部解析，不再因未知而丢弃 |
| **management** | 删本地 `pipeIndustry()`；行业为空时交由服务层 `unknownIndustryCount` 计数，不再提前 `continue` |
| **operating** | 删本地 `pipeIndustry()`；同上；另加固 `metricCode` 对 null 行业用 `unknown_` 前缀（原先会 NPE） |
| **overview** | 设施 `SourceType` 行业改由单源给出（原先恒 `null`，致 5268 条管网被计入 `excluded.unknownTypeCount`） |
| **device-boundary** | 注入 3 条管网类型（`objectKind=FACILITY`）；设施类型码改为解析后的管网命名空间码；改正错误的类注释（原文称 `network_type` 为自由文本且与 `equipment_type.id` 无对应关系——该前提为假） |

**契约零变更**：四个服务的 `excluded` 承接逻辑本就存在（base-archives/overview/device-boundary 的 `unknownTypeCount`，management/operating 的 `unknownIndustryCount`），是适配器提前 `continue` 让它们恒为 0；修复后自然生效。

**对抗式自查**：发现并补上「服务层贯通」覆盖缺口——现象 2 的错误表现发生在响应层，而控制器测试用 mock 适配器测不到，故新增 `CockpitDeviceBoundaryPipeIndustryTest`（真实适配器 + 真实服务，只 mock 数据源）。变异检验两处均确认测试有牙齿（还原隔离后精确复现「排水设施→供水设备」等 7 例转红；还原概览行业后 1 例转红），还原后复跑全量 439/439。

## 复验项（已完成，2026-10-12）

- `base-archives` 管网计数覆盖 `537+3735+996=5268` —— **实测 5268 ✓**
- `overview/infrastructure` 的 `excluded.unknownTypeCount` 不再是 5268 —— **实测 0 ✓**
- 设备边界设施类型名为「燃气/供水/排水管线」、行业正确 —— **实测正确，无「…设备」冒充 ✓**
- 票 18 真人走查第 4 项（界面设施总数 1001）—— 后端口径已回归 5278；界面层复跑步骤见[人工核验步骤说明](../handoff/manual-verify-pipe-type-namespace.md)，由维护者按步骤确认后回写

**遗留（不阻塞本票）**：票 18 的**界面**走查尚未逐项复跑；本票后端契约层已达成 ③。

## 范围

1. 建立管网设施类型与行业的**单一权威来源**，与既有 GIS 规则一致，覆盖 `0/1/2` 与历史字符串。
2. 修正基础档案、管理信息、运行信息、总体概览四个适配器的映射与行业归属，不再静默 `continue`。
3. 修正设备边界的设施类型解析：设施不得借用监测设备类型字典。
4. 保留口径差异说明：`base-archives`（水厂／泵站／管网／排水工程设施）与 `management`（窨井／管网／水源地）本属不同对象域，但两者都必须包含全部管网。
5. 补契约测试：四行业管网各自计数正确、`0/1/2` 不再丢失、跨端点管网总量一致。

## 验收

真实环境复验：`base-archives` 管网计数应覆盖 `537+3735+996`；概览不再把管网整体排除；设备边界设施类型名称与行业正确。编译 + `Cockpit*Test` 全绿 + 提交推送 + 基线卡片更新。

## 关联

发现于票 18；与票 25 后端契约缺口台账同源，需回写。

## 审查补齐（2026-10-12）

独立规范轴未发现阻塞；规格轴发现 P2 跨端点同源回归测试缺失与 P3 基础档案展示字典重复定义，已补齐。五端点测试贯通真实适配器与服务，正常编码／历史字符串及 `3/99/null` 未知值两组均通过；基础档案直接从共享字典读取名称、行业和类型码。同步远端前全量 `zksy-system` **187/187** + `zksy-admin` **441/441**，合计 **628 项**、零失败。整合远端报警描述更新后，报警生命周期顺序断言出现 1 项失败（相关源码与测试与远端一致，本次未改）；整合后的管网专项 **29/29** 通过，不能声称当前整合树全量通过。补齐 `29d1ae2` 与合并 `0a6b108` 已推送。此前“439/439 全量”是管理端模块小计，不是 reactor 合计。

人工说明已更正：前端页面地址与后端 8301 分离，先确认 real 与清空筛选；基础档案 5278、概览 5276、管理信息 5273 是不同对象域；管理信息有 3 处窨井；设备边界清单与 excluded 可在接口响应中核对，不能假设有独立页面；管网长度原始单位是 m。详见[审查报告](../handoff/review-pipe-type-namespace.md)和[人工核验步骤](../handoff/manual-verify-pipe-type-namespace.md)。

## Comments


### local — 2026-10-12T01:13:59.786Z
2026-10-12 收尾审查发现两项规格完整性缺口，暂重开补齐：跨端点同源数据契约测试缺失（P2）；基础档案管网名称/行业仍重复定义（P3）。现场五端点统计已正确，无已知线上映射错误。

### local — 2026-10-12T01:28:41.238Z
收尾审查已完成。规范轴无发现；规格轴 P2 五端点同源真实适配器+服务回归测试、P3 基础档案类型码/名称/行业单源均已补齐，再次只读复核无新增阻塞。补齐29d1ae2、合并0a6b108已推送。同步远端前system187+admin441=628项全过；同步远端报警描述更新后出现一个AlarmLifecycleServiceTest顺序断言失败，相关源码和测试与远端一致，本次未改；整合后的管网专项29/29通过。现场主修复740d896的五端点统计均正确。审查报告与人工核验步骤已提供；界面阶段结论归真实接口联调与阶段收口。


## Answer

管网行业与设施命名空间修复已交付：主修复 `740d896`，审查补齐 `29d1ae2`，整合 `0a6b108` 均已推送。已部署主修复现场五端点管网集合一致为燃气537／供水996／排水3735（5268），未知计数归零、设施名称正确；P2跨端点回归与P3显示单源均已补齐并复核。同步远端前628项通过，整合后管网专项29/29通过；最新远端报警生命周期存在1项全量失败，未在本次管网审查扩展修复，详见审查报告。人工核验说明已交付，完整界面阶段验收仍归真实接口联调与阶段收口票。