railwaysystem/docs/codebase-audit/17_phase0_summary.md

RailwaySystem Phase 0 工程与数据库真实基线总结

业务判断最高依据：doc/RailwaySystem 智慧培训系统一期 PRD V1.0.md。旧数据库设计、V0.9、详细开发说明、HTML 原型和既有生成模型仅作为现状证据；与 V1.0 冲突时，以 V1.0 为准。

1. 当前可以作为正式开发基线的是哪个代码状态？

当前可识别的提交基线是：

• branch：main；
• HEAD：e12eda059679b89eb5d09215ffe1ce7132f161f2；
• 最新提交：docs(prd): 发布RailwaySystem智慧培训系统一期PRD V1.0正式业务基线；
• 该提交已经包含成绩、宿舍、教室接口别名、本地启动脚本、Node 22 适配、Kingbase 本地连接适配和 PRD V1.0。

当前工作树不能整体直接称为一个新的正式提交基线：其中有一组未提交的旧材料移动，即 doc/ 下3个旧文件表现为已跟踪删除，doc/wxy_doc/ 下对应材料表现为未跟踪文件；doc/wxy_doc/readme.md 明确标注这些资料暂不使用。除此之外，核验开始时没有未提交的 Java、Vue、API、SQL 或运行配置代码。

因此，继续开发应以 e12eda0 的代码内容和 PRD V1.0 为起点；开始数据库 V2 工作前，还应先决定是否正式接纳这组旧文档归档变化。本次新增的 12—17 报告是审计产物，没有提交。

2. 14张培训表实际存在多少张？

14张全部存在于 public schema，数据库中也没有第15张 train_% 表。

实际数据量：

• train_teacher：1行；
• 其余13张培训表：均为0行。

所有表均有主键；6张数字主键表使用 bigint GENERATED BY DEFAULT AS IDENTITY，8张字符串主键表没有数据库默认生成器。数据库还存在24个培训表外键、7组业务唯一约束和9个更新时间触发器。

3. 实际表结构和当前代码差异有哪些？

从“数据库字段是否能被当前生成代码映射”看，14个 Mapper XML 的 resultMap 字段数与实际表字段数一致，实际157个字段均能在当前 Mapper 中找到映射，Entity 的 String、Date、Long、BigDecimal 类型也基本兼容。

主要差异和风险是：

1. 旧设计文档中的 t_id、s_id 是 varchar(20)，实际为 varchar(32)；DATETIME 落为 timestamp，TINYINT 落为 smallint，6个 INT AUTO_INCREMENT 落为 bigint identity。
2. 实际数据库比旧设计文档多出外键、唯一约束和更新时间触发器，迁移时不能只按 Markdown 字段表重建。
3. 多个 Java 日期字段使用 @JsonFormat(pattern = "yyyy-MM-dd")，数据库能够保存时分秒，但接口序列化可能只暴露日期。
4. 当前代码与现有表结构相互匹配，不代表满足 PRD V1.0。train_class_plan.c_id/t_id、无参训关系、无课次、住宿与授权耦合、签到无 lesson_id、成绩固定三列，均与正式业务对象冲突。
5. 当前训练表 DDL 没有形成仓库内可追溯的初始化/迁移来源，现有数据库约束和触发器只能从实例读取。

详见 13_live_database_snapshot.md 和 14_database_code_diff.md。

4. 当前数据库是否真正使用Kingbase？

是。通过现有数据源配置和项目已有 JDBC 驱动成功建立只读连接，实测信息为：

• KingbaseES V009R003C018；
• database：training；
• schema：public；
• 当前用户：kingbase；
• database_mode=mysql；
• Maven 驱动依赖版本：8.6.0。

当前数据源通过既有的本地 127.0.0.1:4321 SSH/Tailscale 隧道连接。简单 SELECT 正常。整个核验事务为只读并已回滚关闭，没有修改数据库。

5. 当前Kingbase兼容模式能支持多少现有MySQL语法？

本次指定且可安全执行的语法探测全部通过：

• date_format；
• ifnull；
• find_in_set；
• current_database()；
• sysdate()；
• LIMIT ... OFFSET ...；
• MySQL 风格 LIMIT offset,row_count；
• SELECT 1 FROM dual；
• 反引号标识符。

