railwaysystem/docs/current/02-FUNCTION-MODULES.md

# 02 - 系统业务功能模块全量判定 (Function Modules)

> **判定原则**：严格基于底层代码实现（Controller / Service / DDL）、自动化测试覆盖与实际浏览器交互判定。
> **代码真源**：前端视图基于 `build_ui/src/views/train/`，后端基于 `RuoYi-Vue/`。
> **分类标准**：
> - **`IMPLEMENTED`**：代码完全落地、数据库表就绪、经过真实测试验证、具备完整正向主闭环；
> - **`PARTIAL`**：部分代码或表结构就绪，但存在未闭环的交互或口径待确认项；
> - **`MOCK`**：使用本地假数据或模拟桩进行逻辑联调，未接入真实系统；
> - **`BLOCKED_EXTERNAL`**：内部逻辑具备，因外部厂商环境缺少硬件/真实资源造成客观阻塞；
> - **`NOT_IMPLEMENTED`**：一期未规划或尚未开始开发。

---

## 1. 业务功能模块状态总览表

| 序号 | 业务模块 | 最终状态判定 | 核心后端控制器 (Controller) | 关联核心物理表 | 关键能力与现状边界 |
| :---: | :--- | :---: | :--- | :--- | :--- |
| **01** | **教师档案管理** | **`IMPLEMENTED`** | `TrainTeacherController`<br>`TrainTeacherMeController` | `train_teacher`<br>`sys_user` | 档案增删改查、身份证/手机国密脱敏存储、账号自动绑定、教师个人工作台课表。 |
| **02** | **学员档案管理** | **`IMPLEMENTED`** | `TrainStudentController`<br>`TrainStudentMeController` | `train_student`<br>`sys_user` | 学员主档管理、身份证密文脱敏、批量导入、学员自服务培训中心（个人课表、考勤、住宿查询）。 |
| **03** | **课程资源库** | **`IMPLEMENTED`** | `TrainCourseController` | `train_course`<br>`train_resource` | 理论/实作课程分类管理、标准学时/学分配置、教学大纲、统一资源关联。 |
| **04** | **场地与教室** | **`IMPLEMENTED`** | `TrainClassroomInfoController`<br>`TrainTrainingSiteController` | `train_classroom_info`<br>`train_training_site` | 教室与实训场地物理档案管理、容纳人数上限控制、使用状态互斥校验。 |
| **05** | **开班计划管理** | **`IMPLEMENTED`** | `TrainPlanController` | `train_class_plan` | 培训班全生命周期流转（草稿 0 → 已发布 1 → 培训中 2 → 已结训 3）、多班级并行管理。 |
| **06** | **开班课程配置** | **`IMPLEMENTED`** | `TrainPlanCourseController` | `train_plan_course` | 一班多课绑定、分配各门课程任课教师、排课先后序号与学时分配。 |
| **07** | **课次日程与排课**| **`IMPLEMENTED`** | `TrainLessonController` | `train_lesson` | 课次生成、时段安排；**四维时段冲突校验（教师、教室、学员班级、起止日期范围）**。 |
| **08** | **考勤与报到管理**| **`IMPLEMENTED`** | `TrainReportActionController`<br>`TrainStudentCheckinController`<br>`AttendanceController` | `train_class_report`<br>`train_student_checkin`<br>`train_lesson` | 开班现场报到核验、课次签到/签退、教师代签补卡、人工标记缺勤、请假记录。 |
| **09** | **住宿房间管理** | **`IMPLEMENTED`** | `TrainDormitoryInfoController`<br>`TrainAccommodationController` | `train_dormitory_info`<br>`train_accommodation` | 房间/床位维护、分配住宿、床位重叠校验 (`EX-13`)、防混住约束已实现；<br>✅ **`ACCOM-PERM-01` 已正式闭环**：`train_admin` 具备入住、退宿、调房完整操作权限。 |
| **10** | **成绩管理 (C03)** | **`PARTIAL`** | `TrainScoreInfoController` | `train_score_info` | 数据库已支持动态科目与基础成绩录入；综合成绩加权计算、教师端打分交互流收敛中。 |
| **11** | **统计分析大盘** | **`IMPLEMENTED`** | `TrainAnalysisController` | 聚合多表查询 | 管理驾驶舱看板、考勤专题分析、每日打卡走势、考勤异常 Top 10，**隔离未来课次（0泄漏）**。 |
| **12** | **DMS 外部智能门锁**| **`BLOCKED_EXTERNAL`** | `TrainAccessManagementController`<br>`DmsHttpClient` 等 | `train_external_resource_mapping`<br>`train_dorm_auth`<br>`train_external_operation` | 鉴权/Token TTL/Cookie Token/只读API连通已验证；**外部环境 0 房间 0 门锁，物理硬件操作客观受阻**。 |
| **13** | **电子班牌设备** | **`PARTIAL` / `MOCK`**| `TrainElectronicBoardController` | `train_electronic_board` | 基础档案 CRUD 已实现；现场物理 IoT 设备通信协议采用模拟桩。 |
| **14** | **学员成长画像** | **`PARTIAL`** | `TrainStudentPortraitController` | `train_student`<br>`train_study_duration` | 个人基础档案卡、自主学时累计呈现可用；深度多维雷达图与业务评估模型待甲方定级确认。 |
| **15** | **自主学习时长** | **`IMPLEMENTED`** | `TrainStudyDurationController` | `train_study_duration` | 学员线上课时记录、学习时长统计与台账查询。 |

