Главная Обзор Помощь
Регистрация Вход
ChenJZ
/
City-Lifeline-Cockpit
1
0
Ответвить 0
Файлы Задачи 0 Запросы на слияние 0 Вики
Дерево: 3825890a4e
Ветки Метки
City-Lifelin...
/
.scratch
/
cockpit-shell-panel-layout
/
handoff
/
backend-contract-gaps.md

backend-contract-gaps.md 29 KB
История Исходник

后端契约缺口交付包（供后端项目经理建票）

Status: ready-for-human Labels: ready-for-human Category: handoff Blocked by: None

本交接包的执行入口已迁移到新地图：驾驶舱真实后端数据接线（决策地图）。本文件保留旧 BT-1…BT-8 的历史证据和当前缺口摘要；新地图 01–06 才负责切片拆分、真实联调、前端 real 生命周期和业务语义收口。

最新现状（2026-09-28）

  • 后端 HEAD=origin/master=355a8af。最新文档记录本机 IntelliJ 实例 127.0.0.1:8301 的真实登录态验收：401、非法参数 400、同一 snapshotAt 多页稳定、点位详情/设备详情链路 200/readOnly、主要端点 200/readOnly、WebSocket cockpitSubscribe 回帧成功；另有 16 个非法参数样例全部 400。
  • 目标部署 192.168.110.30:8301 仍不可达，因此上述是本机真实 HTTP/WS 证据，不是目标部署收口证据。凭据未写入仓库、文档或交接包。
  • 当前手册已记录：四行业 MANHOLE、地图 map-snapshot 筛选、Redis 共享快照签发/过期、监测点详情 snapshotAt 对齐、设备自身坐标字段、未校核坐标清单-only 降级、当前 KingbaseES 稀疏数据和 23 个空适配器对应的 @Primary Business*Adapter 运行边界。
  • 仍未收口：地图 pointStatus 与未关联设备状态语义、统一 createdAt/数据时间、前端 real 生命周期、真实联调证据登记、工单公开字典 1–7 与运行时 0–7 的对齐、目标部署可达性和生产规模性能。
  • 本轮没有在 Gogs 新建票；新地图 01–06 均为未解决的 HITL 决策票，后端/前端执行票要等决策地图收口后再创建。

历史建票记录（2026-09-18）：五张草案曾在 Gogs shaoy/pipe-ner-server 建票；BT-1…BT-4 当时关闭，BT-5 的需求重建与状态见前端票据第十一轮。2026-09-24 本轮未复核 Gogs 远端状态；下表「已交付」仅指历史票据，不代表当前 HEAD/真实库已验收：

草案 Gogs 票号 状态
BT-1 #59 ✅ 已交付并关闭（2026-09-18）
BT-2 #60 ✅ 已交付并关闭（2026-09-18，走路径①完整）
BT-3 #61 ✅ 已交付并关闭（2026-09-18）
BT-4 #62 ✅ 已交付并关闭（2026-09-18）
BT-5 真实数据接线（程序级） ⚠️ 第十一轮曾记录旧代码无法编译、进度回到 0%；本轮旧访问器引用已改，但未重新运行编译或联调，当前可验收进度及远端标签未复核

BT-6 为可选票，未建。若后端 PM 确认需要，再按下面草案建。

现行缺口同步（2026-09-24，本轮只读源码与文档）

后端本地 HEAD=c5a5b87=origin/master。当前工作树 BusinessCockpitDeviceFactResolver 已改用 work_order.device_id，CockpitTypeIndustry 与三个监测适配器已改用 equipment_type.id/parent_id；此前文档点名的旧访问器编译错误已不能再作为当前源码事实，但本轮没有跑 Maven，也没有重查 KingbaseES，不能据此宣称构建/联调通过。后端 docs/cockpit/README.md 第 8 节及后端 spec 第 101 行也应按此复核。旧数据库计数、旧 4/22 接线进度只供追溯。

