|
|
@@ -1,8 +1,8 @@
|
|
|
-# 25: 后端契约缺口待办（跨领域两项 + 补契约清单）
|
|
|
+# 25: 后端契约缺口待办（跨领域两项 + 补契约清单）
|
|
|
|
|
|
Status: ready-for-human
|
|
|
Labels: ready-for-human
|
|
|
-**Category:** enhancement
|
|
|
+Category: enhancement
|
|
|
Blocked by: None
|
|
|
|
|
|
> 不阻塞 23 张实现票的 mock 阶段；阻塞的是这些票接真实接口。
|
|
|
@@ -11,66 +11,123 @@ Blocked by: None
|
|
|
|
|
|
## Why ready-for-human
|
|
|
|
|
|
-结论来自 [24: 面板字段与后端契约覆盖调研](24-panel-field-coverage.md)（已 resolved）与主会话的逐条核实。缺口分两类：
|
|
|
+结论来自 [24: 面板字段与后端契约覆盖调研](24-panel-field-coverage.md)（已 resolved）、2026-09-17 对后端仓库的复核，以及主会话的逐条核实。缺口分两类：
|
|
|
|
|
|
-1. **后端补契约**——需要后端负责人实现，agent 无法代做。
|
|
|
+1. **后端补契约**——需要后端负责人实现。本仓库工作区写权限只覆盖 `E:\City-Lifeline-Cockpit-TvT`，且后端仓库当时有并行会话的未提交改动，不适合由本票直接改。
|
|
|
2. **业务定义确认**——需要业务方回答，本票不发明结论。
|
|
|
|
|
|
-## G1 全局行业筛选落不到地图点位（已核实）
|
|
|
+## 复核记录（2026-09-17）
|
|
|
|
|
|
-`CONTEXT.md` 定义行业筛选是作用于整个驾驶舱的全局条件，但今天它无法过滤地图点位：
|
|
|
+复核方式：只读阅读后端仓库 `E:\pipe-ner-server` 的控制器与响应类（`com.zksy.web.controller.cockpit`、`com.zksy.cockpit.*`）；未改动后端任何文件，未跑构建或调试命令。
|
|
|
+
|
|
|
+### 结论：8 组补契约中 4 组已交付，2 项跨领域缺口仍在，跨设备读模型仍未动
|
|
|
+
|
|
|
+后端在 2026-09-16～09-17 落地了 5 个新读模型端点（对应后端 Gogs #33–#37）：
|
|
|
+
|
|
|
+| 端点 | Gogs | 提交状态 | 对应补契约组 |
|
|
|
+| --- | --- | --- | --- |
|
|
|
+| `GET /api/cockpit/v1/infrastructure/operating-information` | #33 | 已提交 | F 运行信息 |
|
|
|
+| `GET /api/cockpit/v1/infrastructure/management-information` | #34 | 已提交 | E 管理信息 |
|
|
|
+| `GET /api/cockpit/v1/infrastructure/emergency-support` | #35 | 已提交 | D 应急保障 |
|
|
|
+| `GET /api/cockpit/v1/monitoring/overview` | #36 | 已提交（当前 HEAD） | 监测概览 |
|
|
|
+| `GET /api/cockpit/v1/monitoring/distribution` | #37 | **工作区未提交** | G 行业/类型维度、G3 |
|
|
|
+
|
|
|
+这 5 个切片与既有切片同样采用「契约 + 空适配器 + demo」形态，真实数据源尚未接线。对「补契约」这一定位算缺口关闭，对「能取到真实数据」则仍待后端后续接线。
|
|
|
+
|
|
|
+### 逐项判定
|
|
|
+
|
|
|
+| 组 | 内容 | 今日状态 | 证据 |
|
|
|
+| --- | --- | --- | --- |
|
|
|
+| D | 应急保障域三件套 | ✅ 已交付 | `CockpitInfrastructureEmergencySupportResponse`：`Totals{emergencyResourceCount,hazardSourceCount,protectionTargetCount,totalObjectCount}` + `Sections{emergencyResources,hazardSources,protectionTargets}`（每项 `objectCode/objectName/category/industry/area/pointCodes/eventAssociations`）+ 三类分布 + `eventSummary` + `mapFilter` + `excluded`；入参 `category/industry/area` |
|
|
|
+| E | 管理信息域 | ✅ 已交付 | `CockpitInfrastructureManagementInformationResponse`：`organizations{organizationCode,organizationName,industry,facilityCount,equipmentCount,unmaintained,ownershipDistribution}` + `ownershipDistribution` + `totals.unmaintainedCount` + `mapFilter{industry,organizationCode}`；入参 `industry/organizationCode`。原建议的 `managementUnits/ownershipUnits/responsibilityZones` 三数组未采用，改为「机构 + 权属分布」形状 |
|
|
|
+| F | 设施/行业运行信息 | ✅ 已交付 | `CockpitInfrastructureOperatingInformationResponse`：`industries[].metrics[]{metricCode,value,capacityValue,loadRatio,loadState,sampledAt,freshness,trend,abnormal,pointCodes}` + `abnormalMetricCount` + `mapFilter{industry,metricCodes,pointCodes}`；入参 `industry/range/from/to` |
|
|
|
+| G3 | 未关联设备补 `industry` 与设备类型 | ✅ 已交付 | `CockpitMonitoringDistributionResponse.UnassociatedEquipmentMarker{deviceCode,deviceName,region,industry,deviceType,pointStatus,...}` |
|
|
|
+| G1 | `map-snapshot` 加 `industry` 入参 | ❌ 未交付 | `CockpitMapSnapshotController` 第 35–39 行入参仍只有 `page/pageSize/snapshotAt` |
|
|
|
+| G2 | 点位摘要加 `industry`、点位类型与徽标 | ❌ 未交付 | `CockpitMonitoringPointSummary` 仍只有 `pointCode/pointName/pointStatus/statusReasons/longitude/latitude/coordinateValidation` 7 个字段 |
|
|
|
+| G4 | 点位摘要返回关联设备编码 | ❌ 未交付 | 同上；`monitoring/distribution` 的 `mapFilter.deviceCodes` 是扁平列表，不构成 device→point 映射 |
|
|
|
+| A | 跨设备当前/历史事件流 | ❌ 未交付 | 事件端点仍只有 `equipments/{deviceCode}/events/current` 与 `events/history` |
|
|
|
+| B | 趋势时间范围可声明 | ⚠️ 部分 | `operating-information` 已有 `range/from/to`；`overview/warning-settings` 入参仍只有 `mode`（`Response.Range{type,start,end}` 结构已在，属加参数） |
|
|
|
+| C | 响应/关闭时长聚合 | ❌ 未交付 | cockpit 包内无任何 duration/Seconds 字段；#31 落地的是比率型 `handlingEfficiency{numerator,denominator,value,state,reason}` 与 `cancelledCount/unlinkedEventCount`，不是时长 |
|
|
|
+| H | 跨设备设备状态清单 | ❌ 未交付 | 只有 `Counts.Status{online,offline,stale,unknownOrMissing,denominator}` 分桶，无逐设备清单；无 `equipments/status` 端点 |
|
|
|
+
|
|
|
+### 两个跨领域缺口的补充证据
|
|
|
+
|
|
|
+`monitoring/distribution`（#37）已能承接全局行业筛选的**意图**：入参 `industry/deviceType/pointStatus/region`，逐点返回 `industry`/`deviceType`，并给 `mapFilter{industry,deviceType,pointStatus,region,pointCodes,deviceCodes}`。因此「给 `map-snapshot` 加 `industry` 入参」不再是唯一可行路径——采用哪条路径属后端设计决定，本票不代为选择，改为在验收项里标注「实现路径待后端负责人定」。
|
|
|
+
|
|
|
+WS 侧仍未解决：`CockpitMonitoringDistributionDeviceStatusDelta`、`CockpitMonitoringOverviewDeviceStatusDelta`、`CockpitOverviewMonitoringDeviceStatusDelta` 三个增量 DTO 都只带 `deviceCode` + `monitoringState`（外加 `sampledAt`/`statusTime`/`serverUpdatedAt`），`DeviceStatusWebSocketHandler` 全文没有 `pointCode`/`monitoringPointCode`。但后端内部已持有映射（`CockpitMonitoringDistributionSnapshot.SourceMonitoringPoint.devices`，且服务端 `applyDeviceStatusDelta` 能按 `deviceCode` 解析到点位），所以最小改动是二选一：点位摘要输出关联设备编码，或 WS 增量帧直接带上 `monitoringPointCode`。
|
|
|
+
|
|
|
+## G1 全局行业筛选落不到地图点位（已核实；实现路径待后端负责人定）
|
|
|
+
|
|
|
+`CONTEXT.md` 定义行业筛选是作用于整个驾驶舱的全局条件，但 `map-snapshot` 至今无法过滤地图点位：
|
|
|
|
|
|
- `GET /api/cockpit/v1/map-snapshot` 无 `industry` 入参（`CockpitMapSnapshotController`）。
|
|
|
- `CockpitMonitoringPointSummary` 字段仅 `pointCode / pointName / pointStatus / statusReasons / longitude / latitude / coordinateValidation`——没有 `industry` 与点位类型，服务端与客户端都无从过滤。
|
|
|
-- 对照：`overview/monitoring` 与 `infrastructure/base-archives` 已支持 `industry` 入参，说明后端具备该维度，只是没给地图摘要。
|
|
|
+- 对照：`overview/monitoring`、`infrastructure/base-archives`、`monitoring/overview`、`monitoring/distribution` 都已支持 `industry` 入参，说明后端具备该维度，只是没给地图摘要。
|
|
|
|
|
|
-**需要后端**：`map-snapshot` 增加 `industry` 入参；`CockpitMonitoringPointSummary` 增加 `industry` 与点位类型字段。
|
|
|
+**需要后端定路径（二选一或都做）**：① `map-snapshot` 增加 `industry` 入参，`CockpitMonitoringPointSummary` 增加 `industry` 与点位类型字段；② 地图点位改由 `monitoring/distribution` 提供——它已有 `industry`/`deviceType`/`pointStatus`/`region` 入参与逐点 `industry`/`deviceType`，但该端点尚未提交，且前端实现票需相应改取数路径。
|
|
|
|
|
|
-## G2 map-snapshot 丢弃设备编码，WS 增量无法回联点位（已核实）
|
|
|
+## G2 map-snapshot 丢弃设备编码，WS 增量无法回联点位（已核实，仍缺）
|
|
|
|
|
|
- 内部快照 `CockpitMapSnapshot.SourceMonitoringPoint.devices` 存在，但 `CockpitMapSnapshotService.monitoringPoint()`（145–160 行）只用它解析点位状态，**没有把设备编码写进响应**。
|
|
|
- WS `cockpitDeviceStatusDelta` 增量只带 `deviceCode` + 状态，前端拿到增量后无法知道它属于哪个监测点，点位状态无法联动。
|
|
|
- 另外 `cockpitSubscribe` 回帧只有 `{scope, serverUpdatedAt}`，无初始状态数组（后端注释明确 REST 是初始快照、WS 只发增量——契约本身成立，前端需按此实现）；线上帧的状态键是 `data.status`，而后端 DTO `CockpitOverviewMonitoringDeviceStatusDelta` 命名为 `monitoringState`，接入时注意别名。
|
|
|
|
|
|
-**需要后端**：`CockpitMonitoringPointSummary` 输出关联设备编码列表。
|
|
|
+**需要后端**：`CockpitMonitoringPointSummary` 输出关联设备编码列表，或 WS 增量帧带上 `monitoringPointCode`——后端两处都已持有该映射，改动量都不大。
|
|
|
|
|
|
## 补契约清单（A–H）
|
|
|
|
|
|
-11 个有缺口面板的完整字段表与分组补契约建议（含字段名、语义、是否需要新端点）见 [research/panel-field-coverage.md](../research/panel-field-coverage.md) 第 4 节，共 8 组：
|
|
|
+11 个有缺口面板的完整字段表与分组补契约建议（含字段名、语义、是否需要新端点）见 [research/panel-field-coverage.md](../research/panel-field-coverage.md) 第 4 节，共 8 组；各组今日状态见上「逐项判定」：
|
|
|
+
|
|
|
+- A 跨设备当前事件读模型（阻塞 `currentEvents`）— ❌ 未交付
|
|
|
+- B 跨设备带时间范围的历史流 + 趋势 `range`（阻塞 `historyAnalysis`）— ⚠️ 仅 `operating-information` 有 `range`；`warning-settings` 仍缺
|
|
|
+- C 响应/关闭时长聚合（阻塞 `responseEfficiency`）— ❌ 未交付
|
|
|
+- D 应急保障域三件套（阻塞 `emergency` 整版）— ✅ 已交付（`emergency-support`）
|
|
|
+- E 管理信息域 — ✅ 已交付（`management-information`）
|
|
|
+- F 设施运行信息域 — ✅ 已交付（`operating-information`）
|
|
|
+- G 地图行业/类型维度（即 G1，含 G2/G3/G4）— G1/G2/G4 ❌，G3 ✅
|
|
|
+- H 跨设备设备状态列表 — ❌ 未交付
|
|
|
|
|
|
-- A 跨设备当前事件读模型（阻塞 `currentEvents`）
|
|
|
-- B 跨设备带时间范围的历史流 + 趋势 `range`（阻塞 `historyAnalysis`）
|
|
|
-- C 响应/关闭时长聚合（阻塞 `responseEfficiency`）
|
|
|
-- D 应急保障域三件套（阻塞 `emergency` 整版）
|
|
|
-- E 管理信息域
|
|
|
-- F 设施运行信息域
|
|
|
-- G 地图行业/类型维度（即 G1）
|
|
|
-- H 跨设备设备状态列表
|
|
|
+实现票 17–20 的 mock 阶段可按已有的面板级聚合响应形状建模（原 4 个 + 新增 5 个）：`/overview/infrastructure`、`/overview/monitoring`、`/overview/warning-settings`、`/infrastructure/base-archives`、`/infrastructure/operating-information`、`/infrastructure/management-information`、`/infrastructure/emergency-support`、`/monitoring/overview`、`/monitoring/distribution`。
|
|
|
|
|
|
-实现票 17–20 的 mock 阶段应按已有的 4 个面板级聚合响应形状建模：`/overview/infrastructure`、`/overview/monitoring`、`/overview/warning-settings`、`/infrastructure/base-archives`。
|
|
|
+## 业务问题（待业务方确认，本票不发明结论）
|
|
|
|
|
|
-## 业务问题（Q4 已决定：先挂着）
|
|
|
+三条仍未答复；下列为复核后掌握的现状与建议口径，供业务方确认或否决：
|
|
|
|
|
|
-- 「故障」是否等同 `stale`？
|
|
|
-- 「处置率」是否就是 `state==6` / 全部事件（含已取消）？
|
|
|
-- 「管理单位」与后端 `maintainer`（维护单位）是否同一概念？
|
|
|
+1. **「故障」是否等同 `stale`？** 现状：`monitoring/overview` 与 `overview/monitoring` 只有 `online/offline/stale/unknownOrMissing` 四个桶，没有独立「故障」桶。建议：业务确认前按「`stale` + `unknownOrMissing`，并显示原因」呈现；若要独立桶，需后端加字段。
|
|
|
+2. **「处置率」是否就是 `handled`/`total`（含已取消事件）？** 现状：`overview/warning-settings` 已把口径显式化——`handlingEfficiency{numerator,denominator,value,state,reason}` 配合 `total/handled/pending/cancelledCount/unlinkedEventCount/invalidWorkOrderStateCount`。建议：确认即为 `handled/total`（含已取消），并在面板标注分子分母；若业务口径要排除已取消，前端可用 `cancelledCount` 复算——但这属于业务定义，需答复。
|
|
|
+3. **「管理单位」与后端 `maintainer`（维护单位）是否同一概念？** 现状：新增的 `management-information` 用 `organizations` + `ownershipDistribution` + `unmaintained` 建模，与 `maintainer` 分开，倾向「不是同一概念」。建议：业务确认「管理单位 = 管理机构/权属单位，`maintainer` = 维护单位」这一区分，并回写术语表。
|
|
|
|
|
|
## 影响的实现票
|
|
|
|
|
|
| 票 | 影响 |
|
|
|
| --- | --- |
|
|
|
-| 06 全局筛选 | G1：筛选联动地图依赖后端补字段 |
|
|
|
+| 06 全局筛选 | G1：筛选联动地图依赖后端定路径（`map-snapshot` 加参 或 改用 `monitoring/distribution`） |
|
|
|
| 08 地图摘要 | G1、G2 |
|
|
|
-| 15 WebSocket | G2：增量回联点位依赖设备编码 |
|
|
|
-| 17–20 面板 | 真实接口路径依赖 A–H 补契约；mock 路径不受阻 |
|
|
|
+| 15 WebSocket | G2：增量回联点位依赖设备编码或增量帧带 `monitoringPointCode` |
|
|
|
+| 17 基础设施面板 | D/E/F 契约已交付，可对接 `operating-information` / `management-information` / `emergency-support`；真实数据源待后端接线 |
|
|
|
+| 18 运行监测面板 | F、G、H：`monitoring/overview`、`monitoring/distribution` 可对接；H 仍缺 |
|
|
|
+| 19 预警处置面板 | A、B、C 仍未交付，接真实接口仍受阻；mock 路径不受阻 |
|
|
|
+| 20 总体概览面板 | B：`situationSummary` 趋势窗口仍不可声明 |
|
|
|
|
|
|
## Acceptance criteria（后端负责人）
|
|
|
|
|
|
-- [ ] `map-snapshot` 支持 `industry` 入参并在点位摘要中返回 `industry` 与点位类型。
|
|
|
-- [ ] 点位摘要返回关联设备编码列表，WS 增量可回联点位。
|
|
|
-- [ ] A–H 各组补契约与后端负责人逐项确认排期（或明确拒绝并记录理由）。
|
|
|
-- [ ] 3 个业务问题得到业务方答复并回写本票。
|
|
|
+- [ ] `map-snapshot` 支持 `industry` 入参并在点位摘要中返回 `industry` 与点位类型。**结论不变，实现路径待后端负责人定**（候选 ① map-snapshot 加参；候选 ② 由 `monitoring/distribution` 承接，前端改取数路径）。
|
|
|
+- [ ] 点位摘要返回关联设备编码列表，WS 增量可回联点位。**结论不变，实现路径待定**（候选 ① 点位摘要带设备编码；候选 ② WS 增量帧带 `monitoringPointCode`）。
|
|
|
+- [ ] A–H 各组补契约与后端负责人逐项确认排期（或明确拒绝并记录理由）。**当前进度：D/E/F/G3 已交付（4/11 项）；A/B/C/H 与 G1/G2/G4 未排期、未确认。**
|
|
|
+- [ ] 3 个业务问题得到业务方答复并回写本票。**当前：0/3，待业务方确认（见上「业务问题」的建议口径）。**
|
|
|
+
|
|
|
+## 进度：30%
|
|
|
+
|
|
|
+据实更新（原记 0%，因后端在 09-16～09-17 已交付 D/E/F/G3 四组契约）：
|
|
|
+
|
|
|
+- 计分口径：8 组补契约拆为 11 个可判定项（A、B、C、D、E、F、G1、G2、G3、G4、H）+ 3 个业务问题 = 14 项。已交付 4 项（D/E/F/G3），B 记部分完成，合计约 30%。
|
|
|
+- 未完成，不 close。理由：AC1/AC2 结论未达成；AC3 只完成一半且「与后端负责人逐项确认排期」没有记录；AC4 三条业务问题 0 答复。
|
|
|
+- 本票未改动任何实现票的验收项；未改动后端仓库任何文件。
|
|
|
|
|
|
-## 进度：0%
|
|
|
+## 下一步
|
|
|
|
|
|
-待办已记录，等后端负责人认领。不改任何实现票验收项。
|
|
|
+1. **后端负责人（决定项）**：定 G1/G2/G4 的实现路径（`map-snapshot` 加参 vs 由 `monitoring/distribution` 承接；设备编码回联取点位摘要还是 WS 增量帧）。
|
|
|
+2. **后端负责人（排期项）**：A 跨设备当前/历史事件流、B `warning-settings` 的 `range` 入参、C 响应/关闭时长聚合、H 跨设备设备状态清单——排期或明确拒绝并记录理由。
|
|
|
+3. **后端（回填项）**：`monitoring/distribution`（#37）当前在工作区未提交，提交后回填本票状态。
|
|
|
+4. **业务方**：答复上「业务问题」三条口径。
|
|
|
+5. **前端实现票 06/08/15/17–20**：mock 阶段不受阻；接真实接口前先取第 1、2 项的结论，避免按错端点建模。
|