---

## 2. 核心模块详细能力边界说明

### 2.1 住宿管理模块 (`IMPLEMENTED` 状态定性说明)
- **已实现能力**：
  - 宿舍楼栋、楼层、房间、床位档案维护；
  - 房间性别属性与防男女混住校验；
  - 学员单在用住宿约束（同一学员同一时段不可多处在住）；
  - 床位重叠冲突业务校验 (`EX-13`，返回标准业务错误提示)；
  - 管理员权限下的分配住宿操作；
  - **住宿全生命周期办理闭环**：
    - 入住办理（状态 0 预分配 → 1 在住）；
    - 退宿办理（状态 1 在住 → 2 已退宿）；
    - 调房办理（状态 1 在住学员迁移至新宿舍与新床位）；
    - 住宿履历查询。
- **历史缺陷闭环说明 (`ACCOM-PERM-01` RESOLVED)**：
  - `015_dms_package_a_hardening.sql` 已完成权限加固，业务管理员角色 `train_admin` (role_id=3) 已被正式授予 `menu_id=2263` (`train:accommodation:edit`)；
  - 真实浏览器验证确认：`qa_train_admin` 登录后，预分配行正常渲染“入住”按钮，在住行正常渲染“调房”和“退宿”按钮，删除按钮按最小权限原则隐藏；
  - 11 个权限契约测试全部通过，本模块正式判定为 **`IMPLEMENTED`**。

### 2.2 成绩管理模块 (C03 `PARTIAL` 状态说明)
- **已实现能力**：
  - 物理表 `train_score_info` 包含 `score` 字段及 `>= 0` CHECK 约束；
  - 后端提供基础增删改查接口；
- **待闭环项**：
  - 多科目加权折算规则（如：理论 40% + 实作 60%）；
  - 教师工作台专属打分与批量录入界面；
  - 导出最终培训成绩汇总合格单。

### 2.3 DMS 智能门锁模块 (`BLOCKED_EXTERNAL` 定性说明)
- **已打通技术链路**：
  - 官方标准登录鉴权接口 `/public/rest/third-party-app/token/get` 联调成功，返回 Cookie Token；
  - TokenManager 实现了 7200 秒 TTL 单例滑动续期与 Single-Flight 并发防抖；
  - 建筑、楼层、房间、门锁 4 大只读接口完成 HTTP 连通与空结果结构适配；
- **客观外部阻塞事实**：
  - 外部系统当前 `building/list`, `room/list`, `doorlock/list` 返回数据集均为 **空列表 (`[]`)**；
  - 外部尚未挂接任何实体通电门锁设备；
  - 生产安全红线严禁在无测试设备授权下调用物理写操作 (`REAL_DMS_MUTATION_COUNT = 0`)。