City-Lifeline-Cockpit/.scratch/cockpit-shell-panel-layout/issues/25-backend-contract-gaps.md

25: 后端契约缺口待办（跨领域两项 + 补契约清单）

Status: resolved Labels: ready-for-human, resolved Category: enhancement Blocked by: None

不阻塞 23 张实现票的 mock 阶段；阻塞的是这些票接真实接口。（2026-10-10 第十六轮：四条 AC 已在远端核销达成。原「目标部署 192.168.110.30:8301 复验」一项按维护者裁定取消——实际线上环境另有服务器，免鉴权行为将在生产部署时于真实环境验证；本票就此关闭。）

This was generated by AI during triage.

Why ready-for-human

结论来自 面板字段与后端契约覆盖调研（2026-09-15 历史基线）、后续复核与本票第十二轮的现行源码检查。缺口分两类：

1. 后端补契约——需要后端负责人实现。本仓库工作区写权限只覆盖 E:\City-Lifeline-Cockpit-TvT，且后端仓库当时有并行会话的在途改动，不适合由本票直接改。
2. 业务定义确认——需要业务方回答，本票不发明结论。

可直接交付给后端项目经理的建票草案已单独产出：后端契约缺口交付包。后续真实数据接线不再由本票继续拆执行票，统一转入新地图：驾驶舱真实后端数据接线（决策地图）。

复核记录（2026-10-10 第十六轮：后端远端逐项核销——四条 AC 基本达成，转 95% 待部署复验）

本轮只读核查后端远端 origin/master=989a707e（免鉴权提交 8c0771a 已在远端；本地另有 1 个无关提交 a96091ce 管径几何未推送，非本票范围）。逐项核销结果：

原四条验收标准的现行状态

1. map-snapshot 支持 industry 并返回行业/类型 — ✅ 已达成且超出：控制器入参现为 page/pageSize/snapshotAt/industry/district/deviceType/pointStatus（pointStatus 为数组入参，即原 I1 缺口已一并关闭）；CockpitMonitoringPointSummary 已含 deviceCodes/region/industry/typeCode/typeName。
2. 点位摘要返回设备编码、WS 增量可回联 — ✅ 已达成：摘要含 deviceCodes；DeviceStatusRedisListener/Handler 的增量帧带 monitoringPointCode（顶层，未关联显式 null）。
3. A–H 补契约逐项确认 — ✅ 已达成：远端 com.zksy.cockpit 下 25 个 Business*Adapter 全部提交（23 个 Empty*Adapter 保留为 fallback）；J1 四行业已在 device/event 全系服务落地（MANHOLE 进白名单与 400 文案）；map-snapshot 免鉴权 + 筛选齐备。
4. 3 个业务问题答复 — ✅ 已由裁定落地为代码：处置率口径 = CLOSED_WORK_ORDERS_OVER_ELIGIBLE_WORK_ORDERS（分子 CLOSED_RATE_CODE=5 已结案、排除 CANCELLED_RATE_CODE=7、分母 0–6），效率服务已改用常量引用；maintainer/district/ownership_unit 各自独立（management-information 已含 districtIndustry 分布）；「故障」桶按六态/八态字典呈现。

免鉴权（第十五轮）在远端的核销

