railwaysystem/RuoYi-Vue/docs/kingbase_compatibility_audit.md

# RuoYi-Vue KingbaseES (人大金仓) 适配审计报告

> **审计说明**：本轮审计仅对代码与配置文件进行静态分析与兼容性评估，未修改任何工程代码文件，未执行任何 DDL/DML 操作，所有凭据敏感信息已脱敏。

---

## A. 已确认适配

1. **JDBC 驱动类已切换**
   - 在 `ruoyi-admin/src/main/resources/application-druid.yml` 中，主库驱动已正确指定为人大金仓驱动：
     ```yaml
     driverClassName: com.kingbase8.Driver
     ```

2. **JDBC 连接串协议与 Schema 参数已配置**
   - 连接串已适配为 `jdbc:kingbase8` 协议，并显式指定了 `currentSchema=public`：
     ```yaml
     url: jdbc:kingbase8://192.168.139.218:4321/training?currentSchema=public&useUnicode=true&characterEncoding=utf8
     ```
   - 经网络探测，Mac 宿主机到目标数据库 `192.168.139.218:4321` 的网络端口畅通可达。

3. **依赖声明已添加**
   - 根模块 `pom.xml` 的 `<dependencyManagement>` 与 `ruoyi-admin/pom.xml` 中已添加 Kingbase 驱动坐标：
     ```xml
     <groupId>com.kingbase</groupId>
     <artifactId>kingbase8</artifactId>
     <version>8.6.0</version>
     ```

4. **业务模块 SQL 规范度较好**
   - 核心业务模块 `ruoyi-train` 下的 14 个业务表 Mapper（如 `TrainStudentMapper.xml` 等）均为标准单表 CRUD 语句，未使用复杂的 MySQL 专有方言函数。

---

## B. 明确存在的问题

### 1. 本地仓库缺失 Kingbase JDBC Jar 包
- 本地 `~/.m2/repository/com/kingbase/kingbase8/8.6.0/` 目录不存在。
- 人大金仓官方商业驱动未公开发布至 Maven 中央仓库或阿里云公共镜像，导致命令行执行 Maven 命令时依赖无法解析，构建失败。

### 2. PageHelper 分页插件方言被硬编码为 MySQL
- 在 `ruoyi-admin/src/main/resources/application.yml` 中明确配置了：
  ```yaml
  pagehelper:
    helperDialect: mysql
  ```
- 强制指定 `mysql` 方言会导致 PageHelper 加载 `MySqlDialect`，而非 Kingbase/PostgreSQL 专属分页与 Count 优化器，埋下深层分页与嵌套查询隐患。

### 3. Mapper XML 中存在反引号（`）转义
- PostgreSQL/Kingbase 识别双引号 `"` 作为标识符定界符，**反引号属于非法语法**。
- `ruoyi-system/src/main/resources/mapper/system/SysMenuMapper.xml` 中共有 6 处使用了反引号字段 `` `query` ``（如第 32、53、59、78、149、173 行），执行对应菜单查询/更新 SQL 时将直接抛出语法错误。

### 4. Mapper XML 中包含 MySQL 专属函数
- **`date_format(...)`（共 14 处）**：
  - 涉及：`SysUserMapper.xml`、`SysJobLogMapper.xml`、`SysOperLogMapper.xml`、`SysLogininforMapper.xml`、`GenTableMapper.xml`。
  - 典型语法：`AND date_format(create_time,'%Y%m%d') >= date_format(#{params.beginTime},'%Y%m%d')`。
  - Kingbase 中无原生 `date_format`，标准函数为 `TO_CHAR(...)`。带时间范围检索的列表查询将直接报错。
- **`find_in_set(...)`（共 3 处）**：
  - 涉及：`SysUserMapper.xml`（部门权限关联）与 `SysDeptMapper.xml`（部门树父子过滤）。
  - Kingbase/PG 无原生 `find_in_set` 函数，涉及组织架构层级查询时将抛出异常。
- **`ifnull(...)`（共 4 处）**：
  - 涉及：`SysMenuMapper.xml` 中的 `ifnull(perms, '')`。
  - PG 标准函数为 `COALESCE`。若 Kingbase 处于非兼容模式，会提示函数不存在。

### 5. 若依代码生成器（ruoyi-generator）完全无法使用
- **表元数据查询失败** (`GenTableMapper.xml`)：
  - 查询语句：`from information_schema.tables where table_schema = (select current_database())`。
  - Kingbase 的 `current_database()` 返回数据库名（如 `training`），与 schema 名（如 `public`）不一致，无法检索出任何表。
  - 查询列中的 `table_comment`、`create_time`、`update_time` 在 Kingbase 的 `information_schema.tables` 视图中并不存在，直接报列不存在异常。
- **字段元数据查询失败** (`GenTableColumnMapper.xml`)：
  - 包含非标准操作符 `&&`（PG 中必须用 `AND`）。
  - 使用了 MySQL 专有的 `column_key`、`extra`、`column_comment`、`column_type` 字段，在 Kingbase 中不可用。
- **代码生成模板中的 MySQL 专有语法** (`vm/sql/sql.vm`)：
  - 包含了 `SELECT @parentId := LAST_INSERT_ID();` 及 `@parentId` 变量，Kingbase 无法解析执行。

