Research: 面板字段与后端契约覆盖

Ticket: 24: 面板字段与后端契约覆盖调研 Date: 2026-09-15 Scope: 决策事实。只读调研，未改动任何业务代码、后端代码或构建产物。 Method: 逐类阅读后端控制器（com.zksy.web.controller.cockpit）与响应/快照类（com.zksy.cockpit.*），不依赖 OpenAPI（Swagger 已注释）。演示页 E:\pipe-ner-server\docs\cockpit\*.html 仅作样例旁证。

Decision

16 个二级面板中，5 个字段完全覆盖，11 个存在缺口。

关键纠偏：本票与上游任务书列举的「现有契约」清单遗漏了 4 个面板级读模型端点。后端已经为总体概览与基础档案提供了一整层聚合读模型（/overview/infrastructure、/overview/monitoring、/overview/warning-settings、/infrastructure/base-archives），还有一个 GET /api/cockpit/v1/events/{eventSource}/{eventCode}/work-orders。因此「总体概览三面板 + 基础档案 + 监测概览」实际上是已有的，不需要补契约。

真正的缺口集中在四类，都是「跨设备 / 跨设施的读模型」缺失，而不是单设备字段缺失：

跨设备事件流（当前 + 历史 + 时间范围参数）— 后端事件读取一律以 deviceCode 为路径参数。
监测点的行业/类型维度（map-snapshot 既无 industry 入参，点位摘要也无 industry/类型字段）— 卡住 CONTEXT.md 定义的全局「行业筛选」。
应急保障域（危险源/防护目标/应急资源）在后端 cockpit 包内完全不存在。
效率时长聚合（响应时长/关闭时长）与事件多维分布聚合。

1. 后端契约基线（实测端点清单）

@GetMapping 全量枚举结果（com.zksy.web.controller.cockpit，共 18 个 GET）：

#	端点	控制器	关键入参	响应类
1	`/api/cockpit/v1/foundation`	`CockpitFoundationController`（类级 `@RequestMapping("/api/cockpit/v1")`）	—	`CockpitFoundationResponse`
2	`/api/cockpit/v1/map-snapshot`	`CockpitMapSnapshotController`	`page`,`pageSize`(默认500,上限1000),`snapshotAt`	`CockpitMapSnapshotResponse`
3	`/api/cockpit/v1/monitoring-points/{monitoringPointCode}`	`CockpitMonitoringPointDetailController`	path	`CockpitMonitoringPointDetailResponse`
4	`/api/cockpit/v1/device-boundary`	`CockpitDeviceBoundaryController`	—	`CockpitDeviceBoundaryResponse`
5	`/api/cockpit/v1/overview/infrastructure`	`CockpitOverviewInfrastructureController`	—	`CockpitOverviewInfrastructureResponse`
6	`/api/cockpit/v1/overview/monitoring`	`CockpitOverviewMonitoringController`	`industry`	`CockpitOverviewMonitoringResponse`
7	`/api/cockpit/v1/overview/warning-settings`	`CockpitOverviewWarningSettingsController`	`mode`(WARNING\|ALARM)	`CockpitOverviewWarningSettingsResponse`
8	`/api/cockpit/v1/infrastructure/base-archives`	`CockpitInfrastructureBaseArchivesController`	`industry`,`facilityType`,`ageBucket`,`region`	`CockpitInfrastructureBaseArchivesResponse`
9	`/api/cockpit/v1/equipments/{deviceCode}/archive`	`CockpitEquipmentArchiveController`	path	`CockpitEquipmentArchiveResponse`
10	`/api/cockpit/v1/equipments/{deviceCode}/detail-aggregate`	`CockpitEquipmentDetailAggregateController`	path	`CockpitEquipmentDetailAggregateResponse`
11	`/api/cockpit/v1/equipments/{deviceCode}/metrics/current`	`CockpitTypeMetricsController`	path	`CockpitTypeMetricsResponse`
12	`/api/cockpit/v1/equipments/{deviceCode}/metrics/history`	`CockpitTypeMetricsController`	`startTime`,`endTime`,`page`,`pageSize`	`CockpitTypeMetricsResponse`
13	`/api/cockpit/v1/equipments/{deviceCode}/events/current`	`CockpitEventReadController`	path	`CockpitEventReadResponse`
14	`/api/cockpit/v1/equipments/{deviceCode}/events/history`	`CockpitEventReadController`	`startTime`(必填),`endTime`(必填),`page`,`pageSize`	`CockpitEventReadResponse`
15	`/api/cockpit/v1/equipments/{deviceCode}/work-orders`	`CockpitWorkOrderReadController`	path	`CockpitWorkOrderReadResponse`
16	`/api/cockpit/v1/events/{eventSource}/{eventCode}/work-orders`	`CockpitWorkOrderReadController`	path	`CockpitWorkOrderReadResponse`
17	`/api/cockpit/v1/work-orders/{workOrderCode}/timeline`	`CockpitWorkOrderReadController`	path	`CockpitWorkOrderTimelineResponse`
18	`/api/cockpit/v1/equipments/{deviceCode}/freshness`	`CockpitFreshnessController`	`calibrationPeriodSeconds`	`CockpitFreshnessResponse`

