#63 BT-5 真实数据接线（程序级）

来源：前端驾驶舱 tracker 票 25「后端契约缺口待办」交付包（handoff/backend-contract-gaps.md，2026-09-18 复核）。完整上下文见该交付包。

背景与证据：23 个 cockpit 适配器接口中 22 个只装配了 Empty*Adapter（@Service，直接返回 ...Snapshot.empty(...)）；唯一接入真实数据的是工单读模型 BusinessCockpitWorkOrderReadAdapter（@Primary）。各切片 docs/cockpit/*-demo.html 用的是内嵌 fixtures，不代表真实库数据。（计数口径：若不计 /foundation 契约自检，则为 22 个读模型接口 / 21 个空实现。）

要做什么：按切片补真实适配器（复用既有表与服务，遵循 cockpit-backend-read-contracts spec 的「先组合既有表与服务，测量后再加投影/索引」）。建议优先级：先地图与监测链路（map-snapshot、monitoring/distribution、monitoring/overview、monitoring/situation、monitoring-points/{code}），再基础设施三切片，最后预警处置四切片（其中工单链路已接）。

验收标准：每个切片存在非空适配器并被 Spring 装配；用真实库跑通 docs/cockpit/README.md 第 6 节的联调检查表 1–7；snapshotAt 分页稳定、监测点不重复；空结果仍走 200 + freshness.state=EMPTY，不用 5xx 表达空。

解除阻塞：所有前端票「接真实接口」的环节（mock 阶段不受阻）。

诊断（2026-09-18）

认领声明：Gogs 指派接口对本账号无效（同 #60–#62），以本评论声明认领。

阶段判定：未动工——无实施记录、无进度区、无评论，带 needs-triage → 先诊断（本评论）。

一、复现：契约已冻结，数据未接线

• 22 个适配器接口只有 Empty*Adapter（返回 ...Snapshot.empty(...)）；唯一真实适配器是 BusinessCockpitWorkOrderReadAdapter（@Primary）。
• 规模量化：22 个适配器 / 34 个接口方法 / 395 个快照字段；验收还要求「用真实库跑通 docs/cockpit/README.md 第 6 节联调检查表 1–7」。

二、环境核查（本轮新增，决定本票可执行性）

• Nacos 配置中心可达，pipe-network-service-dev.yaml 可读。
• 真实数据源是 KingBase（人大金仓）：jdbc:kingbase8://192.168.110.30:54321/pipi_ner?currentSchema=app_user（不是 MySQL）；kingbase8-8.6.0 驱动已在本地 Maven 仓库。
• 只读 JDBC 探查成功：app_user 下 120 张表，契约相关表齐全。
• 关键表计数：equipment_base=37、monitor_point=7、equipment_point_rel=20、equipment_status=22、equipment_type=20、early_warning=29、alarm_data=507、alarm_warning_rel=3、work_order=19。

结论：本票技术前提具备（连得上、有数据、驱动在）。

三、真实数据质量问题（实测，直接影响验收）

1. 设备→点位回联在真实库上极稀疏：equipment_point_rel 20 行中 10 行已逻辑删除，有效行仅 3 条能 Join 到未删除的 monitor_point（覆盖 2 个点位）→ BT-1 (#59) 的 deviceCodes/WS monitoringPointCode 接线后近乎全空。这是数据缺口，不是代码缺陷。
2. monitor_point 无行业列：行业只能由 equipment_type.parent_type_id 推导（1=供水、2=排水、3=燃气、4=窨井）；point_type/status 混用中英文（泄漏检测 vs GAS；正常/预警 vs ACTIVE）。
3. 窨井不在冻结的正式行业里：契约正式行业只有 GAS/WATER_SUPPLY/DRAINAGE，而 equipment_type 有独立根 manhole（parent=4）→ 按现有口径窨井设备会被判非正式行业而排除。属契约/业务缺口，需裁定。
4. 工单状态出现字典外的 0（4 条）：冻结七态为 1–7；既有适配器把越界码收敛为 7（已取消），真实数据的 0 会被映射成「已取消」，是否符合业务需确认。
5. pipe_network_base 大量逻辑删除（样例 del_flag=2），network_type 为数字；monitor_point.network_id 实测关联不上该表（network_code/network_name 全 null）。

四、方案（分片优先级，沿用交付包建议）

1. 地图与监测链路：map-snapshot、monitoring/distribution、monitoring/overview、monitoring/situation、monitoring-points/{code}——决定「一张图」能否出真实点位。
2. 基础设施四切片：base-archives、operating-information、management-information、emergency-support。
3. 预警处置四切片：events/current、history-analysis、handling-efficiency、multidimensional-analysis（工单链路已接）。
4. 其它：overview/*、type-metrics、freshness、foundation、event-read、equipment-archive、detail-aggregate。

每切片工作量 = 真实表/服务组合 + 字段映射 + 空值口径 + 契约测试 + 联调检查项，并须处理第 3 节的数据质量问题。

五、需要裁定（HITL）

本票验收是「全部切片刻非空适配器 + 真实库跑通检查表 1–7」，规模为程序级、跨多次会话，单会话无法诚实完成。需裁定本轮做到哪一层（可选项见下），我按裁定执行并如实记进度。

进度：0% → 诊断完成

诊断完成（环境、数据面、规模、数据质量四类事实均已实测）。下一步：等待范围裁定，再摘 needs-triage 进入实施。

诊断（2026-09-18）

认领声明：Gogs 指派接口对本账号无效（同 #60/#61/#62，多参数变体均 {"ok":true} 不落库），以本评论声明认领。

阶段判定：未动工——无实施记录、无进度区、无评论，带 needs-triage → 先诊断（本评论），摘标签后进入实施。

复现（三条）

1. 22 个 cockpit 适配器接口全部只装配 Empty*Adapter（@Service/@Component，返回 ...Snapshot.empty(...)）：MapSnapshot、MonitoringDistribution/Overview/Situation、MonitoringPointDetail、CurrentEvents、HistoryAnalysis、HandlingEfficiency、MultidimensionalAnalysis、Infrastructure{BaseArchives,OperatingInformation,ManagementInformation,EmergencySupport}、Overview{Infrastructure,Monitoring,WarningSettings}、TypeMetrics、EquipmentArchive、EventRead、Freshness、Foundation、DeviceBoundary 等。
2. 唯一接入真实数据的是工单读模型 BusinessCockpitWorkOrderReadAdapter（@Primary，覆盖同名 Empty 实现）。
3. 因此前端把适配层切到真实接口后拿到的是全空快照（200 + freshness.state=EMPTY），契约已冻结、数据未接线。

根因

契约阶段刻意只交付「契约 + 空适配器 + demo」，把真实数据留在适配器 seam 之后（spec 约定「先组合既有表与服务，测量后再加投影/索引」）。本票就是补上这 22 个 seam 的真实实现。

环境与数据面（本轮只读实测，非推测）

• Nacos 配置中心可达（192.168.110.30:8848），pipe-network-service-dev.yaml 可读。
• 真实数据源是 KingBase（人大金仓）：jdbc:kingbase8://192.168.110.30:54321/pipi_ner?currentSchema=app_user，驱动 kingbase8-8.6.0 本地可用。不是 MySQL（3306 通但不是本库，容易踩错）。
• app_user 下 120 张表，契约相关表齐全且有数据：equipment_base=37、equipment_status=22、monitor_point=7、equipment_point_rel=20、equipment_type=20、early_warning=29、alarm_data=507、alarm_warning_rel=3、work_order=19、pipe_network_base=5269、manhole_base=4、manhole_device_rel=6。

真实数据与契约的对齐情况（决定各切片可行性与口径）

可用：

• 设备台账 equipment_base.equipment_code 与 alarm_data.device_code 完全匹配（23/23）；early_warning.device_code 部分填充（12/29，匹配 4/4）。
• 设备状态 equipment_status 与台账可关联 22 条，提供 current_status/alarm_status/online_status，足以支撑点位六态裁决。
• 在途工单（order_status 1–5）可按 device_code 关联，支撑点位 WORK_ORDER 态。

必须写死口径或降级的坑（真实数据质量，非代码缺陷）：

• 行业无独立列：monitor_point 没有行业字段，只能由 equipment_type.parent_type_id 推导（1=water_supply、2=drainage、3=gas、4=manhole）。
• 中英文混用：monitor_point.status 同时存在 正常/预警 与 ACTIVE；point_type 同时存在 泄漏检测/压力监测/水质监测 与 GAS/PRESSURE。映射需显式列出已知取值，未知值不得静默归类。
• 设备→点位回联在真实库上极少：equipment_point_rel 20 行中 10 行 del_flag=2（逻辑删除），有效行仅 3 条能 Join 到未删除点位（覆盖 2/7 个点位）。→ BT-1（#59）刚交付的 deviceCodes 与 WS monitoringPointCode 在真实数据下近乎全空。这是数据缺口，不是响应层 bug。
• 工单状态越界：work_order.order_status 出现字典外取值 0（4 条）。冻结七态是 1–7；既有适配器用 byLegacyCode 把越界码收敛为 7（已取消）。映射口径需确认（建议：显式记为越界，不冒充已取消）。
• pipe_network_base 大量逻辑删除（样例 del_flag=2），network_type 是数字；monitor_point.network_id 实测关联不上该表（network_code/network_name 全为 null）→ 区域/管线维度暂无可靠来源。
• 坐标脏数据：monitor_point 中 JK03、RQJCD01 经纬度为 null，JC001 为 (12,12)；manhole_base 为 (1212,1212)/(12,12)。按冻结字典一律 renderable=false（MISSING_*/INVALID），即不可上图——这是字典要求的正确行为，不是缺陷。
• 窨井不在冻结的正式行业里：契约正式行业只有 GAS/WATER_SUPPLY/DRAINAGE，而 equipment_type 有独立根 manhole（parent=4）且 manhole_base/manhole_device_rel 是独立域（cockpit 包内无窨井语义）。→ 窨井设备按现有口径会被判「非正式行业」而排除，但前端行业筛选（ADR 0002）里有「井盖」项。属契约/业务缺口。

