## 文件导入（File Import）

用于定义“外部文件作为输入”的数据流：格式、校验、解析、落库、回执与错误处理。

适用场景：
- 批量创建/更新（客户、商品、额度、白名单）
- 对账单导入、历史数据迁移

建议包含的信息：
- 文件格式：CSV/XLSX/JSON，编码、分隔符、表头
- 字段映射：列名 → 目标字段，必填/可选、默认值
- 校验规则：类型、范围、唯一性、跨行/跨表校验
- 处理策略：全量失败/部分成功、错误行回传
- 幂等与去重：导入批次号、重复行处理

文件与安全要求（防重复 / 防覆盖 / 防病毒 / 命名规则）：
- 防覆盖：上传后必须写入“仅追加”的对象存储路径，禁止用原文件名直接覆盖；落库的业务数据必须是“新建导入批次记录 → 按批次入库”，禁止直接覆盖历史批次文件
- 防重复（文件级）：对原始文件计算 hash（如 SHA-256），以 `(tenant_id, uploader_id, file_hash)` 作为幂等键；命中重复时返回“已存在的导入批次号”，不得重复入库
- 防重复（内容级）：必须定义“业务幂等键”（如 `external_id` / `code` / `(org_id, code)`）；同一文件内重复行要可识别并给出错误行回传；跨批次重复要按策略：跳过 / 覆盖 / 报错（必须明确）
- 防病毒：上传后先进入隔离区，完成病毒扫描/类型嗅探后才能进入解析与入库；扫描失败/超时一律拒绝处理并记录审计
- 文件类型白名单：只允许明确列出的扩展名与 MIME（例如 `.csv/.xlsx/.json`），并做文件头嗅探，禁止“伪装扩展名”
- 文件大小与行数限制：明确最大大小（MB）、最大行数、最大列数；超过限制必须拒绝并提示
- 编码与格式：CSV 明确编码（UTF-8 优先）、分隔符、引号转义规则、换行规则；XLSX 明确 sheet 名（或第一个 sheet）与表头行位置
- 文件命名规则（建议）：`<system>_<object>_<yyyymmdd>_<batch>.<ext>`；仅用于展示与检索，不能作为幂等依据；服务端最终存储名应包含批次号（避免冲突）

文件内容与数据映射关系（必须明确到列级/字段级）：

映射表（示例）：
| 源列（Header） | 示例值 | 目标字段（DB/API） | 类型 | 必填 | 默认值 | 转换规则 | 校验规则 | 备注 |
|---|---|---|---|---|---|---|---|---|
| customer_code | C001 | customer.code | string | Y | - | trim+upper | 唯一；长度<=32 | 业务幂等键 |
| customer_name | Alice | customer.name | string | Y | - | trim | 长度<=128 | - |
| phone | 13800000000 | customer.phone | string | N | - | normalize_e164 | 格式合法 | - |
| level | VIP | customer.level | enum | N | Normal | map: VIP->VIP | 枚举校验 | - |

解析与入库口径（建议写清）：
- 表头定位：是否允许表头别名；是否允许缺列；列顺序是否要求固定
- 数据类型：空值/空字符串/NULL 的判定；日期与时区；小数精度与四舍五入规则
- 错误回传：错误行必须包含“行号 + 原始值 + 错误码 + 错误信息 + 目标字段”，并提供下载（CSV/JSON）
- 部分成功策略：明确“成功行入库 + 失败行回传”还是“整批回滚”；若支持部分成功，必须保证幂等键不会因重传导致重复入库
