提交

docs/开发文档/API/API文档总览.md

@@ -174,7 +174,7 @@
 | [学生信息收集批次管理API](./学生信息收集批次管理API.md) | 学生信息收集批次班级权限管理 | ✅ 完成 | 2025-01-27 |
 | [学生信息批次收集API](./学生信息批次收集API.md) | 学生信息批次收集管理（新增） | ✅ 完成 | 2025-01-27 |
 | [学生学籍异动与换班级API](./学生学籍异动与换班级API.md) | 学籍异动与换班级（含复学+换班级事务接口） | ✅ 完成 | 2026-03-13 |
-| [班级信息管理API](./班级信息管理API.md) | 班级基础信息增删改查 | ✅ 完成 | 2025-01-27 |
+| [班级信息管理API](./班级信息管理API.md) | 班级基础信息增删改查、Excel导入（字典下拉+学院专业联动） | ✅ 完成 | 2026-07-22 |
 | [二级学院管理API](./二级学院管理API.md) | 二级学院组织信息管理 | ✅ 完成 | 2025-12-26 |
 | [专业信息管理API](./专业信息管理API.md) | 专业信息管理（树形菜单+列表） | ✅ 完成 | 2025-12-26 |
 | [班级干部信息管理API](./班级干部信息管理API.md) | 班级干部信息管理（含用户角色关联） | ✅ 完成 | 2025-01-27 |

docs/开发文档/API/班级信息管理API.md

@@ -0,0 +1,73 @@
+# 班级信息管理 API
+
+**模块名称**：classMsg / 班级信息  
+**基础路径**：`/classMsg/classMsg`  
+**更新时间**：2026-07-22
+
+## 模块功能
+
+班级基础信息的增删改查、状态批量变更，以及 Excel 批量导入（模板含字典下拉、学院-专业联动下拉）。
+
+## 导入相关接口
+
+### 1. 下载导入模板
+
+- **URL**：`POST /classMsg/classMsg/importTemplate`
+- **说明**：生成带下拉校验的 Excel 模板
+- **模板列**：
+
+| 列名 | 填写方式 | 说明 |
+|------|----------|------|
+| 学院 | 下拉（联动） | 仅显示学院名称，请从下拉选择；列已加宽 |
+| 专业 | 下拉（联动） | 随学院变化，仅显示专业名称；列已加宽 |
+| 班级名称 | 文本 | 必填；同时作为班级代码写入系统 |
+| 学历层级 | 字典下拉 | `zsjy_education_level` 中文标签；列已加宽 |
+| 年级 | 文本 | 如当前年份 |
+| 入学年份 | 数字 | 如当前年份 |
+| 学制(年) | 下拉 | 常见值 2/3/4/5/6 |
+| 毕业年份 | 公式自动计算 | Excel 公式：`入学年份+学制`；导入时同样按此规则计算 |
+| 是否已毕业 | 字典下拉 | `is_graduation`（未毕业/已毕业） |
+| 班级教室位置 | 文本 | 可选 |
+| 班级状态 | 字典下拉 | `xg_class_status`（正常/暂停/毕业/解散） |
+| 班主任 | 文本（姓名） | 选填；按教职工姓名精确匹配。唯一命中才写入；未匹配或多人同名则跳过，**不影响班级保存** |
+| 班级描述 | 文本 | 可选 |
+| 备注信息 | 文本 | 可选 |
+
+- **注意**：
+  - 模板首行示例数据以「示例」开头，导入时会自动跳过
+  - 学院、专业、字典项请务必从下拉框选择，避免手填错误
+  - 班主任匹配失败不会导致该行班级导入失败，可事后在列表中单独设置
+
+### 2. 导入班级数据
+
+- **URL**：`POST /classMsg/classMsg/importData`
+- **Content-Type**：`multipart/form-data`
+- **参数**：`file`（Excel 文件）
+- **成功响应**：`R`，`msg` 为导入成功明细（HTML，含班主任匹配提示）
+- **失败响应**：抛出业务异常，`msg` 含失败行号与原因
+- **处理逻辑**：
+  1. 解析学院/专业名称，并校验专业属于所选学院
+  2. 字典中文标签自动转换为字典值
+  3. 班级名称作为 `classCode` / `className`，重复则该行失败
+  4. 毕业年份按 `入学年份 + 学制` 自动计算
+  5. 调用既有新增逻辑，同步创建对应 `sys_dept` 班级节点
+  6. 班主任按姓名匹配有效教职工：0 人或多人 → 不写班主任；1 人 → 写入并同步关联/角色
+
+## 其他已有接口（摘要）
+
+| 接口 | 方法 | 路径 |
+|------|------|------|
+| 分页列表 | GET | `/classMsg/classMsg/list` |
+| 详情 | GET | `/classMsg/classMsg/{id}` |
+| 新增 | POST | `/classMsg/classMsg` |
+| 修改 | PUT | `/classMsg/classMsg` |
+| 删除 | DELETE | `/classMsg/classMsg/{ids}` |
+| 更新状态 | PUT | `/classMsg/classMsg/status` |
+| 批量更新状态 | PUT | `/classMsg/classMsg/status/batch` |
+| 导出 | POST | `/classMsg/classMsg/export` |
+| 我作为班主任的班级 | GET | `/classMsg/classMsg/myClassListAsTeacher` |
+
+## 前端入口
+
+- 页面：`web/src/views/xg/xsjcxx/classmsg/classMsg/index.vue`
+- 操作：工具栏「导入」→ 下载模板 / 上传 Excel