# 数据接口与数据字典

项目：江南水务601199 水安全韧性与应急协同驾驶舱  
契约版本：`draft-2026-08`  
当前模式：`mock`（脱敏演示快照）

## 1. 接入原则

1. 驾驶舱只读使用企业授权且已脱敏的数据，不向 PLC、SCADA、阀门、泵组或加药设备下发指令。
2. 生产网与办公网之间通过经批准的只读汇聚区和 API 网关交换，前端不直连源系统。
3. 认证凭据保存在服务端或网关，PWA 不内置密钥、口令、设备账号和长期令牌。
4. 坐标、管线、阀门、安防点位等重要数据只返回网格或片区级别结果。
5. 每个接口需返回 `snapshotTime`、`sourceSystem`、`qualityFlag`，便于时效判断和质量追溯。

## 2. 运行模式

| 模式 | 用途 | 数据来源 | 失败策略 |
| --- | --- | --- | --- |
| `mock` | 展示、演练、离线培训 | `data/*.json` | 使用内置最小数据集 |
| `mock-api` | 本地联调演练 | `http://127.0.0.1:4180/api/v1` | 接口失败时回退脱敏快照 |
| `remote` | 企业授权环境 | 同源 API 网关 | 回退到最近脱敏快照，同时标记数据时效 |

切换条件：将 `data/data-source.json` 的 `mode` 设为 `remote`，同时在授权环境将 `gateway.enabled` 设为 `true`。

本地联调也可通过页面参数进入：`?data=mock-api`。该模式只连接本机 Mock API，不代表已经接入企业生产系统。

## 3. 对外读取接口

| 路径 | 刷新频率 | 汇总对象 | 主要来源 |
| --- | --- | --- | --- |
| `GET /api/v1/dashboard/risk` | 60秒 | 总体状态、五链评分、告警、资源 | 六类业务系统 |
| `GET /api/v1/dashboard/kpi` | 5分钟 | 供水、压力、风险、闭环趋势 | 调度、DMA、工单台账 |
| `GET /api/v1/exercise/scenarios` | 60分钟 | 演练剧本、角色、时间轴和评分项 | 应急预案库 |
| `GET /api/v1/health` | 按需 | 网关健康、契约版本和可用端点 | API 网关 |

统一响应包建议：

```json
{
  "code": "OK",
  "message": "",
  "snapshotTime": "2026-08-01T10:30:00+08:00",
  "sourceSystem": "water-data-hub",
  "qualityFlag": "verified",
  "data": {}
}
```

适配层上线时可在 API 网关统一拆包，对前端继续返回当前 `risk.json`、`kpi.json`、`scenario.json` 的对象结构。

## 4. 数源级字典

### 4.1 原水水质

| 字段 | 类型 | 必填 | 说明 | 脱敏要求 |
| --- | --- | --- | --- | --- |
| `stationCode` | string | 是 | 泛化监测点编码 | 不返回精确坐标 |
| `sampleTime` | datetime | 是 | 采样或在线监测时间 | ISO 8601 |
| `turbidity` | number | 是 | 浑浊度 | 保留2位小数 |
| `ph` | number | 是 | pH值 | 保留2位小数 |
| `qualityStatus` | enum | 是 | `normal/watch/alert` | 公开版仅显示分级 |

### 4.2 水厂运行

| 字段 | 类型 | 必填 | 说明 | 边界 |
| --- | --- | --- | --- | --- |
| `plantCode` | string | 是 | 水厂业务编码 | 不使用工控设备编号 |
| `collectTime` | datetime | 是 | 汇总时间 | 分钟级 |
| `outputFlow` | number | 是 | 汇总供水量 | 只读汇总值 |
| `qualityStatus` | enum | 是 | 出厂水合格状态 | 不返回控制参数 |
| `equipmentHealth` | number | 否 | 设备健康度 0-100 | 不返回弱点明细 |

### 4.3 DMA 与管网

| 字段 | 类型 | 必填 | 说明 | 脱敏要求 |
| --- | --- | --- | --- | --- |
| `dmaCode` | string | 是 | DMA分区编码 | 仅显示泛化片区 |
| `collectTime` | datetime | 是 | 数据时间 | ISO 8601 |
| `pressure` | number | 是 | 区域压力汇总 | 不返回单点坐标 |
| `minimumNightFlow` | number | 否 | 夜间最小流量 | 按片区汇总 |
| `workOrderStatus` | enum | 否 | `open/onsite/verified/closed` | 不返回个人信息 |

### 4.4 客服与重点用户

