railwaysystem/docs/codebase-audit/10_gap_and_conflict_analysis.md

# 当前实现与未来业务设计的冲突点

> 本文件只报告基于当前代码能确认的模型/接通冲突，不提供重构代码，也不假定未入库系统的行为。

## 1. 开班计划只能直接挂一个课程和一个教师

**当前实现**  
`TrainClassPlan`/`train_class_plan` 只有一个 `c_id` 和一个 `t_id`，Mapper 为单表 CRUD。

↓

**潜在问题**  
一个培训班无法表达多门课程、多名教师、课程顺序和每次上课的时间地点。

↓

**可能影响哪些业务**  
课程表、教师排课、教室/场地冲突检查、按课次签到、课程成绩和班级统计。

## 2. 没有参训/报名关系

**当前实现**  
学员是独立主数据；报到、签到、成绩、时长、画像各自直接保存 `student_id + plan_id`。代码与表设计中没有 enrollment/plan_student/班级学员关系。

↓

**潜在问题**  
无法明确某学员是否被录取、退训、结业或属于哪一期培训，也无法以一份稳定名单约束后续记录。

↓

**可能影响哪些业务**  
报名审核、班级花名册、报到资格、住宿分配、签到名单、成绩发布、结业证书与教师数据权限。

## 3. 签到没有课次实体

**当前实现**  
`train_student_checkin` 有 `plan_id`、`c_id`、`lesson_start_time`、`lesson_end_time`，但没有 `lesson_id`；每条学生签到重复保存课次时间。

↓

**潜在问题**  
无法稳定标识一次上课，课程时间调整会产生历史不一致，也难以建立“一人一课次一次有效签到”的唯一规则。

↓

**可能影响哪些业务**  
课程表、二维码签到、设备签到幂等、迟到/早退判断、补签、按课次出勤统计。

## 4. 学员模型偏高校学籍，缺少培训账号和身份信息

**当前实现**  
`TrainStudent` 主要字段是院系、专业、班级、学号；没有 `sys_user` 关联、身份证、人脸特征/资源、人员状态或来源单位等代码字段。

↓

**潜在问题**  
业务身份与登录身份无法对应，现场报到和门锁人脸授权的数据来源不完整；非高校培训场景也难以表达。

↓

**可能影响哪些业务**  
学员登录、自助查询、现场报到、门禁授权、教师查看班级、跨单位培训。

## 5. 教师模型不能支撑账号、资质和授课范围

**当前实现**  
`TrainTeacher` 只有工号、姓名、院系、职称、联系方式等基础字段；没有 `sys_user` 关联、启停状态、资质证书、可授课程关系。计划只保存一个 `t_id`。

↓

**潜在问题**  
无法从当前登录用户确定教师身份，也无法约束其可查看班级或可教授课程。

↓

**可能影响哪些业务**  
教师工作台、教师数据权限、排课、资质审查、课程授权。

## 6. 宿舍只有房间聚合，没有独立床位

**当前实现**  
`train_dormitory_info` 保存 `bed_total` 和 `bed_used`；`bed_no` 只作为 `train_dorm_auth` 的自由文本字段存在。

↓

**潜在问题**  
无法可靠管理每张床的状态、性别/房间约束、占用唯一性、维修与预留；`bed_used` 容易与授权记录不一致。

↓

**可能影响哪些业务**  
自动分房、床位冲突、容量统计、换房、退宿、住宿看板。

## 7. 住宿分配与门锁人脸授权耦合

**当前实现**  
`train_dorm_auth` 同时保存学员住宿位置、床位号、授权起止时间和 `face_sync_status`。

↓

**潜在问题**  
业务住宿事实与设备同步状态无法独立演进；没有下发流水、重试次数、失败原因、设备回执和撤权记录。

↓

**可能影响哪些业务**  
分房、换房、门禁下发、失败补偿、到期撤权、审计追踪。

## 8. 报到记录同时承担资源分配

**当前实现**  
`train_class_report` 同一行保存报到事件及 `alloc_dorm_id`、`alloc_classroom_id`、`alloc_site_id`。Service 只是单表新增/修改，没有事务编排。

↓

**潜在问题**  
一次报到被迫绑定三类资源，无法记录多次尝试、资源调整或单独失败，也没有容量和冲突校验。

↓

**可能影响哪些业务**  
现场报到、住宿分配、教室/场地调度、设备异常恢复、操作审计。

## 9. 成绩固定三列且没有计算/发布规则

**当前实现**  
`train_score_info` 固定为 `course_score`、`train_score`、`exam_score`；没有权重、规则版本、综合分、发布状态或审批字段。未跟踪的课程成绩页只按 `examScore` 显示“综合评级”。

↓

**潜在问题**  
无法解释综合结果，课程差异化考核和规则变更会直接影响历史成绩可追溯性；页面名称可能造成错误理解。

↓

**可能影响哪些业务**  
成绩导入、综合成绩、排名、补考、结业判定、画像和报表。

## 10. “成绩可导入/外部采集”目前只是字段枚举

**当前实现**  
`source_type` 注释包含手工、Excel、外部接口，但培训 Controller 只有单条 CRUD和导出，没有导入、回调或批处理接口。

↓

**潜在问题**  
数据来源字段会被人工填写，却没有与真实采集渠道、批次、错误行和幂等键绑定。

↓

