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