aiccs-api/check/迁移检测实施方案.md

# 广州→内蒙信用监管系统迁移检测实施方案

## 一、检测目标

确保从广州市场监督管理局迁移到内蒙市场监督管理局的信用监管综合系统能够：
- Mapper XML与数据库表结构保持一致
- SQL语句兼容目标数据库类型（达梦/MySQL/Oracle/DB2等）
- 数据持久层稳定可靠，确保数据查询和操作正常

---

## 二、检测方案总览

本迁移检测项目包含两个独立的检测方案：

### 1. Mapper XML 与表结构一致性检测方案

**文档位置**：[check/Mapper-XML与表结构一致性检测方案.md](./Mapper-XML与表结构一致性检测方案.md)

**检测目标**：
- 确保 MyBatis Mapper XML 文件与数据库表结构保持一致
- 避免因字段不匹配导致的数据查询错误或运行时异常

**核心检测项**：
- 字段名映射（Mapper字段是否在数据库表中存在）
- 数据类型匹配（Java类型与数据库列类型是否对应）
- 主键/索引配置（主键配置、生成策略是否匹配数据库）

**适用场景**：
- 数据库表结构变更后
- 新增或修改Mapper XML文件时
- 迁移到新的数据库环境前

---

### 2. 跨数据库SQL兼容性检测方案

**文档位置**：[check/跨数据库SQL兼容性检测方案.md](./跨数据库SQL兼容性检测方案.md)

**检测目标**：
- 检测系统中所有SQL语句在目标数据库上的兼容性
- 识别并修复不兼容的SQL语法
- 确保系统平滑迁移到新数据库环境

**核心检测项**：
- SQL语法兼容性（分页、函数、操作符等）
- 数据类型兼容性（MySQL特有类型 → 标准SQL类型）
- 字符串和日期处理（字符串拼接、日期函数等）

**重点检测的MySQL特有语法**：
- `LIMIT offset, count` → `LIMIT count OFFSET offset`
- `NOW()` → `SYSDATE`
- `AUTO_INCREMENT` → `IDENTITY`
- `` `table` `` → `"table"`
- `IF(condition, a, b)` → `CASE WHEN condition THEN a ELSE b END`
- `GROUP_CONCAT()` → `LISTAGG()`

**适用场景**：
- 从MySQL迁移到达梦/Oracle等数据库
- 系统需要支持多种数据库类型
- 检测代码中的数据库特定语法

---

## 三、检测实施流程

### 阶段1：准备阶段

1. **确认目标数据库类型**
   ```bash
   # 查看当前数据库配置
   cat application.yml | grep -A 5 "database:"
   ```

2. **备份代码**
   ```bash
   git add .
   git commit -m "备份：迁移检测前的代码"
   ```

3. **创建检测报告目录**
   ```bash
   mkdir -p check/reports
   mkdir -p check/scripts
   ```

---

### 阶段2：执行检测

#### 步骤1：Mapper XML 与表结构一致性检测

```bash
# 1. 导出数据库表结构
python check/scripts/export_db_schema.py

# 2. 执行一致性检测
python check/scripts/mapper_schema_checker.py

# 3. 查看检测报告
cat check/reports/mapper_schema_report.json
cat check/reports/mapper_schema_report.md
```

#### 步骤2：跨数据库SQL兼容性检测

```bash
# 1. 快速扫描MySQL特有语法
bash check/scripts/scan_mysql_syntax.sh > scan_results.txt

# 2. 执行完整兼容性检测
python check/scripts/mysql_to_dm_checker.py

# 3. 查看检测报告
cat check/reports/compatibility_report.json
cat check/reports/compatibility_report.md
```

---

### 阶段3：问题修复

1. **按优先级修复问题**
   - HIGH（高危）：必须修复，否则系统无法运行
   - MEDIUM（中危）：建议修复，可能影响功能
   - LOW（低危）：可选修复，优化性改进

2. **修复方式**
   - **自动修复**：使用脚本自动修复简单问题（谨慎使用）
   - **手动修复**：根据报告建议逐一修复复杂问题