• SecurityConfig：GET /api/cockpit/v1/** permitAll 在远端 ✅；anyRequest().authenticated() 与其余规则保留 ✅。
• 24 个控制器：远端 grep PreAuthorize 零命中 ✅。
• docs/cockpit/README.md 第 1/5/6 节免鉴权口径在远端 ✅。
• WS：cockpitSubscribe 免鉴权直订口径在远端手册 ✅。

仍开放的事项

1. I2 数据时间（唯一实质残留）：monitoring/overview 响应仍无逐设备/分区数据时间字段（快照 SourceDevice.sampledAt 存在但未聚合输出）。该缺口已由新地图票 03（createdAt 契约）接手，本票不再重复拆票。
2. 陈旧 javadoc 一处：CockpitHandlingEfficiencyService 第 36 行注释仍写 "state 6 已结案"（逻辑已正确用常量 5，仅注释陈旧），建议后端顺手更正。
3. 目标部署复验（需人工/环境）：192.168.110.30:8301 免鉴权生效后的无凭据 200、WS 免 authenticate 直订、非法参数 400 仍需在真实部署环境复验——这是本票转 95% 的唯一待确认项。

为什么剩余项需要人工

目标部署环境的可达性、部署包更新与真实库联调属外部环境权限，agent 无法代劳：本机无该环境访问通道，历史记录亦确认该端口从本机不可达。故本票按进度契约维持 95% 待确认，不 close。

复核记录（2026-09-28 第十五轮：驾驶舱接口免鉴权落地）

用户裁定（最终口径，覆盖此前"仅 GET"的中间稿）：驾驶舱 REST 与 /ws/deviceStatus 均免鉴权，接口安全由网络层内网隔离保障；按 ADR 0005 与鉴权决策票 07 修订 执行。

后端已改（E:\pipe-ner-server 工作树，未提交）：

• SecurityConfig：新增单条 GET /api/cockpit/v1/** 的 permitAll；anyRequest().authenticated()、/ws/deviceStatus 与其余业务 API 规则不变。CockpitAuthenticationEntryPoint 保留为安全网。
• 24 个 cockpit 控制器：28 处 @PreAuthorize("isAuthenticated()") 及 import 全部移除（校验残留 0）。
• DeviceStatusWebSocketHandler：协议注释改为"cockpitSubscribe 免鉴权、连接后可直接订阅"；handleCockpitSubscribe 本就不校验认证，无需改逻辑；authenticate 帧保留（仅管理端工单推送 workOrderReminder 使用）。
• 测试：21 个控制器测试的旧"必须认证"断言移除；新增 CockpitAnonymousAccessSecurityConfigTest（锁单条 GET permitAll + anyRequest authenticated + WS 规则保留）；DeviceStatusCockpitWebSocketHandlerTest 新增"未经 authenticate 直接 cockpitSubscribe 即订阅成功"回归。
• docs/cockpit/README.md：第 1 节契约总则、第 5 节 WS、第 6 节联调检查表改为免鉴权口径。

前端已改（本仓库）：

• services/cockpitApi.js：planCockpitRequest 不再读取/发送 Authorization，credential 字段移除。
• services/runtimeSocket.js：open 后直接 cockpitSubscribe，不再发 authenticate 帧；handleFrame 删除 authenticated 分支；token 会话字段与"鉴权失败不重连"豁免一并下线；AUTHENTICATING/UNAUTHORIZED 状态常量保留供兼容。
• stores/runtimeStore.js：WS token 只认 ws.token，删除 api.token 兜底。
• services/cockpitConfig.js：加载结果 credential 恒为 NONE；api.token 仍被宽松解析（兼容旧配置）但不进任何请求。
• domain/configStatus.js：顶栏 real 文案改为「接口免鉴权（内网隔离）」。
• mocks/wsMock.js：脚本握手对齐新时序（authenticate 不再进入驾驶舱时序）。
• 文档：ADR 0005、docs/cockpit-deployment.md、public/cockpit/README.md 均改为免鉴权口径（api.token/ws.token 废弃、网络层隔离为安全前提）。

验证边界：

• 前端零依赖闸门：t15-websocket.mjs 43/43 通过（含 B 段新时序断言：只发 1 帧 cockpitSubscribe、传入旧 token 不进任何帧、无 authenticate 发送点）；t04-config.mjs 通过；t08-map-summary.mjs 44/44 通过。
• t05-adapter.mjs 249/254，剩余 5 项失败（B7 七态字典 / B8 已结案编码 / C3 工单状态名补齐）属工单状态字典 J2 遗留缺口，与鉴权改动无关（本次 diff 只触及凭据链路），归新地图票 06。
• 后端只做了静态修改与检查（控制器注解残留 0），未运行 Maven 编译/测试；新后端测试（含安全配置测试）需维护者跑 mvn -pl zksy-admin -am test 验证。
• 目标部署 192.168.110.30:8301 仍不可达；免鉴权生效后的真实 HTTP/WS 复验（无凭据 200、WS 直订）待部署后进行。

复核记录（2026-09-28 第十四轮：迁移至真实数据接线地图）

本轮把本票从“缺口草案台账”同步为新地图的事实来源；未修改后端代码，也未在本机重跑构建、测试或数据库查询。后端当前 HEAD=origin/master=355a8af，最新提交已包含 freshness 空态、事件/边界 freshness、监测点管理、Redis 故障分类和本机快照性能烟测等记录。

后端 docs/cockpit/README.md 第 8 节记录了本机 127.0.0.1:8301 的真实登录态证据：未认证 401、非法参数 400、同一 snapshotAt 的多页总数稳定且点位不重复、点位详情和同设备 archive/metrics/events/work-orders/detail-aggregate/freshness 返回 200/readOnly、主要概览/基础设施/监测/事件/自检端点返回 200/readOnly、WebSocket cockpitSubscribe 收到回帧；第 8 节还记录了 16 个非法参数样例全部 400 和同设备 canonical deviceCode 回显。

这组证据的边界必须保留：

• 证据来源是后端维护者记录的本机 IntelliJ 实例，不是本轮 agent 自己运行的命令；目标部署 192.168.110.30:8301 仍不可达，因此不能称为目标环境联调完成。
• 当前 map-snapshot 已有四行业/筛选/共享快照目标契约，监测点详情已支持 snapshotAt 并与地图设备编码集合对齐，设备自身坐标和 coordinateValidation 已写入手册；但真实点位坐标没有可信校核来源，设备位置仍按 UNVERIFIED_COORDINATE / renderable=false 降级，只保留设备清单。
• monitoring/overview、monitoring/situation 已接受 MANHOLE，地图/分布/事件/基础设施也已在当前后端文档记录四行业口径；工单运行时为 0–7，公开 cockpit 旧字典仍有 1–7 遗留，处置率语义由新地图票 06 统一维护。
• BT-5 不再用“4/22 片”或旧的 0% 作为唯一状态；当前后端已有多片真实适配器与测试/HTTP 证据，但目标部署、真实数据稀疏/坐标降级、所有切片和全量验收仍未收口。

新地图的当前 frontier 仍是 6 张未解决决策票：后端切片/票边界、地图状态筛选与未关联设备、监测时间字段、前端 real 生命周期、真实联调证据门槛、跨模式业务语义。它们均为 grilling，本轮不替用户回答，也不把未解决票提前转成执行票。

本轮改的是后端 E:\pipe-ner-server 工作树，未提交、未关 真实数据接线（程序级），也未做真实登录态联调。

• CockpitTypeIndustry 现在沿 parent_id 上溯到根。根 1–4 分别映射 WATER_SUPPLY、DRAINAGE、GAS、MANHOLE；未知根、缺父级和环返回 null。
• monitoring/overview 与 monitoring/situation 已接受 industry=MANHOLE，不再把它计入 nonFormalIndustryCount。非法行业仍返回 400，文案为 industry must be GAS, WATER_SUPPLY, DRAINAGE or MANHOLE。
• 定向测试 34 例 0 失败；mvn -pl zksy-admin -am compile -q 通过。这只证明这两片的契约测试和编译，不证明全量测试或当前 KingbaseES 联调。
• 地图、分布、事件、基础设施服务仍只允许三行业；工单对外字典仍未对齐 0–7。第十二轮关于这两项的缺口仍然有效。

复核记录（2026-09-24 第十二轮：代码与文档同步核查）

本轮只读检查后端本地 HEAD=c5a5b87 与其未提交工作树，不修改后端代码、不运行构建或数据库联调。origin/master 与本地 HEAD 相同；提交版与工作树须分开判断。

• 已有进展：工作树的 BusinessCockpitDeviceFactResolver 已改用 work_order.device_id，CockpitTypeIndustry 与三个监测适配器已改用 equipment_type.id/parent_id；对 cockpit Java 源码检索未再发现第十一轮所列的 WorkOrder::getDeviceCode / EquipmentType.getTypeId/getParentTypeId 调用。故第十一轮的具体编译阻断已过时；但本轮没有跑 Maven，不能反推当前已编译通过。后端 docs/cockpit/README.md 第 8 节及 spec 的「仍引用已删除访问器」句子也需由后端维护者复核后改正。
• 尚未成为可依赖版本：map-snapshot 的 industry/region/deviceType 三入参、点位 deviceCodes/industry/typeCode 和四个真实数据适配器仍是后端未提交工作树的内容；git show HEAD 的地图控制器只有分页和快照三入参。旧 BT-1…BT-4 的关闭记录是历史交付事实，不等于当前 HEAD 已含这些字段或通过新 schema 验收。
• 新模型适配未完成：CockpitTypeIndustry 已把根 4 推导为 MANHOLE，但 CockpitMapSnapshotService、监测/事件/基础设施等服务仍将正式行业限制为三项；CockpitWorkOrderStateDictionary 仍公开 1–7 七态，byLegacyCode(0) 会落到 7「已取消」，而当前 WorkOrderStatusEnum 与 ADR-0010 是 0–7（5 已结案、6 延期中、7 已取消）。这两项是目标文档已裁定、响应与服务尚未对齐的契约缺口，建议后端 PM 确认是否纳入 真实数据接线（程序级） 的跨端验收，不重复宣称已交付，也不在未核对远端范围时擅自认定其已承接。
• 面板级缺口仍在：map-snapshot 无 pointStatus，且其未关联设备摘要无状态/设备运行事实，不能只给点位列表加参数；monitoring/overview 无逐设备最近采集时间的响应字段，备选 /overview/monitoring 虽有 metricFreshness，目前仅空适配器且源为空时回 null；management-information 仍无责任区域维度。分别见下文 I1/I2 与 E 组补充清单。前端 mock 可继续，接真实接口不可假装达成。（2026-09-28：原文末句含「票 18 收口不可假装达成」—— 按维护者裁定，票 18 的交付面是前端页面、其后端边界已转交本票，故票 18 已收口；本段其余后端结论不变。）
• 真实数据：后端手册第 8 节记录 2026-09-24 KingbaseES app_user 的两台设备、三条报警、35 条预警等既有只读观测；本轮未重查数据库，不能把该快照当本次最新实时计数。当前代码中有 23 个适配器接口、23 个 Empty*Adapter 与 5 个 Business*Adapter 文件（其中地图与三个监测适配器未提交）；文件存在或 @Primary 不是可运行/联调通过的证据。

复核记录（2026-09-24 第十一轮：后端模型大改后的需求重建；历史快照）

以下编译失败与数据计数是本轮当时的观察，不代表第十二轮的工作树状态；现行判定以第十二轮为准。

本轮仅重建需求与文档，不修改后端代码。 当前后端 HEAD=c5a5b87，工单/报警/设备类型的实体与数据库结构已发生破坏性变化。BT-5（真实数据接线（程序级））先退回 needs-triage 完成诊断/裁定，现已转回 ready-for-agent；历史 4/22 片是先前尝试记录，不是当前可验收进度。当前进度回调为 0%（需求基线重建，未改代码）。

• 当前 equipment_type 只有 id/type_name/parent_id，旧 type_id/parent_type_id 不存在；BusinessCockpitDeviceFactResolver 仍引用已删除的 WorkOrder::getDeviceCode，CockpitTypeIndustry 及 overview/situation 适配器仍引用已删除的类型访问器。mvn -pl zksy-admin -am compile -q 当前失败；故不能再声称“4 片已接真实库并通过验收”。
• 当前 work_order 通过 device_id 关联设备，报警通过 alarm_data.order_id 关联工单；运行时工单状态以 ADR-0010 为准，为 0–7（含 6 延期中），不是旧契约手册的 1–7 七态。
• 当前 KingbaseES app_user 只读观测：equipment_base=2、equipment_status=2、monitor_point=7、equipment_point_rel=20、early_warning=35、alarm_data=3、work_order=1、alarm_warning_rel=3；1 条报警通过 order_id 匹配工单，35 条预警仅 6 条匹配设备/类型，当前两台设备均没有有效点位关系。旧“37 台设备/507 条报警/3 条设备关联”数字已失效。
• 已裁定：公开 typeCode 使用 equipment_type.id 的字符串形式；井盖成为第四正式行业 MANHOLE；坐标优先复用现有校验器，缺可信校核来源时仍不可渲染（不以通用范围自动放行）；联调以当前真实 KingbaseES 数据为基准，不编造业务行填非空。
• 工单字典已澄清：指代码枚举 WorkOrderStatusEnum（0–7，见 ADR-0010），不是数据库字典表。当前 app_user.sys_dict_type/sys_dict_data 无工单状态条目，不再作为待定位项；设备/报警/预警到工单的关联路径已按当前实体/schema 写入 spec 和手册，后续仍需编译与端到端联调。
• 后端 .scratch/cockpit-backend-read-contracts/spec.md、pipe-network-service/CONTEXT.md、根 CONTEXT-MAP.md 与 docs/cockpit/README.md 已同步当前模型与未决问题；原有历史复核记录保留供追溯，不再视为现行结论。

复核记录（2026-09-18 第十轮：BT-5 第 3、4 片落地，票未关）

BT-5（Gogs #63）继续纵向推进：monitoring/overview + monitoring/situation 两片真实数据接线完成，票保持 open（约 18%）。

• 落地：新增 BusinessCockpitMonitoringOverviewAdapter、BusinessCockpitMonitoringSituationAdapter（均 @Primary）。
• 本轮实测到的关键脏值：现网 alarm_data.device_type（流量监测/environment）与 early_warning.warning_type（GAS_PIPE/MANHOLE）是描述性字符串，不是 equipment_type.type_id → 事件的 typeCode/industry 一律经 device_code → equipment_base → equipment_type 反查，否则服务层类型字典全部落空。
• 拒绝伪造状态：概览 monitoringState 无状态记录→UNKNOWN（不冒充 OFFLINE）；概况指标态不产生 EXPIRED（现网无样本新鲜度依据）。
• 真实库证据（只读）：概览 37 设备（在线 21/离线 1/无状态 15）、7 点位（2 带设备）；概况指标态 报警 5/常规 16/离线 1/无状态 15；事件 预警 29、报警 507。
• 新暴露的数据缺口：事件与设备台账严重脱节——507 条报警仅 51 条能匹配到设备类型（29 条预警仅 5 条），其余被服务层计「未知类型」。属数据侧问题（事件表设备编码与台账不一致），已写进 #63。
• 测试：新增 overview 3 例 + situation 3 例；全量 mvn -pl zksy-admin -am test 480 测试 0 失败。

wayfinder 记法：同前几轮——本票属后端 Gogs tracker，不挂在任何 wayfinder map 之下，故 gist 记在本票（其父台账）。

复核记录（2026-09-18 第九轮：BT-5 第 2 片落地，票未关）

BT-5（Gogs #63）继续纵向推进：monitoring/distribution 第 2 片真实数据接线完成，票保持 open（约 9%）。

• 落地：新增 BusinessCockpitMonitoringDistributionAdapter（@Primary）；并抽共享组件 BusinessCockpitDeviceFactResolver（设备实时事实：在线/报警/预警/在途工单）+ CockpitTypeIndustry（类型根→行业），map-snapshot 适配器重构复用，两片不再各自内联推导。
• 本片修正：① 工单在途判定——现网 order_status 是 0-based，上一片 0..6 把 5=已结案误判为在途，已修正为「0..4 或 6 在途；5/7 终态」；② 设备 typeName——equipment_type_name 是非库列恒 null，改为从 equipment_type 字典解析。
• 真实库证据（只读，同口径 SQL）：分布快照将产出 7 点位（2 带设备）、37 全量设备、5 报警、1 离线、5 在途工单设备、3 预警中设备。
• 测试：新增 resolver 5 例 + distribution 2 例；全量 mvn -pl zksy-admin -am test 472 测试 0 失败。
• 口径不变：坐标校核默认未校核（不上图）、窨井映射 MANHOLE 交服务层判非正式行业、中英文脏值不读列做裁决——三项仍需后端负责人裁定（见第八轮）。

wayfinder 记法：同前几轮——本票属后端 Gogs tracker，不挂在任何 wayfinder map 之下，故 gist 记在本票（其父台账）。

复核记录（2026-09-18 第八轮：BT-5 第 1 片落地，票未关）

BT-5（Gogs #63）按人类裁定走「纵向样板」：完成 map-snapshot 一片的真实数据接线，余 21 片未动，票保持 open（约 5%）。

• 裁定：本轮范围＝map-snapshot 纵向样板（不追求 22 片全接）；井盖口径「以数据库为准」。
• 落地：新增 BusinessCockpitMapSnapshotAdapter（@Primary），组合 monitor_point / equipment_point_rel / equipment_status / early_warning / work_order / equipment_type 六张既有表与服务，不新增表、不加投影，复用 BT-1…BT-4 已冻结的服务层（过滤/分页/mapFilter/坐标校验均不改）。
• 真实库证据（只读，KingBase 192.168.110.30:54321/pipi_ner）：接线后产出 7 个真实点位（2 个带设备）、3 条有效设备关联、34 台未关联设备、5 台报警、1 台离线 —— 非空且与库一致。
• 测试：新增 BusinessCockpitMapSnapshotAdapterTest 4 例；全量 mvn -pl zksy-admin -am test 465 测试 0 失败。
• 实测出的真实数据缺口（阻塞后续切片，已全部写进 #63）：
  1. 设备→点位关联极稀疏（仅 3 条有效，覆盖 2/7 点位）→ BT-1 的 deviceCodes/WS monitoringPointCode 在真实数据下近乎全空（数据缺口，非代码缺陷）；
  2. 现网无坐标校核字段 → 按冻结字典一律 renderable=false（不上图），要上图需数据侧补标志或裁定「默认已校核」；
  3. monitor_point 无行业列，点位类型只能在关联设备类型唯一时推导；
  4. 点位状态/类型中英文脏值（正常/预警 vs ACTIVE）；
  5. 工单状态值域跨端不一致：现网 0-based、cockpit 冻结 1-based；
  6. 窨井（井盖）缺契约位：库里有独立 manhole_base(3 条)/manhole_device_rel(6 条)与 manhole 类型根，前端筛选也有「井盖」项，但后端正式行业枚举只有 3 个；
  7. 窨井坐标脏（1212,1212）。

wayfinder 记法：同前几轮——本票属后端 Gogs tracker，不挂在任何 wayfinder map 之下，故 gist 记在本票（其父台账）。

复核记录（2026-09-18 第七轮：BT-4 已交付）

BT-4（Gogs #62）事件行补坐标校验与报警阈值完成并关闭：

• 落地：events/current 的 EventItem 增加 coordinateValidation（state/reason/renderable/crs）与 thresholdMinValue/thresholdMaxValue（报警族在数据可得时有值，预警族 null）；快照源补 coordinateVerified（报警族另补阈值）。校验复用 CockpitCoordinateValidator，与地图/分布/态势同一实现。
• 不臆造验证：适配器未给 coordinateVerified 时按未验证处理（UNVERIFIED + renderable=false），符合字典「未验证禁止渲染」；接线后按真实标志放行。
• 适用面：events/history-analysis 的行是小时桶聚合、无逐事件行，不适用该字段（与 BT-1 的结论一致）。
• 入册：README 第 4 节三条口径 + current-warnings-demo.html 增「上图」列（标记只画 renderable=true 的事件）。
• 证据：CockpitCurrentEventsControllerTest 14 例（含 INVALID/LONGITUDE_OUT_OF_RANGE、UNVERIFIED/UNVERIFIED_COORDINATE、报警阈值断言）；全量 mvn -pl zksy-admin -am test 453 测试 0 失败。
• 口径说明：本票与 BT-5 不在「11 判定项 + 3 业务问题」的计分口径内，故进度仍记 79%；但它们同属交付包里的后端缺口，BT-1…BT-4 现已全部交付，只剩 BT-5（真实数据接线）与 3 条业务口径问题。

wayfinder 记法：同前几轮——本票属后端 Gogs tracker，不挂在任何 wayfinder map 之下，故 gist 记在本票（其父台账）。

复核记录（2026-09-18 第六轮：BT-3 已交付，B 关闭——11 个契约判定项全部达成）

BT-3（Gogs #61）趋势窗口可声明完成并关闭：

• 落地：GET /overview/warning-settings 增加 range（LAST_24_HOURS/LAST_7_DAYS/LAST_30_DAYS，同 infrastructure/operating-information）与 startTime/endTime（显式 ISO 区间，成对且 startTime ≤ endTime）；range{type,start,end} 回显生效区间（显式区间 type=CUSTOM，不声明时维持 CURRENT_BASELINE + null）；trend[] 按窗口过滤（桶为业务时区日期，含端点，顺序沿用适配器）。
• 错误口径：非法 range、单边区间、startTime > endTime、时间戳不可解析 → 400 INVALID_REQUEST，文案与兄弟切片一致。
• 入册：docs/cockpit/README.md 第 3 节端点参数 + 第 4 节新增「时间范围口径」。
• 证据：CockpitOverviewWarningSettingsControllerTest 9 例 + ServiceTest 3 例；全量 mvn -pl zksy-admin -am test 453 测试 0 失败。
• 本轮据此更新：判定项 B ⚠️→✅。至此 11 个契约判定项（A、B、C、D、E、F、G1、G2、G3、G4、H）全部交付；剩余只有 BT-4（#62 事件坐标校验）、BT-5（#63 真实数据接线）与 3 条业务口径问题。

wayfinder 记法：同前两轮——本票属后端 Gogs tracker，不挂在任何 wayfinder map 之下，故 gist 记在本票（其父台账）。

复核记录（2026-09-18 第五轮：BT-2 已裁定并交付，G1+G2 关闭）

BT-2（Gogs #60）路径裁定 + 落地完成并关闭：

• 裁定：走路径①完整——地图取数以 map-snapshot 为准（不用 monitoring/distribution 供数），map-snapshot 承接全局筛选。理由：前端全局条件是「范围(scope) + 行业」两维，只加 industry 会让范围对地图无效；且票 08 的装载器已按 map-snapshot 的扁平分页形状验收关闭。
• 落地：map-snapshot 增加 industry/region/deviceType 三个入参；逐点补 region/industry/typeCode/typeName（未关联设备同样补）；响应新增 mapFilter{industry,region,deviceType,pointCodes,deviceCodes} 回显生效范围；coordinateValidation 汇总改为「筛选范围内全量口径」；默认不筛时不排除任何对象（行业不可推导为 null）。
• 入册：结论写入 docs/cockpit/README.md 第 3 节「地图筛选路径（冻结结论）」（票面验收第 1 条）。
• 证据：CockpitMapSnapshotControllerTest 14 例（含筛选、回显、非法行业 400、带筛选翻页快照锁）；全量 mvn -pl zksy-admin -am test 450 测试 0 失败。
• 本轮据此更新：判定项 G1 ❌→✅、G2 ❌→✅；AC1 达成。至此契约判定项只剩 B 一处（overview/warning-settings 趋势窗口，Gogs #61），另有 BT-4（#62 事件坐标校验）与 BT-5（#63 真实数据接线）。

wayfinder 记法：同第四轮——本票属后端 Gogs tracker，不挂在任何 wayfinder map 之下，故 gist 记在本票（其父台账）。

复核记录（2026-09-18 第四轮：BT-1 已交付并关闭）

BT-1（Gogs #59）实施完成并关闭——设备→点位回联三件套全部落地：

• ① REST：CockpitMonitoringPointSummary 新增 deviceCodes（从 SourceMonitoringPoint.devices 投影，保序去重），map-snapshot 点位摘要现在能回联设备。
• ② WS：四个增量 DTO 新增 monitoringPointCode；DeviceStatusRedisListener 按 equipment_base.equipment_code → equipment_point_rel → monitor_point.point_code 解析，未关联显式 null（帧序列化 WriteMapNullValue），查询异常降级不阻断推送。
• ③ 事件行：EventItem 新增 monitoringPointCode/monitoringPointName（快照源与 EventRow 同步补字段）。history-analysis 的 row 是小时桶聚合行，无逐事件行，不适用该字段。
• 证据：mvn -pl zksy-admin -am test（全量 zksy-admin 与 zksy-system）445 个测试 0 失败（含 REST 契约与 WS 增量两侧新增断言）。
• 本轮据此更新：判定项 G4 由 ❌ 转为 ✅；AC2 的候选 ①②③ 全部实现，结论达成。

wayfinder 记法：本票属后端 Gogs tracker，不挂在任何 wayfinder map 之下（后端仓库无 map.md），故 gist 记在本票（其父台账）而非某张 map 的「Decisions so far」。

复核记录（2026-09-18 第三轮：建票完成）

承接第二轮结论，重新只读复核后端（HEAD 仍 ed0ace5、远端仍 e2b4e45，G1/G2/G4/BT-3/BT-4 证据逐条复验成立），并把交付包草案在 Gogs 建成真实工单：

BT	Gogs 票号	标题	标签
BT-1	#59	BT-1 Cockpit device-to-point linkage（REST + WebSocket）	needs-triage
BT-2	#60	BT-2 全局行业筛选落图：路径裁定 + 落地	needs-triage
BT-3	#61	BT-3 warning-settings 趋势窗口可声明	needs-triage
BT-4	#62	BT-4 事件行补 coordinateValidation 与报警阈值	needs-triage
BT-5	#63	BT-5 真实数据接线（程序级）	needs-triage

• 每张票正文 = 交付包对应小节 + 一行来源说明（前端 tracker 票 25 / handoff/backend-contract-gaps.md）。
• 标签统一 needs-triage：这些票都含待后端负责人裁定的点（BT-2 路径二选一、BT-1 ①②③、BT-5 排期），应由后端 PM 评估后转 ready-for-agent。
• BT-6（situation 的 monitoringState 过滤）按草案标注为可选，未建。
• 本轮两处事实修正：①「06（全局筛选）」错引改为 18（票 18 验收项「面板筛选可作用于地图点位」，filterStore 已在票 01 落地）；② 适配器计数改为精确口径（23 接口 / 22 空实现 / 1 真实，不计 /foundation 自检则 22/21）。
• 本票与交付包均已同步上述修正。

复核记录（2026-09-17 第二轮，替代同日第一轮）

第一轮复核时后端 HEAD 为 #36、#37 未提交，当时判定「8 组补契约中 4 组已交付」。同日后端又落地 #37–#43，第二轮结论大幅前移：11 个契约判定项中 7 项已交付，1 项只剩一处，3 项未交付。

复核方式：只读阅读后端仓库 E:\pipe-ner-server 的控制器、响应类、适配器与 docs/cockpit/README.md；未改动后端任何文件，未跑构建或调试命令。

• 后端本地 HEAD：ed0ace5（test(cockpit): add contract integration environment and handoff (#43)）。
• 远端 origin HEAD 仍是 e2b4e45（#42）——#43 未推送，联调前需确认部署来源提交。

第二轮逐项判定

项	内容	状态	证据
A	跨设备事件读模型（当前 + 历史）	✅ 已交付	GET /events/current（mode 必填并校验，level/industry/status/分页）与 GET /events/history-analysis（eventFamily 必填并校验 + startTime/endTime）；EventItem 含 eventNo/eventType/level/levelColor/status/eventTime/value/unit/deviceCode/deviceName/location/industry/longitude/latitude/workOrderSummary；历史侧回显 Range{type,startTime,endTime}。残留 monitoringPointCode 与 coordinateValidation（分别见 G4、BT-4）
B	趋势时间范围可声明	✅ 已交付（2026-09-18，Gogs #61）	overview/warning-settings 增加 range 三档 + startTime/endTime，回显 range{type,start,end}，趋势桶按窗口过滤；其余切片早已支持范围参数
C	响应/关闭时长聚合	✅ 已交付	GET /events/handling-efficiency：averageDuration{value,unit,sampleCount,state,reason} + durationTrend[] + 工单 durationHours；口径冻结为 basis = CLOSED_WORK_ORDERS_OVER_TOTAL_EVENTS
D	应急保障域三件套	✅ 已交付	GET /infrastructure/emergency-support：Totals{emergencyResourceCount,hazardSourceCount,protectionTargetCount} + 三 section + eventSummary
E	管理信息域	✅ 已交付	GET /infrastructure/management-information：organizations + ownershipDistribution + unmaintained
F	设施/行业运行信息	✅ 已交付	GET /infrastructure/operating-information：metrics + capacityValue/loadRatio/loadState + trend + range/from/to
G1	全局行业筛选落到地图点位	✅ 已交付（2026-09-18，Gogs #60）	裁定走路径①：map-snapshot 增加 industry/region/deviceType 入参，服务端过滤 + mapFilter 回显生效范围；分页与 snapshotAt 语义不变；结论冻结在 docs/cockpit/README.md 第 3 节
G2	点位摘要补 industry、类型、徽标	✅ 已交付（2026-09-18，Gogs #60）	CockpitMonitoringPointSummary 补 region/industry/typeCode/typeName；徽标所需的设备数由 BT-1 的 deviceCodes 直接得出
G3	未关联设备补 industry、设备类型	✅ 已交付	CockpitMonitoringDistributionResponse.UnassociatedEquipmentMarker
G4	设备编码回联点位	✅ 已交付（2026-09-18，Gogs #59）	点位摘要 deviceCodes + 四个 WS 增量 DTO 的 monitoringPointCode（真实库映射查询，未关联显式 null）+ 事件行 monitoringPointCode/monitoringPointName；REST 与 WS 契约测试两侧覆盖
H	跨设备设备状态清单	✅ 已交付	GET /monitoring/situation：abnormalEquipment[]{deviceCode,deviceName,deviceType,industry,region,abnormalType,status,statusReasons,longitude,latitude,coordinateValidation} + 分页 + mapFilter.deviceCodes

已交付但仍需注意的两条事实

1. #43 交付了一份移交与联调手册：E:\pipe-ner-server\docs\cockpit\README.md（契约总则、字典冻结、端点清单、分页/快照/错误口径、WebSocket 增量、启动与联调检查表、容器化评估、已知未验证项）。票 25 里「字段名与语义」类问题已由它回答，不必再建票。
2. 契约已冻结，真实数据未接线：23 个 cockpit 适配器接口中 22 个只装配了 Empty*Adapter（返回 ...Snapshot.empty(...)），唯一接入真实数据的是 BusinessCockpitWorkOrderReadAdapter（工单，@Primary 覆盖同名 Empty 实现）。前端切到真实接口会拿到全空快照（200 + freshness.state = EMPTY）。这是当前最大的交付差距，已作为 BT-5 写入交付包。（口径：若不计 /foundation 契约自检，则为 22 个读模型接口 / 21 个空实现。）

G1 全局行业筛选落不到地图点位（2026-09-18 历史交付，现行可用性待复验）

下面是建票时的历史问题描述；当前未提交工作树已有行业/区域/类型筛选和摘要字段，但 committed HEAD=c5a5b87 不含这些增量，且第四行业 MANHOLE 仍被旧三行业校验拒绝。接真实接口前须提交、编译与新模型联调。

CONTEXT.md 定义行业筛选是作用于整个驾驶舱的全局条件，但原始 map-snapshot 无法过滤地图点位：

• GET /api/cockpit/v1/map-snapshot 无 industry 入参（CockpitMapSnapshotController）。
• CockpitMonitoringPointSummary 没有 industry 与点位类型，服务端与客户端都无从过滤。
• 对照：overview/monitoring、infrastructure/base-archives、monitoring/overview、monitoring/distribution 都已支持 industry 入参。

历史候选路径（已裁定走①）：① map-snapshot 增加 industry 入参与摘要行业/类型字段；② 以 /monitoring/distribution 供地图取数。当前目标以①为准；未提交实现和 MANHOLE 校验需重新验收，不能回退到②而不另行裁定。

G2 map-snapshot 丢弃设备编码，WS 增量无法回联点位（历史交付，现行可用性待复验）

2026-09-18 的 Gogs 票 59/60 关闭记录保留；deviceCodes、WS monitoringPointCode 与事件行点位字段当前仅在未提交工作树中可见，不能把关闭状态等同于当前提交或部署可用。

以下为原始缺口与接入注意事项：

• 内部快照 CockpitMapSnapshot.SourceMonitoringPoint.devices 存在，但 CockpitMapSnapshotService.monitoringPoint()（145–160 行）只用它解析点位状态，没有把设备编码写进响应。
• WS cockpitDeviceStatusDelta 增量只带 deviceCode + 状态，前端拿到增量后无法知道它属于哪个监测点，点位状态无法联动。
• 事件行同样没有归属点位：CockpitCurrentEventsResponse.EventItem 与 history-analysis 的行都缺 monitoringPointCode。
• 现有替代路径代价高：GET /monitoring-points/{monitoringPointCode} 的 devices[].deviceCode 可反推 device→point，但需要逐点请求（N+1）。
• 后端内部已持有该映射（SourceMonitoringPoint.devices；applyDeviceStatusDelta 能按 deviceCode 解析到点位），改动集中在响应层。
• 另注：cockpitSubscribe 回帧只有 {scope, serverUpdatedAt}，无初始状态数组（后端注释明确 REST 是初始快照、WS 只发增量——契约本身成立，前端按此实现）；线上帧状态键是 data.status，而 DTO 字段名是 monitoringState，接入时注意别名。

需要后端：二选一或全做——① CockpitMonitoringPointSummary 输出关联设备编码列表；② WS 增量帧带上 monitoringPointCode；③ 事件行补 monitoringPointCode。

补契约清单（A–H）

以下 A–H 是 2026-09-18 的历史契约切片交付记录，不是新模型下的编译/部署验收。11 个有缺口面板的原始字段表与补契约建议见 research/panel-field-coverage.md 第 4 节；该调研是时间点快照，metricFreshness 端点归属错误，见 I2。当前待补与重新验收项见第十二轮及下方「现行补契约清单」：

• A 跨设备事件读模型（阻塞 currentEvents、historyAnalysis、eventAnalysis、operationOverview）— ✅ 已交付
• B 趋势时间范围可声明（阻塞 historyAnalysis、situationSummary）— ✅ 已交付（range 三档 + 显式区间）
• C 响应/关闭时长聚合（阻塞 responseEfficiency）— ✅ 已交付
• D 应急保障域三件套（阻塞 emergency 整版）— ✅ 已交付
• E 管理信息域 — ✅ 已交付
• F 设施运行信息域 — ✅ 已交付
• G 地图行业/类型维度 — G1 ✅ / G2 ✅ / G3 ✅ / G4 ✅（2026-09-18 由 Gogs #59、#60 全部交付）
• H 跨设备设备状态清单 — ✅ 已交付（monitoring/situation）

实现票 17–20 的 mock 阶段可按已有的面板级聚合响应形状建模：/overview/infrastructure、/overview/monitoring、/overview/warning-settings、/infrastructure/base-archives、/infrastructure/operating-information、/infrastructure/management-information、/infrastructure/emergency-support、/monitoring/overview、/monitoring/distribution、/monitoring/situation、/events/current、/events/history-analysis、/events/handling-efficiency、/events/multidimensional-analysis。

票 18 实施时新暴露的缺口（I 组）—— 本票已接手维护

票 18（运行监测模式面板）实施时核出来的两条缺口，由本票接手并已补正口径 （见上方「现行缺口同步」的 I1/I2 与「现行补契约清单」）。此处保留原始证据供追溯； 现行结论以本票为准。

2026-09-28 更正（维护者裁定后）：原文写「I1 直接决定票 18 能不能 close」， 现已不成立 —— 票 18 的交付面是前端页面，其两处后端边界已转交本票（I1/I2）， 按裁定「后端接口联调由其他票完成，不阻塞后续页面开发」，票 18 已收口（100% / resolved）。 因此本组两条不再阻塞任何前端票；它们是本票自己的后端待办。

I1 map-snapshot 不收 pointStatus，状态筛选到不了一张图 —— 后端待办（不再阻塞票 18）

归属说明（票 18 补记）：本组是票 18 实施期间提出的观察，已于 2026-09-24 交由本票 （#25，ready-for-human）接手维护 —— 本票第十二轮起把 I1/I2 纳入「现行补契约清单」与 Acceptance criteria，并修正了票 18 当时的分析（未关联设备摘要没有状态/设备运行事实， 不能只给点位列表加参数；/overview/monitoring 的 metricFreshness 目前只有空适配器， 不能当作可用数据）。后续裁定与进度以本票为准；票 18 只引用结论，不再自行修订本段。

• 现状：CockpitMapSnapshotController 只收 page/pageSize/snapshotAt/industry/region/deviceType； /monitoring/distribution 收 pointStatus（resolvePointStatus 对认不出的值 400）。
• 为什么这是个真问题：票 18 验收第 5 条是「面板筛选可作用于地图点位」， 而「监测分布」面板按验收第 2 条必须展示状态分布。前端已把状态做成全局筛选条件 （filterStore.pointStatus），它真的作用到面板与台账 —— 但地图不跟随， 于是同一个条件在界面上是「全局」而在数据上只管运行监测模式。
• 前端当前的处理（不假装跟随）：面板上常驻一条说明「状态筛选作用于本面板与监测点台账； map-snapshot 目前不收状态入参，一张图不随状态变化」；没有在前端对已加载标记做过滤 —— 那只对翻到的页生效，会出现「地图上点少了而摘要说已上图 N 个不变」的自相矛盾。 票 18 因此不 close（记 90%），缺口写在这里与交付包草案。
• 需要后端：map-snapshot 增加 pointStatus 入参（取值同 CockpitMonitoringPointStatus 六态， 认不出的值 400 INVALID_REQUEST），并在 mapFilter 里回显生效状态；逐点状态已在响应中， 但未关联设备摘要没有 pointStatus 或设备运行事实，必须先定义与实现它的筛选口径， 不能简单对点位列表加过滤。筛选后的全量坐标汇总、分页及 snapshotAt 均须保持一致。

I2 「逐设备最近采集时间」不在 /monitoring/overview 上

• 现状：metricFreshness（{status, updatedAt, serverUpdatedAt}）在整个 com.zksy.cockpit 包里 只出现在 CockpitOverviewMonitoringResponse（即 /overview/monitoring，总体概览模式的 「运行监测」面板，票 20 的域）。本模式「监测概览」对应的 /monitoring/overview 只有信封级 updatedAt 与 freshness{status,reason,updatedAt,serverUpdatedAt}。
• 影响：票 18 验收第 1 条点名「最近采集时间」，本面板只能呈现数据时间并以 METRIC_FRESHNESS_GAP 说明区别，不伪造一个逐设备采集时间。 票 24 的字段覆盖表把 metricFreshness 记在「监测概览」面板名下，记错了端点（该表需按此修正）。
• 需要后端（或业务口径）：优先明确「最近采集时间」是范围内设备的最新采样时刻还是状态更新时间； 若补给 /monitoring/overview，须从 SourceDevice.sampledAt 等有根据的真实时间聚合， 无样本时显式返回未知/空态。若裁定从 /overview/monitoring 取 metricFreshness， 必须先补真实适配器（该端点当前只有 EmptyCockpitOverviewMonitoringAdapter，源为空时字段为 null）， 并验证 industry/deviceType 两端筛选口径及采样语义一致，不能因为 DTO 有字段便认定数据可用。

现行补契约清单（2026-09-24）

以下是当前需要后端负责人处理的项目；前四项属于契约语义/字段缺口，后两项属于新模型接线的跨端验收缺口。草案与证据索引同步在 后端契约缺口交付包，不要按 2026-09-17 的草案重新建 BT-1…BT-4。

2026-10-08 更新（按新地图决策票 06）：

1. E1 责任区域 → out-of-scope：本项目不存在独立「责任区域」概念；空间范围维度统一为片区（district 0/1/2 → 城南/城北/太常，空值/乱码＝未分区）。管理信息面板改为片区 × 行业视图；响应中的 organizations/ownershipDistribution/unmaintained 字段按决策删除。历史票 17 的「责任区域」验收文字作废。
2. 处置率口径已冻结：状态 5（已结案）工单数 ÷ 状态 0–6 工单数，状态 7 排除；分母为 0 显示不适用；basis 须改为明确的工单分母语义（如 CLOSED_WORK_ORDERS_OVER_ELIGIBLE_WORK_ORDERS），旧 CLOSED_WORK_ORDERS_OVER_TOTAL_EVENTS 与"状态 6/事件总数"口径废止。
3. 异常统计口径已冻结：监测点异常桶 ALARM/WARNING/OFFLINE/EMPTY（WORK_ORDER 不入）；设备/指标异常桶 WARNING/ALARM/EXPIRED/OFFLINE/UNKNOWN；预警处置地图异常点只认设备 WARNING/ALARM 回联（宽清单、窄地图）。
4. 范围维度修订：region 自由串 + regionMap 配置作废，统一按 district（片区）筛选与回显。 本清单中 I1/I2/J1/J2/BT-5 的后端待办性质不变，但执行票的口径以新地图决策 02–06 与规格 07/08/09 为准。

1. I1 地图状态筛选：补 map-snapshot.pointStatus、非法值 400、mapFilter 回显；先定义未关联设备的状态来源与过滤规则，保证快照、全量坐标汇总和分页一致。（2026-09-28 起不再阻塞票 18 —— 票 18 已按前端交付面收口，其状态筛选只作用于面板与台账、界面如实说明；本项是纯后端待办）
2. I2 最近采集时间：/monitoring/overview 无该响应字段；/overview/monitoring 虽有 metricFreshness，目前仅空适配器，不能直接替代。需裁定时间语义并给出真实数据来源；票 24 调研的端点归属已证伪。
3. E1 管理信息责任区域：CockpitInfrastructureManagementInformationResponse 的 organizations/ownershipDistribution/mapFilter 无 region/area，不能把行业当区域。需裁定管理机构—责任区域的关联及数据来源，补可按区域读取的字段/响应，或书面明确不提供并回写票 17 的产品限制。
4. J1 第四正式行业：MANHOLE 已在 spec/手册裁定，工作树的 CockpitTypeIndustry 也能从直接 parentId=4 推导，但 map-snapshot、监测、事件、基础设施与 device-boundary 等服务仍只允许三行业。须统一校验/分类/统计、覆盖多级类型根和跨端契约测试；避免文档宣称可筛井盖而接口 400 或将其排除。
5. J2 工单状态与效率口径：运行时 WorkOrderStatusEnum 是 0–7（5 结案、6 延期），cockpit CockpitWorkOrderStateDictionary 仍是 1–7 且把 0 回退成 7 已取消；真实工单适配器和预警效率服务沿用旧码。须对齐权威枚举、时间线/处置率分子与测试，不得把待派单当取消、延期当结案。
6. BT-5 真实接线与快照一致性：地图/三个监测真实适配器仍在未提交工作树；旧访问器引用目前看已修，但未跑编译/联调。地图适配器每页重新查询，服务目前只比较回传的 snapshotAt，不能单凭时间戳宣称跨页稳定；须按当前 KingbaseES/类型与关系 schema 验证一致性、只读联调和错误/空态。历史 4/22 片不能自动恢复为已验收。

本轮不新建后端票：现有 真实数据接线（程序级） 覆盖真实数据接线，J1/J2 是否纳入其跨端验收待后端 PM 确认；I1、I2、E1 是明确可交给后端 PM 的补契约条目，待裁定并入现有票还是单独建票。本轮未能完成 Gogs 页面的真人验证，远端标签/评论的现时状态不作为新证据。

业务问题（待业务方确认，本票不发明结论）

三条仍未答复；下列为复核后掌握的现状与建议口径，供业务方确认或否决：

1. 「故障」是否等同 stale？ 现状：点位六态 ALARM/WARNING/WORK_ORDER/NORMAL/OFFLINE/EMPTY；指标六态 NORMAL/WARNING/ALARM/EXPIRED/OFFLINE/UNKNOWN，且字典明确 EXPIRED 不与 OFFLINE 合并；situation.abnormalEquipment.abnormalType 是异常分类。建议：业务确认「故障」是否即这些集合的子集，还是要独立桶。
2. 「处置率」是否就是已结案工单数/事件总数（含已取消事件）？ 手册当前目标写 basis = CLOSED_WORK_ORDERS_OVER_TOTAL_EVENTS，但旧 cockpit 效率服务把状态码 6 当作已处理，当前权威枚举中 5 才是已结案、6 是延期中。需先由后端按 J2 对齐计算与测试，再请业务确认分子、分母和取消事件是否计入；不可把旧接口数值直接当已确认口径。
3. 「管理单位」与后端 maintainer（维护单位）是否同一概念？ 现状：management-information 以 organizations + ownershipDistribution + unmaintained 建模，与 maintainer 分开，倾向「不是同一概念」。建议：业务确认「管理单位 = 管理机构/权属单位，maintainer = 维护单位」并回写术语表。

影响的实现票

下表区分前端 mock 已实现的路径与后端当前提交/真实数据仍待验收的路径；历史后端工单关闭不等于现行接口就绪。

票	影响
地图摘要分页与快照	前端分页/快照装载器已有；地图三筛选与点位字段只在后端未提交工作树，跨页 snapshotAt 一致性及真实库接线待验。
WebSocket 状态增量	回联字段 monitoringPointCode 已见于后端未提交工作树；当前 HEAD/真实点位关联数据尚不足以证明端到端可用。
基础设施模式面板	D/E/F 历史契约切片存在，管理信息责任区域 E1 仍缺；四行业 J1 与真实数据接线同样待验。
运行监测模式面板	前端行业/范围筛选已按目标 map-snapshot 路径实现；目标三入参尚未提交、I1 状态筛选不上图、I2 采集时间无可靠读数。该票 90% 未收口，真机走查也待维护者授权。
预警处置面板	历史 A/C/事件坐标字段切片存在，但旧 1–7 工单字典和结案/延期错位会影响事件工单状态及处置率；真实库接线仍待验。
总体概览面板	目标 warning-settings 范围入参已有历史契约代码；J2 处置率错位及空适配器阻止宣称真实读数可用。

Acceptance criteria（后端负责人）

• map-snapshot 支持 industry 入参并在点位摘要中返回 industry 与点位类型。✅ 达成（2026-10-10 第十六轮远端核销）：远端 origin/master 控制器入参为 page/pageSize/snapshotAt/industry/district/deviceType/pointStatus（含原 I1 多值状态筛选），摘要含 deviceCodes/region/industry/typeCode/typeName。
• 点位摘要返回关联设备编码列表，WS 增量可回联点位。✅ 达成（同上核销）：摘要含 deviceCodes；增量帧顶层带 monitoringPointCode（未关联显式 null）。
• A–H 各组补契约与后端负责人逐项确认排期。✅ 达成（经新地图切片票 11/12/13 关闭与真实环境部署复验回写）：25 个 Business*Adapter 全部提交；J1 四行业全服务落地；J2 处置率 basis=CLOSED_WORK_ORDERS_OVER_ELIGIBLE_WORK_ORDERS（5÷0–6、排除 7）；I1 随 pointStatus 入参关闭；全量 8 模块 422/422。
• 3 个业务问题得到业务方答复并回写本票。✅ 已由裁定落地：处置率口径冻结并实现（新地图决策 06 + 切片票 11）；maintainer/district/ownership_unit 独立（management-information 改 districtIndustry 分布，切片票 12）；「故障」按六态/八态字典呈现，无独立桶。

残留（不阻塞 AC，不计入未完成）：① I2 数据时间字段归新地图票 08/规格 08 接手（monitoring/overview 尚未输出，属规格 08 的前端/后端执行范围）；② CockpitHandlingEfficiencyService 第 36 行 javadoc 仍写 "state 6 已结案"（逻辑已正确用常量 5，仅注释陈旧，建议后端顺手更正）；③ 目标部署 192.168.110.30:8301 免鉴权后的无凭据 200 / WS 直订复验 （2026-10-12 维护者裁定取消：实际线上环境另有服务器，该项验证将在生产部署时于真实环境进行，不再作为本票待办）。

进度：100%（已关闭）

第十六轮远端核销（origin/master=989a707e）确认四条 AC 全部达成：原跨领域两项（G1 行业筛选、G2/G4 设备回联）已在远端提交，A–H 补契约经新地图切片票 11/12/13 关闭与真实环境部署复验全部回写，三条业务口径由裁定落地为代码。

• 2026-10-12 维护者裁定：原 95% 待确认项「目标部署 192.168.110.30:8301 复验」取消——该服务器不是实际部署环境，实际线上环境另有服务器；免鉴权与真实接口行为将在生产部署时于真实环境验证，属部署验收而非本票范围。
• 据此本票按维护者裁定关闭为 100%；下文「下一步」的部署复验清单保留作生产部署时的参考检查表（原样可用于任意部署环境）。

下一步（生产部署时的参考检查表）

原为目标部署复验而写的清单，随本票关闭转为生产部署参考检查表——实际线上环境部署免鉴权版本时逐项核对：

1. 确认部署包含提交 8c0771a（及后续切片提交）。验证：部署机上 git log --oneline -3 或 jar 构建时间晚于 2026-09-28。
2. 无凭据 REST 实测：浏览器无痕窗口或 curl（不带 Authorization）访问 <生产地址>/api/cockpit/v1/foundation 与任一业务端点。通过标准：HTTP 200 且 data.readOnly=true。
3. WS 直订实测：浏览器控制台建连 <生产地址>/ws/deviceStatus 后直接发 {"type":"cockpitSubscribe","scope":"all"}（不发 authenticate）。通过标准：收到 cockpitSubscribed 与后续增量帧。
4. 非法参数仍 400：GET /api/cockpit/v1/monitoring/overview?industry=NOPE。通过标准：400 INVALID_REQUEST。
5. 非 GET 仍拒绝：对任一端点 POST。通过标准：405（映射拒绝）或认证拦截，不产生业务写入。
6. 边界与回归自查：① 携带过期 token 的 GET 仍应 200（匿名放行不受无效凭据影响）；② 管理端任一写接口仍要求登录（未带凭据应 401）；③ workOrderReminder 推送仍需 authenticate 帧（工单链路未受影响）。
7. 若生产验证发现问题，另开缺陷票并回链本票 Comment（本票已关闭，不再作为缺陷载体）。

不在本票范围：I2 数据时间（归新地图规格 08 的执行票）；工单状态 javadoc 更正（后端顺手项）；前端面板对接（归前端执行票 14/15/16）；生产部署验证（按维护者裁定在生产环境进行）。

Comments

• 关闭（2026-10-12，维护者裁定）：第十六轮远端核销确认四条 AC 全部达成；原「目标部署 192.168.110.30:8301 复验」按维护者裁定取消——实际线上环境另有服务器，免鉴权与真实接口行为将在生产部署时于真实环境验证（上方清单转为生产部署参考检查表）。本票以 100% 关闭，I2 数据时间残留归新地图规格 08。

• 管网映射修复回写（2026-10-12）：管网编码与设施类型命名空间已关闭。主修复740d896现场五端点管网集合一致为537燃气／996供水／3735排水（5268），未知计数归零、设施名称行业正确；审查P2/P3补齐29d1ae2与合并0a6b108已推送，管网专项29/29通过。同步远端前system187+admin441=628项全过；同步最新报警描述改动后报警生命周期出现1项顺序断言失败，本次管网未改相关文件，不宣称当前全量通过。说明与证据见审查报告、人工核验步骤；阶段界面验收仍归真实联调收口票。

• 本轮已把真实数据接线的后续路线迁移到 驾驶舱真实后端数据接线（决策地图）。票 25 继续作为历史契约事实台账和地图入口，不再单独拆泛化后端执行票。

• 本轮核对到后端 HEAD=origin/master=355a8af；文档记录的本机真实 HTTP/WS 证据已同步，但目标部署 192.168.110.30:8301 不可达，故本票保持 ready-for-human，不关闭。

• 新地图 02–06 仍未 resolved，且是 HITL grilling 决策票；#01 已解决并写回地图与本票，本票不代替其余票回答。

• 新地图 #01 已 resolved：首阶段改为报警—工单闭环读模型，后端拆为工单状态/处置率读模型、报警/工单回联读模型、实时同步三张切片票；驾驶舱只读 REST /api/cockpit/v1/** 与 WS /ws/deviceStatus 的免鉴权范围已由旧鉴权决策同步修订，本票承接后端实现与目标环境证据。

• 新地图 #02–#04 已 resolved：地图摘要状态筛选与未关联设备语义（设备级匹配/点位 OR 归并、多值 pointStatus 含 UNKNOWN/UNASSOCIATED、顶部状态栏全局组合入口、饼图、坐标汇总筛选后口径、自动分批加载 + 右上角手动刷新）、监测数据时间（createdAt＝create_time 跨类型 max，三端点分区级/逐对象级，与 sampledAt 分离，空态不冒充）、real 生命周期（dataSource 只换 transport、与 mock 全同构、严格不回退 mock、刷新调度唯一权威）。对应规格子票 07/08/09 已发布为 ready-for-agent；仅剩 #06（异常统计/处置率/管理字段业务语义）待决策。

• 上位回写（2026-10-09，按决策 01「切片票关闭时回写」义务）：后端三张切片票 11/12/13 已全部 resolved 并经真实环境部署复验通过（复验记录见 票 17）。①票 11 工单状态与处置率：basis=CLOSED_WORK_ORDERS_OVER_ELIGIBLE_WORK_ORDERS（状态5÷状态0–6），提交 3de679c，实测 num/den=2/3、sum(0–6)==分母（基线卡片 02 至 ③）。②票 12 报警/工单读模型 + district：六族 region→district（编码+中文名双字段、脏值 400、districtFilter 回显），管理信息删 organizations/ownershipDistribution/unmaintained，工单逐张显式 associatedWithCurrentEvent，提交 818a6d7，复验 8 项全通过（基线卡片 03 至 ③）。③票 13 报警/工单实时同步：新增 cockpitWorkOrderStateDelta 工单状态增量帧（扫描-比对-变化才推，首扫建基线不推送，scanIntervalMs 诚实标注延迟）+ 设备帧 eventId 透传，提交 d8a6b03，复验 6 项全通过——含真人操作 284 工单（3→4）40 秒内帧到达的端到端证据（基线卡片 04 至 ③）。测试：全量 8 模块 422/422（自基线 299 起累计 +123 例，含三切片全部契约测试）。下游解锁：后端切片 11–13 完成，前端执行票 14/15/16 的后端依赖全部就绪（15/16 的消费侧契约变更已写入各自票正文：regionMap 失效、管理信息字段删除、新帧契约）。Gogs #63 的同文回写需负责人在远端执行（本会话工具只达本地 Markdown 台账）。