City-Lifeline-Cockpit/.scratch/cockpit-shell-panel-layout/issues/24-panel-field-coverage.md

# 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。

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（维护单位）是否同一概念。

完成标准对照

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