# SRM 供应商档案 导出 / 导入 - 前端联调方案

## 涉及页面

| 页面 | 前端组件 | 后端接口前缀 | 说明 |
|------|----------|--------------|------|
| 供应商档案 | `srm/supplier/index`（组件名 SrmSupplier） | `/srm/supplier` | 新增"导出、导入、下载模板"工具栏入口 |

## 权限（按钮显隐，与后端 @PreAuthorize 一致）

| 操作 | 按钮权限 | 后端接口校验 |
|------|----------|--------------|
| 导出 | `srm:supplier:export` | `/srm/supplier/export-excel` |
| 下载模板 / 导入 | `srm:supplier:import` | `/srm/supplier/get-import-template`、`/srm/supplier/import-excel` |

> 新按钮菜单 SQL 见 `sql/mysql/srm_supplier_import_export_menu.sql`（幂等，含普通角色授权）；超级管理员自动拥有全部菜单。
> 若历史库中 `srm:supplier:export` 按钮菜单已存在但角色未分配，执行该脚本即可补齐。

## API 一览

| 方法 | 路径 | 说明 | 权限 |
|------|------|------|------|
| GET | `/srm/supplier/export-excel` | 按当前列表查询条件导出全部命中行（不分页） | 导出权限 |
| GET | `/srm/supplier/get-import-template` | 下载导入模板（含 1 行示例数据，可删后填写） | 导入权限 |
| POST | `/srm/supplier/import-excel` | 上传 Excel 导入（multipart） | 导入权限 |

### 导入接口参数

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| file | MultipartFile | 是 | 待导入的 Excel（.xls/.xlsx） |
| updateSupport | Boolean | 否 | 是否支持更新：`true`=按"供应商编码"已存在则更新；默认 `false`=仅新增，已存在则该行报"供应商编码已存在" |

### 导入响应结构

`code: 0` 表示接口执行完成（非 0 为参数/系统异常）。业务层的部分成功通过 `data` 返回：

```json
{
  "code": 0,
  "data": {
    "createList": ["新增成功的供应商名称"],
    "updateList": ["更新成功的供应商名称"],
    "failureList": { "失败的供应商名称": "失败原因" }
  }
}
```

> 前端约定：`failureList` 非空即视为"部分失败"，应弹窗逐行提示失败原因；`createList`/`updateList` 用于汇总提示"成功新增 x 条、更新 y 条"。

## 导出接口

- 复用列表查询过滤条件（GET 查询参数：code/name/type/status/contactName/contactMobile），导出全部命中行，无需传页码。
- 成功返回二进制文件流，文件名：`供应商数据.xlsx`；失败时可能返回 HTTP 200 + JSON，需区分二进制与 JSON。
- 导出表头为中文，**类型列显示名称（生产型/贸易型/服务型/其他），状态列显示 启用/禁用**（与页面标签一致），便于阅读：

| 列名 | 对应字段 | 说明 |
|------|----------|------|
| 供应商编码 | code | |
| 供应商名称 | name | |
| 供应商简称 | shortName | |
| 供应商类型 | type | 导出为中文名称 |
| 企业性质 | companyNature | |
| 注册资金(万元) | registeredCapital | |
| 营业执照编号 | businessLicenseNo | |
| 税号 | taxNo | |
| 法人代表 | legalPerson | |
| 公司地址 | address | |
| 公司网址 | website | |
| 联系人 | contactName | |
| 联系电话 | contactMobile | |
| 邮箱 | contactEmail | |
| 开户银行 | bankName | |
| 银行账号 | bankAccount | |
| 状态 | status | 导出为 启用/禁用 |
| 备注 | remark | |
| 创建时间 | createTime | |

> 说明：此前导出直接使用 `SrmSupplierRespVO` 输出，表头为英文字段名；本次改造为独立 `SrmSupplierExcelVO`，表头与取值口径变化如上，导出文件不可直接回导（回导请用导入模板）。

## 导入模板说明（业务规则）

下载模板文件名：`供应商导入模板.xlsx`，内含 1 行示例数据（可删除后整表填写）。

| 列名 | 必填 | 填写规则 |
|------|------|----------|
| 供应商编码 | 是 | 全局唯一，重复编码按 `updateSupport` 决定报错或更新 |
| 供应商名称 | 是 | |
| 供应商简称 | 否 | |
| 供应商类型(生产型/贸易型/服务型/其他) | 否 | 可填中文名称或编码 1/2/3/4；无法识别时按原样保存 |
| 企业性质(国企/民营/外资/合资) | 否 | 填实际文本 |
| 注册资金(万元) | 否 | 数值 |
| 营业执照编号 / 税号 | 否 | |
| 法人代表 | 否 | |
| 公司地址 / 公司网址 | 否 | |
| 联系人 / 联系电话 / 邮箱 | 否 | |
| 开户银行 / 银行账号 | 否 | |
| 状态(0启用/1禁用) | 否 | 填 0/1；留空默认 0（启用） |
| 备注 | 否 | |

行级处理规则：

| 场景 | 规则 |
|------|------|
| 编码或名称为空 | 该行失败："供应商编码和供应商名称不能为空" |
| 编码已存在 且 updateSupport=false | 该行失败："供应商编码已存在" |
| 编码已存在 且 updateSupport=true | 更新该供应商档案 |
| 编码不存在 | 新增供应商档案 |
| 单行其它校验异常（如编码唯一冲突） | 该行失败并记录原因，不影响其它行导入 |

## 注意事项

1. 建议在供应商档案工具栏增加"导入""下载模板"两个入口；导入交互需包含 `updateSupport` 选项（复选框"更新已存在的供应商"，默认不勾选），导入结果按上文响应结构给出成功/失败汇总与失败原因。
2. "导出"按钮现有实现保持不变（`export-excel`），仅后端输出列/表头优化。
3. 供应商数据可通过准入审批自动创建，此类记录可能缺少编码/类型，导入模板不受影响（按编码匹配，空编码不影响既有数据）。
4. 权限说明：模板下载与导入使用同一权限 `srm:supplier:import`。