2026-05-12
This commit is contained in:
165
training/context/03-功能模块/02-系统管理模块.md
Normal file
165
training/context/03-功能模块/02-系统管理模块.md
Normal file
@@ -0,0 +1,165 @@
|
||||
# 系统管理模块（system）
|
||||
|
||||
> 证据来源：[SRC-FEAT-01] [SRC-SQL-01] [SRC-CODE-01：module/system/]
|
||||
|
||||
---
|
||||
|
||||
## 1. 模块定位
|
||||
|
||||
- **模块目标**：管理企业的组织架构（中心→部门→小组三级）和用户生命周期（录入、角色分配、状态管理），为所有业务模块的部门数据隔离提供基础。
|
||||
- **解决问题**：3-5名管理员管理约500人的组织结构，人员分配到正确部门和角色，是知识库/考试/培训数据隔离的前置条件。
|
||||
|
||||
---
|
||||
|
||||
## 2. 功能清单
|
||||
|
||||
[SRC-FEAT-01：模块一] [SRC-CODE-01：module/system/]
|
||||
|
||||
| 功能名称 | 功能描述 | 输入 | 输出 | 依赖模块 |
|
||||
|---------|---------|------|------|---------|
|
||||
| 中心管理（CRUD） | 创建/修改/删除最高级组织单元"中心" | CenterDTO（name, sort_order） | CenterVO | - |
|
||||
| 部门管理（CRUD） | 在中心下创建/修改/删除部门，每中心最多8个部门 | DepartmentDTO（name, center_id） | DepartmentVO | - |
|
||||
| 小组管理（CRUD） | 在部门下创建/修改/删除小组，每部门最多10个小组 | GroupDTO（name, department_id） | GroupVO | - |
|
||||
| 组织树查询 | 一次性返回完整组织树（中心→部门→小组层级） | - | OrgTreeVO（树形结构） | - |
|
||||
| 员工列表查询 | 分页查询员工，支持按部门/角色/姓名筛选 | UserQueryDTO | PageResult<UserVO> | - |
|
||||
| 员工录入 | 管理员手动录入员工信息，绑定企业微信 userid | UserDTO（wx_userid, real_name, role, department_id…） | UserVO | - |
|
||||
| 员工信息修改 | 修改员工姓名、部门、角色、小组归属 | UserDTO | UserVO | - |
|
||||
| 员工禁用/启用 | 切换员工账号状态（0启用/1禁用） | userId, status | - | auth（下次登录校验） |
|
||||
| 密码重置 | 管理员重置员工的账号密码（BCrypt） | PasswordDTO（userId, newPassword） | - | auth |
|
||||
| 讲师查看本部门员工 | 讲师可查看本部门员工列表（只读，无编辑权限） | department_id（从Token注入） | PageResult<UserVO> | auth |
|
||||
|
||||
---
|
||||
|
||||
## 3. 核心逻辑
|
||||
|
||||
### 3.1 业务规则
|
||||
|
||||
[SRC-FEAT-01：模块一]
|
||||
|
||||
- **层级约束**：中心 → 部门（一个中心最多8个部门）→ 小组（一个部门最多10个小组），超限不允许创建
|
||||
- **角色约束**：用户角色只能为 ADMIN(0) / LECTURER(1) / STUDENT(2) 三种，创建时必填
|
||||
- **部门归属**：LECTURER 和 STUDENT 必须归属某部门（department_id 不可为空），ADMIN 可无部门
|
||||
- **逻辑删除**：所有实体使用 `deleted=1` 软删除，禁止物理删除，防止外键依赖失效
|
||||
- **员工录入方式**：V1 仅支持管理员手动逐条录入，不支持批量导入（V2 规划 EasyExcel 导入）
|
||||
|
||||
### 3.2 校验逻辑
|
||||
|
||||
| 校验项 | 规则 | 失败响应 |
|
||||
|-------|------|---------|
|
||||
| 部门数量上限 | 同一 center_id 下 deleted=0 的部门数 ≤ 8 | 400：该中心部门数已达上限(8个) |
|
||||
| 小组数量上限 | 同一 department_id 下 deleted=0 的小组数 ≤ 10 | 400：该部门小组数已达上限(10个) |
|
||||
| wx_userid 唯一 | sys_user.wx_userid 全局唯一（uk_wx_userid 索引） | 400：该企业微信账号已录入 |
|
||||
| username 唯一 | sys_user.username 全局唯一（uk_username 索引） | 400：用户名已存在 |
|
||||
| 讲师数据隔离 | LECTURER 调用员工列表时，强制追加 department_id = 当前用户部门 | 自动过滤，不报错 |
|
||||
| 删除有子项的上级 | 删除中心前，其下所有部门必须已删除；删除部门前，其下所有小组和用户必须已处理 | 400：请先删除部门下的小组和员工 |
|
||||
|
||||
### 3.3 状态流转
|
||||
|
||||
```mermaid
|
||||
stateDiagram-v2
|
||||
[*] --> 启用 : 员工录入时默认 status=0
|
||||
启用 --> 禁用 : 管理员操作禁用
|
||||
禁用 --> 启用 : 管理员操作启用
|
||||
禁用 --> 已删除 : 逻辑删除（deleted=1）
|
||||
启用 --> 已删除 : 逻辑删除（deleted=1）
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. 数据结构
|
||||
|
||||
[SRC-SQL-01：一、系统管理模块]
|
||||
|
||||
### 4.1 涉及数据表
|
||||
|
||||
**sys_center**
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| id | BIGINT | 主键 |
|
||||
| name | VARCHAR(100) | 中心名称 |
|
||||
| sort_order | INT DEFAULT 0 | 排序 |
|
||||
| deleted | TINYINT | 逻辑删除（0/1） |
|
||||
|
||||
**sys_department**
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| id | BIGINT | 主键 |
|
||||
| name | VARCHAR(100) | 部门名称 |
|
||||
| center_id | BIGINT NOT NULL | 所属中心（idx_center_id 索引） |
|
||||
| sort_order | INT | 排序 |
|
||||
| deleted | TINYINT | 逻辑删除 |
|
||||
|
||||
**sys_group**
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| id | BIGINT | 主键 |
|
||||
| name | VARCHAR(100) | 小组名称 |
|
||||
| department_id | BIGINT NOT NULL | 所属部门（idx_department_id 索引） |
|
||||
| sort_order | INT | 排序 |
|
||||
| deleted | TINYINT | 逻辑删除 |
|
||||
|
||||
**sys_user**
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| id | BIGINT | 主键 |
|
||||
| wx_userid | VARCHAR(100) | 企业微信 userid（唯一） |
|
||||
| username | VARCHAR(50) NOT NULL | 账号（唯一） |
|
||||
| password | VARCHAR(100) | BCrypt 加密密码 |
|
||||
| real_name | VARCHAR(50) NOT NULL | 真实姓名 |
|
||||
| phone | VARCHAR(20) | 手机号 |
|
||||
| avatar | VARCHAR(255) | 头像 URL |
|
||||
| role | TINYINT NOT NULL | 0-管理员 / 1-讲师 / 2-学员 |
|
||||
| department_id | BIGINT | 所属部门（可空，ADMIN 用） |
|
||||
| group_id | BIGINT | 所属小组（可空） |
|
||||
| status | TINYINT DEFAULT 0 | 0-启用 / 1-禁用 |
|
||||
| deleted | TINYINT | 逻辑删除 |
|
||||
|
||||
### 4.2 数据关联
|
||||
|
||||
- `sys_user.department_id` → `sys_department.id`（无外键约束，逻辑关联）
|
||||
- `sys_user.group_id` → `sys_group.id`（可空）
|
||||
- `sys_department.center_id` → `sys_center.id`
|
||||
|
||||
---
|
||||
|
||||
## 5. 对外接口
|
||||
|
||||
[SRC-CODE-01：module/system/controller/]
|
||||
|
||||
| API 名称 | 方法 | 路径 | 权限 |
|
||||
|---------|------|------|------|
|
||||
| 获取组织树 | GET | /api/system/org/tree | ADMIN |
|
||||
| 查询中心列表 | GET | /api/system/center | ADMIN |
|
||||
| 创建中心 | POST | /api/system/center | ADMIN |
|
||||
| 修改中心 | PUT | /api/system/center/{id} | ADMIN |
|
||||
| 删除中心 | DELETE | /api/system/center/{id} | ADMIN |
|
||||
| 查询部门列表 | GET | /api/system/department | ADMIN |
|
||||
| 创建部门 | POST | /api/system/department | ADMIN |
|
||||
| 修改部门 | PUT | /api/system/department/{id} | ADMIN |
|
||||
| 删除部门 | DELETE | /api/system/department/{id} | ADMIN |
|
||||
| 查询小组列表 | GET | /api/system/group | ADMIN |
|
||||
| 创建小组 | POST | /api/system/group | ADMIN |
|
||||
| 修改小组 | PUT | /api/system/group/{id} | ADMIN |
|
||||
| 删除小组 | DELETE | /api/system/group/{id} | ADMIN |
|
||||
| 查询员工列表 | GET | /api/system/user | ADMIN(全部) / LECTURER(本部门只读) |
|
||||
| 创建员工 | POST | /api/system/user | ADMIN |
|
||||
| 修改员工 | PUT | /api/system/user/{id} | ADMIN |
|
||||
| 禁用/启用员工 | PUT | /api/system/user/{id}/status | ADMIN |
|
||||
| 重置密码 | PUT | /api/system/user/{id}/password | ADMIN |
|
||||
|
||||
---
|
||||
|
||||
## 6. 异常与边界处理
|
||||
|
||||
| 场景 | 处理方式 |
|
||||
|------|---------|
|
||||
| 删除有下级的中心/部门 | 校验子项是否全部删除，否则返回 400 + 提示 |
|
||||
| 部门/小组数量超限 | 严格校验上限（8/10），超出返回 400 |
|
||||
| 员工 wx_userid 重复 | 唯一索引捕获 DuplicateKeyException，友好提示 |
|
||||
| LECTURER 访问其他部门员工 | AuthInterceptor / Service 层强制 department_id 过滤，返回空列表 |
|
||||
| 管理员误操作禁用自己 | [ASSUMPTION] PRD 未明确说明是否限制，建议禁止禁用最后一个 ADMIN |
|
||||
| 员工转移部门 | 修改 department_id 即可，但其历史知识进度/考试记录中的 department_id 为冗余字段不随之更新 |
|
||||
Reference in New Issue
Block a user