139 lines
9.6 KiB
Markdown
139 lines
9.6 KiB
Markdown
# 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表设计来源。
|