当前 PageHelper helperDialect=mysql 的分页尾句具备语法基础，identity 和 JDBC generated keys 的元数据条件也满足。由于本阶段禁止写入，真实 INSERT 生成键回填和完整 PageHelper 请求链仍无法只读确认。

同时已经确认两个比单项语法更严重的应用级问题：

1. 代码生成器用 table_schema=current_database()，当前 database 为 training、schema 为 public，所以生成器按现有 SQL 查到0张表、0个字段。
2. Kingbase 的 sys_catalog 存在 sys_user、sys_role、sys_config 系统视图；当前搜索顺序优先于 public。若依 Mapper 使用未限定 schema 的表名时会命中系统视图并因字段不匹配失败。

因此结论是“列出的 MySQL 语法在当前实例中全部可用”，不能表述为“项目已经完成 Kingbase 适配”。

6. 培训菜单是否真实存在？

真实存在。public.sys_menu 中有23条培训相关菜单记录：6个目录、17个组件页面，ID 范围为2154—2176。17个 component 均能在前端找到对应 Vue 页面。

但这些记录存在关键缺口：

• 全部 perms 为空；
• 没有培训按钮权限记录；
• 没有 plan-course、参训关系、课次/课表、床位/住宿安排、独立门禁授权、成绩项目/权重和培训班工作台页面；
• 前端按钮主要使用 train:*，Controller 主要使用 system:*，数据库菜单没有对应权限字符串。

所以“菜单数据存在”和“培训权限链路可用”是两个不同结论。

7. 普通角色权限是否可能正常工作？

按当前实时数据，不能认为普通角色权限可以正常工作：

1. public.sys_role 为0行，没有培训角色。
2. public.sys_user_role 有20行，其中18行找不到对应应用用户，20行全部找不到对应应用角色。
3. public.sys_role_menu 有170行，全部找不到对应应用角色，另有9行找不到菜单。
4. 培训菜单 perms 全为空，前端和后端权限字符串也不一致。
5. 未限定的核心 sys_user、sys_role、sys_config 查询会命中 Kingbase 系统视图，登录、角色和配置查询本身存在阻塞。

若依已有 RBAC、菜单、按钮、数据权限和日志框架仍值得复用，但当前数据库权限数据及 schema 解析必须先核实和修复，不能据此新造一套账号权限系统。本阶段没有修改任何 sys_* 表。

8. 哪些问题必须在数据库V2以前处理？

1. 固定正式代码基线，并决定当前旧文档归档移动是否进入后续提交，避免 V2 设计建立在不清晰工作树上。
2. 明确若依 sys_* 应用表的 schema 访问方式，解决与 Kingbase 系统视图的名称冲突；在解决前，登录和权限核验不具备可靠基础。
3. 查明 sys_role 为空及用户—角色—菜单关系大量孤儿的来源，制定非破坏性恢复或迁移方案；不能直接改 sys_* 表试错。
4. 建立可审查、可版本化的数据库结构来源，完整保留实际外键、唯一约束、identity 和触发器信息。
5. 按 PRD V1.0 先确认开班计划—课程、参训关系和课次三个核心关系，再决定当前 CRUD 的字段去留。
6. 确认床位、住宿安排和门禁授权的业务边界，避免延续当前住宿事实与设备授权耦合。
7. 确认成绩项目/权重与参训学员得分的迁移边界，停止把固定三列当成最终成绩模型。
8. 统一数据库菜单、前端 v-hasPermi 和 Controller @PreAuthorize 的权限命名，并补齐按钮权限设计。
9. 明确字符串业务主键、identity 主键和 MyBatis 生成键的统一策略，并用后续可回滚集成环境验证真实写链路。
10. 明确时间字段是否需要时分秒，避免数据库 timestamp 与 Java yyyy-MM-dd 输出之间继续产生语义差异。
11. 在学员 V2 模型中确定身份证等敏感字段的可逆加密、脱敏展示和访问权限方案。
12. 修正代码生成器对 database/schema 的错误假设后，再把它作为 V2 代码生成依据。

9. 哪些现有数据必须迁移/保留？

当前培训业务只有 train_teacher 的1行真实数据需要明确保留和迁移；其他13张培训表为空，没有成绩、签到、住宿、报到或画像历史业务数据。

