# 后端契约缺口交付包（供后端项目经理建票）

Status: ready-for-human
Labels: ready-for-human
Category: handoff
Blocked by: None

本交接包的执行入口已迁移到新地图：[驾驶舱真实后端数据接线（决策地图）](../../cockpit-real-data-wayfinding/map.md)。本文件保留旧 BT-1…BT-8 的历史证据和当前缺口摘要；新地图 01–06 才负责切片拆分、真实联调、前端 real 生命周期和业务语义收口。

## 最新现状（2026-09-28）

- 后端 `HEAD=origin/master=355a8af`。最新文档记录本机 IntelliJ 实例 `127.0.0.1:8301` 的真实登录态验收：401、非法参数 400、同一 `snapshotAt` 多页稳定、点位详情/设备详情链路 200/readOnly、主要端点 200/readOnly、WebSocket `cockpitSubscribe` 回帧成功；另有 16 个非法参数样例全部 400。
- 目标部署 `192.168.110.30:8301` 仍不可达，因此上述是**本机真实 HTTP/WS 证据**，不是目标部署收口证据。凭据未写入仓库、文档或交接包。
- 当前手册已记录：四行业 `MANHOLE`、地图 `map-snapshot` 筛选、Redis 共享快照签发/过期、监测点详情 `snapshotAt` 对齐、设备自身坐标字段、未校核坐标清单-only 降级、当前 KingbaseES 稀疏数据和 23 个空适配器对应的 `@Primary Business*Adapter` 运行边界。
- 仍未收口：地图 `pointStatus` 与未关联设备状态语义、统一 `createdAt`/数据时间、前端 real 生命周期、真实联调证据登记、工单公开字典 1–7 与运行时 0–7 的对齐、目标部署可达性和生产规模性能。
- 本轮没有在 Gogs 新建票；新地图 01–06 均为未解决的 HITL 决策票，后端/前端执行票要等决策地图收口后再创建。

**历史建票记录（2026-09-18）**：五张草案曾在 Gogs `shaoy/pipe-ner-server` 建票；BT-1…BT-4 当时关闭，BT-5 的需求重建与状态见前端票据第十一轮。2026-09-24 本轮未复核 Gogs 远端状态；下表「已交付」仅指历史票据，不代表当前 HEAD/真实库已验收：

