yitisheng
/
art-management-fronted
2
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
art-management-fronted/docs/art-school-import-export-ap...

4.8 KiB
Raw Blame History

院校主子表导入导出接口文档（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 统一结构）。
  • 本文档新增导入导出接口可与现有列表/编辑功能并行使用。