3. **验证修复**
   ```bash
   # 重新执行检测
   python check/scripts/mapper_schema_checker.py
   python check/scripts/mysql_to_dm_checker.py

   # 对比修复前后的报告
   diff check/reports/before_fix.json check/reports/after_fix.json
   ```

---

### 阶段4：测试验证

1. **单元测试**
   ```bash
   mvn test -Dtest=*MapperTest
   ```

2. **集成测试**
   ```bash
   mvn verify
   ```

3. **功能测试**
   - 启动应用
   - 测试核心业务功能
   - 验证数据查询和操作

---

## 四、检测工具和脚本

### 1. Mapper XML 与表结构一致性检测工具

| 工具名称 | 文件路径 | 说明 |
|---------|---------|------|
| 数据库Schema导出工具 | `check/scripts/export_db_schema.py` | 导出数据库表结构为JSON |
| 一致性检测工具 | `check/scripts/mapper_schema_checker.py` | 检测Mapper与表结构一致性 |
| 检测报告 | `check/reports/mapper_schema_report.json` | JSON格式检测报告 |
| 检测报告 | `check/reports/mapper_schema_report.md` | Markdown格式检测报告 |

### 2. 跨数据库SQL兼容性检测工具

| 工具名称 | 文件路径 | 说明 |
|---------|---------|------|
| 快速扫描脚本 | `check/scripts/scan_mysql_syntax.sh` | Linux/Mac快速扫描脚本 |
| 快速扫描脚本 | `check/scripts/scan_mysql_syntax.ps1` | Windows快速扫描脚本 |
| 兼容性检测工具 | `check/scripts/mysql_to_dm_checker.py` | 完整的兼容性检测工具 |
| 自动修复脚本 | `check/scripts/fix_compatibility.sh` | 自动修复MySQL语法（谨慎使用） |
| 检测报告 | `check/reports/compatibility_report.json` | JSON格式检测报告 |
| 检测报告 | `check/reports/compatibility_report.md` | Markdown格式检测报告 |

---

## 五、常见问题排查

### 问题1：Mapper字段与数据库表不匹配

**症状**：
```
org.apache.ibatis.exceptions.PersistenceException:
### Error querying database. Cause: java.sql.SQLException: 无效的列索引
```

**排查步骤**：
1. 检查Mapper XML中的字段名是否正确
2. 对比数据库表结构
3. 使用一致性检测工具扫描
4. 查看详细报告：`check/reports/mapper_schema_report.md`

**参考文档**：[Mapper-XML与表结构一致性检测方案.md](./Mapper-XML与表结构一致性检测方案.md)

---

### 问题2：SQL语句在新数据库中报错

**症状**：
```
java.sql.SQLSyntaxErrorException: 语法分析错误
```

**排查步骤**：
1. 确认错误SQL语句
2. 检查是否使用了MySQL特有语法
3. 使用兼容性检测工具扫描
4. 查看兼容性对照表

**参考文档**：[跨数据库SQL兼容性检测方案.md](./跨数据库SQL兼容性检测方案.md)

---

### 问题3：分页查询不工作

**症状**：
```
LIMIT语法错误或分页结果不正确
```

**解决方案**：
- MySQL: `LIMIT offset, count`
- 达梦8+: `LIMIT count OFFSET offset`
- 达梦7: 使用 `ROWNUM`

**参考文档**：[跨数据库SQL兼容性检测方案.md](./跨数据库SQL兼容性检测方案.md)

---

## 六、检测报告示例

### Mapper XML 与表结构一致性检测报告

```json
{
  "summary": {
    "total_issues": 15,
    "by_severity": {
      "HIGH": 8,
      "MEDIUM": 5,
      "LOW": 2
    }
  },
  "issues": [
    {
      "type": "EXTRA_FIELDS",
      "table": "ABNORMAL_LIST",
      "file": "src/main/resources/mybatis/mapper/aiccs/abnormal/AbnormalListMapper.xml",
      "severity": "HIGH",
      "message": "Mapper中多余字段（数据库中不存在）: NEW_FIELD, DEPRECATED_FIELD"
    }
  ]
}
```

