25-backend-contract-gaps.md 14 KB
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: 面板字段与后端契约覆盖调研（已 resolved）、2026-09-17 对后端仓库的复核，以及主会话的逐条核实。缺口分两类：
- 后端补契约——需要后端负责人实现。本仓库工作区写权限只覆盖
E:\City-Lifeline-Cockpit-TvT，且后端仓库当时有并行会话的未提交改动，不适合由本票直接改。 - 业务定义确认——需要业务方回答，本票不发明结论。
复核记录（2026-09-17）
复核方式：只读阅读后端仓库 E:\pipe-ner-server 的控制器与响应类（com.zksy.web.controller.cockpit、com.zksy.cockpit.*）；未改动后端任何文件，未跑构建或调试命令。
结论：8 组补契约中 4 组已交付，2 项跨领域缺口仍在，跨设备读模型仍未动
后端在 2026-09-16～09-17 落地了 5 个新读模型端点（对应后端 Gogs #33–#37）：
| 端点 | Gogs | 提交状态 | 对应补契约组 |
|---|---|---|---|
GET /api/cockpit/v1/infrastructure/operating-information |
#33 | 已提交 | F 运行信息 |
GET /api/cockpit/v1/infrastructure/management-information |
#34 | 已提交 | E 管理信息 |
GET /api/cockpit/v1/infrastructure/emergency-support |
#35 | 已提交 | D 应急保障 |
GET /api/cockpit/v1/monitoring/overview |
#36 | 已提交（当前 HEAD） | 监测概览 |
GET /api/cockpit/v1/monitoring/distribution |
#37 | 工作区未提交 | G 行业/类型维度、G3 |
这 5 个切片与既有切片同样采用「契约 + 空适配器 + demo」形态，真实数据源尚未接线。对「补契约」这一定位算缺口关闭，对「能取到真实数据」则仍待后端后续接线。
逐项判定
| 组 | 内容 | 今日状态 | 证据 |
|---|---|---|---|
| D | 应急保障域三件套 | ✅ 已交付 | CockpitInfrastructureEmergencySupportResponse：Totals{emergencyResourceCount,hazardSourceCount,protectionTargetCount,totalObjectCount} + Sections{emergencyResources,hazardSources,protectionTargets}（每项 objectCode/objectName/category/industry/area/pointCodes/eventAssociations）+ 三类分布 + eventSummary + mapFilter + excluded；入参 category/industry/area |
| E | 管理信息域 | ✅ 已交付 | CockpitInfrastructureManagementInformationResponse：organizations{organizationCode,organizationName,industry,facilityCount,equipmentCount,unmaintained,ownershipDistribution} + ownershipDistribution + totals.unmaintainedCount + mapFilter{industry,organizationCode}；入参 industry/organizationCode。原建议的 managementUnits/ownershipUnits/responsibilityZones 三数组未采用，改为「机构 + 权属分布」形状 |
| F | 设施/行业运行信息 | ✅ 已交付 | CockpitInfrastructureOperatingInformationResponse：industries[].metrics[]{metricCode,value,capacityValue,loadRatio,loadState,sampledAt,freshness,trend,abnormal,pointCodes} + abnormalMetricCount + mapFilter{industry,metricCodes,pointCodes}；入参 industry/range/from/to |
| G3 | 未关联设备补 industry 与设备类型 |
✅ 已交付 | CockpitMonitoringDistributionResponse.UnassociatedEquipmentMarker{deviceCode,deviceName,region,industry,deviceType,pointStatus,...} |
| G1 | map-snapshot 加 industry 入参 |
❌ 未交付 | CockpitMapSnapshotController 第 35–39 行入参仍只有 page/pageSize/snapshotAt |
| G2 | 点位摘要加 industry、点位类型与徽标 |
❌ 未交付 | CockpitMonitoringPointSummary 仍只有 pointCode/pointName/pointStatus/statusReasons/longitude/latitude/coordinateValidation 7 个字段 |
| G4 | 点位摘要返回关联设备编码 | ❌ 未交付 | 同上；monitoring/distribution 的 mapFilter.deviceCodes 是扁平列表，不构成 device→point 映射 |
| A | 跨设备当前/历史事件流 | ❌ 未交付 | 事件端点仍只有 equipments/{deviceCode}/events/current 与 events/history |
| B | 趋势时间范围可声明 | ⚠️ 部分 | operating-information 已有 range/from/to；overview/warning-settings 入参仍只有 mode（Response.Range{type,start,end} 结构已在，属加参数） |
| C | 响应/关闭时长聚合 | ❌ 未交付 | cockpit 包内无任何 duration/Seconds 字段；#31 落地的是比率型 handlingEfficiency{numerator,denominator,value,state,reason} 与 cancelledCount/unlinkedEventCount，不是时长 |
| H | 跨设备设备状态清单 | ❌ 未交付 | 只有 Counts.Status{online,offline,stale,unknownOrMissing,denominator} 分桶，无逐设备清单；无 equipments/status 端点 |
两个跨领域缺口的补充证据
monitoring/distribution（#37）已能承接全局行业筛选的意图：入参 industry/deviceType/pointStatus/region，逐点返回 industry/deviceType，并给 mapFilter{industry,deviceType,pointStatus,region,pointCodes,deviceCodes}。因此「给 map-snapshot 加 industry 入参」不再是唯一可行路径——采用哪条路径属后端设计决定，本票不代为选择，改为在验收项里标注「实现路径待后端负责人定」。
WS 侧仍未解决：CockpitMonitoringDistributionDeviceStatusDelta、CockpitMonitoringOverviewDeviceStatusDelta、CockpitOverviewMonitoringDeviceStatusDelta 三个增量 DTO 都只带 deviceCode + monitoringState（外加 sampledAt/statusTime/serverUpdatedAt），DeviceStatusWebSocketHandler 全文没有 pointCode/monitoringPointCode。但后端内部已持有映射（CockpitMonitoringDistributionSnapshot.SourceMonitoringPoint.devices，且服务端 applyDeviceStatusDelta 能按 deviceCode 解析到点位），所以最小改动是二选一：点位摘要输出关联设备编码，或 WS 增量帧直接带上 monitoringPointCode。
G1 全局行业筛选落不到地图点位（已核实；实现路径待后端负责人定）
CONTEXT.md 定义行业筛选是作用于整个驾驶舱的全局条件，但 map-snapshot 至今无法过滤地图点位：
GET /api/cockpit/v1/map-snapshot无industry入参（CockpitMapSnapshotController）。CockpitMonitoringPointSummary字段仅pointCode / pointName / pointStatus / statusReasons / longitude / latitude / coordinateValidation——没有industry与点位类型，服务端与客户端都无从过滤。- 对照：
overview/monitoring、infrastructure/base-archives、monitoring/overview、monitoring/distribution都已支持industry入参，说明后端具备该维度，只是没给地图摘要。
需要后端定路径（二选一或都做）：① map-snapshot 增加 industry 入参，CockpitMonitoringPointSummary 增加 industry 与点位类型字段；② 地图点位改由 monitoring/distribution 提供——它已有 industry/deviceType/pointStatus/region 入参与逐点 industry/deviceType，但该端点尚未提交，且前端实现票需相应改取数路径。
G2 map-snapshot 丢弃设备编码，WS 增量无法回联点位（已核实，仍缺）
- 内部快照
CockpitMapSnapshot.SourceMonitoringPoint.devices存在，但CockpitMapSnapshotService.monitoringPoint()（145–160 行）只用它解析点位状态，没有把设备编码写进响应。 - WS
cockpitDeviceStatusDelta增量只带deviceCode+ 状态，前端拿到增量后无法知道它属于哪个监测点，点位状态无法联动。 - 另外
cockpitSubscribe回帧只有{scope, serverUpdatedAt}，无初始状态数组（后端注释明确 REST 是初始快照、WS 只发增量——契约本身成立，前端需按此实现）；线上帧的状态键是data.status，而后端 DTOCockpitOverviewMonitoringDeviceStatusDelta命名为monitoringState，接入时注意别名。
需要后端：CockpitMonitoringPointSummary 输出关联设备编码列表，或 WS 增量帧带上 monitoringPointCode——后端两处都已持有该映射，改动量都不大。
补契约清单（A–H）
11 个有缺口面板的完整字段表与分组补契约建议（含字段名、语义、是否需要新端点）见 research/panel-field-coverage.md 第 4 节，共 8 组；各组今日状态见上「逐项判定」：
- A 跨设备当前事件读模型（阻塞
currentEvents）— ❌ 未交付 - B 跨设备带时间范围的历史流 + 趋势
range（阻塞historyAnalysis）— ⚠️ 仅operating-information有range；warning-settings仍缺 - C 响应/关闭时长聚合（阻塞
responseEfficiency）— ❌ 未交付 - D 应急保障域三件套（阻塞
emergency整版）— ✅ 已交付（emergency-support） - E 管理信息域 — ✅ 已交付（
management-information） - F 设施运行信息域 — ✅ 已交付（
operating-information） - G 地图行业/类型维度（即 G1，含 G2/G3/G4）— G1/G2/G4 ❌，G3 ✅
- H 跨设备设备状态列表 — ❌ 未交付
实现票 17–20 的 mock 阶段可按已有的面板级聚合响应形状建模（原 4 个 + 新增 5 个）：/overview/infrastructure、/overview/monitoring、/overview/warning-settings、/infrastructure/base-archives、/infrastructure/operating-information、/infrastructure/management-information、/infrastructure/emergency-support、/monitoring/overview、/monitoring/distribution。
业务问题（待业务方确认，本票不发明结论）
三条仍未答复；下列为复核后掌握的现状与建议口径，供业务方确认或否决：
- 「故障」是否等同
stale？ 现状：monitoring/overview与overview/monitoring只有online/offline/stale/unknownOrMissing四个桶，没有独立「故障」桶。建议：业务确认前按「stale+unknownOrMissing，并显示原因」呈现；若要独立桶，需后端加字段。 - 「处置率」是否就是
handled/total（含已取消事件）？ 现状：overview/warning-settings已把口径显式化——handlingEfficiency{numerator,denominator,value,state,reason}配合total/handled/pending/cancelledCount/unlinkedEventCount/invalidWorkOrderStateCount。建议：确认即为handled/total（含已取消），并在面板标注分子分母；若业务口径要排除已取消，前端可用cancelledCount复算——但这属于业务定义，需答复。 - 「管理单位」与后端
maintainer（维护单位）是否同一概念？ 现状：新增的management-information用organizations+ownershipDistribution+unmaintained建模，与maintainer分开，倾向「不是同一概念」。建议：业务确认「管理单位 = 管理机构/权属单位，maintainer= 维护单位」这一区分，并回写术语表。
影响的实现票
| 票 | 影响 |
|---|---|
| 06 全局筛选 | G1：筛选联动地图依赖后端定路径（map-snapshot 加参 或 改用 monitoring/distribution） |
| 08 地图摘要 | G1、G2 |
| 15 WebSocket | G2：增量回联点位依赖设备编码或增量帧带 monitoringPointCode |
| 17 基础设施面板 | D/E/F 契约已交付，可对接 operating-information / management-information / emergency-support；真实数据源待后端接线 |
| 18 运行监测面板 | F、G、H：monitoring/overview、monitoring/distribution 可对接；H 仍缺 |
| 19 预警处置面板 | A、B、C 仍未交付，接真实接口仍受阻；mock 路径不受阻 |
| 20 总体概览面板 | B：situationSummary 趋势窗口仍不可声明 |
Acceptance criteria（后端负责人）
-
map-snapshot支持industry入参并在点位摘要中返回industry与点位类型。结论不变，实现路径待后端负责人定（候选 ① map-snapshot 加参；候选 ② 由monitoring/distribution承接，前端改取数路径）。 - 点位摘要返回关联设备编码列表，WS 增量可回联点位。结论不变，实现路径待定（候选 ① 点位摘要带设备编码；候选 ② WS 增量帧带
monitoringPointCode）。 - A–H 各组补契约与后端负责人逐项确认排期（或明确拒绝并记录理由）。当前进度：D/E/F/G3 已交付（4/11 项）；A/B/C/H 与 G1/G2/G4 未排期、未确认。
- 3 个业务问题得到业务方答复并回写本票。当前：0/3，待业务方确认（见上「业务问题」的建议口径）。
进度：30%
据实更新（原记 0%，因后端在 09-16～09-17 已交付 D/E/F/G3 四组契约）：
- 计分口径：8 组补契约拆为 11 个可判定项（A、B、C、D、E、F、G1、G2、G3、G4、H）+ 3 个业务问题 = 14 项。已交付 4 项（D/E/F/G3），B 记部分完成，合计约 30%。
- 未完成，不 close。理由：AC1/AC2 结论未达成；AC3 只完成一半且「与后端负责人逐项确认排期」没有记录；AC4 三条业务问题 0 答复。
- 本票未改动任何实现票的验收项；未改动后端仓库任何文件。
下一步
- 后端负责人（决定项）：定 G1/G2/G4 的实现路径（
map-snapshot加参 vs 由monitoring/distribution承接；设备编码回联取点位摘要还是 WS 增量帧）。 - 后端负责人（排期项）：A 跨设备当前/历史事件流、B
warning-settings的range入参、C 响应/关闭时长聚合、H 跨设备设备状态清单——排期或明确拒绝并记录理由。 - 后端（回填项）：
monitoring/distribution（#37）当前在工作区未提交，提交后回填本票状态。 - 业务方：答复上「业务问题」三条口径。
- 前端实现票 06/08/15/17–20：mock 阶段不受阻；接真实接口前先取第 1、2 项的结论，避免按错端点建模。