# 系统管理模块（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 为冗余字段不随之更新 |