端点 1、5、6、7、8、16 不在本票与上游任务书给出的清单里。这是本调研对字段覆盖判定影响最大的一条事实。

响应统一包在 AjaxResult 里（ResponseEntity<AjaxResult>），业务负载在 data 下。

WebSocket `/ws/deviceStatus`

DeviceStatusWebSocketHandler（zksy-admin/.../web/websocket/）消息类型：authenticate、subscribe、unsubscribe、cockpitSubscribe、deviceStatus、workOrderReminder、ping。

驾驶舱相关链路：

订阅：→ {"type":"cockpitSubscribe","scope":"all"}；← {"type":"cockpitSubscribed","scope":"all","serverUpdatedAt":"..."}
增量：← {"type":"cockpitDeviceStatusDelta","deviceCode":"DEV001","device_code":"DEV001","data":{"status":"ALARM","statusTime":"...","serverUpdatedAt":"...","reason":"..."}}

重要语义（DeviceStatusWebSocketHandler 第 341-357 行注释原文）：「驾驶舱全量范围订阅；REST 仍是初始快照，这里只接收后续状态增量」。cockpitSubscribed 回帧不含任何初始设备状态数组。

字段名不一致：WS 线上帧的增量状态键是 data.status（DeviceStatusRedisListener.cockpitDeltaMessage 第 179 行），而后端 DTO CockpitOverviewMonitoringDeviceStatusDelta 的字段名是 monitoringState。前端映射时需按 WS 线上帧的 status 取值。

增量不含坐标、行业、设备类型——只能靠 deviceCode 回联 REST 快照。

2. 判定口径

等级	含义
已有	现有端点响应中存在对应字段（可能需换一个端点取）
可推导	需组合/回联现有字段，或有 N+1 代价；不需后端改契约
缺失	现有契约无论怎么组合都拿不到，需后端补契约

每条判定附后端类名。字段语义以 ADR 0003 的面板词典 + CONTEXT.md 术语为准，实现细节参考票 17-20 的验收项，未发明业务。

3. 逐面板字段覆盖

3.1 `overview` 模式

`situationSummary` 态势总览 — ⚠️ 1 处缺口

CONTEXT.md 定义：跨行业 KPI，展示设施底数、监测规模、在线率、当前预警/报警、处置率和近 7 日趋势。

需要的字段	来源	判定
设施底数	`CockpitOverviewInfrastructureResponse.Totals.facilityCount`	已有
监测规模（智能设备数）	`CockpitOverviewInfrastructureResponse.Totals.smartDeviceCount`	已有
监测点规模	`CockpitOverviewMonitoringResponse.Counts.monitoringPointCount`	已有
在线率	`CockpitOverviewMonitoringResponse.Counts.OnlineRate.{value,onlineCount,denominator,state,reason}`	已有
当前预警/报警数	`CockpitOverviewWarningSettingsResponse.FamilyMetrics.{total,pending}`（`warning` / `alarm` 各一份）	已有
处置率	`FamilyMetrics.handlingEfficiency.{numerator,denominator,value,state,reason}`	已有（语义为「结案率」：分子=state 6，分母=全部事件，见 `CockpitOverviewWarningSettingsService` 第 32、133-146 行）
近 7 日趋势	`FamilyMetrics.trend[]`（`TrendPoint.{bucket,total,handled,handlingEfficiency}`）	缺失（窗口不可声明）
可读的「无数据」态	`FamilyMetrics.{state,stateReason}`、`Freshness.{status,reason}`	已有

缺口证据：CockpitOverviewWarningSettingsService.load 第 59 行硬编码 new Range("CURRENT_BASELINE", null, null)，且控制器只接受 mode（CockpitOverviewWarningSettingsController 第 35 行）。趋势桶完全由适配器快照决定，前端无法声明「近 7 日」。ADR 0003 明确要求「近 7 日趋势」。

`infrastructureSummary` 基础设施 — ✅ 全覆盖

需要的字段	来源	判定
设施底数	`CockpitOverviewInfrastructureResponse.Totals.facilityCount`	已有
行业构成	`CockpitOverviewInfrastructureResponse.Industry[]`（`code,key,label,facilityCount,smartDeviceCount`）	已有
行业下的类型构成	`Industry.facilityTypes[] / deviceTypes[]` → `TypeSummary.{code,name,count,lengthKm,scale,range}`	已有
区域分布	`CockpitInfrastructureBaseArchivesResponse.regionDistribution[].{code,count}`	已有（经 #8 端点）
规模里程	`CockpitInfrastructureBaseArchivesResponse.Totals.{lengthKm,scale}`	已有
剔除口径可解释性	`CockpitOverviewInfrastructureResponse.Excluded.{unknownTypeCount,typeKindMismatchCount}`	已有

CockpitOverviewInfrastructureResponse 自身不含区域字段，但 #8 端点提供，故判「已有」。

`monitoringSummary` 运行监测 — ✅ 全覆盖