规模（本票为何是「程序级」）

22 个适配器、34 个接口方法、395 个快照字段需要从真实表组合映射；验收还要求「用真实库跑通 docs/cockpit/README.md 第 6 节联调检查表 1–7」，并保持 snapshotAt 分页稳定、监测点不重复、空结果走 200 + EMPTY。

建议的分片优先级（来自交付包 §二，按解除阻塞收益排序）：

1. 地图与监测链路：map-snapshot、monitoring/distribution、monitoring/overview、monitoring/situation、monitoring-points/{code}；
2. 基础设施四切片：base-archives、operating-information、management-information、emergency-support；
3. 预警处置四切片：events/current、history-analysis、handling-efficiency、multidimensional-analysis（工单链路已接）；
4. 其余：overview/*、type-metrics、freshness、foundation、event-read、equipment-archive、detail-aggregate。

验收自查计划（分片落地时逐片执行）

• 每片：真实适配器 + @Primary 装配 + 契约测试保持全绿 + 至少一项真实库联调证据（真实行数/字段抽查），并覆盖空表/脏坐标/非法枚举等降级路径。
• 数据缺口（如设备→点位关联仅 3 条）以如实返回空/null + 不臆造为准，不得用假数据填充。

进度：0%

诊断完成（复现、根因、环境与数据面、坑与规模已实测）。下一步：摘 needs-triage → 按分片优先级逐片接线 → 逐片留真实库证据。

实施记录（2026-09-18，第 1 片：map-snapshot 纵向样板）

范围：按裁定「纵向样板」交付 map-snapshot 一片的真实数据适配器，为余下 21 片立模板。本票不改 22 片全接，未完成部分如实记进度、不关票。

改动

• 新增 BusinessCockpitMapSnapshotAdapter（@Component + @Primary，覆盖 EmptyCockpitMapSnapshotAdapter），组合现网既有表与服务，不新增表、不加投影：
  • 点位 monitor_point（@TableLogic 自动过滤 del_flag）；
  • 点位→设备 equipment_point_rel（经既有 EquipmentBaseService.getEquipmentByPoint）；
  • 设备状态 equipment_status（在线/报警）；
  • 预警 early_warning（未关闭视为预警中）；
  • 在途工单 work_order；
  • 类型字典 equipment_type（行业由 parent_type_id 根推导：1 供水、2 排水、3 燃气、4 窨井）。
• 适配器复用既有 CockpitMapSnapshotService 的过滤/分页/mapFilter/坐标校验逻辑，不改契约层（BT-1…BT-4 的成果原样保留）。

验收自查（对抗式）

真实库实测数据（只读，凭据未落盘/未回显）

• 点位 7 个；带设备点位 2 个（Z-RQXLJC01=1、Z-RQYLJC01=2）；其余 5 个点位无有效关联（JK03/RQJC01/RQJCD01/JC001/JC002）。
• 设备台账 37 台，其中已关联 3 台、未关联 34 台。
• 设备状态：报警 5 台、离线 1 台。

本轮实测出的真实数据缺口（阻塞后续切片，需数据侧处理）

1. 设备→点位关联极稀疏：equipment_point_rel 有效行中仅 3 条能联到未删除点位（覆盖 2/7 点位）→ BT-1（#59）的 deviceCodes/WS monitoringPointCode 在真实数据下近乎全空。属数据缺口，代码已如实返回，不臆造。
2. 现网无「坐标已校核」字段：适配器一律按未校核上报 → 按冻结字典全部 renderable=false（不上图）。这是字典要求，不是缺陷；若业务要上图，需数据侧补校核标志或明确「默认已校核」口径（需裁定）。
3. monitor_point 无行业/类型列：点位 typeCode 只能在其关联设备类型唯一时推导，多类型或零设备时为 null。
4. 中英文脏值：monitor_point.status 混用 正常/预警 与 ACTIVE；point_type 混用中文与 GAS/PRESSURE。本片不读该列做状态裁决（状态由设备事实推导），故不受影响；后续切片若需该列须显式列出取值。
5. 工单状态值域不一致：现网 work_order.order_status 为 0-based（0 待派单 … 5 已结案、7 已取消），cockpit 冻结字典是 1-based（1–7）。本片只判「是否在途」（0–6 视为在途），不冒充冻结字典；跨端对齐需裁定。
6. 窨井（井盖）缺契约位：真实库有独立 manhole_base（3 条有效）+ manhole_device_rel（6 条有效），equipment_type 有独立根 manhole(4)；但 cockpit 正式行业枚举只有 GAS/WATER_SUPPLY/DRAINAGE，而前端筛选有「井盖」项（ADR 0002）。本片已把窨井根映射为 MANHOLE 并传入类型字典，但契约枚举未含该值 → 需后端负责人裁定是否扩枚举（BT-2 #60 的 industry 契约会被影响）。
7. 窨井坐标脏：manhole_base 坐标为 (1212,1212)/(12,12)，按字典必判 INVALID（不上图）。

未完成（本票不关）

余下 21 片仍未接线，按建议优先级分片推进：

1. 地图与监测链路剩余 4 片：monitoring/distribution、monitoring/overview、monitoring/situation、monitoring-points/{code}；
2. 基础设施 4 片；3. 预警处置 4 片（工单已接）；4. 其余 9 片。

进度：5%（约 1/22 片）

按裁定完成第 1 片（map-snapshot 真实适配器 + 4 例新测试 + 真实库端到端证据）。余 21 片未接线，不满足本票「每个切片存在非空适配器」的验收，故不 close；进度按片数记约 5%。

下一步：按分片优先级继续（下一片建议 monitoring/distribution，与 map-snapshot 共用点位/设备/类型链路，边际成本最低）；并请裁定上文第 2、5、6 项口径。

实施记录（2026-09-18，第 2 片：monitoring/distribution）

范围：按裁定继续「纵向样板」推进，本片交付 monitoring/distribution 真实数据适配器（第 2/22 片）。本票仍不关。

改动

• 抽共享组件（防两片漂移）：
  • BusinessCockpitDeviceFactResolver（com.zksy.cockpit.point）：从 equipment_status + early_warning + work_order 组合「单台设备实时事实」（在线/报警/预警/在途工单 + 原因 + 状态时间）。缺状态按离线、状态/工单取值大小写/值域均已固化口径。
  • CockpitTypeIndustry（com.zksy.cockpit.foundation）：类型根 → 行业（1 供水、2 排水、3 燃气、4 窨井）；窨井映射为 MANHOLE 传值交服务层判「非正式行业」，不在适配器吞掉。
• BusinessCockpitMapSnapshotAdapter 重构为复用上述共享组件，去掉内联的设备事实推导（行为不变）。
• 新增 BusinessCockpitMonitoringDistributionAdapter（@Primary，覆盖 EmptyCockpitMonitoringDistributionAdapter），与地图快照同构图：monitor_point + equipment_point_rel + equipment_base + equipment_type；分布的未关联智能设备额外携带设备事实字段。

验收自查（对抗式）

本片修正/固化的事实

• 工单在途判定修正：现网 order_status 是 0-based，上一片把「在途」写成 0..6，其中 5=已结案 误判为在途。本片修正为「0..4 或 6（延期中）在途；5 已结案、7 已取消为终态」，并补断言防回归。
• 设备 typeName 修正：equipment_base.equipmentTypeName 是非库列（@TableField(exist=false)）恒为 null，上片直接取它导致设备类型名为空。本片改为从 equipment_type 字典按 equipmentTypeId 解析。

仍未完成（本票不关）

余 20 片未接线。按优先级继续：地图与监测链路还剩 monitoring/overview、monitoring/situation、monitoring-points/{code}；再基础设施 4 片；再预警处置 4 片；其余 9 片。

进度：9%（约 2/22 片）

已交付 2/22 片（map-snapshot + monitoring/distribution）。余 20 片未接线，不满足「每个切片存在非空适配器」验收，故不 close。

下一步：monitoring/overview 或 monitoring/situation（复用同一构图与共享组件，边际成本低）。

实施记录（2026-09-18，第 3、4 片：monitoring/overview + monitoring/situation）

范围：按裁定继续纵向推进，本片交付 monitoring/overview 与 monitoring/situation 两个真实数据适配器（第 3、4/22 片）。本票仍不关。

改动

• 新增 BusinessCockpitMonitoringOverviewAdapter（@Primary）：equipment_base + equipment_status.online_status + equipment_point_rel + monitor_point + equipment_type。
  • monitoringState 由现网可得事实映射：有状态且在线→ONLINE、有状态但离线→OFFLINE、无状态记录→UNKNOWN；绝不伪造 STALE（现网无样本新鲜度依据），sampledAt 取状态更新时间、缺失即 null。
  • 设备→点位归属沿用现网有效关联；点位类型仅在其关联设备类型唯一时推导。
• 新增 BusinessCockpitMonitoringSituationAdapter（@Primary）：设备指标态 + 两类事件。
  • 指标态优先序：缺状态→UNKNOWN、离线→OFFLINE、报警→ALARM、预警中→WARNING、其余→NORMAL；不产生 EXPIRED（无样本新鲜度依据）。
  • 预警←early_warning、报警←alarm_data，两列分池不混。
  • 事件的 typeCode/industry 一律经 device_code → equipment_base → equipment_type 反查（一次建索引，避免 N+1）。

本轮实测到的关键脏值（决定了上面的反查设计）

• 现网 alarm_data.device_type（流量监测/environment/flammable-gas）与 early_warning.warning_type（GAS_PIPE/WATER_PIPE/MANHOLE）都是描述性字符串，不是 equipment_type.type_id。若直接当 typeCode 用，服务层类型字典会全部落空（判定为空快照）。
• 事件时间用 alarm_time/publish_time，统一转成带偏移 ISO 串供服务层入趋势桶。

验收自查（对抗式）

本轮新暴露的真实数据缺口（需数据侧处理）

• 事件与设备台账严重脱节：507 条报警中仅 51 条的 device_code 能在 equipment_base 匹配到类型（29 条预警中仅 5 条）。其余事件因查不到类型，服务层会按「未知类型」计入 excluded 而不上分布/趋势。这不是响应层缺陷，是事件表的设备编码与设备台账不一致。
• 15/37 台设备无 equipment_status 记录 → 概览计入 UNKNOWN、概况计入 UNKNOWN。按契约这正确（不冒充离线），但也意味着在线率分母偏小。

仍未完成（本票不关）

余 18 片未接线。地图与监测链路还剩 monitoring-points/{code}，然后基础设施 4 片、预警处置 4 片、其余 9 片。

进度：18%（约 4/22 片）

已交付 4/22 片（map-snapshot、distribution、overview、situation）。余 18 片未接线，不满足「每个切片存在非空适配器」验收，故不 close。

下一步：monitoring-points/{code}（点位详情，收尾地图与监测链路后再进基础设施片）。

需求重建记录（2026-09-24，本轮不改代码）

本轮按 /ask-matt 路由执行「现状重建 + domain/context/spec/issue 同步」，没有修改 Java/SQL 代码，也没有把历史接线进度继续累加。当前代码、当前 KingbaseES schema、当前领域模型取代 2026-09-18 以前的接线假设。

一、代码基线已发生破坏性变化

• equipment_type 当前实体/表字段是 id、type_name、parent_id；旧 type_id、parent_type_id 已不存在。此前 4 片适配器与 CockpitTypeIndustry 仍调用 getTypeId()/getParentTypeId()，当前 zksy-system 编译失败。
• work_order 当前只有 device_id 作为设备关联，不再有 device_code、alarm_id、case_id、hazard_id；报警转工单关系是 alarm_data.order_id → work_order.order_id。BusinessCockpitWorkOrderReadAdapter 已部分切到新关系，但共享 BusinessCockpitDeviceFactResolver 仍调用已删除的 WorkOrder::getDeviceCode()，当前同样阻断编译。
• 当前运行时工单编码以 WorkOrderStatusEnum 为准：0 待派单 / 1 待接单 / 2 已接单 / 3 处理中 / 4 待验收 / 5 已结案 / 6 延期中 / 7 已取消；终态 5/7，6 是处理旁路。旧 ADR-0008「从 1 开始七态」不能作为当前数据库编码。

二、当前 KingbaseES 只读实测（app_user）

当前真实库不是此前记录的旧测试快照，核心行数为：

当前真实样例：

• work_order.order_id=271、device_id 指向设备 21119740，对应 alarm_data.order_id=271；这是当前报警→工单的可验证链路。
• 当前 equipment_type 是纯层级模型（id/type_name/parent_id），不再提供稳定 slug；公开 cockpit typeCode/行业推导仍需需求裁定与重新设计。
• 当前点位关联表虽然有 10 条有效关系，但与当前 2 台设备均未匹配；不能继续引用上一轮「3 条有效关联、37 台设备」的结论。

三、需求重新确认项（本轮只记录，不替用户裁定）

1. 公开类型编码：当前类型表没有旧 type_id。需决定 cockpit typeCode 是使用 equipment_type.id 的字符串、另建稳定业务编码，还是暂时返回 null 并以 typeName 展示；所有 map/monitoring/events 适配器必须统一。
2. 工单读取链路：设备工单必须走 work_order.device_id → equipment_base.equipment_id → equipment_code；报警工单必须走 alarm_data.order_id → work_order.order_id；预警工单必须经 alarm_warning_rel → alarm_data → order_id。不得恢复对已删除 work_order.device_code 的查询。
3. 真实数据稀疏是否可接受：当前只有 2 台设备、1 条关联工单、3 条报警、35 条预警；不能把空结果当代码失败，也不能用 fixtures 填充真实适配器。
4. 井盖行业：数据库仍有 equipment_type.id=4「窨井设备」与 parent_id=4 的窨井监测类型，但当前正式 cockpit 行业枚举仍只有 GAS/WATER_SUPPLY/DRAINAGE；前端「井盖」与后端枚举的冲突仍待裁定。
5. 坐标校核：当前数据库仍没有 coordinateVerified 字段；null/异常坐标与默认未校核口径需在真实接线前明确。

四、当前验收状态

• 历史第八至第十轮记录的「BT-5 4/22 片已接线」不再是当前可验收状态：本轮编译检查已证明类型模型/工单模型重构后，适配器代码未同步完成。
• 当前 #63 进入需求重建/重新诊断，进度回到 0%（等待新基线与口径确认）；不关闭、不宣称已有适配器通过真实库验收。
• 下一步前置：确认 typeCode 方案与工单关系规则，修复/重写适配器以符合当前实体模型，再重新跑 compile、contract tests 与当前 KingbaseES 联调检查表。

进度：0%（需求基线重建完成，代码未修改）

需求裁定补记（2026-09-24，本轮仍不修改代码）

已确认并回写 CONTEXT.md、spec.md、docs/cockpit/README.md：

1. 公开 typeCode 使用当前 equipment_type.id，在 JSON 边界序列化为字符串；type_name 是展示名，旧 type_id/parent_type_id 不再使用。
2. 井盖为第四正式行业 MANHOLE，与当前类型树独立根和前端筛选项对齐；目前服务层仍只允许三行业，此为待实现的跨端契约变化，不宣称当前可用。
3. 坐标校核按最小修改原则复用既有 CockpitCoordinateValidator：无可信校核来源时 coordinateVerified=false、renderable=false。通用经纬度范围会放过 (12,12)，不能替代业务校核；区域自动校核需先有权威边界/CRS 来源。
4. BT-5 联调以当前 KingbaseES 真实数据为基准，不用人工编造业务行填非空；稀疏关联场景需如实验收并标注未覆盖的场景。
5. 工单运行时以 WorkOrderStatusEnum/ADR-0010 的 0–7 为准；对 app_user.sys_dict_type/sys_dict_data 的只读检查未发现工单状态字典条目。用户提到的字典表还未定位，故数据库字典一致性不能标记为已核对。

进度：0%（需求基线重建，字典来源待定位；代码未改）

下一步：定位工单状态字典来源/表名并确认其值；随后才将本票从 needs-triage 转为可执行，修复当前编译、实现新类型/行业映射并以当前库重新联调。

工单字典来源确认（2026-09-24）

人类澄清：“工单字典”指当前代码中的 WorkOrderStatusEnum，不是独立数据库字典表。枚举与 ADR-0010 确认 0 待派单 / 1 待接单 / 2 已接单 / 3 处理中 / 4 待验收 / 5 已结案 / 6 延期中 / 7 已取消；终态 5/7。app_user.sys_dict_type/sys_dict_data 未发现工单状态条目符合该解释，不再作为未决阻塞。

其余需求裁定不变：公开 typeCode 使用当前 equipment_type.id（JSON 字符串）；井盖扩为第四正式行业 MANHOLE；无可信坐标校核来源时 renderable=false；以当前真实 KingbaseES 数据联调且不编造业务行。

本轮仅同步文档，不修改代码。#63 仍处于 needs-triage，当前工作树编译失败，历史 4/22 接线不可作为验收。

进度：0%（需求口径已确认，待实现基线重建）

BT-5 实施/验收更新（2026-09-28）

已完成并推送：

• 54dd693：基础设施概览接入水厂、按 station_type 隔离的供水/排水泵站，修正当前 Kingbase schema 的 monitor_point / equipment_point_rel 映射及关联查询；设施总量与智能设备总量分离。
• 前序快照提交已补齐 Redis 跨实例共享、10 分钟窗口、TTL 舍入、加载中/返回前过期重校验、canonical deviceCode 和同 snapshotAt 详情一致性。
• README 已更新；长期记忆已同步当前 0..7 工单状态和验收边界。

验证：

• mvn -pl zksy-admin -am test -DfailIfNoTests=false -q 全量通过。
• 本机 127.0.0.1:8301 当前 Kingbase 实例真实登录态：未认证 401 UNAUTHORIZED；非法参数 400 INVALID_REQUEST；地图同一 snapshotAt 5 页、total=15 稳定且点位不重复；点位详情及 archive / metrics / events / work-orders / detail-aggregate / freshness 均 200 且只读；概览、基础设施、监测、事件、自检端点均 200 且只读。
• 浏览器 WebSocket /ws/deviceStatus 发送 cockpitSubscribe(scope=all) 后收到 cockpitSubscribed 和 serverUpdatedAt；抽查时间戳为 +08:00。

边界：192.168.110.30:8301 部署端口仍不可达，因此本评论不把它当作 HTTP 证据。Issue #63 保持开启，不在本轮关闭。

补充说明：5ce0458 已修复快照 token 必须为 +08:00、Redis/缓存故障返回 SERVER_ERROR、本地缓存并发容量边界，并补充 station_type 条件查询与契约测试；15c1c52 已在 README 明确：HTTP 200/readOnly 通过不等于 #63 要求的全部 22 个切片均已非空真实接线，仓库仍有 Empty*Adapter，issue 继续保持开启。

本轮继续修复并推送：11e5d9a 对齐深层 equipment_type.parent_id 行业上溯、RELEASED 当前预警、未知行业 excluded 统计，以及 work_order_log.oper_type 0–10 到当前 0–7 状态的时间线映射；84a7834 同步 README。定向与全量 Maven 回归均通过。#63 仍保持开启，剩余 Empty*Adapter 全量非空接线和目标部署实例验收未宣称完成。

本轮继续推进：已完成并推送 11e5d9a（深层类型树行业上溯、RELEASED 预警态、未知行业进入 excluded、工单日志 0–10 操作码映射当前 0–7 时间线），84a7834 同步 README。定向测试和 mvn -pl zksy-admin -am test -DfailIfNoTests=false -q 全量回归均通过。#63 仍保持开启；剩余是详情 freshness/stale、全量检查表逐端点证据和目标部署实例不可达等验收项。

真实数据量补充（本轮只读核对）：概览/基础设施/监测概况及事件切片均返回 200；历史预警分析返回 169 行，处置效率返回 2 条事件。监测分布返回 200 且 freshness=EMPTY、点位/未关联设备列表为空，原因是当前点位/设备没有可信坐标校核，按契约 renderable=false，不使用 fixture 强行填充。

第 2 轮进度：7e0d2c8 已将基础档案/运行信息适配器的共用 pump_station 查询改为显式 station_type IN (water_supply, drainage)，与此前总体概览保持一致；678f3e7 同步 README。定向与全量 Maven 回归通过。#63 保持开启，目标部署实例和逐端点完整验收仍待继续。

第 3 轮真实 HTTP 验收补充：16/16 个端点非法参数样例均返回 400 INVALID_REQUEST；真实 deviceCode=860347065467627 的 archive、metrics、events、work-orders、detail-aggregate、freshness 均返回 200、readOnly=true，并回显同一 canonical deviceCode。1676396 已同步 README，#63 继续保持开启。

第 4 轮最终收口（合并远端并发改动后 HEAD=6ef71ef）：严格 snapshotAt 签发/续页契约已通过，未签发或缓存丢失 token 不重建当前库；显式快照丢失统一 SNAPSHOT_EXPIRED；detail-aggregate 时间线校验工单号、设备号和每条日志工单号，错误时间线不泄漏，兄弟分区保留并返回 PARTIAL。定向测试和合并后全量 Maven 回归均通过。目标部署实例仍不可达，#63 保持开启。

第 5 轮静态装配盘点：当前仓库 23 个 Empty*Adapter 均有对应 @Primary Business*Adapter，另有 1 个共享事件事实适配器；fallback 类保留不等于运行时未接线。合并远端监测点重构后全量 Maven 回归仍通过，77b4a34 已同步 README。剩余是逐切片代表性真实数据、空/脏数据和故障注入证据，#63 保持开启。

第 6 轮真实切片核对（重启加载合并后代码）：overview/infrastructure、overview/monitoring、overview/warning-settings、基础档案、运行信息、应急、monitoring/overview、monitoring/situation 均 200/readOnly/CURRENT；monitoring/situation 返回 6 个异常设备；历史预警分析 169 行，处置效率 2 条，事件多维分析 7 个维度。monitoring/distribution 合法返回 200/readOnly/EMPTY，点位和未关联设备为 0，因坐标未可信校核而禁止渲染。31597fd 已同步 README；#63 保持开启。

第 7 轮完成：补充 Redis GET/SET 运行时异常契约测试，确认适配器包装为 CockpitReadException，控制器映射 500 SERVER_ERROR，不误报 SNAPSHOT_EXPIRED。定向与全量 Maven 回归通过，73a8ae3 已推送并同步 README。#63 继续保持开启。

第 8 轮补充本机受控性能烟测：同一真实 snapshotAt 连续认证请求 30 次，30/30 成功，平均 24.10ms、P95 30.60ms、最大 34.35ms，本次 live 样例 total=7。该数据仅代表本机当前进程/数据量，不替代生产压测；2b9fea9 已同步 README，#63 继续保持开启。

第 9 轮时间戳/freshness 扫描：16 个主要 endpoint 全部 HTTP/app code 200；所有观察到的 ISO 时间戳均为 +08:00；11 个 endpoint 显式提供 freshness。events/current、history-analysis、handling-efficiency、multidimensional-analysis 和 device-boundary 尚未提供统一 freshness 字段，已在 README 标为未完成契约项。合并远端监测点改动后全量回归通过，当前 HEAD=c531835，#63 保持开启。

第 10 轮完成：事件 current/history/handling/multidimensional 与 device-boundary 响应 DTO 补充 freshness getter；重启后真实认证 HTTP 复验五个端点均 200、readOnly=true、freshness=CURRENT；补充事件空态 freshness=EMPTY 断言，定向与全量 Maven 回归通过。355a8af 已推送。#63 继续开启，生产 freshness 实际时效、空/故障数据和目标部署实例仍待验收。

票 25 里那段三切片摘要可直接粘贴，我的工具只达本地台账。