**可能影响哪些业务**  
Excel 批量导入、VR/3D/实操系统对接、数据追溯、重复数据处理。

## 11. 学习时长“统计”仍是人工可编辑明细

**当前实现**  
`train_study_duration` 同时存起止时间和 `study_seconds`；Controller 可手工增改删，未见计算校验、外部事件 ID、同步状态或汇总 SQL。

↓

**潜在问题**  
同一记录的时间差与秒数可能不一致，外部重传可能重复入库，汇总结果缺少可信来源。

↓

**可能影响哪些业务**  
学习达标、时长报表、设备对接、学员画像、考核结果。

## 12. 画像是手工 CRUD 快照，没有生成链路

**当前实现**  
`train_student_portrait` 直接保存总时长、平均成绩、签到率、标签和文本；Service 不读取签到、成绩、时长表，前端只提供编辑表格。

↓

**潜在问题**  
画像指标可能与来源明细不一致，无法说明何时、按何规则生成，也不能回溯历史版本。

↓

**可能影响哪些业务**  
学员评价、推荐、教学改进、结业报告、管理驾驶舱。

## 13. 设备表有状态字段，但没有设备协议接口

**当前实现**  
电子班牌保存最后心跳和在线状态，宿舍授权保存人脸同步状态；后端只有管理 CRUD。设备相关前端另有两个无 API 的占位页。

↓

**潜在问题**  
页面可编辑“在线/已下发”等结果字段，却没有系统生成这些状态的接入、认证、回执和超时逻辑。

↓

**可能影响哪些业务**  
班牌内容发布、签到、人脸门锁、设备在线监控、故障告警。

## 14. 培训权限前后端不一致

**当前实现**  
前端多数使用 `train:*`，后端使用 `system:*`；宿舍、教室、成绩后端共用 `system:info:*`；仓库没有培训菜单 SQL。

↓

**潜在问题**  
普通角色的按钮显示与后端授权可能不一致，三个资源也无法独立授权；管理员通配权限会隐藏问题。

↓

**可能影响哪些业务**  
所有培训菜单、增改删、导入导出和角色验收。

## 15. 培训查询没有数据范围

**当前实现**  
`ruoyi-train` 无 `@DataScope`，教师/学员也未关联 `sys_user`，Mapper 列表是单表条件查询。

↓

**潜在问题**  
拥有列表权限的普通账号可能看到所有培训数据，无法实现“教师只看所带班级”或“学员只看本人”。

↓

**可能影响哪些业务**  
教师门户、学员门户、成绩与画像隐私、组织隔离。

## 16. 培训表没有可执行数据库基线

**当前实现**  
14 张表只有 DOCX 设计和 Mapper引用；仓库只有若依系统/Quartz SQL，没有培训 DDL、迁移、索引、外键或菜单脚本。

↓

**潜在问题**  
不同环境可能靠人工建表而漂移，代码中字段对齐不代表真实数据库一致，也无法在新环境复现。

↓

**可能影响哪些业务**  
所有培训 CRUD、联调、测试、部署、回滚和交接。

## 17. Kingbase 配置与 MySQL 方言并存

**当前实现**  
Datasource 使用 Kingbase 8.6.0，但 PageHelper 为 mysql；若依 Mapper/生成器和系统 SQL使用 MySQL 特有语法，设计文档也含 `AUTO_INCREMENT`、`ON UPDATE CURRENT_TIMESTAMP`。

↓

**潜在问题**  
是否可运行取决于 Kingbase兼容模式和具体版本；部分系统能力可能启动正常但在特定查询/生成/数据权限路径失败。

↓

**可能影响哪些业务**  
分页、用户/角色/菜单查询、数据权限、Quartz、代码生成、初始化部署和数字主键回填。

## 18. DATETIME 在接口展示中被格式化为日期

**当前实现**  
开班起止、报到、签到、课次、授权、学习起止/同步、导入、心跳等 Java `Date` 字段普遍使用 `@JsonFormat(pattern="yyyy-MM-dd")`，Excel也只导出日期。

↓

**潜在问题**  
时分秒在 JSON/Excel 表示中丢失，时间型业务无法准确展示和回传，前端日期选择器也多按日处理。

↓

**可能影响哪些业务**  
课表、报到时间、迟到早退、门禁授权时段、设备心跳、学习时长和数据同步审计。

## 19. 字符串主键没有代码生成策略

**当前实现**  
8 个字符串主键只在非空时由 Mapper插入，没有 UUID/雪花/业务编号生成服务；生成页面让用户填写主键。

↓

**潜在问题**  
空值是否可插入取决于数据库默认值，手工编号又可能冲突；不同入口难以统一编号规则。

↓

**可能影响哪些业务**  
教师、学员、课程、计划、宿舍、教室、场地、班牌的新建和外部同步。

## 20. 当前工作树不是稳定可复现基线

**当前实现**  
存在 9 个已跟踪修改文件、多项未跟踪业务页面/API、未跟踪启动脚本，以及大量已跟踪依赖文件。现有 JAR也不保证与当前源码一致。

↓

**潜在问题**  
高级负责人、测试和部署人员从 `main` 获取的代码与本机可见能力不同，难以判断哪个状态应作为后续开发起点。

↓

**可能影响哪些业务**  
所有开发任务拆分、缺陷复现、联调、发布和责任边界。