### 跨数据库SQL兼容性检测报告

```json
{
  "scan_time": "2025-01-05T14:30:00",
  "summary": {
    "total_issues": 45,
    "by_severity": {
      "HIGH": 23,
      "MEDIUM": 15,
      "LOW": 7
    },
    "by_type": {
      "NOW": 18,
      "LIMIT": 12,
      "IF_FUNCTION": 8
    }
  },
  "issues": [
    {
      "issue_type": "NOW",
      "severity": "HIGH",
      "file_path": "src/main/resources/mybatis/mapper/aiccs/abnormal/AbnormalListMapper.xml",
      "line_number": 45,
      "mysql_pattern": "NOW()",
      "dm_pattern": "SYSDATE",
      "description": "达梦不支持NOW()函数",
      "suggestion": "将 NOW() 改为 SYSDATE"
    }
  ]
}
```

---

## 七、最佳实践建议

### 1. 定期执行检测

- **每次数据库表结构变更后**：执行Mapper XML一致性检测
- **每次修改SQL语句后**：执行兼容性检测
- **迁移到新环境前**：执行完整检测

### 2. 集成到CI/CD流程

在项目的CI/CD流程中集成检测工具，确保每次代码提交都经过检测：

```yaml
# .gitlab-ci.yml 示例
test:
  script:
    - python check/scripts/mapper_schema_checker.py
    - python check/scripts/mysql_to_dm_checker.py
    - mvn test
```

### 3. 代码审查

- 将检测报告作为代码审查的参考
- 重点关注高危和中危问题
- 确保所有问题都已修复或确认可忽略

### 4. 文档维护

- 及时更新检测工具和脚本
- 维护兼容性对照表
- 记录常见问题和解决方案

---

## 八、相关资源

### 项目文档

- [Mapper-XML与表结构一致性检测方案.md](./Mapper-XML与表结构一致性检测方案.md) - Mapper一致性检测详细方案
- [跨数据库SQL兼容性检测方案.md](./跨数据库SQL兼容性检测方案.md) - SQL兼容性检测详细方案

### 数据库参考文档

- **达梦数据库**: [https://www.dameng.com/](https://www.dameng.com/)
- **MySQL**: [https://dev.mysql.com/doc/](https://dev.mysql.com/doc/)
- **Oracle**: [https://docs.oracle.com/en/database/](https://docs.oracle.com/en/database/)

### MyBatis参考文档

- **MyBatis官方文档**: [https://mybatis.org/mybatis-3/](https://mybatis.org/mybatis-3/)
- **MyBatis-Plus文档**: [https://baomidou.com/](https://baomidou.com/)

---

## 九、检查清单

### 迁移前检查

- [ ] 确认目标数据库类型和版本
- [ ] 备份当前代码和数据
- [ ] 创建检测报告目录
- [ ] 导出数据库表结构

### 执行检测

- [ ] Mapper XML 与表结构一致性检测
- [ ] 跨数据库SQL兼容性检测
- [ ] 生成检测报告
- [ ] 分析检测报告

### 问题修复

- [ ] 修复高危问题
- [ ] 修复中危问题
- [ ] 修复低危问题（可选）
- [ ] 验证修复结果

### 测试验证

- [ ] 单元测试通过
- [ ] 集成测试通过
- [ ] 功能测试通过
- [ ] 性能测试通过

### 部署上线

- [ ] 灰度发布
- [ ] 监控系统运行状态
- [ ] 收集用户反馈
- [ ] 完成迁移

---

## 十、技术支持

如果在执行迁移检测过程中遇到问题，请：

1. 查阅相关文档和参考资料
2. 检查检测报告中的错误信息
3. 联系项目负责人或DBA
4. 提交Issue到项目仓库

---

**最后更新时间**: 2025-01-05
**文档版本**: v1.0
**维护人**: 开发团队