需要的字段	来源	判定
在线率	`CockpitOverviewMonitoringResponse.Counts.OnlineRate`	已有
离线统计	`Counts.Status.{online,offline,stale,unknownOrMissing,denominator}`	已有
故障统计	同上（无独立「故障」桶；只能映射到 `stale` / `unknownOrMissing`）	已有（语义需确认，见 §5 待定项）
监测覆盖	`Counts.{deviceCount,monitoringPointCount,monitoringFacilityCount,infrastructureFacilityCount}` + `FormalScope.{industries,keys}`	已有
最近采集时间	`CockpitOverviewMonitoringResponse.MetricFreshness.{status,updatedAt,serverUpdatedAt}`	已有
数据新鲜度	`CockpitOverviewMonitoringResponse.Freshness.{status,reason,...}`	已有
类型分布	`CockpitOverviewMonitoringResponse.TypeDistribution[]`（`industry`,`deviceType{code,name}`,`deviceCount`）	已有
行业筛选回显	`selectedIndustry{code,key,label}`	已有

`alertSettings` 预警设置 — ✅ 全覆盖

票 20 要求「保持合同名称，只读展示预警/报警统计」，与 CockpitOverviewWarningSettingsResponse 一一对应。

需要的字段	来源	判定
预警/报警总览	`FamilyMetrics.{total,handled,pending}`	已有
已取消	`FamilyMetrics.cancelledCount`	已有
未关联工单 / 异常工单状态	`FamilyMetrics.{unlinkedEventCount,invalidWorkOrderStateCount}`	已有
工单七态分布	`FamilyMetrics.workOrderStates`（`Map<Integer,Integer>`，键 1-7，字典见 `CockpitWorkOrderStateDictionary`）	已有
处置率	`FamilyMetrics.handlingEfficiency`	已有
趋势	`FamilyMetrics.trend[]`	已有
双模式选择与地图过滤语义	`selectedMode`、`MapFilter.{eventFamily,label}`	已有
时间范围声明	`Range`	缺失（`type="CURRENT_BASELINE"`，start/end 为 null）

3.2 `infrastructure` 模式

`archive` 基础档案 — ✅ 全覆盖

需要的字段	来源	判定
设施规模	`CockpitInfrastructureBaseArchivesResponse.Totals.{facilityCount,lengthKm,scale}`	已有
行业分类	`industryDistribution[].{code,count}`	已有
设施类型分布	`facilityTypeDistribution[]` → `TypeSummary`	已有
区域分布	`regionDistribution[].{code,count}`	已有
档案摘要（年限）	`ageDistribution[].{code,count}` + `ageReference.{asOfDate,commissionedCount,builtCount,unknownCount}`	已有
筛选回显	`selectedFilters` + `mapFilter`	已有
口径剔除	`excluded.{unknownTypeCount,typeKindMismatchCount,smartDeviceCount,futureDateCount}`	已有
单设备档案明细	`CockpitEquipmentArchive`（`deviceModel,deviceSpec,manufacturer,productionDate,deviceType,deviceTypeName,assetValue,expectedServiceYears,longitude,latitude,equipmentLocation,installTime,maintainer,maintainerPhone,ownershipUnit,remark,coordinateSystem,latestImage`）	已有（#9 端点）

`operation` 运行信息 — ❌ 2 处缺口

票 17 要求「供应、输送、承载能力和指标占位」。

需要的字段	来源	判定
指标占位（当前值）	`CockpitMetric.{metricCode,metricName,value,unit,status,sampledAt,freshness}`	已有（设备级，#11 端点）
指标历史序列	`CockpitMetric.points[]` → `CockpitMetricPoint.{value,status,sampledAt,freshness}`	已有（设备级，#12 端点）
指标可用性态	`CockpitTypeMetricsResponse.{state,stateReason}`	已有
设施级「供应能力」	无任何设施属性契约（`CockpitFacilityBoundary` 只有 `facilityCode,facilityName,facilityType,objectKind,industry,formalScope`）	缺失
设施级「输送能力」	同上	缺失
设施级「承载能力」	同上	缺失
设施级指标聚合（一个设施下多设备的汇总）	#11/#12 只以 `deviceCode` 为路径参数；无 `facilityCode` 维度	缺失

注：若「供应/输送/承载能力」首期只是指标占位，则可先以设备级 CockpitMetric 占位满足；但设施级聚合仍缺失。

`management` 管理信息 — ❌ 3 处缺口

票 17 要求「管理单位、权属单位和责任区域」。

需要的字段	来源	判定
权属单位	`CockpitEquipmentArchive.ownershipUnit`	已有（仅设备级）
维护方与联系人	`CockpitEquipmentArchive.{maintainer,maintainerPhone}`	已有
管理单位	无该字段；最接近的是 `maintainer`（维护单位），与「管理单位」是不同的业务概念	缺失
责任区域（设施维度）	`CockpitInfrastructureBaseArchivesSnapshot.SourceFacility.region` 存在，但未在响应里逐设施暴露；响应只有聚合的 `regionDistribution`	可推导（弱）
责任区域（设备维度）	`CockpitEquipmentArchive.equipmentLocation`（自由文本）	可推导
按区域聚合的管理单位/权属单位	无任何按 `ownershipUnit` / `maintainer` 分组的契约	缺失

`emergency` 应急保障 — ❌ 全域缺失

票 17 要求「危险源、防护目标和应急资源」。

需要的字段	判定
危险源	缺失
防护目标	缺失
应急资源	缺失
空间定位与可上图状态	缺失

`monitoring` 模式

`monitoringOverview` 监测概览 — ✅ 全覆盖