### 6. 初始化 SQL 脚本完全未做 Kingbase 迁移
- `sql/ry_20250522.sql` 和 `sql/quartz.sql` 均为纯 MySQL 语法。
- 包含 `engine=innodb`、`auto_increment`、`bigint(20)`、`datetime`、`sysdate()`、`blob` 等 MySQL 专有 DDL 与函数，且未创建任何序列（Sequence），在 Kingbase 中无法直接执行初始化。

---

## C. 潜在风险

1. **Druid 连接保活查询配置风险**
   - `application-druid.yml` 中配置了 `validationQuery: SELECT 1 FROM DUAL`。
   - Kingbase 在默认或 PG 模式下并无 `DUAL` 虚拟表（仅 Oracle 兼容模式或手工建视图才有），通用保活语句应为 `SELECT 1`。
2. **Druid WallFilter（SQL 防火墙）误拦截**
   - `application-druid.yml` 启用了 `filter.wall`，但未配置 Kingbase/PostgreSQL 专属的 WallFilter 白名单规则。Druid 内置 SQL 解析器在解析国产库特有语法时极易抛出 `SQLSyntaxErrorException: druid wall filter sql error`。
3. **pom.xml 构建插件硬编码 Windows 路径**
   - `pom.xml` 和 `ruoyi-admin/pom.xml` 中的 `maven-dependency-plugin` 包含了写死的路径：
     `<outputDirectory>D:\maven_repository\com\kingbase\kingbase8\8.6.0</outputDirectory>`。
   - 在 macOS 或 Linux 打包部署时将导致构建阶段报错或路径异常。
4. **MySQL JDBC 驱动残留**
   - `ruoyi-admin/pom.xml` 中仍声明有 `mysql-connector-java`，易引起类加载冗余或驱动加载冲突。
5. **Schema 硬编码不一致**
   - `SysUserMapper.xml` 与 `SysConfigMapper.xml` 中部分 SQL 被硬编码加入了 `public.` 前缀，而其余所有 Mapper 均未带前缀。一旦未来生产环境数据库 schema 迁移或变更，将导致部分 SQL 跨 schema 访问失效。
6. **标识符大小写与 LIKE 模糊匹配规则差异**
   - MySQL 对表名、列名以及 `LIKE` 匹配默认不区分大小写，而 Kingbase/PG 默认区分大小写（`LIKE` 严格匹配大小写，需用 `ILIKE` 或 `lower()` 处理）。若数据库中存在大小写敏感数据，前端模糊搜索可能出现遗漏。

---

## D. 后续建议

1. **建立本地/私服 Kingbase 依赖规范**
   - 通过 `mvn install:install-file` 将 `kingbase8-8.6.0.jar` 安装至本地仓库，或上传至团队私有 Nexus 镜像库。
   - 清理 `pom.xml` 中残留的 `mysql-connector-java` 与硬编码的 `D:\` 路径插件。
2. **修正数据源与连接池配置**
   - 将 `validationQuery` 修改为标准跨库通用的 `SELECT 1`。
   - 将 PageHelper 的 `helperDialect` 修正为自动识别或 `kingbase` / `postgresql`。
   - 如果遇到 Druid 报防火墙拦截错误，调整 WallFilter 配置或针对 Kingbase 禁用 WallFilter。
3. **统一定义或兼容 SQL 函数**
   - 方式一（推荐）：修改 Mapper XML，将 `date_format` 替换为 `to_char`，反引号替换为双引号，`find_in_set` 替换为数组/字符串函数或子查询。
   - 方式二：在 Kingbase 数据库的 public schema 下自定义创建 `date_format`、`find_in_set`、`ifnull` 兼容函数，降低改动范围。
4. **改造代码生成器元数据查询**
   - 重构 `GenTableMapper.xml` 与 `GenTableColumnMapper.xml`，使用 `information_schema.tables` 配合 PostgreSQL 系统目录 `pg_class`、`pg_description`、`pg_attribute` 读取表及字段元数据。

---

## E. 开始业务开发前必须解决的问题（阻断级 Checklist）

| 序号 | 优先级 | 类别 | 阻断问题与解决要点 |
| :--- | :--- | :--- | :--- |
| **1** | 🔴 P0 | 依赖构建 | **安装 Kingbase JDBC Jar**：在开发机执行 `mvn install:install-file` 导入 `kingbase8-8.6.0.jar`，确保编译构建通过。 |
| **2** | 🔴 P0 | 配置项 | **纠正 PageHelper 方言**：移除 `application.yml` 中的 `helperDialect: mysql`，避免分页 SQL 生成异常。 |
| **3** | 🔴 P0 | SQL 语法 | **消除 Mapper XML 中的反引号**：修改 `SysMenuMapper.xml` 中的 `` `query` ``，避免系统菜单相关接口直接崩溃。 |
| **4** | 🔴 P0 | SQL 函数 | **解决 `find_in_set` 与 `date_format`**：在数据库端创建兼容函数，或在 `SysUserMapper.xml`、`SysDeptMapper.xml` 等核心 XML 中重写对应 SQL，否则用户管理、部门管理、时间检索必定报错。 |
| **5** | 🔴 P0 | 初始化数据 | **准备 Kingbase 版基础 DDL 脚本**：当前项目中的 `sql/ry_*.sql` 无法在 Kingbase 跑通，需提供适配 Kingbase 语法的主键序列及数据初始化脚本。 |
| **6** | 🟡 P1 | 代码生成 | **修复代码生成器元数据 SQL**：若业务开发需要使用若依代码生成器，必须先重写 `ruoyi-generator` 的元数据查询 SQL。 |