# 城市生命线驾驶舱后端契约：移交与联调手册

本手册面向 UE / 前端对接团队，冻结 `/api/cockpit/v1/` 的字段、字典、分页、错误与实时增量口径，并给出联调检查表。对应的可执行基线是 `CockpitContractIntegrationTest` 与 `CockpitContractDictionaryTest`。

## 1. 契约总则

- 所有接口均为**只读**：仅 `GET` + `@PreAuthorize("isAuthenticated()")`，不存在任何处置、派发、确认类写入口。
- 统一响应信封：`{ "code": 200, "msg": "操作成功", "data": {...} }`；错误为 `{ "code": <httpStatus>, "msg": "<message>", "data": { category, message, requestId, serverTime } }`。
- JSON 字段一律 `camelCase`。数据库列名属适配器内部细节，不出现在契约中。
- 设备唯一关联键：`deviceCode`（对应 `equipment_base.equipment_code`）。WebSocket 迁移期同时下发 `device_code` 作为兼容别名。
- 时区：业务时区固定 `Asia/Shanghai`，所有时间戳为带偏移量的 ISO-8601（如 `2026-09-02T10:00:00+08:00`）。
- 可选请求头 `X-Request-Id`；未提供时服务端生成，响应与错误体中都会回传。

## 2. 字典冻结

| 字典 | 取值 | 说明 |
| --- | --- | --- |
| 等级颜色 | `1 RED` / `2 YELLOW` / `3 BLUE` / `4 GREEN` / `UNKNOWN` | 1红2黄3蓝4绿 |
| 监测点状态 | `ALARM` `WARNING` `WORK_ORDER` `NORMAL` `OFFLINE` `EMPTY` | 优先级即此顺序，后端负责裁决 |
| 指标状态 | `NORMAL` `WARNING` `ALARM` `EXPIRED` `OFFLINE` `UNKNOWN` | 运行监测专用，`EXPIRED` 不与 `OFFLINE` 合并 |
| 工单状态 | 1待派单 2待接单 3已接单 4处理中 5待验收 6已结案 7已取消 | 权威七态；历史"九态"已废弃，不得回填 |
| 新鲜度 | `CURRENT` `STALE` `EXPIRED` `EMPTY` `FAILED` | 每次响应携带 `freshness` |
| 错误类别 | `UNAUTHORIZED` `SERVER_ERROR` `INVALID_REQUEST` `SNAPSHOT_EXPIRED` `NOT_FOUND` | 401/500/400/400/404 |

效率口径固定为 `basis = CLOSED_WORK_ORDERS_OVER_TOTAL_EVENTS`（已结案工单数 ÷ 事件总数）；系统不判断预警真伪，契约中不存在任何准确率、误报率字段。

## 3. 端点清单

四大业务模式：

| 模式 | 端点 | 主要参数 |
| --- | --- | --- |
| 总体概览 | `GET /api/cockpit/v1/overview/infrastructure` | — |
| 总体概览 | `GET /api/cockpit/v1/overview/monitoring` | `industry` |
| 总体概览 | `GET /api/cockpit/v1/overview/warning-settings` | `mode`(WARNING\|ALARM) |
| 基础设施 | `GET /api/cockpit/v1/infrastructure/base-archives` | `industry` `facilityType` `ageBucket` `region` |
| 基础设施 | `GET /api/cockpit/v1/infrastructure/operating-information` | `industry` `range` `from` `to` |
| 基础设施 | `GET /api/cockpit/v1/infrastructure/management-information` | `industry` `organizationCode` |
| 基础设施 | `GET /api/cockpit/v1/infrastructure/emergency-support` | `category` `industry` `area` |
| 运行监测 | `GET /api/cockpit/v1/monitoring/overview` | `industry` `deviceType` |
| 运行监测 | `GET /api/cockpit/v1/monitoring/distribution` | `industry` `deviceType` `pointStatus` `region` `page` `pageSize` `snapshotAt` |
| 运行监测 | `GET /api/cockpit/v1/monitoring/situation` | `industry` `deviceType` `startTime` `endTime` `page` `pageSize` |
| 预警处置 | `GET /api/cockpit/v1/events/current` | `mode`(必填) `level` `industry` `status` `page` `pageSize` |
| 预警处置 | `GET /api/cockpit/v1/events/history-analysis` | `eventFamily`(必填) `level` `industry` `startTime` `endTime` |
| 预警处置 | `GET /api/cockpit/v1/events/handling-efficiency` | `eventFamily`(必填) `industry` `level` `workOrderState` `startTime` `endTime` `page` `pageSize` |
| 预警处置 | `GET /api/cockpit/v1/events/multidimensional-analysis` | `eventFamily`(必填) `industry` `level` `eventType` `cause` `deviceType` `region` `startTime` `endTime` |

一张图与详情：

| 用途 | 端点 |
| --- | --- |
| 地图分页快照 | `GET /api/cockpit/v1/map-snapshot?page&pageSize&snapshotAt` |
| 监测点详情 | `GET /api/cockpit/v1/monitoring-points/{monitoringPointCode}` |
| 设备档案（含最新图片） | `GET /api/cockpit/v1/equipments/{deviceCode}/archive` |
| 类型指标 | `GET /api/cockpit/v1/equipments/{deviceCode}/metrics/current`、`.../metrics/history` |
| 事件 | `GET /api/cockpit/v1/equipments/{deviceCode}/events/current`、`.../events/history` |
| 工单 | `GET /api/cockpit/v1/equipments/{deviceCode}/work-orders`、`/events/{eventSource}/{eventCode}/work-orders` |
| 工单时间线 | `GET /api/cockpit/v1/work-orders/{workOrderCode}/timeline` |
| 设备详情聚合 | `GET /api/cockpit/v1/equipments/{deviceCode}/detail-aggregate` |
| 新鲜度 | `GET /api/cockpit/v1/equipments/{deviceCode}/freshness` |
| 契约自检 | `GET /api/cockpit/v1/foundation`、`GET /api/cockpit/v1/device-boundary` |