需要的字段	来源	判定
监测点规模	`CockpitOverviewMonitoringResponse.Counts.monitoringPointCount`	已有
设备规模	`Counts.deviceCount`	已有
在线率	`Counts.OnlineRate`	已有
类型分布	`typeDistribution[]`	已有
最近采集时间	`metricFreshness.updatedAt`	已有
行业筛选	端点 `industry` 入参 + `selectedIndustry`	已有
监测设施/基础设施口径	`Counts.{monitoringFacilityCount,infrastructureFacilityCount}`	已有

`monitoringDistribution` 监测分布 — ❌ 2 处缺口

票 18 要求「覆盖情况、状态分布和地图筛选」。

需要的字段	来源	判定
覆盖情况	`CockpitOverviewMonitoringResponse.FormalScope` + `Counts.{monitoringFacilityCount,infrastructureFacilityCount}`	已有
状态分布（点位状态）	`CockpitMonitoringPointSummary.pointStatus`（`CockpitMonitoringPointStatus` 6 值：ALARM/WARNING/WORK_ORDER/NORMAL/OFFLINE/EMPTY）	已有（前端计数）
状态原因明细	`CockpitMonitoringPointSummary.statusReasons[]` + `CockpitMonitoringPointStatusReason.{status,deviceCode,reason}`	已有
状态字典与优先级	`CockpitMonitoringPointDetailResponse.statusDictionary[]` → `{status,label,priority}`	已有
无坐标点位分布	`CockpitCoordinateValidationSummary` + 逐点 `CockpitCoordinateValidation.{state,reason,renderable,crs}`	已有
未关联设备	`CockpitMapSnapshotResponse.unassociatedEquipment[]`	已有
地图按行业筛选	`CockpitMapSnapshotController` 只接受 `page,pageSize,snapshotAt`（第 33-38 行）；`CockpitMonitoringPointSummary` 无 `industry` 字段	缺失
地图按点位类型筛选	`CockpitMonitoringPointSummary` 无类型字段（内部 `CockpitMapSnapshot.SourceMonitoringPoint` 也无类型）	缺失

影响面超出本面板：CONTEXT.md 定义「行业筛选」是作用于整个驾驶舱的全局范围条件。overview/monitoring 与 base-archives 支持 industry，但一张图的 map-snapshot 不支持，且点位摘要无法回联行业（见 monitoringPointLedger），所以全局行业筛选目前无法落到地图点位上。

`operationOverview` 运行概况 — ❌ 1 处缺口

票 18 要求「事件趋势、离线设备和异常态势」。

需要的字段	来源	判定
事件趋势	`CockpitOverviewWarningSettingsResponse.FamilyMetrics.trend[]`	已有（窗口不可声明）
离线数量	`CockpitOverviewMonitoringResponse.Counts.Status.offline`	已有
离线设备清单	无跨设备设备状态列表；`map-snapshot` 只给点位状态，`CockpitOverviewMonitoringDeviceStatusDelta` 只是增量	缺失
异常态势	设备级 `CockpitTypeMetricsResponse.{state,stateReason}`、`CockpitFreshnessResponse.freshness`	已有（逐设备）
跨设备异常汇总	无	缺失

`monitoringPointLedger` 监测点台账 — ❌ 4 处缺口

CONTEXT.md：以滚动卡片列出当前筛选范围内监测点；点击卡片进入两级详情。

需要的字段	来源	判定
点位编码/名称	`CockpitMonitoringPointSummary.{pointCode,pointName}`	已有
点位状态 + 原因	`pointStatus`,`statusReasons[]`	已有
坐标与可上图状态	`longitude`,`latitude`,`coordinateValidation`	已有
滚动分页	`page`,`pageSize`,`total`,`complete`,`snapshotAt`	已有
所属行业（筛选范围）	点位摘要无 `industry`；`map-snapshot` 无 `industry` 入参	缺失
点位类型	点位摘要无类型字段	缺失
设备计数徽标（总数/在线/报警/预警）	需对每个点调 `monitoring-points/{code}` 取 `CockpitMonitoringPointDeviceStatistics.{totalDeviceCount,alarmDeviceCount,warningDeviceCount,workOrderDeviceCount,normalDeviceCount,offlineDeviceCount}`	可推导（N+1）
点位最近采集时间	需逐设备 `metrics/current` 或 `freshness`	缺失（批量）
关联设备编码	`CockpitMapSnapshot.SourceMonitoringPoint.devices` 存在于内部快照，但 `CockpitMapSnapshotService.monitoringPoint()` 第 145-160 行不写入响应	缺失

台账面板因此无法在单次 map-snapshot 分页内渲染卡片，必须退化为 N+1 调用。

3.3 `warningResponse` 模式

`currentEvents` 当前预警 — ❌ 2 处缺口

票 19 要求「当前事件、工单状态和设备定位」。ADR 0003：当前事件列表默认 10-15 条。

