# 驾驶舱真实后端数据接线（决策地图）

Status: open
Labels: wayfinder:map

本 effort 先产出跨前后端真实数据接线所需的决策，再为已收口的决策创建前端/后端执行票。地图不直接修改后端代码；后端执行票需在后端仓库、负责人和权限明确后开启。

## Destination

为 `/cockpit` 四个只读一级模式建立一条可验收的真实数据接线路线：报警—工单闭环读模型 → 地图摘要 + 运行监测 → 基础设施 → 预警处置 → 总体概览。报警—工单阶段由外部业务系统执行工单流程，驾驶舱只读取并实时呈现真实报警、工单关系和状态，不提供任何写操作。

目的地达成的判据：后端契约与真实适配器已提交并通过测试，前端 real 生命周期与 mock 同构，真实联调基线（提交版本、环境、认证、只读数据源）已锁定，筛选/分页/快照/推送/空态/失败态语义通过验证，并完成真人团队的真实设备报警闭环验收；real 失败不回退 mock。

## Notes

- Domain：城市生命线 Web 驾驶舱。术语以 [`CONTEXT.md`](../../CONTEXT.md) 为准；`监测点`、`监测设备`、`地图摘要`、`快照`、`异常点`不可混用。
- 复用现有事实台账：[`后端契约缺口待办`](../cockpit-shell-panel-layout/issues/25-backend-contract-gaps.md) 及其 [`后端契约缺口交付包`](../cockpit-shell-panel-layout/handoff/backend-contract-gaps.md)。后端 Gogs `真实数据接线（程序级）`作为上位来源，但不作为唯一笼统执行票；后续按切片拆分粒度明确的后端票，并注明承接关系。
- 已确认推进顺序：报警—工单闭环读模型 → 地图摘要 + 运行监测 → 基础设施 → 预警处置 → 总体概览。
- 首阶段由外部业务系统完成工单流程，驾驶舱只读消费报警、工单、设备和监测点关系；后端拆为工单状态与处置率读模型、报警/工单回联读模型、实时同步三票，前端另建对应迁移/接线/实时消费票。
- 已确认运行策略：默认 mock；`real` 必须由部署配置显式开启；真实请求失败只影响对应分区，不回退 mock，也不牵连其它分区。
- 已确认业务口径：处置率 = 状态 5（已结案）工单数 / 状态 0–6 工单数，状态 7（取消）排除；数据库 `create_time` → Java `createTime` → API `createdAt` → 前端“数据时间”；`maintainer`、`district`、`ownership_unit` 各自保持字段语义，历史“责任区域”不属于本次目的地。
- “异常”允许按监测点、监测设备/指标分别统计各自异常集合；预警处置地图的“异常点”仍只由设备 `WARNING`/`ALARM` 回联决定，不因统计总称扩大可见范围。
- 驾驶舱鉴权范围已修订为只读 REST `/api/cockpit/v1/**` 与 WS `/ws/deviceStatus` 不鉴权；后端其他路径与未来写接口不受此变更影响。权威记录见旧鉴权决策与 ADR 0005，票 25 承接后端执行证据。
- 技能：`grilling`、`domain-modeling`、`research`；决策票逐张处理，决策完成后再创建执行票。
- 本地 tracker 仅支持 Markdown 的 `Blocked by:` 依赖表达，没有独立原生建边接口；本图按 tracker 规则落依赖并在建图后校验数量。

## 任务清单

- [x] [01: 报警—工单闭环读模型与 Gogs 票拆分边界](issues/01-backend-slice-ticket-boundary.md)
- [x] [02: 地图摘要状态筛选与未关联设备语义](issues/02-map-status-filter-and-unassociated-devices.md)
- [ ] [03: 监测数据时间字段与异构设备来源](issues/03-monitoring-created-at-contract.md)
- [ ] [04: real 生命周期与 mock 同构启动契约](issues/04-real-lifecycle-contract.md)
- [ ] [05: 真实联调基线与收口证据门槛](issues/05-integration-baseline-and-evidence.md)
- [ ] [06: 异常统计、工单处置率与管理字段词汇](issues/06-cross-mode-business-semantics.md)

## Decisions so far

