training-system/training/context/03-功能模块/02-系统管理模块.md

系统管理模块（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	-
员工录入	管理员手动录入员工信息，绑定企业微信 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	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 状态流转

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 为冗余字段不随之更新