25-backend-contract-gaps.md 4.1 KB
# 25: 后端契约缺口待办（跨领域两项 + 补契约清单）
Status: ready-for-human Labels: ready-for-human Category: enhancement Blocked by: None
不阻塞 23 张实现票的 mock 阶段；阻塞的是这些票接真实接口。
This was generated by AI during triage.
Why ready-for-human
结论来自 24: 面板字段与后端契约覆盖调研（已 resolved）与主会话的逐条核实。缺口分两类：
- 后端补契约——需要后端负责人实现，agent 无法代做。
- 业务定义确认——需要业务方回答，本票不发明结论。
G1 全局行业筛选落不到地图点位（已核实）
CONTEXT.md 定义行业筛选是作用于整个驾驶舱的全局条件，但今天它无法过滤地图点位：
GET /api/cockpit/v1/map-snapshot无industry入参（CockpitMapSnapshotController）。CockpitMonitoringPointSummary字段仅pointCode / pointName / pointStatus / statusReasons / longitude / latitude / coordinateValidation——没有industry与点位类型，服务端与客户端都无从过滤。- 对照：
overview/monitoring与infrastructure/base-archives已支持industry入参，说明后端具备该维度，只是没给地图摘要。
需要后端：map-snapshot 增加 industry 入参；CockpitMonitoringPointSummary 增加 industry 与点位类型字段。
G2 map-snapshot 丢弃设备编码，WS 增量无法回联点位（已核实）
- 内部快照
CockpitMapSnapshot.SourceMonitoringPoint.devices存在，但CockpitMapSnapshotService.monitoringPoint()（145–160 行）只用它解析点位状态，没有把设备编码写进响应。 - WS
cockpitDeviceStatusDelta增量只带deviceCode+ 状态，前端拿到增量后无法知道它属于哪个监测点，点位状态无法联动。 - 另外
cockpitSubscribe回帧只有{scope, serverUpdatedAt}，无初始状态数组（后端注释明确 REST 是初始快照、WS 只发增量——契约本身成立，前端需按此实现）；线上帧的状态键是data.status，而后端 DTOCockpitOverviewMonitoringDeviceStatusDelta命名为monitoringState，接入时注意别名。
需要后端：CockpitMonitoringPointSummary 输出关联设备编码列表。
补契约清单（A–H）
11 个有缺口面板的完整字段表与分组补契约建议（含字段名、语义、是否需要新端点）见 research/panel-field-coverage.md 第 4 节，共 8 组：
- A 跨设备当前事件读模型（阻塞
currentEvents） - B 跨设备带时间范围的历史流 + 趋势
range（阻塞historyAnalysis） - C 响应/关闭时长聚合（阻塞
responseEfficiency） - D 应急保障域三件套（阻塞
emergency整版） - E 管理信息域
- F 设施运行信息域
- G 地图行业/类型维度（即 G1）
- H 跨设备设备状态列表
实现票 17–20 的 mock 阶段应按已有的 4 个面板级聚合响应形状建模：/overview/infrastructure、/overview/monitoring、/overview/warning-settings、/infrastructure/base-archives。
业务问题（Q4 已决定：先挂着）
- 「故障」是否等同
stale？ - 「处置率」是否就是
state==6/ 全部事件（含已取消）？ - 「管理单位」与后端
maintainer（维护单位）是否同一概念？
影响的实现票
| 票 | 影响 |
|---|---|
| 06 全局筛选 | G1：筛选联动地图依赖后端补字段 |
| 08 地图摘要 | G1、G2 |
| 15 WebSocket | G2：增量回联点位依赖设备编码 |
| 17–20 面板 | 真实接口路径依赖 A–H 补契约；mock 路径不受阻 |
Acceptance criteria（后端负责人）
-
map-snapshot支持industry入参并在点位摘要中返回industry与点位类型。 - 点位摘要返回关联设备编码列表，WS 增量可回联点位。
- A–H 各组补契约与后端负责人逐项确认排期（或明确拒绝并记录理由）。
- 3 个业务问题得到业务方答复并回写本票。
进度：0%
待办已记录，等后端负责人认领。不改任何实现票验收项。