当前已核实的待办按性质分开：

  • I1（BT-7）：map-snapshot 不收 pointStatus；逐点已有状态，但未关联设备摘要没有状态或设备运行事实，后端须先定未关联设备的状态筛选口径，维护同一 snapshotAt 下过滤、分页与全量坐标汇总一致。阻塞前端《运行监测模式面板》收口。
  • I2（BT-8）：/monitoring/overview 无逐设备最近采集时间响应字段。/overview/monitoring 虽有 metricFreshness DTO，但当前只有空适配器，源为空时仍为 null；必须明确采样语义和真实来源，不能把另一个 DTO 当成可用数据。票 24 的旧字段覆盖表把端点归属记错。
  • E1（管理信息责任区域）：/infrastructure/management-information 的 organizations、ownershipDistribution、mapFilter 没有区域/责任区域维度。需裁定组织—责任区域关系与数据源，并补契约或明确不提供；前端《基础设施模式面板》目前如实标缺口。
  • J1（四行业）：已裁定 MANHOLE 为第四正式行业、typeCode=String(equipment_type.id)；未提交类型助手仅能由直接 parentId=4 推导，map-snapshot、监测、事件、基础设施和 device-boundary 等服务仍只认三行业。需覆盖类型层级、筛选、统计与契约测试，避免实际返回 400/被排除；归入现有票或新建契约票待 PM 确认。
  • J2（工单状态）：权威 WorkOrderStatusEnum 为 0–7，5 结案、6 延期；cockpit 仍公开 1–7 七态，byLegacyCode(0) 落 7 已取消，真实工单适配器和预警效率服务沿用旧码。须对齐字典、时间线、处置率和测试；业务口径仍待人确认，归票范围也待 PM 确认。
  • BT-5（真实接线）：地图/三个监测真实适配器等只在未提交工作树，文件与 @Primary 不证明可运行；地图适配器逐页重新查询，服务仅验证回显 snapshotAt，跨页一致性未获实证。须提交/编译/契约测试/当前 KingbaseES 只读联调后，才能恢复接线验收进度。

本轮没有在 Gogs 新建或修改工单。历史《Cockpit device-to-point linkage》等四张票的关闭事实保留，但其关键地图/回联字段目前不在 committed HEAD；《真实数据接线（程序级）》涉及新模型接线，I1/I2/E1/J1/J2 的归票与负责人待后端 PM 裁定。下方历史工单草案与旧「BT-5 唯一缺口」结论不得作为现行判据。

历史基线（2026-09-24，已被上节最新现状覆盖）

  • 当时后端 HEAD=c5a5b87，工作树含未提交 cockpit 适配器改动；当时的 Maven 编译失败点是已删除的 WorkOrder.getDeviceCode、EquipmentType.getTypeId/getParentTypeId。这些引用在上节本轮源码里已改，但编译/联调尚未重跑；历史 4/22 片仍只是工作记录，不是当前验收结果。
  • KingbaseES app_user 当前只读观测：equipment_base=2、equipment_status=2、monitor_point=7、equipment_point_rel=20、early_warning=35、alarm_data=3、work_order=1；旧 37 台设备、507 条报警、3 条有效关联已经失效。
  • 当前类型表是 equipment_type.id/type_name/parent_id，没有旧 type_id/parent_type_id；当前工单表由 device_id 关联设备，报警通过 alarm_data.order_id 关联工单。当前工单状态为 0–7（含 6 延期中），以 ADR-0010 为准。
  • 已裁定：公开 typeCode 使用 equipment_type.id（JSON 为字符串）；井盖为第四正式行业 MANHOLE；当前无可信坐标校核来源时保持 renderable=false，不以通用经纬度范围自动放行；联调以当前真实 KingbaseES 数据为基准。旧三行业校验与类型映射尚未实现。
  • 已澄清“工单字典”指代码枚举 WorkOrderStatusEnum（0–7，见 ADR-0010），不是数据库字典表；当前 app_user.sys_dict_type/sys_dict_data 无工单状态条目是符合现状的，无须另找表。修复编译、跑契约测试与当前库联调前，不沿用历史 BT-5 完成度结论。

