# 可靠性系统 Excel 标准导入：过程留痕与数据规范方案

## 1. 建设目标与边界

本功能解决“现场无法直接登录系统，先人工记录，再集中整理 Excel 并导入”的业务问题。系统不迁就历史非标准表格，也不猜测含义不明的代码；用户按照系统提供的固定模板整理数据，系统负责逐格检查、明确报错、人工确认和整批写入。

导入覆盖以下全部范围：设备、实验部件、子系统、设备内部部件、设备结构绑定、故障模式、故障原因、故障溯源、整机实验项目、部件实验项目、现场故障、故障更换件、整机模拟实验故障、部件模拟实验故障。

## 2. 输入工作簿结构

|顺序|工作表|作用|关键引用|
|---:|---|---|---|
|1|设备|建立或复用具体机床|设备代码唯一|
|2|实验部件|建立独立部件模拟实验对象|实验部件代码唯一|
|3|子系统|建立适用于某设备类型的子系统字典|子系统代码唯一|
|4|部件|建立子系统下的设备部件字典|必须引用子系统代码|
|5|设备结构配置|给具体设备绑定可用子系统和部件|设备、子系统、部件必须从属一致|
|6|故障模式|建立故障表现形式字典|故障模式代码唯一|
|7|故障原因|建立根因字典|故障原因代码唯一|
|8|故障溯源|建立设计、制造、使用等来源字典|故障溯源代码唯一|
|9|整机实验项目|给具体设备建立整机模拟项目|必须引用设备代码|
|10|部件实验项目|给独立实验部件建立模拟项目|必须引用实验部件代码|
|11|现场故障记录|导入现场跟踪故障|设备必填，其余关联字段按数据库可空规则处理|
|12|故障更换件|记录某条现场故障更换的元器件|必须引用同一工作簿中的现场故障外部编号|
|13|整机模拟故障|导入整机模拟实验故障|引用设备、实验项目，可引用该设备绑定的子系统和部件|
|14|部件模拟故障|导入独立部件模拟实验故障|引用实验部件和该部件的实验项目，不填写设备子系统/部件|

完整的逐列定义、必填性、类型、长度、数据库表和字段见 `02_Excel字段与数据库映射表.xlsx`。该表由后端实际字段规范生成，与程序共用同一来源。

## 3. 不存疑的硬性数据标准

|项目|标准|不符合时|
|---|---|---|
|文件类型|仅 `.xlsx`|拒绝预检|
|文件大小|不超过 20 MB|拒绝预检|
|工作表名|只能使用 14 个规定名称；`填写说明`例外|定位到错误工作表|
|表头|固定中文名称，不可增加、删除、改名或重复|定位到第 1 行和列名|
|代码|仅英文字母、数字、点、下划线、短横线|定位到具体单元格|
|时间|Excel 真日期时间或 `yyyy-mm-dd hh:mm:ss`，年份大于 1900|定位到具体单元格|
|布尔值|只允许“是”或“否”|定位到具体单元格|
|正整数|明细序号、数量必须大于 0|定位到具体单元格|
|空值|直接留空，不用占位符|占位符按错误处理|
|禁止占位符|`NULL`、`N/A`、`NONE`、`-`、`--`、`无`、`1900-01-01`|定位到具体单元格|
|公式|数据区不得使用 Excel 公式|定位到具体单元格|
|推荐填写|允许为空，仅给提示|不阻断提交|
|维修结束为空|该现场故障保存为未关闭|正常导入|
|外部记录编号|三类故障记录中必填且全局用于防重复|重复则阻断|

## 4. 预检逻辑与数据流

```mermaid
flowchart LR
    A[现场人工记录] --> B[按标准模板整理]
    B --> C[上传 Excel]
    C --> D[文件与表结构检查]
    D --> E[逐格类型/必填/长度检查]
    E --> F[工作簿内唯一性检查]
    F --> G[数据库及工作簿引用检查]
    G --> H[设备-子系统-部件层级检查]
    H --> I[时间顺序与更换件一致性检查]
    I --> J{错误数为 0?}
    J -- 否 --> K[生成单元格级问题清单]
    K --> B
    J -- 是 --> L[管理员人工确认]
    L --> M[数据库事务整批写入]
    M --> N{全部成功?}
    N -- 否 --> O[整批回滚并记录失败原因]
    N -- 是 --> P[保存导入结果与来源批次]
```

