Files
hzdyjs/docs/superpowers/specs/2026-09-01-class-msg-campus-design.md
T
2026-09-02 09:58:57 +08:00

200 lines
7.1 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 班级信息增加「所在校区」
> 日期: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`
- 手工:导入模板下拉可选到西溪/临安等现有校区
- 回归:原有批量毕业/暂停/解散、学院专业导入联动不受影响