devlab-dao-sql-compat

用途

面向使用任何持久层框架（MyBatis / JPA / MyBatis-Plus / SQLAlchemy）的项目，解决"同一套 DAO 代码需要运行在不同数据库（Oracle / PostgreSQL / MySQL）"或"数据库迁移"场景下的 SQL 方言兼容性问题：

• 检查：通过 adapter 模式扫描框架专属源码文件，按模块输出三方言命中矩阵与风险分级
• 修复：AI 按转换方向加载对应映射表（references/dialects/），逐模块修复
• 验证：静态复扫必做，库级语法预检可选，明确降级声明
• 记录：输出前后对比与待人工复核清单

支持三方言全对称 6 个转换方向：O→PG、PG→O、O→MySQL、MySQL→O、PG→MySQL、MySQL→PG。

框架探测

本技能支持 4 种 DAO 框架的 adapter，默认自动探测：

检测特征	判定框架	扫描目标
**/mapper/**/*.xml 含 SQL 标签	MyBatis	Mapper XML
**/*.java 含 @Query / @NamedQuery	JPA/Hibernate	Java 源码
**/*.java 含 QueryWrapper / LambdaQueryWrapper / BaseMapper	MyBatis-Plus	Java + XML
**/*.py 含 text() / .execute() / session.execute	SQLAlchemy	Python 源码
多个命中	提示用户选择	monorepo 可能多框架

也可手动指定：bash scripts/scan-sql-compat.sh --adapter mybatis

各框架的扫描模式、提取逻辑和方言陷阱详见 references/adapters/ 下对应文档。

配置上下文

本 Skill 的运行时配置遵循 harness-ai-kit 配置治理规范的三级优先级：

L3 对话中用户明确声明的参数 > L2 用户配置（~/.harness-ai-kit/config.yaml → 环境变量 → ~/.harness-ai-kit/.env.tak）> L1 本目录 config.defaults.yaml

配置项见 config.defaults.yaml：adapter / scan_dir / module_glob / report_path / custom_procs_file / fail_on_critical / verify_jdbc_url。 其中 verify_jdbc_url 为 sensitive：无默认值，只能经 L2/L3 注入，禁止写入任何文档或提交。

工作流（七阶段）

Phase 0 环境确认

1. 确认 DAO 框架类型（auto-detect 或手动 --adapter）
2. 确认扫描根目录（scan_dir）；框架专属源码位置默认自动探测，非标准布局时向用户确认 module_glob
3. 向用户确认目标方言拓扑（二选一）：
   • 单一目标库：整个项目最终只跑一种数据库 → 所有非目标方言都是待修复项
   • 多库路由：不同模块路由到不同数据库 → 逐模块建立"模块 → 目标方言"映射表
4. 询问是否有自定义存储过程/函数（写入 custom_procs_file 清单）

Phase 1 扫描

bash <本Skill目录>/scripts/scan-sql-compat.sh \
  --adapter <auto|mybatis|jpa|mybatis-plus|sqlalchemy> \
  --dir <scan_dir> [--module-glob <glob>] [--procs <file>] --report <report_path>

产出报告含：三方言命中明细、模块级风险矩阵、自定义存储过程依赖。 风险等级：CRITICAL（同模块方言混用）/ HIGH（单方言文件数 >5）/ MEDIUM（单方言文件数 ≤5）。

Phase 2 范围决策

向用户呈现风险矩阵，确认本次修复范围（CRITICAL 优先，或用户指定模块）。禁止全量静默修复。

Phase 3 自动修复

在人工修复之前，先运行自动修复引擎处理 4 类系统性问题：

bash <本Skill目录>/scripts/fix-sql-compat.sh \
  --adapter <adapter> --type <fix-type> --dir <scan_dir> [--dry-run]

支持的修复类型：

--type	问题	修复方式	自动化程度
regex-operator	PG ~ / !~ 正则运算符	→ Oracle REGEXP_LIKE() / NOT REGEXP_LIKE()	100% 自动
coalesce-nullstr	coalesce(col, '') 空字符串陷阱	→ NVL(col, ' ')	100% 自动
todate-concat	to_date 拼接场景格式掩码	→ 修正为 'yyyy-mm-dd'	100% 自动
todate-direct	to_date 直接参数绑定格式掩码	→ Agent 标记候选项，需人工确认	仅标记
all	以上所有	按顺序执行	80% 自动

建议先用 --dry-run 预览变更。4 类陷阱根因详见 references/systematic-fixes/。

Phase 4 人工修复

逐模块执行，每个模块：

1. 由"模块目标方言"和"命中方言"确定转换方向，只读取 references/dialects/ 下对应方向的映射表（如消除 PG 语法、目标 Oracle → 读 postgres-to-oracle.md）
2. 修复原则：
   • 最小 diff：只改方言函数本身，不重排 SQL、不改格式
   • 优先标准 SQL：映射表给出多个替代时选跨库兼容写法（COALESCE、CASE WHEN）
   • 结构性重写（映射表 ⚠ 项：CONNECT BY、MERGE INTO、ROWNUM 复杂分页、generate_series 等）：完成后标记"需人工复核"
   • 自定义存储过程/函数调用不自动改写：仅列入报告
3. 动态分支（MyBatis <if>/<choose>、JPA 条件拼接、SQLAlchemy if/else 分支）逐分支检查

Phase 5 验证

按 references/REFERENCE-VERIFICATION.md 执行：

• L1 静态复扫（必做）：重跑扫描脚本，逐模块对比前后命中数
• L2 语法预检（可选）：仅当配置了 verify_jdbc_url 时，对结构性重写项逐条 EXPLAIN/PREPARE 预检
• L2 不可用时，输出降级声明

Phase 6 记录

输出修复记录（Markdown），必须包含：

1. 模块 × (修复前 → 修复后) 方言命中数对比表
2. 待人工复核清单（结构性重写项：文件、行号、重写类型）
3. 未处理项及原因
4. 验证方式声明（L1/L2 执行情况，含降级声明）

约束

• 修复前必须完成 Phase 0 的框架确认 + 目标方言拓扑确认
• 结构性重写项必须标记"需人工复核"，不得静默视为完成
• MySQL 相关 4 个转换方向的映射表未经实战验证（文件头已标注），使用时加倍复核
• 扫描为正则匹配，存在少量误报可能，修复前先确认上下文
• 不修改扫描脚本检测不到但语义不同的写法，依赖 L2 验证与人工复核兜底
• JPA/SQLAlchemy adapter 的扫描正则为通用模式，项目特殊写法可能遗漏

参考文档

框架适配器

• references/adapters/mybatis.md - MyBatis Mapper XML 扫描模式与动态 SQL 方言陷阱
• references/adapters/jpa.md - JPA/Hibernate @Query 注解扫描与 JPQL vs native SQL
• references/adapters/mybatis-plus.md - MyBatis-Plus QueryWrapper 模式与分页插件方言
• references/adapters/sqlalchemy.md - SQLAlchemy text()/execute() 扫描与 Python ORM 方言

方言映射表

• references/dialects/oracle-to-postgres.md - Oracle → PostgreSQL
• references/dialects/oracle-to-mysql.md - Oracle → MySQL
• references/dialects/postgres-to-oracle.md - PostgreSQL → Oracle
• references/dialects/postgres-to-mysql.md - PostgreSQL → MySQL
• references/dialects/mysql-to-oracle.md - MySQL → Oracle
• references/dialects/mysql-to-postgres.md - MySQL → PostgreSQL

自动修复与验证

• references/systematic-fixes/regex-operator.sed - PG 正则运算符自动修复
• references/systematic-fixes/coalesce-nullstr.sed - coalesce 空字符串自动修复
• references/systematic-fixes/todate-concat.sed - to_date 拼接格式自动修复
• references/systematic-fixes/todate-format-guide.md - to_date 参数格式判断指南
• references/REFERENCE-VERIFICATION.md - 验证方法论（L1 静态复扫 + L2 语法预检）

深入阅读（可选依赖）

若环境已安装以下知识基座（skill.json 中声明为 optional 依赖），可延伸阅读数据库深度知识： public-oracle-expert-base、public-postgres-expert-base、public-mysql-expert-base。缺失不影响本 Skill 运行。