# 源系统样例映射指南

项目：江南水务601199 水安全韧性与应急协同驾驶舱  
映射版本：`draft-2026-08-map-01`  
适用阶段：企业脱敏样例接收、字段核对、API 网关联调准备

## 本地校验工作台

正式演示版可从“态势总览 → 真实样例映射进度 → 样例导入校验”进入工作台。选择源系统后可载入模板、粘贴或选择本地 JSON 文件，并执行必填字段、类型、枚举、业务范围与敏感字段校验。校验过程只在浏览器本地运行，不上传样例。

## 1. 样例文件

| 源系统 | 模板文件 | 当前状态 |
| --- | --- | --- |
| 在线监测 / LIMS | `samples/source-quality.lims.example.json` | 模板就绪，待企业样例 |
| SCADA只读汇聚 / EAM | `samples/plant-operation.scada.example.json` | 模板就绪，待企业样例 |
| DMA / GIS / 管网工单 | `samples/dma-network.example.json` | 模板就绪，待企业样例 |
| CRM / 热线工单 | `samples/customer-service.example.json` | 模板就绪，待企业样例 |
| 应急资源台账 | `samples/emergency-resource.example.json` | 模板就绪，待企业样例 |
| 统一事件中心 | `samples/event-ledger.example.json` | 模板就绪，待企业样例 |

字段映射总表位于：`data/source-mapping.json`。

## 2. 接收真实样例的要求

1. 样例必须来自企业授权测试环境或经授权导出的脱敏快照。
2. 每类源系统先提供 1-3 条记录即可，重点确认字段名、类型、单位、枚举和时间格式。
3. 不接收生产账号、密码、令牌、设备编号、精确坐标、用户姓名、电话、地址、户号和处置敏感细节。
4. 若源系统返回统一响应包，可先保留原包络，同时标注实际数据数组所在路径。
5. 样例通过字段校验后，再进入 API 网关路由和认证联调。

## 3. 校验方式

```bash
node tools/source-sample-check.mjs
```

校验覆盖：

- `data/data-source.json` 中登记的六类源系统是否都有映射。
- 每类源系统的 `requiredFields` 是否都有目标字段映射。
- 样例文件中的 `records` 是否至少包含 1 条记录。
- 样例首条记录是否覆盖必填字段。
- 数字、整数、字符串、枚举、时间字段类型是否符合约定。

## 4. 与驾驶舱的关系

样例映射不会直接改写领导驾驶舱指标。它只回答三个问题：

1. 源系统是否能提供驾驶舱需要的字段。
2. 字段是否已脱敏、可追溯、可统一口径。
3. 是否具备进入 API 网关联调的条件。

通过映射校验后，再由网关或后端适配层把源系统字段转换为驾驶舱当前使用的 `risk.json`、`kpi.json`、`scenario.json` 结构。

## 5. 验收口径

| 阶段 | 通过条件 |
| --- | --- |
| 模板准备 | 六类样例模板和字段映射均存在 |
| 样例接收 | 企业脱敏样例替换模板后仍通过 `source-sample-check` |
| 口径确认 | 业务部门确认单位、枚举、刷新周期和质量标记 |
| 网关联调 | `contract-check` 对指定 API 地址通过 |
| 上线评审 | 安全负责人确认前端包不含敏感字段和凭据 |