art-management-fronted/docs/art-school-import-export-api.md

院校主子表导入导出接口文档（art/school）

1. 目标

面向前端提供“院校主表 + 子表（详情/校区/学院/专业/招生计划）”的一体化导出与导入能力，支持：

• 多 Sheet 标准模板导出
• 导入前冲突预检
• 按院校编码选择性替换（原子事务）
• 导入明细反馈（成功/失败/跳过与原因）

---

2. 接口清单

2.1 导出模板数据（含业务数据）

• URL: POST /art/school/export
• 权限: art:school:export
• Content-Type: application/x-www-form-urlencoded
• 响应: Excel 文件下载（.xlsx）

查询参数（同院校列表）

参数	类型	必填	说明
mainCode	string	否	院校编码
mainName	string	否	院校名称（模糊）
shortName	string	否	院校简称（模糊）
province/city/district	string	否	行政区
universityType	string	否	大学类型
educationLevel	string	否	学历层次
schoolNature	string	否	办学性质

导出 Sheet 结构

1. 院校基本信息
2. 院校详情信息
3. 校区信息
4. 学院信息
5. 专业信息
6. 招生计划信息
7. 模板说明

子表均包含 院校编码*、院校名称* 用于与主表关联。

---

2.2 导出空模板

• URL: POST /art/school/importTemplate
• 权限: art:school:export
• 响应: 空模板 Excel（仅表头 + 模板说明）

---

2.3 导入预检

• URL: POST /art/school/importPreview
• 权限: art:school:import
• Content-Type: multipart/form-data
• 入参:
  • file（Excel 文件，必填）

返回示例

{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "totalSchoolCount": 10,
    "conflictCount": 3,
    "invalidCount": 1,
    "details": [
      {
        "mainCode": "1001",
        "mainName": "测试院校01",
        "status": "CONFLICT",
        "message": "系统已存在该院校数据，导入时需确认是否替换"
      },
      {
        "mainCode": "",
        "mainName": "",
        "status": "INVALID",
        "message": "必填字段缺失：院校编码/院校名称不能为空"
      }
    ]
  }
}

状态说明

• CONFLICT: 系统已存在（按院校编码/名称命中）
• INVALID: 模板数据无效（缺失、重复、子表关联不到主表）

---

2.4 导入执行

• URL: POST /art/school/importData
• 权限: art:school:import
• Content-Type: multipart/form-data
• 入参:
  • file（Excel 文件，必填）
  • replaceAll（boolean，选填，默认 false）
  • replaceMainCodes（string[]，选填，可多值传参）

前端推荐调用逻辑

1. 先调 importPreview。
2. 对 CONFLICT 院校弹窗询问“是否替换”。
3. 将用户同意替换的院校编码组装为 replaceMainCodes，再调 importData。
4. 用户全量替换时可直接传 replaceAll=true。

返回示例

{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "totalSchoolCount": 10,
    "successCount": 8,
    "failCount": 1,
    "skippedCount": 1,
    "details": [
      {
        "mainCode": "1001",
        "mainName": "测试院校01",
        "status": "SUCCESS",
        "message": "替换成功"
      },
      {
        "mainCode": "1002",
        "mainName": "测试院校02",
        "status": "SKIPPED",
        "message": "院校名称重复且用户取消替换"
      },
      {
        "mainCode": "1003",
        "mainName": "测试院校03",
        "status": "FAILED",
        "message": "学院保存失败"
      }
    ]
  }
}

状态说明

• SUCCESS: 导入/替换成功
• SKIPPED: 冲突且用户未选择替换
• FAILED: 导入失败（事务回滚）
• INVALID: 文件预校验失败

---

3. 原子性与一致性

• 导入按“单院校”为最小事务单元：
  • 该院校主表 + 子表（详情/校区/学院/专业/招生计划）要么全部成功，要么全部回滚。
• 替换逻辑：
  1. 删除该院校历史主表及上述子表数据
  2. 插入新主表数据
  3. 插入新子表数据

---

4. 模板必填规则（简表）

• 院校基本信息: 院校编码*、院校名称*
• 院校详情信息: 院校编码*、院校名称*
• 校区信息: 院校编码*、院校名称*、校区名称*
• 学院信息: 院校编码*、院校名称*、学院名称*
• 专业信息: 院校编码*、院校名称*、学院ID*、专业名称*
• 招生计划信息: 院校编码*、院校名称*、年份*、招生省份*、专业名称*、计划数*

* 表示模板必填字段。

---

5. 兼容说明

• 现有 POST /art/school 与 PUT /art/school 仍用于单院校编辑（school + detail 统一结构）。
• 本文档新增导入导出接口可与现有列表/编辑功能并行使用。