200 lines
7.1 KiB
Markdown
200 lines
7.1 KiB
Markdown
# 班级信息增加「所在校区」
|
||
|
||
> 日期:2026-09-01
|
||
> 状态:已实现(待库表执行 SQL 后验收)
|
||
> 方案:A — 班级表直接挂 `campus_id` + `campus_name`
|
||
> 范围:Web 班级信息模块 + 后端 `classMsg` + 导入模板/导入;不改移动端
|
||
|
||
---
|
||
|
||
## 1. 背景与目标
|
||
|
||
### 1.1 问题
|
||
|
||
班级信息(`xg_class_msg`)目前无校区属性。业务需要标识班级所属校区,数据来源于【校区信息】(`xg_dorm_campus`),并支持历史数据逐步补齐。
|
||
|
||
### 1.2 目标
|
||
|
||
1. 班级增加「所在校区」(选填)
|
||
2. 列表可按校区筛选;表格展示校区名称
|
||
3. 新增/修改可选择校区
|
||
4. 列表多选后「批量设置校区」
|
||
5. 导入模板与导入支持校区(下拉 + 按名称解析)
|
||
|
||
### 1.3 已确认产品决策
|
||
|
||
| 项 | 决策 |
|
||
|----|------|
|
||
| 必填性 | 选填,允许为空 |
|
||
| 存储方案 | A:`campus_id` + `campus_name` 冗余(对齐学院/专业) |
|
||
| 批量设置 | 列表多选 → 按钮 → 弹窗选一个校区统一写入 |
|
||
| 导入识别 | 模板下拉填校区名称;导入按名称解析为 ID |
|
||
| 列表筛选 | 搜索区增加校区下拉 |
|
||
| 历史补齐 | 主要靠批量设置;导入仅服务新建班级 |
|
||
|
||
---
|
||
|
||
## 2. 数据模型
|
||
|
||
表 `xg_class_msg` 新增:
|
||
|
||
| 字段 | 类型 | 可空 | 说明 |
|
||
|------|------|------|------|
|
||
| `campus_id` | `bigint(20)` | YES | 关联 `xg_dorm_campus.id` |
|
||
| `campus_name` | `varchar(100)` | YES | 冗余校区名称 |
|
||
|
||
- 索引:`KEY idx_campus_id (campus_id)`
|
||
- **不建数据库外键**(与学院/专业一致)
|
||
- 校区改名/删除:本期不做级联同步;班级保留已写入值;筛选仍按 `campus_id`
|
||
|
||
同步改动的类型:
|
||
|
||
- 后端:`XgClassMsg`、`XgClassMsgBo`、`XgClassMsgVo`、`XgClassMsgImportVo`
|
||
- 前端:`ClassMsgVO` / `ClassMsgForm` / `ClassMsgQuery`(`web/src/api/xg/xsjcxx/classMsg/...`)
|
||
|
||
增量 SQL 放入 `docs/数据库脚本/`(文件名建议 `2026-09-01-xg_class_msg-add-campus.sql`),实现时同步更新 `docs/设计文档/database/` 中班级表说明(若有)。
|
||
|
||
---
|
||
|
||
## 3. 接口设计
|
||
|
||
### 3.1 扩展现有接口
|
||
|
||
| 方法 | 路径 | 变化 |
|
||
|------|------|------|
|
||
| GET | `/classMsg/classMsg/list` | Query 支持 `campusId`;行数据含 `campusId`/`campusName` |
|
||
| GET | `/classMsg/classMsg/{id}` | 详情含校区字段 |
|
||
| POST | `/classMsg/classMsg` | Body 可选 `campusId`;服务端校验存在后回填 `campusName` |
|
||
| PUT | `/classMsg/classMsg` | 同上;允许将校区改为空(清空) |
|
||
| POST | `/classMsg/classMsg/export` | 导出列增加「所在校区」(`campusName`) |
|
||
| POST | `/classMsg/classMsg/importTemplate` | 模板增加「所在校区」下拉 |
|
||
| POST | `/classMsg/classMsg/importData` | 解析并写入校区 |
|
||
|
||
单条增改校区规则:
|
||
|
||
- `campusId` 为空:`campus_id`、`campus_name` 置空
|
||
- `campusId` 有值:必须在 `xg_dorm_campus` 且未删除;用该记录的 `campus_name` 覆盖冗余字段(不信任前端传的 name)
|
||
|
||
### 3.2 新增批量接口
|
||
|
||
```
|
||
PUT /classMsg/classMsg/campus/batch
|
||
```
|
||
|
||
请求体:
|
||
|
||
```json
|
||
{
|
||
"ids": [1, 2, 3],
|
||
"campusId": 1946815553291304962
|
||
}
|
||
```
|
||
|
||
| 字段 | 校验 |
|
||
|------|------|
|
||
| `ids` | 非空 |
|
||
| `campusId` | 非空;必须存在于 `xg_dorm_campus`(未删除) |
|
||
|
||
行为:将选中班级的 `campus_id`、`campus_name` 统一更新为该校区。
|
||
权限:`classMsg:classMsg:edit`(与现有批量状态一致,当前控制器上部分权限注解可能被注释,实现时保持与同模块其他写接口同一风格)。
|
||
日志:`@Log` 业务类型 UPDATE,标题「班级信息-新版」。
|
||
|
||
BO 建议:`XgClassCampusBatchBo`(对齐 `XgClassStatusBatchBo`)。
|
||
|
||
校区选项:前端继续使用 `GET /xqxx/dormCampus/list`,不新增选项 API。
|
||
|
||
---
|
||
|
||
## 4. 前端设计
|
||
|
||
页面:`web/src/views/xg/xsjcxx/classmsg/classMsg/index.vue`
|
||
|
||
| 区域 | 改动 |
|
||
|------|------|
|
||
| 搜索区 | 「所在校区」`el-select`,选项来自 `listDormCampus`,`queryParams.campusId` |
|
||
| 工具栏 | 「批量设置校区」按钮;未勾选行时禁用(与毕业/暂停同用 `:disabled="multiple"`);`v-hasPermi="['classMsg:classMsg:edit']"` |
|
||
| 表格 | 列「所在校区」→ `campusName` |
|
||
| 新增/修改弹窗 | 「所在校区」下拉,选填;变更时同步 `form.campusId` / `form.campusName` |
|
||
| 批量弹窗 | 仅校区下拉(必选)+ 确认;调用 `updateClassCampusBatch` |
|
||
|
||
API 封装:在 `classMsg/index.ts` 增加 `updateClassCampusBatch`,指向 `/classMsg/classMsg/campus/batch`。
|
||
|
||
交互:成功后提示并 `getList()`,对齐批量毕业/暂停。
|
||
|
||
---
|
||
|
||
## 5. 导入 / 模板规则
|
||
|
||
### 5.1 模板
|
||
|
||
- `XgClassMsgImportVo` 增加字段「所在校区」(选填,无 `@NotBlank`)
|
||
- 列顺序:插在「班级教室位置」之后;其后「班级状态 / 班主任 / 班级描述 / 备注」index 依次 +1
|
||
- `buildImportDropDownOptions`:加载全部有效校区名称,注册为该列下拉
|
||
- 示例行可不填校区;若填写须为真实可解析的校区名
|
||
|
||
### 5.2 导入解析(`XgClassMsgImportListener`)
|
||
|
||
| 情况 | 行为 |
|
||
|------|------|
|
||
| 单元格为空 | 不设置校区,班级仍可导入成功 |
|
||
| 名称唯一匹配到未删除校区 | 写入 `campusId` + `campusName` |
|
||
| 名称不存在 / 已删除 | **该行失败**,提示「校区不存在:xxx」 |
|
||
| 重名校区(极端) | 该行失败,提示「校区名称不唯一:xxx」 |
|
||
|
||
说明:现有导入为**仅新增**;班级名重复则失败。历史班级补校区依赖批量设置,**本期不做导入更新已有班级**。
|
||
|
||
---
|
||
|
||
## 6. 主要改动文件(预估)
|
||
|
||
**数据库**
|
||
|
||
- 增量 SQL:`xg_class_msg` 加列 + 索引
|
||
|
||
**后端**
|
||
|
||
- `XgClassMsg.java` / `XgClassMsgBo` / `XgClassMsgVo` / `XgClassMsgImportVo`
|
||
- `XgClassCampusBatchBo`(新建)
|
||
- `XgClassMsgController`:list/export/importTemplate/importData + `/campus/batch`
|
||
- `IXgClassMsgService` / `XgClassMsgServiceImpl`:查询条件、回填名称、批量更新
|
||
- `XgClassMsgImportListener`:校区解析
|
||
- `XgClassMsgMapper.xml`:若自定义列清单需补字段
|
||
|
||
**前端**
|
||
|
||
- `api/.../classMsg/types.ts`、`classMsg/index.ts`
|
||
- `views/.../classMsg/index.vue`
|
||
|
||
**文档**
|
||
|
||
- 本 spec;实现后按项目规范同步 API/业务模块文档(若有班级信息专档)
|
||
|
||
---
|
||
|
||
## 7. 不在本期
|
||
|
||
- 批量清空校区
|
||
- 校区改名/删除后同步班级冗余名
|
||
- 导入更新已有班级
|
||
- 移动端班级相关页面
|
||
- 数据库物理外键
|
||
|
||
---
|
||
|
||
## 8. 验收要点
|
||
|
||
1. 新增班级可不选校区;可选校区后列表显示名称
|
||
2. 搜索按校区过滤正确(含「空校区」班级不被误筛入有校区条件)
|
||
3. 多选批量设置后,选中行 `campusId`/`campusName` 一致更新
|
||
4. 下载模板「所在校区」为下拉;导入空校区成功;错误校区名行失败且有明确提示
|
||
5. 导出含所在校区列
|
||
6. 修改班级时可更换或清空校区
|
||
|
||
---
|
||
|
||
## 9. 测试建议
|
||
|
||
- 单测/手工:批量接口非法 `campusId`、空 `ids`
|
||
- 手工:导入模板下拉可选到西溪/临安等现有校区
|
||
- 回归:原有批量毕业/暂停/解散、学院专业导入联动不受影响
|