历史复核基线（2026-09-17，2026-09-18 第三轮复验无变化；仅供追溯）

  • 后端仓库 E:\pipe-ner-server，本地 HEAD ed0ace5（test(cockpit): add contract integration environment and handoff (#43)）。
  • 远端 origin HEAD 仍是 e2b4e45（#42）——#43 尚未推送，联调前请确认部署来源是其预期提交。
  • 复核方式：只读阅读控制器、响应类、适配器与 docs/cockpit/README.md；未改动后端任何文件，未跑构建或调试命令。

一、完成情况总览（2026-09-17 历史快照）

下表只保留最初建票的时间点证据，不是当前缺口清单；现行判定请读本文件「现行缺口同步」与前端《后端契约缺口待办（跨领域两项 + 补契约清单）》：

项 内容 状态 证据
A1 跨设备当前事件流 ✅ 已交付 GET /api/cockpit/v1/events/current（mode 必填，level/industry/status/分页）；CockpitCurrentEventsResponse.EventItem 含 eventNo/eventType/level/levelColor/status/value/unit/deviceCode/location/industry/longitude/latitude/workOrderSummary + sections{events,workOrders} + mapFilter.deviceCodes
A2 跨设备历史事件流 + 时间范围 ✅ 已交付 GET /api/cockpit/v1/events/history-analysis（eventFamily 必填 + startTime/endTime）；回显 Range{type,startTime,endTime}
B 趋势时间范围可声明 ⚠️ 仅剩一处 monitoring/situation、infrastructure/operating-information、events/history-analysis、events/handling-efficiency、events/multidimensional-analysis 均已支持范围参数；overview/warning-settings 仍只有 mode（→ 见 BT-3）
C 响应/关闭时长聚合 ✅ 已交付 GET /api/cockpit/v1/events/handling-efficiency：averageDuration{value,unit,sampleCount,state,reason} + durationTrend[] + 工单 durationHours；口径已冻结 basis = CLOSED_WORK_ORDERS_OVER_TOTAL_EVENTS
D 应急保障域三件套 ✅ 已交付 GET /api/cockpit/v1/infrastructure/emergency-support
E 管理信息域 ✅ 已交付 GET /api/cockpit/v1/infrastructure/management-information
F 设施/行业运行信息 ✅ 已交付 GET /api/cockpit/v1/infrastructure/operating-information
G1 全局行业筛选落到地图点位 ❌ 未交付（且路径待裁定） map-snapshot 入参仍只有 page/pageSize/snapshotAt；但 /monitoring/distribution（#37）已带 industry/deviceType/pointStatus/region 与逐点 industry/deviceType（→ 见 BT-2）
G2 点位摘要补 industry、类型、徽标 ❌ 未交付 CockpitMonitoringPointSummary 仍只有 pointCode/pointName/pointStatus/statusReasons/longitude/latitude/coordinateValidation
G3 未关联设备补 industry、设备类型 ✅ 已交付 CockpitMonitoringDistributionResponse.UnassociatedEquipmentMarker
G4 设备编码回联点位（WS 增量可用） ❌ 未交付 四个增量 DTO 均只有 deviceCode + 状态，无 monitoringPointCode（→ 见 BT-1）
H 跨设备设备状态清单 ✅ 已交付 GET /api/cockpit/v1/monitoring/situation：abnormalEquipment[]{deviceCode,deviceName,deviceType,industry,region,abnormalType,status,statusReasons,longitude,latitude,coordinateValidation} + 分页 + mapFilter.deviceCodes

另有 #43 交付的移交与联调手册：docs/cockpit/README.md（契约总则、字典冻结、端点清单、分页/快照/错误口径、WebSocket 增量、启动与联调检查表、容器化评估、已知未验证项）。这份手册本身已解答了票 25 里「字段名、语义、字典」类的问题，不需要再建票。

二、真实数据接线状态（程序级缺口）

后端目前交付的是契约，不是数据：

  • 历史基线（2026-09-17）：23 个 cockpit 适配器接口中，22 个只装配了 Empty*Adapter；唯一真实实现是工单读模型。
  • 未提交工作树已新增地图与监测链路的 4 个真实适配器，先前已删除的类型/工单访问器在本轮源码检查中已更换；本轮未跑 Maven 或联调，不能视为 4/22 已交付。
  • 各切片在 docs/cockpit/ 下的 *-demo.html 是内嵌 fixtures，不代表真实库数据。
  • 后端手册记录的现行数据库样本极小且关系稀疏；本轮未重查数据库，验收需以当前实体/schema 与真实库重新验证。

后果：BT-5 的需求已重建，但历史“全空快照”与“4/22 进度”都不是当前可验收结论；票面此前记载它从 needs-triage 转回 ready-for-agent，本轮未通过 Gogs 真人验证复核标签。

三、历史后端工单草案与新增待裁定项

BT-1…BT-5 已在 2026-09-18 建票，下列原始草案供追溯，不要重复提交到 Gogs；BT-7/BT-8 与 E1 是 2026-09-24 仍待后端 PM 裁定归票的新增需求。

BT-1 Cockpit device-to-point linkage（REST + WebSocket）→ Gogs #59 ✅ 已交付

背景与证据

  • CockpitMapSnapshotService.monitoringPoint() 只把 CockpitMapSnapshot.SourceMonitoringPoint.devices 用于解析点位状态，没有写进响应；CockpitMonitoringPointSummary 没有任何设备字段。
  • WS 增量只带 deviceCode：CockpitMonitoringDistributionDeviceStatusDelta、CockpitMonitoringOverviewDeviceStatusDelta、CockpitMonitoringSituationDeviceStatusDelta、CockpitOverviewMonitoringDeviceStatusDelta 四个 DTO 均无 monitoringPointCode；DeviceStatusWebSocketHandler 全文无点位字段。
  • 事件读模型的行也没有归属点位：CockpitCurrentEventsResponse.EventItem 与 history-analysis 的 row 都缺 monitoringPointCode。
  • 现有可用但代价高的替代路径：GET /monitoring-points/{monitoringPointCode} 的 devices[].deviceCode（逐点 N+1）。
  • 后端内部已持有该映射（SourceMonitoringPoint.devices；applyDeviceStatusDelta 能按 deviceCode 解析到点位），因此改动量集中在响应层。

要做什么（建议 ①+②，③ 视事件面板需要）

  1. CockpitMonitoringPointSummary 增加 deviceCodes（关联设备编码列表），并顺带补 industry 与 typeCode。
  2. WS 增量帧增加 monitoringPointCode（未关联设备为 null / 不出现）。
  3. 事件读模型行增加 monitoringPointCode 与 monitoringPointName。

验收标准

  • 点位摘要返回关联设备编码；同一 snapshotAt 下与 /monitoring-points/{code} 的 devices[] 一致，且不产生重复点位。
  • WS 增量给出 monitoringPointCode；未关联设备显式 null，不静默丢失。
  • 事件行返回 monitoringPointCode，无归属时为 null。
  • 契约测试覆盖 REST 与 WS 两侧；docs/cockpit/README.md 与字段字典同步更新。

解除阻塞的前端票：15（WebSocket 状态联动）、08（地图摘要）、19（当前预警 / 历史分析上图联动）。

BT-2 全局行业筛选落图：路径裁定 + 落地 → Gogs #60 ✅ 已交付（走路径①完整）

背景与证据

  • CONTEXT.md 定义行业筛选是作用于整个驾驶舱的全局条件。
  • GET /map-snapshot 没有 industry 入参；CockpitMonitoringPointSummary 也没有 industry/类型字段，服务端与客户端都无从过滤。
  • 但 GET /monitoring/distribution（#37）与 GET /monitoring/overview 已支持 industry/deviceType，distribution 还逐点返回 industry/deviceType 并给 mapFilter{industry,deviceType,pointStatus,region,pointCodes,deviceCodes}。

要做什么（二选一，并在 docs/cockpit/README.md 第 3 节写明结论）

  1. 给 map-snapshot 增加 industry（以及 deviceType）入参，并给 CockpitMonitoringPointSummary 补 industry/typeCode；或
  2. 正式声明地图筛选以 /monitoring/distribution 为准，map-snapshot 保持纯分页快照，前端改取数路径。

验收标准

  • 决策结论写入契约手册，前端不需要猜路径。
  • 选定路径端到端可用：服务端完成过滤，mapFilter 回显实际生效范围，分页与 snapshotAt 语义不变。

解除阻塞的前端票：18（运行监测面板，含验收项「面板筛选可作用于地图点位」与监测点台账）、08（地图摘要）。

BT-3 warning-settings 趋势窗口可声明 → Gogs #61 ✅ 已交付

背景与证据：其余切片都已接受时间范围并回显 Range，只有 GET /overview/warning-settings 仍只有 mode；CockpitOverviewWarningSettingsResponse.Range{type,start,end} 结构已存在，窗口目前固定。

要做什么：给该端点增加 range / startTime / endTime 入参，填充 Range 与 trend[].bucket，沿用兄弟切片的范围语义。

验收标准：非法范围返回 400 INVALID_REQUEST；range 回显实际生效区间；趋势桶跟随窗口变化；契约测试与手册同步。

解除阻塞的前端票：20（态势总览近 7 日趋势）、总体概览的预警设置面板。

BT-4 事件行补 coordinateValidation 与报警阈值 → Gogs #62 ✅ 已交付

背景与证据：字典已冻结「无效或未验证坐标 renderable=false，禁止渲染」，CockpitMonitoringDistributionResponse、CockpitMonitoringSituationResponse 等都已携带 CockpitCoordinateValidation；但 CockpitCurrentEventsResponse.EventItem 只有 longitude/latitude，没有 coordinateValidation，事件因此无法判定能否上图。A1 原建议中的 thresholdMinValue/thresholdMaxValue（仅报警族）同样缺失。

要做什么：事件读模型（events/current 与 events/history-analysis）的行补 coordinateValidation；报警族在数据可得时补阈值字段。

验收标准：每条事件携带 coordinateValidation（state/reason/renderable/crs）；坐标缺失或未验证时 renderable=false 且有 reason；契约测试与手册同步。

解除阻塞的前端票：19（当前预警上图、历史分析定位）。

BT-5 真实数据接线（程序级） → Gogs #63

背景与证据：见上文「二、真实数据接线状态」——23 个适配器接口中 22 个仍为空实现（不计 /foundation 自检则 21/22）。

要做什么：按切片补真实适配器（复用既有表与服务，遵循 cockpit-backend-read-contracts spec 的「先组合既有表与服务，测量后再加投影/索引」）。建议优先级：先地图与监测链路（map-snapshot、monitoring/distribution、monitoring/overview、monitoring/situation、monitoring-points/{code}），再基础设施三切片，最后预警处置四切片（其中工单链路已接）。

验收标准：每个切片存在非空适配器并被 Spring 装配；用真实库跑通 docs/cockpit/README.md 第 6 节的联调检查表 1–7；snapshotAt 分页稳定、监测点不重复；空结果仍走 200 + freshness.state=EMPTY，不用 5xx 表达空。

解除阻塞：所有前端票「接真实接口」的环节（mock 阶段不受阻）。

BT-6（可选，待确认）situation 支持 monitoringState 过滤

背景：H 的原始需求是「跨设备设备状态清单（如离线设备清单）」。/monitoring/situation 已给出分页的 abnormalEquipment[]，但它按 industry/deviceType/时间过滤，没有 monitoringState 入参。

要做什么：若 operationOverview 的离线设备清单需要按状态取数，给 situation 增加 monitoringState（六态字典）入参。

验收标准：传 OFFLINE 只返回离线设备；mapFilter 回显；不改变默认行为。

备注：若 abnormalEquipment 已满足面板需求，此票不必建。

BT-7 地图快照补 pointStatus 入参（票 18 实施时新暴露，阻塞票 18 收口）

归属说明（票 18 补记）：本草案由票 18 实施时提出，已由票 25 接手—— 其 2026-09-24「现行缺口同步」把本条记为 I1（BT-7） 并补正了口径 （未关联设备摘要没有状态/设备运行事实，须先定义其筛选口径；同一 snapshotAt 下 过滤、分页与全量坐标汇总要一致）。后续修订与排期以票 25 为准，本段不再由票 18 维护。

背景与证据

  • 票 25 第 3 节已冻结「全局筛选落到地图以 map-snapshot 为准、服务端完成过滤」， 且该端点当前收 industry/region/deviceType 三入参并回显 mapFilter。
  • 但状态维度没有落图路径：/monitoring/distribution 收 pointStatus （resolvePointStatus 对认不出的值 400），map-snapshot 不收。
  • 票 18 验收第 5 条是「面板筛选可作用于地图点位」，而验收第 2 条要求「监测分布」展示状态分布。 前端已把状态做成全局筛选条件（filterStore.pointStatus），它真的作用到面板与台账， 但地图不跟随 —— 同一个条件在界面上是「全局」而在数据上只管运行监测模式。
  • 逐点状态已在响应里（CockpitMonitoringPointSummary.pointStatus），但未关联设备摘要没有同等状态字段；不是只加参数就能安全过滤整个快照。

要做什么

  1. CockpitMapSnapshotController 增加 pointStatus 入参（取值 CockpitMonitoringPointStatus 六态： ALARM/WARNING/WORK_ORDER/NORMAL/OFFLINE/EMPTY），认不出的值 400 INVALID_REQUEST （与 /monitoring/distribution 的 resolvePointStatus 同一口径）。
  2. 点位已有 pointStatus，但未关联设备快照与摘要没有状态/设备实时事实；先裁定它如何参与状态筛选，补可信的状态来源或明示不参与，不能把它简单当成点位状态。
  3. 服务端按裁定后的规则过滤点位及未关联设备；mapFilter 增加 pointStatus 回显。保持 snapshotAt 跨页一致，并按筛选范围全量计算 coordinateValidation 汇总。

验收标准

  • 传 pointStatus=ALARM 只返回符合状态的点位；未关联设备按已裁定的状态规则处理、不能被误算作无设备点位；mapFilter.pointStatus 回显，分页、snapshotAt 与全量坐标汇总一致。
  • 不传时行为与今天的目标快照契约一致（默认不排除任何对象）；但 industry/region/deviceType 三筛选目前也只在后端未提交工作树，不能用 committed HEAD 的行为冒充对照组。
  • 非法值 400 INVALID_REQUEST，文案与兄弟切片一致。

当前前端处理（不假装跟随）：面板上常驻一条说明「状态筛选作用于本面板与监测点台账； map-snapshot 目前不收状态入参，一张图不随状态变化」；没有在前端对已加载标记做过滤 —— 那只对翻到的页生效，会出现「地图上点少了而摘要说已上图 N 个不变」的自相矛盾。 票 18 因此不 close（记 90%）。

BT-8 「逐设备最近采集时间」补到 /monitoring/overview（或裁定取别的端点）

归属说明（票 18 补记）：同 BT-7 —— 已由票 25 接手并记为 I2（BT-8）， 且补正了口径（/overview/monitoring 的 metricFreshness 当前只有空适配器， 不能当作可用数据）。后续修订与排期以票 25 为准。

背景与证据

  • 票 18 验收第 1 条点名「监测概览展示…最近采集时间」。
  • metricFreshness（{status, updatedAt, serverUpdatedAt}）在整个 com.zksy.cockpit 包里 只出现在 CockpitOverviewMonitoringResponse —— 那是 /overview/monitoring （总体概览模式的「运行监测」面板，票 20 的域）。
  • 本模式「监测概览」对应的 /monitoring/overview 只有信封级 updatedAt 与 freshness{status,reason,updatedAt,serverUpdatedAt}，没有逐指标的采集时间。
  • 票 24 的字段覆盖表把 metricFreshness 记在「监测概览」面板名下，记错了端点（该表需按此修正）。

要做什么（二选一，需后端或业务裁定）

  1. 给 /monitoring/overview 补 metricFreshness（与 /overview/monitoring 同结构）；或
  2. 明确「监测概览」的采集时间口径就取 /overview/monitoring 的那一份 （代价：该面板要拉第二个端点，且两个端点的筛选入参不完全一致）。

验收标准

  • 选 1：先裁定「最近采集时间」是采样时刻还是状态更新时间；/monitoring/overview 从可信源（如现有设备 sampledAt，经业务确认后）聚合并返回生效时间与空态，不用响应信封的 updatedAt 冒充。
  • 选 2：/overview/monitoring 的 metricFreshness 目前只有 DTO，真实适配器未接且源为空时为 null；先补真实接线，再在契约手册明确时间与筛选语义，并验证 industry/deviceType 与本面板一致，前端才能改取数路径。

当前前端处理：面板用信封级 updatedAt 呈现「数据时间」，并以 METRIC_FRESHNESS_GAP（domain/monitoringPanels.js）在界面上说明它不是逐设备采集时间； 不伪造一个采集时间。

E1 管理信息补责任区域（票 17 的既有缺口）

证据：CockpitInfrastructureManagementInformationResponse 只含 organizations、ownershipDistribution、mapFilter 等机构/权属结构，没有 region/area 或组织—责任区域关系；相邻 base-archives 的 regionDistribution 是汇总，不等价于逐管理单位责任区域。前端《基础设施模式面板》已将该差异如实呈现。

交由后端/业务裁定：确认管理单位与责任区域的关系和可信来源；有来源则补可按区域查询/展示的读模型字段及测试，无来源则明确拒绝并记录口径，前端继续标示缺口，不能把 industry 冒充责任区域。

J1/J2 当前领域模型跨端对齐（建议并入 BT-5，待 PM 确认）

  • J1：MANHOLE 已被裁定为正式第四行业，但过滤/统计仍有三行业白名单；对外 typeCode 已裁定为类型主键字符串，未提交的直接父级推导助手还需覆盖多级类型树。统一地图、监测、事件、基础设施和设备边界的校验/分类与测试。
  • J2：后端权威工单状态为 0–7，cockpit 字典仍为 1–7，0 被映成已取消、5 被读成待验收、6 被读成已结案；需修工单摘要、时间线和效率聚合。旧口径不可当成当前真实库验收结果。
  • BT-5：地图与三个监测适配器未提交；新模型下编译与当前 KingbaseES 联调尚未重新验证。地图适配器每页重新查询，服务目前只校验回显的 snapshotAt，不能据此证明分页锁住同一份数据。建议写入后端《真实数据接线（程序级）》的实现验收，由 PM 确认范围，不重复建泛化票。

四、需要业务方口径（不是后端工单）

  1. 「故障」是什么？ 字典现状：点位六态 ALARM/WARNING/WORK_ORDER/NORMAL/OFFLINE/EMPTY；指标六态 NORMAL/WARNING/ALARM/EXPIRED/OFFLINE/UNKNOWN，且明确 EXPIRED 不与 OFFLINE 合并；situation.abnormalEquipment.abnormalType 是异常分类。需业务确认「故障」是否等于这些集合的子集，还是要一个独立桶。
  2. 「处置率」口径：手册目标为 basis = CLOSED_WORK_ORDERS_OVER_TOTAL_EVENTS（已结案工单数 ÷ 事件总数），但 cockpit 旧效率服务仍以状态码 6 为已处理，权威运行时 5 才是已结案、6 是延期中。先按 J2 修正计算和测试，再由业务确认分母是否含取消事件。
  3. 「管理单位」与 maintainer：management-information 以 organizations + ownershipDistribution + unmaintained 建模，与维护单位分开。需业务确认这一区分并回写术语表。

五、给项目经理的决策点

  1. G1 的落图路径二选一（BT-2 的两个方案）。 已裁定（2026-09-18）：走路径①——地图以 map-snapshot 为准，且补全 industry/region/deviceType 三入参与 mapFilter 回显；结论见 docs/cockpit/README.md 第 3 节。
  2. G2/G4 的实现取一或全做（BT-1 的 ①②③）。 已全部实现：BT-1（#59）交付 G4 三件套，BT-2（#60）交付 G1+G2。
  3. 现行后端缺口不止 BT-5：I1/BT-7 的未关联设备状态口径、I2/BT-8 的可信采集时间、E1 的管理责任区域待 PM 裁定归票；J1 四行业与 J2 工单状态对齐是否并入《真实数据接线（程序级）》待 PM 确认，真实接线/分页一致性仍需验收。BT-1…BT-4 的关闭是历史票据事实，不代替新 schema 联调。
  4. 当前本地 HEAD=c5a5b87=origin/master，地图三筛选、回联字段及四个真实适配器只在未提交工作树；旧「#43 未推送、远端仍是 #42」只是 2026-09-17 历史事实。联调前确认来源提交及构建/数据库证据。
  5. 各切片 *-demo.html 是 fixtures，不是真实数据；手册第 7/8 节的容器化与性能均为未验证项。
  6. 票 18 实施时新暴露两条（2026-09-18，草案见上 BT-7/BT-8）：
    • BT-7 map-snapshot 补 pointStatus 入参 —— 决定票 18 能否收口（其验收第 5 条「面板筛选可作用于地图点位」 的状态维度缺后端路径）。
    • BT-8 逐设备最近采集时间归属 —— 或给 /monitoring/overview 补 metricFreshness， 或裁定该口径取 /overview/monitoring。两条都需要后端或业务给结论，前端已按「如实说明、不伪造」处理。