# 24: 面板字段与后端契约覆盖调研

Type: research
Status: resolved
Labels: wayfinder:research
Blocked by: None

**What to find:** 16 个二级面板各自需要的数据字段，现有 `/api/cockpit/v1/**` 与 `/ws/deviceStatus` 契约能不能供上；供不上的缺口要逐条列出，并给出补契约建议。

注意：本票是 AFK 调研，不改业务代码。结论写入本票链接的调研资产。

## 范围

对 ADR 0003 锁定的 16 个 `panelId` 逐一对照后端契约：

- `overview`：`situationSummary`、`infrastructureSummary`、`monitoringSummary`、`alertSettings`
- `infrastructure`：`archive`、`operation`、`management`、`emergency`
- `monitoring`：`monitoringOverview`、`monitoringDistribution`、`operationOverview`、`monitoringPointLedger`
- `warningResponse`：`currentEvents`、`historyAnalysis`、`responseEfficiency`、`eventAnalysis`

## 要产出

每个面板一段，包含：

- 面板需要的字段清单（按 ADR 0003 与 `CONTEXT.md` 的语义描述，不要发明业务）
- 现有契约是否已提供：`map-snapshot`、`monitoring-points/{code}`、`equipments/{code}/detail-aggregate`、`equipments/{code}/archive`、`equipments/{code}/metrics/{current,history}`、`equipments/{code}/events/{current,history}`、`equipments/{code}/work-orders`、`work-orders/{code}/timeline`、`foundation`、`device-boundary`、`freshness`
- 缺口分级：**已有** / **可推导**（由已有字段组合得出）/ **缺失**（需要后端补）
- 缺失项的补契约建议（字段名、语义、是否需要新端点）

## 约束

- 只读：不改业务代码，不改后端代码，不跑构建或调试命令。
- 后端契约以后端仓库实际控制器与响应结构为准（`E:\pipe-ner-server\pipe-network-server` 的 `com.zksy.web.controller.cockpit` 与 `com.zksy.cockpit.*`），后端演示页 `E:\pipe-ner-server\docs\cockpit\*.html` 作为样例响应的旁证。
- 当前后端没有可用 OpenAPI 文档，所以逐类读控制器与响应类，不要假设。
- 结论要能直接支撑实现票 17–20 的字段映射；不要写成泛泛的接口清单。

## 与其他票的关系

- 不阻塞实现票 17–20 的 mock 版实现（默认数据源是 mock）。
- 阻塞的是这些面板**接真实接口**时的字段映射确认；结论供实现票 05（Mock 领域适配层）与 17–20 参考。
- 本票不改任何实现票的验收项。

## 完成标准

- [ ] 16 个面板逐一给出字段清单与覆盖判定（已有 / 可推导 / 缺失）。
- [ ] 所有「缺失」项聚合成一份补契约清单，含字段名与语义。
- [ ] 每条判定都附后端类名或响应结构作为证据。
- [ ] 结论写入 `.scratch/cockpit-shell-panel-layout/research/panel-field-coverage.md` 并从本票链接。
- [ ] 不改业务代码，不跑构建或调试命令。

## 进度：100%

已完成。结论写入 [`.scratch/cockpit-shell-panel-layout/research/panel-field-coverage.md`](../research/panel-field-coverage.md)。

## Answer

**16 个面板：5 个字段完全覆盖，11 个存在缺口。** 完整字段表与补契约清单见调研资产。

### 决策要点

**1. 任务书给出的「现有契约」清单漏了 4 个面板级端点。** 后端已经为总体概览与基础档案提供了一整层聚合读模型：

- `GET /api/cockpit/v1/overview/infrastructure`
- `GET /api/cockpit/v1/overview/monitoring`
- `GET /api/cockpit/v1/overview/warning-settings`
- `GET /api/cockpit/v1/infrastructure/base-archives`
- 另有 `GET /api/cockpit/v1/events/{eventSource}/{eventCode}/work-orders`

因此 `infrastructureSummary`、`monitoringSummary`、`alertSettings`、`archive`、`monitoringOverview` 是**已有**的，不需要补契约。实现票 17-20 的 mock 首期可直接按这 4 个响应的形状建模。

**2. 缺口不是「单设备字段缺失」，而是「跨设备/跨设施读模型缺失」。** 所有事件端点（current/history）与指标端点都以 `deviceCode` 为路径参数，没有跨设备视图。

**3. 逐面板判定**

| 模式 | 完全覆盖 | 存在缺口 |
| --- | --- | --- |
| `overview` | `infrastructureSummary`、`monitoringSummary`、`alertSettings` | `situationSummary`（趋势窗口不可声明，弱缺口） |
| `infrastructure` | `archive` | `operation`、`management`、`emergency` |
| `monitoring` | `monitoringOverview` | `monitoringDistribution`、`operationOverview`、`monitoringPointLedger` |
| `warningResponse` | 无 | 4 个面板全部有缺口 |

**4. Top 5 缺失字段**

1. 跨设备当前事件流（`eventCode` + 归属设备/监测点/行业 + 分页）— 完全阻塞 `currentEvents`
2. 跨设备带时间范围的历史事件流 + 趋势 `range` 参数（7/30/90/自定义）— 阻塞 `historyAnalysis`
3. 应急保障域三件套（`hazardSources` / `protectionTargets` / `emergencyResources`）— `emergency` 整版，后端 cockpit 包内该域**完全不存在**
4. 监测点 `industry` + 点位类型 + 设备计数徽标，含 `map-snapshot` 的 `industry` 入参 — 阻塞 `monitoringPointLedger` / `monitoringDistribution`
5. 事件经纬度（`longitude`/`latitude` + `coordinateValidation`）与响应/关闭时长聚合（`averageResponseSeconds` / `averageCloseSeconds`）

**5. 两个影响面超出单面板的发现**

- **全局「行业筛选」目前落不到地图点位上**：`overview/monitoring` 与 `base-archives` 支持 `industry`，但 `map-snapshot` 既无 `industry` 入参，`CockpitMonitoringPointSummary` 也无 `industry`/类型字段，无法服务端或客户端过滤。CONTEXT.md 定义行业筛选是作用于整个驾驶舱的全局条件。
- **`map-snapshot` 丢弃了设备编码**：内部快照 `CockpitMapSnapshot.SourceMonitoringPoint.devices` 存在，但 `CockpitMapSnapshotService.monitoringPoint()` 不写入响应，导致 WS `cockpitDeviceStatusDelta`（增量只带 `deviceCode` + `status`）无法回联到点位状态。

**6. WS 契约现状**：`cockpitSubscribe` 回帧只有 `{scope, serverUpdatedAt}`，无初始设备状态数组——后端注释明确「REST 仍是初始快照，这里只接收后续状态增量」。另注意线上帧增量状态键是 `data.status`，而后端 DTO `CockpitOverviewMonitoringDeviceStatusDelta` 的字段名是 `monitoringState`。

**7. 待业务确认（本票不发明结论）**：「故障」是否等同 `stale`；「处置率」当前定义是 `state==6` / 全部事件（含已取消），是否即业务所说处置率；「管理单位」与 `maintenance`（维护单位）是否同一概念。

### 完成标准对照

- [x] 16 个面板逐一给出字段清单与覆盖判定（已有 / 可推导 / 缺失）
- [x] 所有「缺失」项聚合为补契约清单（A–H 共 8 组，含字段名与语义）
- [x] 每条判定附后端类名或响应结构作为证据
- [x] 结论写入 `.scratch/cockpit-shell-panel-layout/research/panel-field-coverage.md` 并从本票链接
- [x] 未改业务代码，未跑构建或调试命令