# 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: 面板字段与后端契约覆盖调研](24-panel-field-coverage.md)（已 resolved）与主会话的逐条核实。缺口分两类：

1. **后端补契约**——需要后端负责人实现，agent 无法代做。
2. **业务定义确认**——需要业务方回答，本票不发明结论。

## 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`，而后端 DTO `CockpitOverviewMonitoringDeviceStatusDelta` 命名为 `monitoringState`，接入时注意别名。

**需要后端**：`CockpitMonitoringPointSummary` 输出关联设备编码列表。

## 补契约清单（A–H）

11 个有缺口面板的完整字段表与分组补契约建议（含字段名、语义、是否需要新端点）见 [research/panel-field-coverage.md](../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%

待办已记录，等后端负责人认领。不改任何实现票验收项。