24-panel-field-coverage.md 6.9 KB
# 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、alertSettingsinfrastructure：archive、operation、management、emergencymonitoring：monitoringOverview、monitoringDistribution、operationOverview、monitoringPointLedgerwarningResponse：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/infrastructureGET /api/cockpit/v1/overview/monitoringGET /api/cockpit/v1/overview/warning-settingsGET /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 缺失字段
- 跨设备当前事件流（
eventCode+ 归属设备/监测点/行业 + 分页）— 完全阻塞currentEvents - 跨设备带时间范围的历史事件流 + 趋势
range参数（7/30/90/自定义）— 阻塞historyAnalysis - 应急保障域三件套（
hazardSources/protectionTargets/emergencyResources）—emergency整版，后端 cockpit 包内该域完全不存在 - 监测点
industry+ 点位类型 + 设备计数徽标，含map-snapshot的industry入参 — 阻塞monitoringPointLedger/monitoringDistribution - 事件经纬度（
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()不写入响应，导致 WScockpitDeviceStatusDelta（增量只带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并从本票链接 - 未改业务代码，未跑构建或调试命令