在线试用每个切片的样例响应：打开 `docs/cockpit/` 下的同名 `*-demo.html`（离线自包含，无需后端）。

## 4. 分页、快照与错误口径

- `page` 默认 1；`pageSize` 默认 100（地图快照默认 500），上限 1000；越界返回 `INVALID_REQUEST`。
- `map-snapshot` 的 `page > 1` 必须携带同一 `snapshotAt`，否则 `SNAPSHOT_EXPIRED`；同一 `snapshotAt` 下分页结果稳定，监测点优先、已关联设备不重复出点。
- 无效或未验证坐标的对象保留在列表与详情中，但 `coordinateValidation.renderable = false`，禁止渲染。
- 成功但无数据返回 200（例如 `freshness.state = EMPTY`），不得用 5xx 表达空；仅上游读取失败才 `SERVER_ERROR`。
- 未知类型、非智能设备、非正式行业一律显式排除，不做静默归类。

## 5. WebSocket 实时增量

端点：`/ws/deviceStatus`。

```
// 订阅全量驾驶舱状态
→ {"type":"cockpitSubscribe","scope":"all"}
← {"type":"cockpitSubscribed","scope":"all","serverUpdatedAt":"2026-09-02T10:00:00+08:00"}

// 增量推送（迁移期同时下发 device_code 别名）
← {"type":"cockpitDeviceStatusDelta","deviceCode":"TC-PS-WS-202609020012",
   "device_code":"TC-PS-WS-202609020012",
   "data":{"status":"ALARM","statusTime":"2026-09-02T09:59:50+08:00",
           "serverUpdatedAt":"2026-09-02T10:00:00+08:00"}}

// 兼容旧客户端：按设备订阅
→ {"type":"subscribe","deviceCodes":["TC-PS-WS-202609020012"]}
← {"type":"subscribed","deviceCodes":["TC-PS-WS-202609020012"]}
```

客户端以 `serverUpdatedAt` 判新旧（新者胜），REST 提供首帧权威快照，WebSocket 只推变化设备；断线后重新订阅即可。设备状态校准周期默认 60 秒，可配置延长。

## 6. 启动与联调

后端启动（Java 11+，Maven 3.9）：

```bash
cd pipe-network-service
mvn -DskipTests package
java -jar zksy-admin/target/zksy-admin.jar --spring.profiles.active=dev
```

或使用自带脚本 `./ry.sh start|stop|restart|status`。`ry.sh` 已固定 `-Duser.timezone=Asia/Shanghai`。

契约回归：

```bash
mvn -pl zksy-admin -am test -Dtest='Cockpit*Test'
```

联调检查表：

1. 携带正确凭据访问任一端点，返回 200 且 `data.readOnly = true`；无凭据返回 401 `UNAUTHORIZED`。
2. 对每个端点构造一次非法参数，确认 400 `INVALID_REQUEST` 且不产生业务写入。
3. 用 `snapshotAt` 连续请求 `page=1..n`，确认 `total` 一致、监测点不重复。
4. 用同一 `deviceCode` 依次请求 archive / metrics / events / work-orders / detail-aggregate，确认关联一致。
5. `detail-aggregate` 中任一分区失败时，其余分区仍返回数据。
6. 建立 WebSocket，发送 `cockpitSubscribe(scope=all)`，确认收到 `cockpitSubscribed` 与后续增量。
7. 校验所有时间戳均为 `+08:00`，`freshness` 与实际数据新鲜度一致。

## 7. 国产化与容器化可行性

本仓库**当前没有** Dockerfile 或容器编排文件，容器化属于后续工作，此处只记录评估结论：

- 运行面：标准 JVM 应用（Java 11 字节码）+ MySQL/Redis/（可选）Nacos，无平台相关本地依赖，迁移到 aarch64/loongarch64 信创环境不需要改代码，只需对应架构的 JDK 与数据库驱动。
- 银河麒麟：主要风险在中文字体、时区与 TLS 库，而非业务代码；`Asia/Shanghai` 已由 `ry.sh` 与各切片 `Clock` 统一约束。
- Docker：可行。建议以 `eclipse-temurin:11-jre`（或信创基础镜像）为基座，外置 `application-prod.yml` 与密钥，数据库走独立容器或既有实例。若目标环境禁止容器，直接以 systemd + `ry.sh` 部署同样可行。
- 内存基线：`ry.sh` 默认 `-Xms512m -Xmx1024m`，如需在驾驶舱工作站与渲染任务共存，建议按实际并发上调堆上限。
- 性能测量：本轮未做生产规模压测，属未验证项；建议在取得真实设备规模后，用同一 `snapshotAt` 对 `map-snapshot` 与 `monitoring/distribution` 做分页吞吐与前端渲染测量，再决定是否加投影或索引。

## 8. 已知边界与未验证项

- 预警生命周期仍处于向统一工单模型迁移阶段；当前实现以目录七态为权威，适配器对旧编码做兼容收敛。
- 数据库级联调、生产规模性能、银河麒麟与 Docker 的实机验证均为**未执行项**，不在本切片结论内。
- 本仓库的工作区可能包含与本契约无关的在途改动，联调前请确认部署来源是其预期提交。