| 字段 | 类型 | 必填 | 说明 | 脱敏要求 |
| --- | --- | --- | --- | --- |
| `regionCode` | string | 是 | 片区编码 | 不返回用户地址 |
| `priorityUserCount` | integer | 是 | 重点用户数量 | 只返回数量 |
| `openTicketCount` | integer | 是 | 未闭环工单数 | 不返回姓名和电话 |
| `closedTicketCount` | integer | 是 | 已闭环工单数 | 汇总数据 |
| `snapshotTime` | datetime | 是 | 快照时间 | ISO 8601 |

### 4.5 应急资源

| 字段 | 类型 | 必填 | 说明 | 脱敏要求 |
| --- | --- | --- | --- | --- |
| `resourceType` | string | 是 | 队伍或物资类别 | 类别级 |
| `availableCount` | integer | 是 | 可用数量 | 不返回人员名单 |
| `totalCount` | integer | 是 | 总数量 | 汇总数据 |
| `etaMinutes` | integer | 是 | 预计到场分钟 | 不返回实时轨迹 |
| `snapshotTime` | datetime | 是 | 快照时间 | ISO 8601 |

### 4.6 事件与复盘

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `eventId` | string | 是 | 事件唯一编号 |
| `eventLevel` | enum | 是 | `green/amber/red` |
| `ownerGroup` | string | 是 | 责任组，不显示个人 |
| `slaMinutes` | integer | 是 | 响应或闭环时限 |
| `eventStatus` | enum | 是 | `open/processing/verified/closed` |

## 5. 质量与验收规则

- 时效：实时类数据超过两个刷新周期标记为 `stale`。
- 完整性：必填字段缺失时不进入领导总览指标，保留在接入质量台账。
- 一致性：状态枚举、时间格式、单位和小数精度在网关层统一。
- 可追溯：保留数据源、快照时间、质量标记和契约版本。
- 安全：不在前端日志、离线缓存或导出包中保留凭据与敏感明细。
- 健康态：前端记录每个数据集的来源、HTTP 状态、加载时延、刷新周期、数据时间和降级原因。
- 契约测试：本地数据与指定网关均需通过 `tools/contract-check.mjs`，再进入业务验收。
- 样例映射：六类源系统样例模板和字段映射统一登记在 `data/source-mapping.json`，并通过 `tools/source-sample-check.mjs` 校验。

## 6. 样例映射层

| 文件 | 用途 |
| --- | --- |
| `data/source-mapping.json` | 源系统字段到驾驶舱目标字段的映射总表 |
| `samples/*.example.json` | 六类源系统脱敏样例模板 |
| `docs/源系统样例映射指南.md` | 样例接收、校验、联调和安全评审口径 |

当前状态：模板已就绪，等待企业提供授权脱敏响应样例。模板不代表已接入真实生产系统。

## 7. 待企业确认清单

1. 六类源系统的正式名称、系统负责人和数据负责人。
2. 可供驾驶舱使用的脱敏字段、刷新频率和历史数据保留期。
3. API 网关、单点登录、权限分组和审计日志方案。
4. 快照回退的最长容忍时间以及页面“数据过期”提示规则。
5. 与应急预案、工单、重点用户和复盘整改流程的业务编号对应关系。

## 8. V2.4供水资产与模拟数据

| 数据 | 关键字段 | 口径 |
| --- | --- | --- |
| supply-assets.json | schemaVersion=supply-assets-1；assets[].id | 与原GLB的11个设施ID一致，非企业ERP编码 |
| 公开规模 | capacity.value/unit/basis/period/source | 设计/历史应急/规划现状分开，不代表当班能力；原水未单列为null |
| 事实与历史 | facts[].source/period；history[].date/kind/source/note | 保留日期精度，试运、验收、投产及公告不互换 |
| 财务与权属 | legalOwner/originalCost/netBookValue | 暂为null；企业归属与委托运维陈述仅作为带来源事实 |
| 历史金额 | historicalFinance[].label/value/unit/source | 绮山项目批准投资与审定工程结算，不能替代账面净值 |
| 模拟巡检 | asset-inspection-simulation-1；kind=simulation | 33条固定SIM记录，独立文件，不写入生产/本机工单库 |
| 模拟记录 | assetId/finding/confirmed/status/observedAt/dueAt/audit | UTC时间，界面统一北京时间；固定时点计算，不滚动冒充实时 |
| 会商草稿 | asset-meeting-draft-1；assetId/items | localStorage独立命名空间，approved与dispatched始终false |

外部原文需联网；离线保存的是核验后的事实摘录与出处索引，不是政府/企业原报告全文。所有上行接口、权限和审批服务均未接入。