预检只生成标准化暂存数据和问题清单，不写入设备、字典、实验或故障业务表。只有状态为“预检通过”且错误数为零的批次，管理员才能点击“确认整批导入”。

## 5. 自动检测项目

### 5.1 文件和表结构

- 文件后缀、文件大小、工作表名称。
- 缺少表头、未知表头、重复表头。
- 至少存在一个可识别的数据工作表。

### 5.2 单元格

- 必填为空、占位符、公式、类型错误、文本超长、代码格式错误。
- 错误结果包含工作表、Excel 行号、列名、错误代码、说明和原值。

### 5.3 业务关联

- 代码可引用数据库已有主数据，也可引用同一工作簿前置工作表中的新主数据。
- 部件必须属于其声明的子系统，且设备类型一致。
- 设备结构配置必须满足设备类型、子系统、部件三者一致。
- 整机模拟故障的实验项目必须属于所选设备；部件模拟故障的实验项目必须属于所选实验部件。
- 整机模拟故障中填写的子系统和部件必须已绑定到该设备。

### 5.4 时间与更换件

- 故障结束不得早于故障开始。
- 维修结束不得早于维修开始。
- 维修结束为空不报错，导入后状态为未关闭。
- “是否更换元器件=是”时必须存在更换件明细；填写明细时主记录也必须标记为“是”。

## 6. 过程留痕

每次上传都会形成导入批次，记录以下内容：原文件名、文件大小、SHA-256 摘要、上传人、创建时间、校验时间、提交时间、状态、工作表数、数据行数、错误数、提示数、写入数、跳过数、逐表汇总、标准化暂存数据和逐格问题清单。

三类故障业务表额外保存 `external_record_no` 和 `import_batch_id`。因此可以从故障记录反查来自哪个 Excel 批次，也可用外部编号阻止重复导入。

状态流转固定为：`validated`（预检通过）、`validation_failed`（预检失败）、`importing`（提交中）、`imported`（导入成功）、`import_failed`（写入失败且已回滚）。

## 7. 写入规则

1. 按“设备/实验部件 → 子系统 → 部件 → 字典 → 设备结构 → 实验项目 → 现场故障及更换件 → 两类模拟故障”的依赖顺序写入。
2. 已存在且内容一致的配置数据跳过；代码相同但关键名称或从属关系冲突时，预检阶段即报错。
3. 三类故障以外部记录编号防重；同一文件摘要已成功导入时阻断重复提交。
4. 历史现场故障导入不会把设备当前状态强制改成“故障”，避免一条旧记录污染设备实时状态。
5. 整个批次使用一个数据库事务；任意一条失败，所有本批次业务写入全部回滚。

## 8. 权限和使用步骤

Excel 导入仅管理员可见、可访问。普通用户继续使用现有手工故障录入功能。

管理员操作顺序：下载标准模板 → 保留本次需要的工作表 → 填写并上传 → 查看预检统计和逐格问题 → 下载问题报告并修正 → 重新上传 → 零错误后确认整批导入 → 在批次历史中复核结果。

## 9. 验收材料

- `03_标准导入模板.xlsx`：正式空白模板。
- `04_全量正确验收样例.xlsx`：14 个区域均有一条正确数据。
- `05_全量错误验收样例.xlsx`：14 个区域均含刻意错误，用于检验阻断和定位。
- `验收样例/01...14`：每个录入区域各有正确、错误两份，正确文件附带最小依赖数据。
- `02_Excel字段与数据库映射表.xlsx`：工作表清单、字段/数据库映射、错误代码和硬性规则。

验收判定：28 个分项样例中，14 个正确样例必须零错误；14 个错误样例必须至少发现一个错误；全量正确样例必须可以完成事务写入；全量错误样例不得写入任何业务记录；前端必须显示并可下载精确到单元格的问题清单。