需要的字段	来源	判定
事件明细字段（预警）	`CockpitEventWarning.{warningNo,warningName,warningType,level,levelColor,status,eventTime,value,unit,deviceCode,deviceName,location}`	已有（设备级）
事件明细字段（报警）+ 阈值	`CockpitEventAlarm.{alarmId,warningCode,warningName,warningType,level,levelColor,status,eventTime,value,thresholdMinValue,thresholdMaxValue,unit,deviceCode,deviceName,location}`	已有（设备级）
预警-报警关联	`CockpitAlarmWarningRelation.{relationId,warningNo,alarmId,relatedAt}`	已有
等级配色	`level` + `levelColor`（`CockpitEventLevelColor.resolve`：1→RED,2→YELLOW,3→BLUE,4→GREEN）	已有
工单状态（设备维度）	`CockpitWorkOrderReadResponse.workOrders[]` → `CockpitWorkOrderSummary.stateCode/stateName` + `stateDictionary`	已有（#15）
工单状态（事件维度）	#16 `events/{eventSource}/{eventCode}/work-orders`	已有
动作轨迹	`CockpitWorkOrderTimelineResponse.timelineEntries[]` → `CockpitWorkOrderTimelineEntry.{stateCode,stateName,operationName,operationDesc,operatorName,operatedAt}`	已有（#17）
跨设备当前事件列表（一次取 10-15 条）	三个事件端点全部以 `deviceCode` 为路径参数；无跨设备事件读模型	缺失
事件 → 地图坐标	`CockpitEventWarning/Alarm` 只有 `location`（文本），无经纬度；`map-snapshot` 也不返回已关联设备的坐标	缺失
事件排序/截断规则	无跨设备契约	缺失

`historyAnalysis` 历史分析 — ❌ 2 处缺口

票 19 要求「历史事件趋势和时间范围筛选」。ADR 0003：历史列表提供 7/30/90 天和自定义时间范围。

需要的字段	来源	判定
历史事件明细（单设备，带时间范围）	`equipments/{deviceCode}/events/history?startTime&endTime&page&pageSize`	已有（设备级，`startTime`/`endTime` 必填）
历史分页	`CockpitEventReadResponse.{page,pageSize,total,startTime,endTime,timezone}`	已有
跨设备历史事件列表	无	缺失
趋势的时间范围参数（7/30/90/自定义）	`overview/warning-settings` 只接受 `mode`；`Range("CURRENT_BASELINE",null,null)` 硬编码	缺失
趋势桶序列	`FamilyMetrics.trend[].bucket`	已有（但窗口服务端固定）

`responseEfficiency` 预警效率 — ❌ 1 处缺口（含 2 个字段）

票 19 要求「处置率、响应时长、关闭时长和工单七态分布」。

需要的字段	来源	判定
处置率	`FamilyMetrics.handlingEfficiency`	已有
工单七态分布	`FamilyMetrics.workOrderStates` + `CockpitWorkOrderStateDictionary`（7 态）	已有
趋势效率	`trend[].handlingEfficiency`	已有
单工单时长（可算）	`CockpitWorkOrderSummary.{createTime,updateTime,planFinishTime,realFinishTime}`	可推导（逐工单）
接单时点（算响应时长所需）	`CockpitWorkOrderTimelineEntry` 中 `stateCode=3`（已接单）的 `operatedAt`	可推导（逐工单，需拉 timeline）
响应时长聚合 KPI	无任何时长字段	缺失
关闭时长聚合 KPI	无任何时长字段	缺失

