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

2026-09-13 23:16:37 +08:00
1 parent 83797f9286
commit 9d053bf41f
@@ -0,0 +1,147 @@
+# 数据库当前状态
+
+## 1. 审计边界与结论
+
+本次只检查代码、Mapper XML、配置、SQL 文件和数据表设计文档，没有连接或查询实时数据库。因此本文件区分三种事实：
+
+- **代码引用**：Mapper 明确执行某张表。
+- **设计存在**：`doc/学员管理系统数据表设计_20260907_1_.docx` 描述了该表。
+- **数据库实存**：本次未验证，不能由 Entity 或 Mapper 的存在推导。
+
+代码正配置为 KingbaseES，但仓库中的唯一系统初始化脚本和多处 Mapper 仍为 MySQL 方言；培训业务又完全没有可执行 DDL/迁移。这是继续开发前必须先确认的数据库基线问题。
+
+## 2. 数据源与驱动
+
+| 项目 | 当前状态 | 代码依据 |
+| --- | --- | --- |
+| 数据库 | KingbaseES | `RuoYi-Vue/ruoyi-admin/src/main/resources/application-druid.yml` 使用 `jdbc:kingbase8:` |
+| 驱动类 | `com.kingbase8.Driver` | 同上 |
+| Maven 驱动 | `com.kingbase:kingbase8:8.6.0` | `RuoYi-Vue/pom.xml`、`ruoyi-admin/pom.xml` |
+| 连接池 | Druid 1.2.27 | 根 POM、`application-druid.yml` |
+| 当前库/schema | 配置指向 `training` / `public` | `application-druid.yml`；主机、用户名和口令不在报告中复述 |
+| 其他驱动 | MySQL Connector 仍在 `ruoyi-admin` 依赖中 | `RuoYi-Vue/ruoyi-admin/pom.xml:46` |
+| PageHelper 方言 | 固定为 `mysql` | `application.yml:109` |
+
+## 3. 表分类
+
+### A. 若依系统表，不建议修改
+
+`RuoYi-Vue/sql/ry_20250522.sql` 定义并由 `ruoyi-system`、`ruoyi-framework`、`ruoyi-quartz`、`ruoyi-generator` 使用的主要表包括：
+
+- 账号与组织：`sys_user`、`sys_dept`、`sys_post`、`sys_role`。
+- 权限关系：`sys_menu`、`sys_user_role`、`sys_role_menu`、`sys_role_dept`、`sys_user_post`。
+- 基础配置：`sys_config`、`sys_dict_type`、`sys_dict_data`、`sys_notice`。
+- 日志：`sys_oper_log`、`sys_logininfor`。
+- 定时任务：`sys_job`、`sys_job_log`，以及 `quartz.sql` 中的 `qrtz_*` 表。
+- 代码生成：`gen_table`、`gen_table_column`。
+
+这些表支撑若依登录、RBAC、菜单、数据权限、字典、配置、公告、日志、任务和代码生成。培训业务应通过新增菜单、角色关系和业务关联复用它们，不应改造其结构来代替培训领域表。本次未修改任何 `sys_*` 表。
+
+### B. 当前培训业务表
+
+以下 14 张表同时出现在设计文档和 Mapper XML 中：
+
+| 表 | Entity | 主键 | Mapper SQL | 设计字段与 Entity/Mapper |
+| --- | --- | --- | --- | --- |
+| `train_teacher` | `TrainTeacher` | `t_id` / `String` | 查、增、改、物理删 | 显式业务字段一致；另继承 BaseEntity 属性 |
+| `train_student` | `TrainStudent` | `s_id` / `String` | 查、增、改、物理删 | 显式业务字段一致；另继承 BaseEntity 属性 |
+| `train_course` | `TrainCourse` | `c_id` / `String` | 查、增、改、物理删 | 显式业务字段一致；另继承 BaseEntity 属性 |
+| `train_class_plan` | `TrainClassPlan` | `plan_id` / `String` | 查、增、改、物理删 | 显式业务字段一致；另继承 BaseEntity 属性 |
+| `train_dormitory_info` | `TrainDormitoryInfo` | `dorm_id` / `String` | 查、增、改、物理删 | 显式业务字段一致；另继承 BaseEntity 属性 |
+| `train_dorm_auth` | `TrainDormAuth` | `auth_id` / `Long` | 查、增、改、物理删；generated keys | 显式业务字段一致；另继承 BaseEntity 属性 |
+| `train_classroom_info` | `TrainClassroomInfo` | `class_room_id` / `String` | 查、增、改、物理删 | 显式业务字段一致；另继承 BaseEntity 属性 |
+| `train_training_site` | `TrainTrainingSite` | `site_id` / `String` | 查、增、改、物理删 | 显式业务字段一致；另继承 BaseEntity 属性 |
+| `train_class_report` | `TrainClassReport` | `report_id` / `Long` | 查、增、改、物理删；generated keys | 显式业务字段一致；另继承 BaseEntity 属性 |
+| `train_electronic_board` | `TrainElectronicBoard` | `board_id` / `String` | 查、增、改、物理删 | 显式业务字段一致；另继承 BaseEntity 属性 |
+| `train_student_checkin` | `TrainStudentCheckin` | `checkin_id` / `Long` | 查、增、改、物理删；generated keys | 显式业务字段一致；另继承 BaseEntity 属性 |
+| `train_score_info` | `TrainScoreInfo` | `score_id` / `Long` | 查、增、改、物理删；generated keys | 显式业务字段一致；另继承 BaseEntity 属性 |
+| `train_study_duration` | `TrainStudyDuration` | `dur_id` / `Long` | 查、增、改、物理删；generated keys | 显式业务字段一致；另继承 BaseEntity 属性 |
+| `train_student_portrait` | `TrainStudentPortrait` | `portrait_id` / `Long` | 查、增、改、物理删；generated keys | 显式业务字段一致；另继承 BaseEntity 属性 |
+
+“一致”仅指设计文档字段名与 Entity/Mapper 显式映射的静态比对，未验证真实 Kingbase 表结构、长度、默认值、约束和类型。
+
+### C. 代码中引用但设计文档没有的培训表
+
+在 `ruoyi-train/src/main/resources/mapper/train` 的当前 14 个 XML 中未发现此类表。旧知识图谱/天气前端页面调用的接口没有相应当前培训后端 Controller，不能据此认定存在业务表。
+
+### D. 设计文档存在但代码尚未实现的表
+
+以《学员管理系统数据表设计》列出的 14 张具体表为范围，未发现只在设计文档存在而完全没有 Entity/Mapper 的表。
+
+需要区分：需求与功能分析材料提出或暗示了参训关系、课次/课表、床位、设备同步流水等概念，但这些并不是该数据表设计文档中已经命名的表，因此不计入本节 D 类；它们作为领域缺口列在 `10_gap_and_conflict_analysis.md`。
+
+## 4. 字段与公共字段
+
+14 个 `Train*` Domain 全部 `extends BaseEntity`。`BaseEntity` 提供：`searchValue`、`createBy`、`createTime`、`updateBy`、`updateTime`、`remark`、`params`。
+
+当前培训设计和 Mapper 的实际使用方式并不完全统一：
+
+- 教师、学员、课程、计划、宿舍、宿舍权限、教室、场地、班牌显式定义 `createUser`，映射数据库 `create_user`；同时从 BaseEntity 继承 `createTime`、`updateTime`、`remark`。
+- 报到表只显式映射 `create_time`，没有 `create_user`、`update_time`、`remark`。
+- 签到表没有通用审计字段。
+- 成绩表使用 `import_time`，学习时长表使用 `sync_time`，画像表使用 `update_time`。
+- 培训表 Mapper 未使用 BaseEntity 的 `createBy`/`updateBy` 写入 `create_by`/`update_by`；业务表设计使用的是 `create_user`。
+- 部分 ServiceImpl 会设置 `createTime` 或 `updateTime`，但没有统一填充器；这不是 MyBatis-Plus 项目。
+
+因此，虽然所有实体继承 BaseEntity，不能据此认为所有培训表都具备完整一致的若依公共字段。
+
+## 5. 主键生成
+
+- 字符串业务主键：`t_id`、`s_id`、`c_id`、`plan_id`、`dorm_id`、`class_room_id`、`site_id`、`board_id`。Mapper 仅在属性非空时插入，没有 UUID/雪花算法等 Java 侧生成逻辑；前端表单需提供或数据库必须有另行默认值。
+- 数字主键：`auth_id`、`report_id`、`checkin_id`、`score_id`、`dur_id`、`portrait_id`。相应 XML 使用 `useGeneratedKeys="true"` 与 `keyProperty`。
+- 设计文档将数字主键写为 `INT AUTO_INCREMENT`。这属于 MySQL 表述；在 Kingbase 应由实际 identity/sequence 定义与驱动回填能力共同保证。本次未连接数据库，未验证生成键行为。
+
+## 6. 删除方式
+
+- 14 个培训 Mapper 的删除语句均为 `delete from train_*`，包括批量 `IN` 删除。
+- 培训 Domain 未发现 `delFlag`，设计文档也未为这些表定义 `del_flag`。
+- 因此当前培训 CRUD 是物理删除，不是若依系统表常用的逻辑删除。
+
+## 7. 外键与完整性
+
+设计文档在描述列中标注多处“外键”，但仓库没有培训 DDL，也没有 `FOREIGN KEY` 约束脚本。Mapper 采用单表 SQL，ServiceImpl 未见关联对象存在性检查、级联策略或事务编排。
+
+所以当前只能确认“字段表达了引用意图”，不能确认数据库中已创建外键、唯一索引或级联规则。
+
+## 8. SQL 初始化与迁移
+
+仓库中可见：
+
+- `RuoYi-Vue/sql/ry_20250522.sql`：若依系统表初始化，整体为 MySQL DDL/DML 风格。
+- `RuoYi-Vue/sql/quartz.sql`：Quartz 表脚本。
+
+未发现：
+
+- 14 张 `train_*` 表的可执行 DDL或种子数据。
+- 培训 `sys_menu`、角色和权限初始化 SQL。
+- Flyway、Liquibase 或其他版本化迁移目录/配置。
+
+设计 DOCX 只是表结构说明，不是可执行迁移。
+
+## 9. Kingbase 兼容性事实
+
+当前配置与代码同时存在以下待验证点：
+
+1. `application.yml` 固定 `pagehelper.helperDialect: mysql`。
+2. `ry_20250522.sql` 大量使用 `AUTO_INCREMENT`、`ENGINE=InnoDB`、反引号、MySQL 类型宽度和 `sysdate()`。
+3. 系统 Mapper 使用 `date_format(...)`、`find_in_set(...)`、`ifnull(...)` 和反引号列名，例如 `SysUserMapper.xml`、`SysDeptMapper.xml`、`SysMenuMapper.xml`。
+4. `DataScopeAspect` 动态拼接 `find_in_set`。
+5. 代码生成器读取 `information_schema` 时同时依赖 `current_database()` 以及 MySQL 的 `column_key`、`column_comment`、`extra='auto_increment'`、`column_type` 语义。
+6. 培训设计文档采用 `DATETIME`、`TINYINT`、`AUTO_INCREMENT` 和 `ON UPDATE CURRENT_TIMESTAMP`。
+7. 培训数字主键依赖 JDBC generated keys。
+8. Druid 校验 SQL 为 `SELECT 1 FROM DUAL`。
+
+这不等于所有语句在 Kingbase 必然失败，因为 Kingbase 可能启用兼容模式；但仓库没有记录目标兼容模式，也没有验证脚本/测试结果。不能把“已换驱动和 URL”视为完成数据库适配。
+
+## 10. `sys_*` 表当前如何被使用
+
+- `sys_user`：登录主体、个人资料、用户管理、角色/岗位关系。
+- `sys_role`：角色定义与数据范围类型。
+- `sys_menu`：菜单树、路由组件、权限字符串；`/getRouters` 动态返回前端路由。
+- `sys_role_menu`、`sys_user_role`：RBAC 关系。
+- `sys_dept`、`sys_role_dept`：部门树与数据权限。
+- `sys_oper_log`、`sys_logininfor`：操作与登录日志。
+- `sys_dict_*`、`sys_config`、`sys_notice`：字典、参数、公告。
+- `sys_job`、`sys_job_log`：Quartz 任务定义与执行日志。
+
+培训表当前未与 `sys_user` 建立代码层关系，培训 Service 也未应用若依数据权限切面。后续应在现有权限体系上增加培训关系和权限配置，不应修改系统表结构来复制一套登录/RBAC。