| 草案 | Gogs 票号 | 状态 |
| --- | --- | --- |
| BT-1 | [#59](http://192.168.110.30:3000/shaoy/pipe-ner-server/issues/59) | ✅ 已交付并关闭（2026-09-18） |
| BT-2 | [#60](http://192.168.110.30:3000/shaoy/pipe-ner-server/issues/60) | ✅ 已交付并关闭（2026-09-18，走路径①完整） |
| BT-3 | [#61](http://192.168.110.30:3000/shaoy/pipe-ner-server/issues/61) | ✅ 已交付并关闭（2026-09-18） |
| BT-4 | [#62](http://192.168.110.30:3000/shaoy/pipe-ner-server/issues/62) | ✅ 已交付并关闭（2026-09-18） |
| BT-5 | [真实数据接线（程序级）](http://192.168.110.30:3000/shaoy/pipe-ner-server/issues/63) | ⚠️ 第十一轮曾记录旧代码无法编译、进度回到 0%；本轮旧访问器引用已改，但未重新运行编译或联调，当前可验收进度及远端标签未复核 |

BT-6 为可选票，未建。若后端 PM 确认需要，再按下面草案建。

## 现行缺口同步（2026-09-24，本轮只读源码与文档）

后端本地 `HEAD=c5a5b87=origin/master`。当前工作树 `BusinessCockpitDeviceFactResolver` 已改用 `work_order.device_id`，`CockpitTypeIndustry` 与三个监测适配器已改用 `equipment_type.id/parent_id`；此前文档点名的旧访问器编译错误**已不能再作为当前源码事实**，但本轮没有跑 Maven，也没有重查 KingbaseES，不能据此宣称构建/联调通过。后端 `docs/cockpit/README.md` 第 8 节及后端 spec 第 101 行也应按此复核。旧数据库计数、旧 4/22 接线进度只供追溯。

当前已核实的待办按性质分开：

- **I1（BT-7）**：`map-snapshot` 不收 `pointStatus`；逐点已有状态，但**未关联设备摘要没有状态或设备运行事实**，后端须先定未关联设备的状态筛选口径，维护同一 `snapshotAt` 下过滤、分页与全量坐标汇总一致。阻塞前端《运行监测模式面板》收口。
- **I2（BT-8）**：`/monitoring/overview` 无逐设备最近采集时间响应字段。`/overview/monitoring` 虽有 `metricFreshness` DTO，但当前只有空适配器，源为空时仍为 `null`；必须明确采样语义和真实来源，不能把另一个 DTO 当成可用数据。票 24 的旧字段覆盖表把端点归属记错。
- **E1（管理信息责任区域）**：`/infrastructure/management-information` 的 `organizations`、`ownershipDistribution`、`mapFilter` 没有区域/责任区域维度。需裁定组织—责任区域关系与数据源，并补契约或明确不提供；前端《基础设施模式面板》目前如实标缺口。
- **J1（四行业）**：已裁定 `MANHOLE` 为第四正式行业、`typeCode=String(equipment_type.id)`；未提交类型助手仅能由直接 `parentId=4` 推导，`map-snapshot`、监测、事件、基础设施和 `device-boundary` 等服务仍只认三行业。需覆盖类型层级、筛选、统计与契约测试，避免实际返回 400/被排除；归入现有票或新建契约票待 PM 确认。
- **J2（工单状态）**：权威 `WorkOrderStatusEnum` 为 0–7，5 结案、6 延期；cockpit 仍公开 1–7 七态，`byLegacyCode(0)` 落 7 已取消，真实工单适配器和预警效率服务沿用旧码。须对齐字典、时间线、处置率和测试；业务口径仍待人确认，归票范围也待 PM 确认。
- **BT-5（真实接线）**：地图/三个监测真实适配器等只在未提交工作树，文件与 `@Primary` 不证明可运行；地图适配器逐页重新查询，服务仅验证回显 `snapshotAt`，跨页一致性未获实证。须提交/编译/契约测试/当前 KingbaseES 只读联调后，才能恢复接线验收进度。

**本轮没有在 Gogs 新建或修改工单**。历史《Cockpit device-to-point linkage》等四张票的关闭事实保留，但其关键地图/回联字段目前不在 committed HEAD；《真实数据接线（程序级）》涉及新模型接线，I1/I2/E1/J1/J2 的归票与负责人待后端 PM 裁定。下方历史工单草案与旧「BT-5 唯一缺口」结论不得作为现行判据。

## 历史基线（2026-09-24，已被上节最新现状覆盖）

- 当时后端 `HEAD=c5a5b87`，工作树含未提交 cockpit 适配器改动；当时的 Maven 编译失败点是已删除的 `WorkOrder.getDeviceCode`、`EquipmentType.getTypeId/getParentTypeId`。这些引用在上节本轮源码里已改，但编译/联调尚未重跑；历史 4/22 片仍只是工作记录，不是当前验收结果。
- 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`；旧 37 台设备、507 条报警、3 条有效关联已经失效。
- 当前类型表是 `equipment_type.id/type_name/parent_id`，没有旧 `type_id/parent_type_id`；当前工单表由 `device_id` 关联设备，报警通过 `alarm_data.order_id` 关联工单。当前工单状态为 0–7（含 6 延期中），以 ADR-0010 为准。
- 已裁定：公开 `typeCode` 使用 `equipment_type.id`（JSON 为字符串）；井盖为第四正式行业 `MANHOLE`；当前无可信坐标校核来源时保持 `renderable=false`，不以通用经纬度范围自动放行；联调以当前真实 KingbaseES 数据为基准。旧三行业校验与类型映射尚未实现。
- 已澄清“工单字典”指代码枚举 `WorkOrderStatusEnum`（0–7，见 ADR-0010），不是数据库字典表；当前 `app_user.sys_dict_type/sys_dict_data` 无工单状态条目是符合现状的，无须另找表。修复编译、跑契约测试与当前库联调前，不沿用历史 BT-5 完成度结论。

### 历史复核基线（2026-09-17，2026-09-18 第三轮复验无变化；仅供追溯）

- 后端仓库 `E:\pipe-ner-server`，本地 HEAD `ed0ace5`（`test(cockpit): add contract integration environment and handoff (#43)`）。
- 远端 `origin` HEAD 仍是 `e2b4e45`（#42）——**#43 尚未推送**，联调前请确认部署来源是其预期提交。
- 复核方式：只读阅读控制器、响应类、适配器与 `docs/cockpit/README.md`；未改动后端任何文件，未跑构建或调试命令。

## 一、完成情况总览（2026-09-17 历史快照）

下表只保留最初建票的时间点证据，**不是当前缺口清单**；现行判定请读本文件「现行缺口同步」与前端《后端契约缺口待办（跨领域两项 + 补契约清单）》：

| 项 | 内容 | 状态 | 证据 |
| --- | --- | --- | --- |
| A1 | 跨设备当前事件流 | ✅ 已交付 | `GET /api/cockpit/v1/events/current`（`mode` 必填，`level`/`industry`/`status`/分页）；`CockpitCurrentEventsResponse.EventItem` 含 `eventNo/eventType/level/levelColor/status/value/unit/deviceCode/location/industry/longitude/latitude/workOrderSummary` + `sections{events,workOrders}` + `mapFilter.deviceCodes` |
| A2 | 跨设备历史事件流 + 时间范围 | ✅ 已交付 | `GET /api/cockpit/v1/events/history-analysis`（`eventFamily` 必填 + `startTime`/`endTime`）；回显 `Range{type,startTime,endTime}` |
| B | 趋势时间范围可声明 | ⚠️ 仅剩一处 | `monitoring/situation`、`infrastructure/operating-information`、`events/history-analysis`、`events/handling-efficiency`、`events/multidimensional-analysis` 均已支持范围参数；`overview/warning-settings` 仍只有 `mode`（→ 见 BT-3） |
| C | 响应/关闭时长聚合 | ✅ 已交付 | `GET /api/cockpit/v1/events/handling-efficiency`：`averageDuration{value,unit,sampleCount,state,reason}` + `durationTrend[]` + 工单 `durationHours`；口径已冻结 `basis = CLOSED_WORK_ORDERS_OVER_TOTAL_EVENTS` |
| D | 应急保障域三件套 | ✅ 已交付 | `GET /api/cockpit/v1/infrastructure/emergency-support` |
| E | 管理信息域 | ✅ 已交付 | `GET /api/cockpit/v1/infrastructure/management-information` |
| F | 设施/行业运行信息 | ✅ 已交付 | `GET /api/cockpit/v1/infrastructure/operating-information` |
| G1 | 全局行业筛选落到地图点位 | ❌ 未交付（且路径待裁定） | `map-snapshot` 入参仍只有 `page/pageSize/snapshotAt`；但 `/monitoring/distribution`（#37）已带 `industry`/`deviceType`/`pointStatus`/`region` 与逐点 `industry`/`deviceType`（→ 见 BT-2） |
| G2 | 点位摘要补 `industry`、类型、徽标 | ❌ 未交付 | `CockpitMonitoringPointSummary` 仍只有 `pointCode/pointName/pointStatus/statusReasons/longitude/latitude/coordinateValidation` |
| G3 | 未关联设备补 `industry`、设备类型 | ✅ 已交付 | `CockpitMonitoringDistributionResponse.UnassociatedEquipmentMarker` |
| G4 | 设备编码回联点位（WS 增量可用） | ❌ 未交付 | 四个增量 DTO 均只有 `deviceCode` + 状态，无 `monitoringPointCode`（→ 见 BT-1） |
| H | 跨设备设备状态清单 | ✅ 已交付 | `GET /api/cockpit/v1/monitoring/situation`：`abnormalEquipment[]{deviceCode,deviceName,deviceType,industry,region,abnormalType,status,statusReasons,longitude,latitude,coordinateValidation}` + 分页 + `mapFilter.deviceCodes` |

另有 #43 交付的**移交与联调手册**：`docs/cockpit/README.md`（契约总则、字典冻结、端点清单、分页/快照/错误口径、WebSocket 增量、启动与联调检查表、容器化评估、已知未验证项）。这份手册本身已解答了票 25 里「字段名、语义、字典」类的问题，不需要再建票。

## 二、真实数据接线状态（程序级缺口）

后端目前交付的是**契约**，不是**数据**：

- 历史基线（2026-09-17）：23 个 cockpit 适配器接口中，22 个只装配了 `Empty*Adapter`；唯一真实实现是工单读模型。
- 未提交工作树已新增地图与监测链路的 4 个真实适配器，先前已删除的类型/工单访问器在本轮源码检查中已更换；**本轮未跑 Maven 或联调，不能视为 4/22 已交付**。
- 各切片在 `docs/cockpit/` 下的 `*-demo.html` 是内嵌 fixtures，不代表真实库数据。
- 后端手册记录的现行数据库样本极小且关系稀疏；本轮未重查数据库，验收需以当前实体/schema 与真实库重新验证。

后果：BT-5 的需求已重建，但历史“全空快照”与“4/22 进度”都不是当前可验收结论；票面此前记载它从 `needs-triage` 转回 `ready-for-agent`，本轮未通过 Gogs 真人验证复核标签。

## 三、历史后端工单草案与新增待裁定项

BT-1…BT-5 已在 2026-09-18 建票，下列原始草案供追溯，**不要重复提交到 Gogs**；BT-7/BT-8 与 E1 是 2026-09-24 仍待后端 PM 裁定归票的新增需求。

### BT-1 Cockpit device-to-point linkage（REST + WebSocket）→ Gogs #59 ✅ 已交付

**背景与证据**

- `CockpitMapSnapshotService.monitoringPoint()` 只把 `CockpitMapSnapshot.SourceMonitoringPoint.devices` 用于解析点位状态，没有写进响应；`CockpitMonitoringPointSummary` 没有任何设备字段。
- WS 增量只带 `deviceCode`：`CockpitMonitoringDistributionDeviceStatusDelta`、`CockpitMonitoringOverviewDeviceStatusDelta`、`CockpitMonitoringSituationDeviceStatusDelta`、`CockpitOverviewMonitoringDeviceStatusDelta` 四个 DTO 均无 `monitoringPointCode`；`DeviceStatusWebSocketHandler` 全文无点位字段。
- 事件读模型的行也没有归属点位：`CockpitCurrentEventsResponse.EventItem` 与 `history-analysis` 的 row 都缺 `monitoringPointCode`。
- 现有可用但代价高的替代路径：`GET /monitoring-points/{monitoringPointCode}` 的 `devices[].deviceCode`（逐点 N+1）。
- 后端内部已持有该映射（`SourceMonitoringPoint.devices`；`applyDeviceStatusDelta` 能按 `deviceCode` 解析到点位），因此改动量集中在响应层。

**要做什么**（建议 ①+②，③ 视事件面板需要）

1. `CockpitMonitoringPointSummary` 增加 `deviceCodes`（关联设备编码列表），并顺带补 `industry` 与 `typeCode`。
2. WS 增量帧增加 `monitoringPointCode`（未关联设备为 `null` / 不出现）。
3. 事件读模型行增加 `monitoringPointCode` 与 `monitoringPointName`。

**验收标准**

- 点位摘要返回关联设备编码；同一 `snapshotAt` 下与 `/monitoring-points/{code}` 的 `devices[]` 一致，且不产生重复点位。
- WS 增量给出 `monitoringPointCode`；未关联设备显式 `null`，不静默丢失。
- 事件行返回 `monitoringPointCode`，无归属时为 `null`。
- 契约测试覆盖 REST 与 WS 两侧；`docs/cockpit/README.md` 与字段字典同步更新。

**解除阻塞的前端票**：15（WebSocket 状态联动）、08（地图摘要）、19（当前预警 / 历史分析上图联动）。

### BT-2 全局行业筛选落图：路径裁定 + 落地 → Gogs #60 ✅ 已交付（走路径①完整）

**背景与证据**

- `CONTEXT.md` 定义行业筛选是作用于整个驾驶舱的全局条件。
- `GET /map-snapshot` 没有 `industry` 入参；`CockpitMonitoringPointSummary` 也没有 `industry`/类型字段，服务端与客户端都无从过滤。
- 但 `GET /monitoring/distribution`（#37）与 `GET /monitoring/overview` 已支持 `industry`/`deviceType`，distribution 还逐点返回 `industry`/`deviceType` 并给 `mapFilter{industry,deviceType,pointStatus,region,pointCodes,deviceCodes}`。

**要做什么**（二选一，并在 `docs/cockpit/README.md` 第 3 节写明结论）

1. 给 `map-snapshot` 增加 `industry`（以及 `deviceType`）入参，并给 `CockpitMonitoringPointSummary` 补 `industry`/`typeCode`；或
2. 正式声明地图筛选以 `/monitoring/distribution` 为准，`map-snapshot` 保持纯分页快照，前端改取数路径。

**验收标准**

- 决策结论写入契约手册，前端不需要猜路径。
- 选定路径端到端可用：服务端完成过滤，`mapFilter` 回显实际生效范围，分页与 `snapshotAt` 语义不变。

**解除阻塞的前端票**：18（运行监测面板，含验收项「面板筛选可作用于地图点位」与监测点台账）、08（地图摘要）。

### BT-3 warning-settings 趋势窗口可声明 → Gogs #61 ✅ 已交付

**背景与证据**：其余切片都已接受时间范围并回显 `Range`，只有 `GET /overview/warning-settings` 仍只有 `mode`；`CockpitOverviewWarningSettingsResponse.Range{type,start,end}` 结构已存在，窗口目前固定。

**要做什么**：给该端点增加 `range` / `startTime` / `endTime` 入参，填充 `Range` 与 `trend[].bucket`，沿用兄弟切片的范围语义。

**验收标准**：非法范围返回 400 `INVALID_REQUEST`；`range` 回显实际生效区间；趋势桶跟随窗口变化；契约测试与手册同步。

**解除阻塞的前端票**：20（态势总览近 7 日趋势）、总体概览的预警设置面板。

### BT-4 事件行补 coordinateValidation 与报警阈值 → Gogs #62 ✅ 已交付

**背景与证据**：字典已冻结「无效或未验证坐标 `renderable=false`，禁止渲染」，`CockpitMonitoringDistributionResponse`、`CockpitMonitoringSituationResponse` 等都已携带 `CockpitCoordinateValidation`；但 `CockpitCurrentEventsResponse.EventItem` 只有 `longitude`/`latitude`，没有 `coordinateValidation`，事件因此无法判定能否上图。A1 原建议中的 `thresholdMinValue`/`thresholdMaxValue`（仅报警族）同样缺失。

**要做什么**：事件读模型（`events/current` 与 `events/history-analysis`）的行补 `coordinateValidation`；报警族在数据可得时补阈值字段。

**验收标准**：每条事件携带 `coordinateValidation`（`state`/`reason`/`renderable`/`crs`）；坐标缺失或未验证时 `renderable=false` 且有 reason；契约测试与手册同步。

**解除阻塞的前端票**：19（当前预警上图、历史分析定位）。

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

**背景与证据**：见上文「二、真实数据接线状态」——23 个适配器接口中 22 个仍为空实现（不计 `/foundation` 自检则 21/22）。

**要做什么**：按切片补真实适配器（复用既有表与服务，遵循 `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 阶段不受阻）。

### BT-6（可选，待确认）situation 支持 monitoringState 过滤

**背景**：H 的原始需求是「跨设备设备状态清单（如离线设备清单）」。`/monitoring/situation` 已给出分页的 `abnormalEquipment[]`，但它按 `industry`/`deviceType`/时间过滤，没有 `monitoringState` 入参。

**要做什么**：若 `operationOverview` 的离线设备清单需要按状态取数，给 `situation` 增加 `monitoringState`（六态字典）入参。

**验收标准**：传 `OFFLINE` 只返回离线设备；`mapFilter` 回显；不改变默认行为。

**备注**：若 `abnormalEquipment` 已满足面板需求，此票不必建。

### BT-7 地图快照补 `pointStatus` 入参（票 18 实施时新暴露，**阻塞票 18 收口**）

> **归属说明（票 18 补记）**：本草案由票 18 实施时提出，**已由票 25 接手**——
> 其 2026-09-24「现行缺口同步」把本条记为 **I1（BT-7）** 并补正了口径
> （未关联设备摘要没有状态/设备运行事实，须先定义其筛选口径；同一 `snapshotAt` 下
> 过滤、分页与全量坐标汇总要一致）。**后续修订与排期以票 25 为准**，本段不再由票 18 维护。

**背景与证据**

- 票 25 第 3 节已冻结「全局筛选落到地图以 `map-snapshot` 为准、服务端完成过滤」，
  且该端点当前收 `industry`/`region`/`deviceType` 三入参并回显 `mapFilter`。
- 但**状态维度没有落图路径**：`/monitoring/distribution` 收 `pointStatus`
  （`resolvePointStatus` 对认不出的值 400），`map-snapshot` 不收。
- 票 18 验收第 5 条是「面板筛选可作用于地图点位」，而验收第 2 条要求「监测分布」展示**状态分布**。
  前端已把状态做成全局筛选条件（`filterStore.pointStatus`），它真的作用到面板与台账，
  但地图不跟随 —— 同一个条件在界面上是「全局」而在数据上只管运行监测模式。
- 逐点状态已在响应里（`CockpitMonitoringPointSummary.pointStatus`），但未关联设备摘要没有同等状态字段；**不是**只加参数就能安全过滤整个快照。

**要做什么**

1. `CockpitMapSnapshotController` 增加 `pointStatus` 入参（取值 `CockpitMonitoringPointStatus` 六态：
   `ALARM`/`WARNING`/`WORK_ORDER`/`NORMAL`/`OFFLINE`/`EMPTY`），认不出的值 400 `INVALID_REQUEST`
   （与 `/monitoring/distribution` 的 `resolvePointStatus` 同一口径）。
2. 点位已有 `pointStatus`，但未关联设备快照与摘要**没有状态/设备实时事实**；先裁定它如何参与状态筛选，补可信的状态来源或明示不参与，不能把它简单当成点位状态。
3. 服务端按裁定后的规则过滤点位及未关联设备；`mapFilter` 增加 `pointStatus` 回显。保持 `snapshotAt` 跨页一致，并按筛选范围全量计算 `coordinateValidation` 汇总。

**验收标准**

- 传 `pointStatus=ALARM` 只返回符合状态的点位；未关联设备按已裁定的状态规则处理、不能被误算作无设备点位；`mapFilter.pointStatus` 回显，分页、`snapshotAt` 与全量坐标汇总一致。
- 不传时行为与今天的目标快照契约一致（**默认不排除任何对象**）；但 `industry/region/deviceType` 三筛选目前也只在后端未提交工作树，不能用 committed HEAD 的行为冒充对照组。
- 非法值 400 `INVALID_REQUEST`，文案与兄弟切片一致。

**当前前端处理（不假装跟随）**：面板上常驻一条说明「状态筛选作用于本面板与监测点台账；
`map-snapshot` 目前不收状态入参，一张图不随状态变化」；**没有**在前端对已加载标记做过滤 ——
那只对翻到的页生效，会出现「地图上点少了而摘要说已上图 N 个不变」的自相矛盾。
票 18 因此**不 close**（记 90%）。

### BT-8 「逐设备最近采集时间」补到 `/monitoring/overview`（或裁定取别的端点）

> **归属说明（票 18 补记）**：同 BT-7 —— 已由票 25 接手并记为 **I2（BT-8）**，
> 且补正了口径（`/overview/monitoring` 的 `metricFreshness` 当前只有空适配器，
> 不能当作可用数据）。**后续修订与排期以票 25 为准**。

**背景与证据**

- 票 18 验收第 1 条点名「监测概览展示…最近采集时间」。
- `metricFreshness`（`{status, updatedAt, serverUpdatedAt}`）在整个 `com.zksy.cockpit` 包里
  **只出现在** `CockpitOverviewMonitoringResponse` —— 那是 `/overview/monitoring`
  （总体概览模式的「运行监测」面板，票 20 的域）。
- 本模式「监测概览」对应的 `/monitoring/overview` 只有信封级 `updatedAt` 与
  `freshness{status,reason,updatedAt,serverUpdatedAt}`，没有逐指标的采集时间。
- 票 24 的字段覆盖表把 `metricFreshness` 记在「监测概览」面板名下，**记错了端点**（该表需按此修正）。

**要做什么**（二选一，需后端或业务裁定）

1. 给 `/monitoring/overview` 补 `metricFreshness`（与 `/overview/monitoring` 同结构）；或
2. 明确「监测概览」的采集时间口径就取 `/overview/monitoring` 的那一份
   （代价：该面板要拉第二个端点，且两个端点的筛选入参不完全一致）。

**验收标准**

- 选 1：先裁定「最近采集时间」是采样时刻还是状态更新时间；`/monitoring/overview` 从可信源（如现有设备 `sampledAt`，经业务确认后）聚合并返回生效时间与空态，不用响应信封的 `updatedAt` 冒充。
- 选 2：`/overview/monitoring` 的 `metricFreshness` 目前只有 DTO，真实适配器未接且源为空时为 `null`；先补真实接线，再在契约手册明确时间与筛选语义，并验证 `industry`/`deviceType` 与本面板一致，前端才能改取数路径。

**当前前端处理**：面板用信封级 `updatedAt` 呈现「数据时间」，并以
`METRIC_FRESHNESS_GAP`（`domain/monitoringPanels.js`）在界面上说明它**不是**逐设备采集时间；
**不伪造**一个采集时间。

### E1 管理信息补责任区域（票 17 的既有缺口）

**证据**：`CockpitInfrastructureManagementInformationResponse` 只含 `organizations`、`ownershipDistribution`、`mapFilter` 等机构/权属结构，没有 `region`/`area` 或组织—责任区域关系；相邻 `base-archives` 的 `regionDistribution` 是汇总，不等价于逐管理单位责任区域。前端《基础设施模式面板》已将该差异如实呈现。

**交由后端/业务裁定**：确认管理单位与责任区域的关系和可信来源；有来源则补可按区域查询/展示的读模型字段及测试，无来源则明确拒绝并记录口径，前端继续标示缺口，不能把 `industry` 冒充责任区域。

### J1/J2 当前领域模型跨端对齐（建议并入 BT-5，待 PM 确认）

- J1：`MANHOLE` 已被裁定为正式第四行业，但过滤/统计仍有三行业白名单；对外 `typeCode` 已裁定为类型主键字符串，未提交的直接父级推导助手还需覆盖多级类型树。统一地图、监测、事件、基础设施和设备边界的校验/分类与测试。
- J2：后端权威工单状态为 0–7，cockpit 字典仍为 1–7，0 被映成已取消、5 被读成待验收、6 被读成已结案；需修工单摘要、时间线和效率聚合。旧口径不可当成当前真实库验收结果。
- BT-5：地图与三个监测适配器未提交；新模型下编译与当前 KingbaseES 联调尚未重新验证。地图适配器每页重新查询，服务目前只校验回显的 `snapshotAt`，不能据此证明分页锁住同一份数据。建议写入后端《真实数据接线（程序级）》的实现验收，由 PM 确认范围，不重复建泛化票。

## 四、需要业务方口径（不是后端工单）

1. **「故障」是什么？** 字典现状：点位六态 `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` 建模，与维护单位分开。需业务确认这一区分并回写术语表。

## 五、给项目经理的决策点

1. ~~G1 的落图路径二选一（BT-2 的两个方案）。~~ **已裁定（2026-09-18）**：走路径①——地图以 `map-snapshot` 为准，且补全 `industry`/`region`/`deviceType` 三入参与 `mapFilter` 回显；结论见 `docs/cockpit/README.md` 第 3 节。
2. ~~G2/G4 的实现取一或全做（BT-1 的 ①②③）。~~ **已全部实现**：BT-1（#59）交付 G4 三件套，BT-2（#60）交付 G1+G2。
3. **现行后端缺口不止 BT-5**：I1/BT-7 的未关联设备状态口径、I2/BT-8 的可信采集时间、E1 的管理责任区域待 PM 裁定归票；J1 四行业与 J2 工单状态对齐是否并入《真实数据接线（程序级）》待 PM 确认，真实接线/分页一致性仍需验收。BT-1…BT-4 的关闭是历史票据事实，不代替新 schema 联调。
4. 当前本地 `HEAD=c5a5b87=origin/master`，地图三筛选、回联字段及四个真实适配器只在未提交工作树；旧「#43 未推送、远端仍是 #42」只是 2026-09-17 历史事实。联调前确认来源提交及构建/数据库证据。
5. 各切片 `*-demo.html` 是 fixtures，不是真实数据；手册第 7/8 节的容器化与性能均为未验证项。
6. **票 18 实施时新暴露两条**（2026-09-18，草案见上 BT-7/BT-8）：
   - **BT-7 `map-snapshot` 补 `pointStatus` 入参** —— 决定票 18 能否收口（其验收第 5 条「面板筛选可作用于地图点位」
     的状态维度缺后端路径）。
   - **BT-8 逐设备最近采集时间归属** —— 或给 `/monitoring/overview` 补 `metricFreshness`，
     或裁定该口径取 `/overview/monitoring`。两条都需要后端或业务给结论，前端已按「如实说明、不伪造」处理。