189 lines
4.8 KiB
Markdown
189 lines
4.8 KiB
Markdown
# 院校主子表导入导出接口文档（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 文件，必填）
|
||
|
||
#### 返回示例
|
||
|
||
```json
|
||
{
|
||
"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`。
|
||
|
||
#### 返回示例
|
||
|
||
```json
|
||
{
|
||
"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` 统一结构）。
|
||
- 本文档新增导入导出接口可与现有列表/编辑功能并行使用。
|