对 docs/cockpit/*.html 按 duration|响应时长|关闭时长|responseTime 检索：零命中，旁证该维度确未实现。

`eventAnalysis` 预警分析 — ❌ 1 处缺口（多个维度）

票 19 要求「多维事件分布和重点识别」。

需要的字段	来源	判定
按类型（单设备）	`CockpitEventWarning.warningType` / `CockpitEventAlarm.warningType`	可推导（仅逐设备事件）
按等级（单设备）	`level` + `levelColor`	可推导（逐设备）
按设备类型（单设备）	`CockpitEventReadResponse.{deviceType,deviceTypeName}`	可推导（逐设备，响应级字段）
按类型聚合分布	无聚合契约	缺失
按等级聚合分布	无聚合契约	缺失
按行业分布	事件对象无 `industry` 字段	缺失
按区域分布	事件对象无区域字段	缺失
重点识别 / Top-N / 热点	无	缺失

4. 补契约清单（汇总所有「缺失」项）

A. 跨设备事件读模型 —— 最高优先级

覆盖面板：currentEvents、historyAnalysis、eventAnalysis、operationOverview（异常态势）。

现有事件端点全部是 equipments/{deviceCode}/...，无法支撑「当前事件列表 10-15 条」这类跨设备视图。

A1. 建议新端点 GET /api/cockpit/v1/events/current

参数	语义
`industry`	行业筛选（对齐 CONTEXT.md 全局行业筛选）
`family`	`WARNING` \| `ALARM` \| 空=两者
`page`,`pageSize`	分页，默认 1 / 15

建议字段	语义
`eventFamily`	`WARNING` \| `ALARM`
`eventCode`	预警用 `warningNo`，报警用 `alarmId`，统一键
`eventName`,`eventType`,`level`,`levelColor`,`status`,`eventTime`,`value`,`unit`	复用 `CockpitEventWarning`/`CockpitEventAlarm` 同名语义
`thresholdMinValue`,`thresholdMaxValue`	仅报警；复用 `CockpitEventAlarm`
`deviceCode`,`deviceName`	复用
`monitoringPointCode`,`monitoringPointName`	新增：事件归属监测点，供两张图/台账联动
`industry`,`drainageScope`,`objectKind`	新增：行业归属，供全局行业筛选与事件分析
`longitude`,`latitude`	新增：事件定位（当前只有文本 `location`）
`coordinateValidation`	复用 `CockpitCoordinateValidation`（`state,reason,renderable,crs`）
`workOrderCode`,`workOrderStateCode`,`workOrderStateName`	新增：事件当前工单状态，省掉按事件二次请求
`page`,`pageSize`,`total`,`updatedAt`,`freshness`	复用既有分页/新鲜度语义

A2. 建议新端点 GET /api/cockpit/v1/events/history

参数在 A1 基础上加 startTime、endTime（必填，支持 7/30/90 天与自定义）。响应体结构与 A1 一致，另加 range{type,start,end}。

B. 趋势时间范围可声明

覆盖面板：situationSummary（近 7 日趋势）、historyAnalysis、alertSettings、operationOverview。

建议扩展 GET /api/cockpit/v1/overview/warning-settings 入参：range + startTime + endTime。

建议字段	语义
`range.type`	`LAST_7_DAYS` \| `LAST_30_DAYS` \| `LAST_90_DAYS` \| `CUSTOM`（替换硬编码的 `CURRENT_BASELINE`）
`range.start`,`range.end`	实际生效区间；`CUSTOM` 时回显请求值
`trend[].bucket`	保持 `yyyy-MM-dd`；窗口跟随 `range`

CockpitOverviewWarningSettingsResponse.Range 与 TrendPoint 结构已存在，属加参数 + 填值，不需新端点。

C. 效率时长聚合

覆盖面板：responseEfficiency。

建议在 CockpitOverviewWarningSettingsResponse.FamilyMetrics 内新增：

建议字段	语义
`averageResponseSeconds`	平均响应时长 = avg(首次接单时间 − 事件发生时间)；接单时间取工单 timeline 中 `stateCode=3` 的 `operatedAt`
`averageCloseSeconds`	平均关闭时长 = avg(结案时间 − 事件发生时间)；结案时间取 `CockpitWorkOrderSummary.realFinishTime`
`medianResponseSeconds`,`medianCloseSeconds`	中位数，抗长尾（大屏指标更稳健）
`durationSampleCount`	参与计算的样本数，供口径透明
`durationState`,`durationReason`	复用既有 `state`/`reason` 模式表达 `EMPTY`/`NO_SAMPLES`

数据源已存在（createTime/realFinishTime + timeline operatedAt），缺的是聚合层。

D. 应急保障域 —— 需全新读模型

覆盖面板：emergency。后端 cockpit 包内该域完全不存在。

建议新端点 GET /api/cockpit/v1/infrastructure/emergency，参数 industry、facilityType、region。

建议结构	字段
`totals`	`hazardSourceCount`,`protectionTargetCount`,`emergencyResourceCount`
`hazardSources[]`	`code`,`name`,`hazardType`,`hazardLevel`,`industry`,`region`,`relatedFacilityCode`,`longitude`,`latitude`,`coordinateValidation`
`protectionTargets[]`	`code`,`name`,`targetType`,`targetLevel`,`industry`,`region`,`distanceToSourceMeters`,`longitude`,`latitude`,`coordinateValidation`
`emergencyResources[]`	`code`,`name`,`resourceType`,`quantity`,`unit`,`ownershipUnit`,`contactName`,`contactPhone`,`region`,`longitude`,`latitude`
信封	`freshness`,`selectedFilters`,`mapFilter`,`excluded`（对齐 `CockpitInfrastructureBaseArchivesResponse` 既有模式）

E. 管理信息读模型

覆盖面板：management。

E1. 扩展 CockpitEquipmentArchive / CockpitEquipmentArchiveSnapshot 补 managementUnit、managementUnitCode（当前只有 ownershipUnit + maintainer，「管理单位」缺失）。

E2. 建议新端点 GET /api/cockpit/v1/infrastructure/management，参数 industry、region：

建议结构	字段
`managementUnits[]`	`code`,`name`,`unitType`,`contactName`,`contactPhone`,`region`,`facilityCount`
`ownershipUnits[]`	`code`,`name`,`unitType`,`region`,`facilityCount`
`responsibilityZones[]`	`code`,`name`,`region`,`managementUnitCode`,`ownershipUnitCode`,`facilityCount`

E3. 或最小改动：在 CockpitInfrastructureBaseArchivesResponse.facilityTypeDistribution 之外逐设施暴露 region + managementUnitCode（CockpitInfrastructureBaseArchivesSnapshot.SourceFacility.region 已存在，只是未输出）。

F. 运行信息（设施级能力指标）

覆盖面板：operation。

建议新端点 GET /api/cockpit/v1/facilities/{facilityCode}/operation：

建议字段	语义
`supplyCapacity`	`{metricCode,metricName,value,unit,status,sampledAt}` — 供应能力
`transmissionCapacity`	同上 — 输送能力
`carryingCapacity`	同上 — 承载能力
`metrics[]`	复用 `CockpitMetric` 结构承载其余指标
`state`,`stateReason`,`freshness`	复用既有可用性语义

备选：给 #11/#12 指标端点增加 facilityCode 维度以支持设施级汇总。

G. 监测点/地图的行业与类型维度 —— 全局行业筛选的前置条件

覆盖面板：monitoringPointLedger、monitoringDistribution，并影响 CONTEXT.md 的全局「行业筛选」。

G1. GET /api/cockpit/v1/map-snapshot 增加入参 industry。

G2. CockpitMonitoringPointSummary 增设：

建议字段	语义
`industry`	行业归属（燃气/供水/排水…），供全局筛选与台账分组
`pointTypeCode`,`pointTypeName`	点位类型
`deviceCount`,`onlineDeviceCount`,`alarmDeviceCount`,`warningDeviceCount`	卡片徽标；可直接复用 `CockpitMonitoringPointDeviceStatistics` 结构
`latestSampledAt`	最近采集时间，省掉逐点 `metrics/current`

G3. CockpitUnassociatedEquipmentSummary 同样增设 industry、deviceTypeCode/Name。

G4. 保留 CockpitMapSnapshot.SourceMonitoringPoint.devices 的设备编码到响应（当前在 CockpitMapSnapshotService.monitoringPoint() 被丢弃），供 WS cockpitDeviceStatusDelta 用 deviceCode 回联点位状态。

H. 跨设备设备状态清单

覆盖面板：operationOverview（离线设备清单）、monitoringSummary。

WS 已明确「REST 是初始快照，WS 只推增量」，但当前没有跨设备设备状态 REST 快照。

建议新端点 GET /api/cockpit/v1/equipments/status，参数 industry、monitoringState（如 OFFLINE）、page、pageSize：

建议字段	语义
`devices[]`	`deviceCode`,`deviceName`,`deviceTypeCode`,`deviceTypeName`,`industry`,`monitoringState`,`statusTime`,`serverUpdatedAt`,`freshness`,`longitude`,`latitude`,`monitoringPointCode`
`total`,`counts`	`counts` 复用 `CockpitOverviewMonitoringResponse.Counts.Status` 语义

备选：让 cockpitSubscribe 的 cockpitSubscribed 回帧携带初始全量状态数组（与 WS 处理器注释的现状相反，需后端确认）。

5. 结论摘要

判定	面板数	面板
✅ 完全覆盖	5	`infrastructureSummary`、`monitoringSummary`、`alertSettings`、`archive`、`monitoringOverview`
⚠️ 存在缺口	11	`situationSummary`、`operation`、`management`、`emergency`、`monitoringDistribution`、`operationOverview`、`monitoringPointLedger`、`currentEvents`、`historyAnalysis`、`responseEfficiency`、`eventAnalysis`

按模式：

模式	覆盖	缺口
`overview`	3 / 4	`situationSummary`（趋势窗口不可声明，弱缺口）
`infrastructure`	1 / 4	`operation`、`management`、`emergency`（`emergency` 为全域缺失）
`monitoring`	1 / 4	`monitoringDistribution`、`operationOverview`、`monitoringPointLedger`
`warningResponse`	0 / 4	四个面板全部有缺口，根因都是「跨设备事件读模型缺失」

Top 5 缺失字段（按阻塞强度）：

跨设备当前事件流（eventCode + 归属设备/监测点/行业 + 分页）— 完全阻塞 currentEvents
跨设备带时间范围的历史事件流 + 趋势 range 参数（7/30/90/自定义）— 阻塞 historyAnalysis
应急保障域三件套（hazardSources / protectionTargets / emergencyResources）— 阻塞 emergency 整版
监测点 industry + 点位类型 + 设备计数徽标（含 map-snapshot 的 industry 入参）— 阻塞 monitoringPointLedger / monitoringDistribution 与全局行业筛选
事件经纬度（longitude/latitude + coordinateValidation）与响应/关闭时长聚合（averageResponseSeconds / averageCloseSeconds）— 阻塞 currentEvents 上图与 responseEfficiency

补充观察：

后端已存在一整层面板级聚合读模型（#5/#6/#7/#8），前端实现票 17-20 的 mock 首期可直接按这 4 个响应的形状建模，不必从单设备端点上拼装。
4 个面板级端点 + AjaxResult 信封 + freshness/state/stateReason/excluded 的错误与空态模式是全后端统一的，前端只需实现一套分区状态渲染（对应 CockpitSectionState：SUCCESS/EMPTY/STALE/FAILED）。
待业务确认（本调研不发明结论）：
1. 「故障」是否等同 stale，还是需要独立桶。
2. 「处置率」当前定义是 state==6 / 全部事件（含已取消），是否即业务所说的处置率。
3. 「管理单位」与 maintainer（维护单位）是否同一概念。

6. 证据索引

控制器（`E:\pipe-ner-server\pipe-network-service\zksy-admin\src\main\java\com\zksy\web\controller\cockpit\`）

CockpitFoundationController、CockpitMapSnapshotController、CockpitMonitoringPointDetailController、CockpitDeviceBoundaryController、CockpitOverviewInfrastructureController、CockpitOverviewMonitoringController、CockpitOverviewWarningSettingsController、CockpitInfrastructureBaseArchivesController、CockpitEquipmentArchiveController、CockpitEquipmentDetailAggregateController、CockpitTypeMetricsController、CockpitEventReadController、CockpitWorkOrderReadController、CockpitFreshnessController

响应/快照类（`E:\pipe-ner-server\pipe-network-service\zksy-system\src\main\java\com\zksy\cockpit\`）

foundation/（CockpitFoundationResponse、CockpitMapFrame、CockpitFreshnessResponse、CockpitFreshnessSection、CockpitFreshnessSectionData、CockpitFreshnessStatus、CockpitCoordinateValidation） map/（CockpitMapSnapshotResponse、CockpitMapSnapshot、CockpitMapSnapshotService、CockpitMonitoringPointSummary、CockpitUnassociatedEquipmentSummary、CockpitCoordinateValidationSummary） point/（CockpitMonitoringPointDetailResponse、CockpitMonitoringPointStatus、CockpitMonitoringPointStatusEntry、CockpitMonitoringPointStatusReason、CockpitMonitoringPointDeviceCard、CockpitMonitoringPointDeviceStatistics、CockpitMonitoringPointStatusResolver） equipment/（CockpitEquipmentArchiveResponse、CockpitEquipmentArchive、CockpitEquipmentArchiveSnapshot、CockpitEquipmentImage） type/（CockpitTypeMetricsResponse、CockpitMetric、CockpitMetricPoint） event/（CockpitEventReadResponse、CockpitEventWarning、CockpitEventAlarm、CockpitAlarmWarningRelation、CockpitEventLevelColor） workorder/（CockpitWorkOrderReadResponse、CockpitWorkOrderSummary、CockpitWorkOrderTimelineResponse、CockpitWorkOrderTimelineEntry、CockpitWorkOrderState、CockpitWorkOrderStateDictionary、CockpitWorkOrderEventAssociation） detail/（CockpitEquipmentDetailAggregateResponse、CockpitSectionResult、CockpitSectionState） overview/（CockpitOverviewInfrastructureResponse、CockpitOverviewMonitoringResponse、CockpitOverviewWarningSettingsResponse、CockpitOverviewWarningSettingsService、CockpitOverviewMonitoringDeviceStatusDelta） infrastructure/（CockpitInfrastructureBaseArchivesResponse、CockpitInfrastructureBaseArchivesSnapshot） device/（CockpitDeviceBoundaryResponse、CockpitDeviceBoundary、CockpitFacilityBoundary、CockpitDeviceBoundaryStatistics、CockpitIndustryStatistics、CockpitTypeScope、CockpitDeviceType）

WebSocket

E:\pipe-ner-server\pipe-network-service\zksy-admin\src\main\java\com\zksy\web\websocket\DeviceStatusWebSocketHandler.java（协议注释第 34-86 行；cockpitSubscribe 第 341-357 行） ...\web\websocket\DeviceStatusRedisListener.java（cockpitDeltaMessage 第 171-185 行） ...\web\websocket\WebSocketConfig.java（注册 /ws/deviceStatus）

本仓库

docs/adr/0003-web-page-information-architecture.md — 模式→面板词典与列布局
CONTEXT.md — 态势总览、监测点台账、点位状态、行业筛选、两级详情等术语
.scratch/cockpit-shell-panel-layout/issues/17|18|19|20-*.md — 各模式面板验收项
.scratch/cockpit-shell-panel-layout/issues/24-panel-field-coverage.md — 本票

旁证（样例响应，非权威）

E:\pipe-ner-server\docs\cockpit\*.html：overview-infrastructure、overview-monitoring、overview-warning-settings、infrastructure-base-archives、map-snapshot、monitoring-point-detail、equipment-archive、type-metrics、event-read、work-order-seven-states、equipment-detail-aggregate、freshness-semantics、websocket-scope-delta、foundation、device-boundary

注：overview-warning-settings-demo.html 的 points:[{code,x,y}] 事件点位数组只存在于演示页，真实 CockpitOverviewWarningSettingsResponse 无对应字段（只有 mapFilter），是本报告 A 项缺口的旁证。

panel-field-coverage.md 38 KB Cronologia Originale

Research: 面板字段与后端契约覆盖

Decision

1. 后端契约基线（实测端点清单）

WebSocket /ws/deviceStatus

2. 判定口径

3. 逐面板字段覆盖

3.1 overview 模式

situationSummary 态势总览 — ⚠️ 1 处缺口

infrastructureSummary 基础设施 — ✅ 全覆盖

monitoringSummary 运行监测 — ✅ 全覆盖

alertSettings 预警设置 — ✅ 全覆盖

3.2 infrastructure 模式

archive 基础档案 — ✅ 全覆盖

operation 运行信息 — ❌ 2 处缺口

management 管理信息 — ❌ 3 处缺口

emergency 应急保障 — ❌ 全域缺失

monitoring 模式

monitoringOverview 监测概览 — ✅ 全覆盖

monitoringDistribution 监测分布 — ❌ 2 处缺口

operationOverview 运行概况 — ❌ 1 处缺口

monitoringPointLedger 监测点台账 — ❌ 4 处缺口

3.3 warningResponse 模式

currentEvents 当前预警 — ❌ 2 处缺口

historyAnalysis 历史分析 — ❌ 2 处缺口

responseEfficiency 预警效率 — ❌ 1 处缺口（含 2 个字段）

eventAnalysis 预警分析 — ❌ 1 处缺口（多个维度）