仍需保留或纳入迁移评估的非业务明细包括：

• 23条培训菜单的层级、名称、component 和排序，可作为 V1.0 菜单迁移底稿；
• sys_user_role、sys_role_menu 的现有记录需要先确认来源，虽然当前为孤儿关系，也不应直接删除；
• 14张表的实际约束、identity、sequence 和触发器定义；
• 唯一一条教师记录的标识、业务字段及审计时间。

由于其他培训表均为空，以下业务模型的数据迁移成本当前较低：

• train_class_plan.c_id/t_id 转向开班计划—课程及课次关系；
• 重复的 student_id + plan_id 转向正式参训关系；
• 签到转向 lesson_id；
• 宿舍/授权拆分；
• 固定三列成绩转向成绩项目和学员得分。

“数据为空”只降低历史数据迁移风险，不降低代码、接口、菜单和约束迁移工作量。

10. 哪些现有CRUD值得继续复用？

可优先复用业务外壳

• 教师、学员、课程、教室、实训场地：列表、分页、表单校验、导入导出、权限注解和基础 Mapper 结构可继续作为实现底稿。
• 电子班牌：设备资源 CRUD 外壳可保留，但与班级、教室、课次的关系需按 V1.0 重新确认。
• 开班计划、报到、学习时长、简单画像：页面和接口骨架可复用，领域字段及关联对象需要调整。

只能部分复用

• 宿舍房间：资源维护部分可复用，必须补足床位对象；
• 宿舍授权：现有 CRUD 可作为历史字段和设备接入参考，不能继续同时承担住宿安排与门禁授权；
• 签到：采集来源、时间和状态字段有参考价值，关联主线需要从 plan/course/time 转向参训关系与课次；
• 成绩：导入来源、录入人、录入时间等审计能力可参考，固定三列成绩及当前唯一约束不能作为最终模型。

不应按现状继续扩展

• 遗留的 person、character、analysis、weather 等页面没有形成 PRD V1.0 核心业务链，不应被当作领域模型依据。
• 现有代码没有课程版本/审批、复杂画像规则和自动结业引擎，这些缺失不构成一期阻塞。

11. 哪些表可以原地改造，哪些领域明显需要新增表？

本节仅作领域级初步分类，不确定最终表名、字段、主键、外键或迁移 DDL。

可保留主体并调整关联或字段

• train_teacher、train_student、train_course；
• train_class_plan 的计划主体；
• train_classroom_info、train_training_site；
• train_electronic_board；
• train_class_report、train_student_checkin、train_study_duration、train_student_portrait。

明显需要拆分或由新模型承接

• train_dormitory_info 目前只有房间层级，床位需要成为独立正式对象；
• train_dorm_auth 同时承载住宿事实和授权事实，需要由住宿安排与门禁授权分别表达；
• train_score_info 固定三列成绩不符合 V1.0，应由成绩项目/权重与参训学员得分模型承接。

PRD V1.0已经明确、当前缺失的正式关系或对象

• 开班计划—课程关系；
• 参训关系；
• 课次；
• 教学资源及课程资源关系；
• 床位；
• 住宿安排；
• 独立门禁授权；
• 成绩项目及权重；
• 参训学员按成绩项目的得分。

最终哪些对象使用新表、关系表或原表改造，应在数据库 V2 评审中确定。

12. 当前14张培训表与 PRD V1.0 核心对象的映射

当前表	PRD V1.0对应对象	判断
train_teacher	教师	修改
train_student	学员	修改
train_course	课程	修改
train_class_plan	开班计划	修改
train_dormitory_info	宿舍资源、房间、床位	拆分
train_dorm_auth	住宿安排、门禁授权	拆分
train_classroom_info	教室	原样保留
train_training_site	实训场地	原样保留
train_class_report	报到	修改
train_electronic_board	电子班牌	修改
train_student_checkin	课次考勤	修改
train_score_info	成绩项目、权重、参训学员得分	被新模型替代
train_study_duration	学习记录/学习时长	修改
train_student_portrait	基础指标、简单标签、雷达图	修改

这里的“原样保留”表示其资源主体可以继续作为 V2 基础，不代表无需增加审计字段、关联表或约束；“修改、拆分、被新模型替代”也只是 Phase 0 初判，不构成最终数据库 V2 设计。