- [01: 报警—工单闭环读模型与 Gogs 票拆分边界](issues/01-backend-slice-ticket-boundary.md) — 首阶段只读消费外部业务系统的报警/工单真实关系与状态；后端拆为工单状态与处置率、报警/工单读模型回联、实时同步三票，前端另建三票；真人团队的真实设备报警闭环是阶段总收口。
- [02: 地图摘要状态筛选与未关联设备语义](issues/02-map-status-filter-and-unassociated-devices.md) — 行业/范围/类型＝设备级匹配、点位 OR 归并；状态筛选对监测点按聚合六态、对未关联设备按设备状态词表各自匹配；「无关联设备」桶＝只看该类对象；`pointStatus` 多值（含 UNKNOWN/UNASSOCIATED）；顶部状态栏＝全局组合筛选入口（八桶 OR，计数为全局未筛全集）；饼图共用同一份分布；坐标汇总按筛选后口径；移除加载下一页、自动分批加载，右上角留 🔄 手动刷新；刷新时机＝筛选变化/新鲜度 tick/WS 增量。

## Not yet specified

- 首批真实接线完成后，基础设施四个面板各自需要哪些真实适配器、`district`/`ownership_unit` 的筛选与展示边界，以及井盖（`MANHOLE`）跨端是否已可用。
- 预警处置的事件读模型、设备异常回联、时间线展示与处置率聚合在真实后端中的切片拆分和数据稀疏降级。
- 总体概览缺失的前端面板实现、聚合端点与其对基础设施/运行监测/预警处置的复用关系。
- 后端真实数据库快照中坐标校验、设备—监测点关联稀疏和空数据的最终演示样本。

## Out of scope

- 登录、权限管理、工单处置等写操作。
- 将历史“责任区域”验收文字复活为本次字段，或用 `district`、`industry`、`maintainer` 冒充责任区域。
- 用前端本地过滤替代后端 `map-snapshot` 的状态筛选；不得把未加载分页的数据静默删掉。
- 失败时静默回退 mock，或把 mock 走查结果当成真实后端联调证据。
- 重写既有 mock 面板、模式词典、地图/相机决策和已关闭的前端实现票。
- 移动端、写操作业务、UE5、Docker、国产化认证及非驾驶舱领域。

## Current status

**02/6 决策票已解决。** 首阶段（报警—工单闭环读模型）与地图摘要状态筛选已收口；驾驶舱只读 REST/WS 免鉴权范围已落地（未提交，待票 05 登记基线复验）。下一步可按 frontier 处理 03、04、06；05 仍依赖 04。

**2026-09-28 追加（免鉴权已落地，未提交）**：免鉴权范围已按 ADR 0005 修订实现——后端（`E:\pipe-ner-server` 工作树）：`SecurityConfig` 放行 `GET /api/cockpit/v1/**`、24 个 cockpit 控制器移除方法级认证、WS 协议注释与手册对齐"cockpitSubscribe 直订无需 authenticate"（authenticate 帧保留给管理端工单推送）；新增 `CockpitAnonymousAccessSecurityConfigTest` 等回归。前端（本仓库）：`cockpitApi` 不再发送 `Authorization`，`runtimeSocket` open 后直接 `cockpitSubscribe`（无 authenticate 帧）、token 链路下线，mock/文档/验证脚本同步。验证：前端 t15 43/43、t04、t08 通过；后端改动**未跑 Maven**，且前后端均未提交——票 05 的联调基线只需补提交哈希/环境/数据快照，但免鉴权的真实 HTTP/WS 复验（无凭据 200、WS 直订）须在部署后进行。落地明细见 [票 25 第十五轮](../cockpit-shell-panel-layout/issues/25-backend-contract-gaps.md)。

后端最新基线（2026-09-28）：`E:\pipe-ner-server` 的 `HEAD=origin/master=355a8af`。后端手册记录本机 `127.0.0.1:8301` 已完成认证 HTTP/WS 主要验收：401/400、同一 `snapshotAt` 多页稳定、点位详情与设备详情链路、主要只读端点和 `cockpitSubscribe` 均有证据；目标部署 `192.168.110.30:8301` 仍不可达，因此地图目的地的“真实联调完成”尚未达成。

票 25 已同步为本图入口和历史契约台账，最新事实见 [`25: 后端契约缺口待办`](../cockpit-shell-panel-layout/issues/25-backend-contract-gaps.md) 与 [交接包](../cockpit-shell-panel-layout/handoff/backend-contract-gaps.md)。下一步处理 02、03、04、06，明确地图状态筛选、数据时间、real 生命周期和跨模式业务语义；05 仍依赖 04；不把本机 HTTP 证据或未提交工作树直接当作目标部署完成。