docs: 归档项目需求分析、一期开发说明书及Kingbase数据库审计报告

2026-09-13 23:16:37 +08:00
1 parent 83797f9286
commit 9d053bf41f
@@ -0,0 +1,138 @@
+# RailwaySystem 代码基线审计 Executive Summary
+
+## 1. 当前工程一句话描述
+
+RailwaySystem 是基于 RuoYi-Vue 3.9.1、Spring Boot 2.5.15、Vue 2 与 KingbaseES 配置的前后端分离培训管理项目；当前已形成 14 组培训数据 CRUD 脚手架，但数据库对象、菜单权限、Kingbase兼容和业务闭环尚无仓库证据证明已经端到端跑通。
+
+## 2. 当前技术栈
+
+- 后端：Java 8 编译目标、Spring Boot 2.5.15、Spring Framework 5.3.39、Spring Security 5.7.14、MyBatis XML、PageHelper 1.4.7、Druid 1.2.27、JJWT 0.9.1、Redis、Quartz、Apache POI。
+- 数据库：当前 datasource 指向 KingbaseES，驱动 `com.kingbase:kingbase8:8.6.0`；MySQL驱动和多处 MySQL方言仍保留。
+- 前端：Vue 2.6.12、Vue Router 3.4.9、Vuex 3.6.0、Element UI 2.15.12、Axios 0.24.0、ECharts 5.4.0、Vue CLI 4.4.6。
+- 模块：`ruoyi-admin`、`ruoyi-framework`、`ruoyi-system`、`ruoyi-quartz`、`ruoyi-generator`、`ruoyi-common`、`ruoyi-train`，以及培训前端 `build_ui`。
+- 当前机器：Java 21.0.2、Maven 3.9.2、Node 22.23.2、npm 10.9.8；源码目标与本机工具链有明显年代跨度。
+
+## 3. 已经存在的培训模块
+
+共 14 组：
+
+1. 教师 `train_teacher`
+2. 学员 `train_student`
+3. 课程 `train_course`
+4. 开班计划 `train_class_plan`
+5. 宿舍 `train_dormitory_info`
+6. 宿舍权限/门锁授权 `train_dorm_auth`
+7. 教室 `train_classroom_info`
+8. 实训场地 `train_training_site`
+9. 开班报到 `train_class_report`
+10. 电子班牌 `train_electronic_board`
+11. 学员签到 `train_student_checkin`
+12. 多类型成绩 `train_score_info`
+13. 学习时长 `train_study_duration`
+14. 学员画像 `train_student_portrait`
+
+每组都有 Entity、Mapper接口、Mapper XML、Service接口、ServiceImpl和 Controller。当前工作树也有对应前端 CRUD页面和 API，但成绩、宿舍等部分文件尚未跟踪。
+
+## 4. 已经真正跑通的功能
+
+本次审计没有启动服务或连接数据库，因此**不能确认任何培训模块已经端到端跑通**。
+
+能够确认的只是代码能力：
+
+- 若依登录、RBAC、动态菜单、日志、分页、统一返回、异常处理、Excel、上传、Quartz和代码生成框架都在仓库中。
+- 14 组培训后端静态 CRUD调用链完整。
+- 当前文件系统中 14 组前端页面/API可找到。
+- 当前存在后端 JAR和前端依赖目录，但它们不保证与未提交源码一致，也不能替代运行验证。
+
+## 5. 目前只是 CRUD、尚未形成业务闭环的部分
+
+14 个培训 Controller 合计 84 个映射，全部属于列表、导出、详情、新增、修改、删除。没有发现：
+
+- 开班/结班、报名审核、参训名单等业务动作。
+- 课次、排课、课程表和资源冲突校验。
+- 现场身份证/人脸报到流程。
+- 电子班牌心跳、内容发布、签到回调。
+- 门锁人脸下发、回执、重试、撤权。
+- Excel成绩/学员导入、外部成绩与学习记录采集。
+- 综合成绩计算、发布、锁定和追溯。
+- 画像计算规则与生成任务。
+- 培训统计聚合接口或真正业务工作台。
+
+## 6. 当前数据库现状
+
+- 代码和设计文档一致指向 14 张 `train_*` 业务表，但仓库没有这些表的可执行 DDL、迁移或种子数据。
+- 本次未查询实时数据库，不能确认表是否存在、字段/索引/外键/默认值是否一致。
+- 14 个 Entity 都继承 BaseEntity，但表的公共字段不统一；业务表主要用 `create_user`，并未统一使用若依 `create_by/update_by`。
+- 所有培训删除都是物理删除，没有 `del_flag` 逻辑删除。
+- 数字主键依赖 JDBC generated keys，设计写为 MySQL `AUTO_INCREMENT`；字符串主键没有代码生成策略。
+- `sys_*` 表继续支撑若依系统功能，不应修改结构或复制一套权限系统。
+- 当前 Kingbase驱动配置与 MySQL方言并存，是上线/联调前的关键验证项。
+
+## 7. 当前前端现状
+
+- `build_ui` 是培训前端，14 个核心模块页面本质都是 CRUD。
+- 首页只是“基地学员管理平台 V1.0”信息卡，不是业务工作台。
+- 报到、签到、画像、学习时长、电子班牌均只有数据维护页，没有对应业务流程。
+- 两个未跟踪成绩页只是对同一成绩列表做筛选；课程成绩页把 `examScore` 单列当作评级依据。
+- `equipment`、`extra` 是未跟踪占位页；旧 `character`/`analysis` 页面含随机或遗留接口，不能算培训统计已实现。
+- 未发现课程表页面。
+- 培训路由依赖实时 `sys_menu` 动态加载，仓库没有培训菜单 SQL，所以现有菜单无法由代码仓库确认。
+
+## 8. 当前权限体系
+
+- 登录主体是 `sys_user`，角色为 `sys_role`，菜单/按钮权限来自 `sys_menu.perms`。
+- Controller 用 `@PreAuthorize("@ss.hasPermi(...)")`，前端用 `v-hasPermi`。
+- 培训前端多数使用 `train:*`，后端使用 `system:*`，权限码不一致。
+- 宿舍、教室、成绩三个 Controller共用 `system:info:*`，授权粒度冲突。
+- 教师和学员均未关联 `sys_user`。
+- 培训模块未使用 `@DataScope`，不存在“教师只能看所带班级”或“学员只能看本人”的代码。
+- 培训增改删和导出已使用若依操作日志；列表/详情和领域状态变化没有专门审计轨迹。
+
+## 9. 可以直接复用的若依能力
+
+可以直接复用：登录、用户/角色基础 RBAC、操作日志、字典框架、文件上传下载、Excel工具、分页、统一返回、异常处理、系统配置。
+
+需要在现有框架上扩展：培训菜单/按钮权限、培训数据权限、培训 Excel导入、培训 Quartz任务、业务操作流水、公告之外的消息/设备通知。
+
+需要进一步确认：代码生成器、若依系统 Mapper、PageHelper、Quartz和初始化 SQL在目标 Kingbase模式下的完整兼容性。
+
+## 10. 当前最重要的10个代码/业务冲突
+
+1. **没有可执行培训数据库基线**：14 张表只有设计文档与 Mapper，无 DDL/迁移，实际数据库状态不可复现。
+2. **Kingbase与MySQL方言混用**：Kingbase驱动已启用，但 PageHelper、系统 Mapper、生成器和 SQL仍含 MySQL语法。
+3. **培训权限未接通**：前端 `train:*` 与后端 `system:*` 不一致，三个模块共用 `system:info:*`，也没有菜单初始化 SQL。
+4. **无账号业务身份和数据范围**：教师/学员不关联 `sys_user`，没有教师班级范围和学员本人范围。
+5. **无参训关系**：学员与培训计划之间没有正式 enrollment/花名册实体，后续业务各自直接引用两个 ID。
+6. **无课次/课表**：计划只能关联一个课程与一个教师，签到以重复的起止时间代替课次 ID。
+7. **报到只是 CRUD且混合资源分配**：没有设备报到流程，报到、宿舍、教室、场地绑定在同一记录。
+8. **住宿和门锁授权耦合**：没有独立床位、分配状态、设备下发流水和失败补偿。
+9. **成绩/时长/画像没有计算与采集闭环**：字段存在，但导入、外部采集、综合算法、画像生成均不存在。
+10. **工作树不是稳定基线**：关键路径适配和多个页面/API未提交，当前 JAR与源码也未证明一致。
+
+## 11. 如果继续开发，建议首先确认的代码层问题
+
+1. 确定以当前工作树还是提交 `83797f92` 为开发基线，逐项归属现有未提交/未跟踪文件。
+2. 获取只读数据库结构快照，核验 14 张业务表、系统表、主键、索引、外键、默认值和 Kingbase兼容模式。
+3. 建立可版本管理的培训 DDL/迁移与菜单权限 SQL基线；不要修改 `sys_*` 表结构。
+4. 统一培训 API前缀与权限字符串，取消 `system:info:*` 的跨模块复用，并验证普通角色。
+5. 明确教师/学员与 `sys_user` 的关联，以及教师、学员、管理员的数据可见范围。
+6. 在扩展页面前确认参训关系、课次/课表、独立床位等基础领域关系；这些关系决定报到、签到、住宿、成绩和画像的可实现性。
+7. 在目标 Kingbase环境逐项验证 PageHelper、若依系统查询、数据权限、代码生成、Quartz和 generated keys。
+8. 统一 DATETIME 的 JSON/Excel格式；当前多个时间字段只输出 `yyyy-MM-dd`。
+9. 明确字符串主键生成规则与物理删除/逻辑删除策略。
+10. 区分管理端 CRUD、业务动作、外部接入和统计接口，避免继续用可编辑状态字段代替真实流程。
+
+## 12. 需要高级技术负责人进一步评审的文件路径
+
+优先级从高到低：
+
+1. `docs/codebase-audit/10_gap_and_conflict_analysis.md`：决定后续领域模型和开发顺序。
+2. `docs/codebase-audit/03_database_current_state.md`：确认 Kingbase、DDL、主键、公共字段、物理删除和系统表边界。
+3. `docs/codebase-audit/06_security_and_permissions.md`：确认权限命名、账号关联和数据范围。
+4. `docs/codebase-audit/02_training_modules_inventory.md`：掌握14组 CRUD的实际代码边界。
+5. `docs/codebase-audit/08_git_status.md`：确定可复现基线和未提交文件归属。
+6. `RuoYi-Vue/ruoyi-admin/src/main/resources/application-druid.yml`：数据库连接与兼容配置；含敏感信息，评审时注意脱敏。
+7. `RuoYi-Vue/ruoyi-admin/src/main/resources/application.yml`：端口、Redis、JWT、MyBatis和 PageHelper配置。
+8. `RuoYi-Vue/ruoyi-system/src/main/resources/mapper/system/` 与 `RuoYi-Vue/ruoyi-generator/src/main/resources/mapper/generator/`：Kingbase兼容重点。
+9. `RuoYi-Vue/ruoyi-train/src/main/resources/mapper/train/`：14张表的当前实际 SQL契约。
+10. `doc/学员管理系统数据表设计_20260907_1_.docx`：当前14表设计来源。