wwjcloud-nest-v1/wwjcloud/docs/TOOLS-MIGRATION-USAGE.md

# 迁移工具使用指南

## 概述

迁移工具模块提供了从 PHP/Java 项目迁移到 NestJS 的完整解决方案。该模块基于 common 层的代码生成器，提供了多种调用方式。

## 架构设计

```
tools/
├── migration/
│   ├── migration.module.ts           # 迁移模块
│   ├── services/
│   │   ├── php-migration.service.ts  # PHP 迁移服务
│   │   ├── java-migration.service.ts # Java 迁移服务
│   │   └── generator-cli.service.ts  # 生成器 CLI 服务
│   └── controllers/
│       └── migration.controller.ts   # 迁移控制器
└── tools.module.ts                   # 工具模块入口
```

## 使用方式

### 1. 直接使用 common 层生成器

```typescript
import { GeneratorService } from '@/common/generator';

@Injectable()
export class SomeBusinessService {
  constructor(private generatorService: GeneratorService) {}
  
  async createModule() {
    return this.generatorService.generate({
      tableName: 'sys_user',
      generateType: 1,
      generateController: true,
      generateService: true,
      generateEntity: true,
      generateDto: true,
      generateMapper: true,
      generateEvents: true,
      generateListeners: true,
    });
  }
}
```

### 2. 使用 tools 迁移服务

```typescript
import { PhpMigrationService } from '@/tools/migration';

@Injectable()
export class MigrationService {
  constructor(private phpMigrationService: PhpMigrationService) {}
  
  async migrateFromPHP() {
    // 迁移单个表
    const result = await this.phpMigrationService.migrateTable('sys_user');
    
    // 批量迁移
    const tables = ['sys_user', 'sys_menu', 'sys_config'];
    const results = await this.phpMigrationService.migrateTables(tables);
    
    // 生成迁移报告
    const report = await this.phpMigrationService.generateMigrationReport(tables);
    
    return { result, results, report };
  }
}
```

### 3. 使用 CLI 服务

```typescript
import { GeneratorCliService } from '@/tools/migration';

@Injectable()
export class CliService {
  constructor(private generatorCliService: GeneratorCliService) {}
  
  async generateFromCommandLine() {
    return this.generatorCliService.generateFromCLI({
      tableName: 'sys_user',
      moduleName: 'user',
      className: 'SysUser',
      author: 'NiuCloud Team',
      generateController: true,
      generateService: true,
      generateEntity: true,
      generateDto: true,
      generateMapper: true,
      generateEvents: true,
      generateListeners: true,
      outputDir: './generated',
    });
  }
}
```

## API 接口

### PHP 迁移接口

| 接口 | 方法 | 说明 |
|------|------|------|
| `/adminapi/migration/php/tables` | GET | 获取 PHP 项目表列表 |
| `/adminapi/migration/php/migrate` | POST | 迁移单个 PHP 表 |
| `/adminapi/migration/php/batch-migrate` | POST | 批量迁移 PHP 表 |
| `/adminapi/migration/php/report` | POST | 生成 PHP 迁移报告 |

### Java 迁移接口

| 接口 | 方法 | 说明 |
|------|------|------|
| `/adminapi/migration/java/tables` | GET | 获取 Java 项目表列表 |
| `/adminapi/migration/java/migrate` | POST | 迁移单个 Java 表 |
| `/adminapi/migration/java/batch-migrate` | POST | 批量迁移 Java 表 |
| `/adminapi/migration/java/report` | POST | 生成 Java 迁移报告 |

### 通用生成器接口

| 接口 | 方法 | 说明 |
|------|------|------|
| `/adminapi/migration/tables` | GET | 获取所有表列表 |
| `/adminapi/migration/table/:tableName` | GET | 获取表信息 |
| `/adminapi/migration/generate` | POST | 生成代码 |
| `/adminapi/migration/preview` | POST | 预览代码 |
| `/adminapi/migration/batch-generate` | POST | 批量生成代码 |

## 请求示例

### 迁移单个表

```bash
POST /adminapi/migration/php/migrate
Content-Type: application/json

{
  "tableName": "sys_user",
  "options": {
    "generateController": true,
    "generateService": true,
    "generateEntity": true,
    "generateDto": true,
    "generateMapper": true,
    "generateEvents": true,
    "generateListeners": true
  }
}
```

### 批量迁移

```bash
POST /adminapi/migration/php/batch-migrate
Content-Type: application/json

{
  "tableNames": ["sys_user", "sys_menu", "sys_config"],
  "options": {
    "generateController": true,
    "generateService": true,
    "generateEntity": true,
    "generateDto": true,
    "generateMapper": true,
    "generateEvents": true,
    "generateListeners": true
  }
}
```

### 生成迁移报告

```bash
POST /adminapi/migration/php/report
Content-Type: application/json

{
  "tableNames": ["sys_user", "sys_menu", "sys_config"]
}
```

## 响应格式

### 成功响应

```json
{
  "code": 200,
  "message": "迁移成功",
  "data": [
    {
      "filePath": "src/common/sysUser/controllers/adminapi/sysUser.controller.ts",
      "content": "...",
      "type": "controller"
    }
  ]
}
```

### 错误响应

```json
{
  "code": 500,
  "message": "错误信息",
  "data": null
}
```

## 迁移报告格式

```json
{
  "totalTables": 3,
  "successCount": 2,
  "failedCount": 1,
  "details": [
    {
      "tableName": "sys_user",
      "status": "success",
      "fileCount": 8,
      "analysis": {
        "tableName": "sys_user",
        "fields": [],
        "relations": [],
        "indexes": []
      }
    }
  ]
}
```

## 配置选项

### GeneratorOptions

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| tableName | string | ✅ | 数据库表名 |
| moduleName | string | ❌ | 模块名，默认从表名转换 |
| className | string | ❌ | 类名，默认从表名转换 |
| addonName | string | ❌ | 插件名，用于插件开发 |
| author | string | ❌ | 作者信息 |
| generateType | number | ✅ | 生成类型：1-预览，2-下载，3-同步 |
| outputDir | string | ❌ | 输出目录，默认项目根目录 |
| generateController | boolean | ❌ | 是否生成控制器，默认true |
| generateService | boolean | ❌ | 是否生成服务，默认true |
| generateEntity | boolean | ❌ | 是否生成实体，默认true |
| generateDto | boolean | ❌ | 是否生成DTO，默认true |
| generateMapper | boolean | ❌ | 是否生成数据访问层，默认false |
| generateEvents | boolean | ❌ | 是否生成事件，默认false |
| generateListeners | boolean | ❌ | 是否生成监听器，默认false |
| generateTest | boolean | ❌ | 是否生成测试文件，默认false |

## 最佳实践

1. **渐进式迁移**: 先迁移核心表，再迁移业务表
2. **批量处理**: 使用批量迁移接口提高效率
3. **预览模式**: 先使用预览模式检查生成结果
4. **报告分析**: 定期生成迁移报告分析进度
5. **错误处理**: 妥善处理迁移过程中的错误

## 扩展开发

### 添加新的迁移源

1. 创建新的迁移服务类
2. 实现相应的接口方法
3. 在 migration.module.ts 中注册服务
4. 在 migration.controller.ts 中添加 API 接口

### 自定义生成逻辑

1. 继承 GeneratorService
2. 重写相关方法
3. 在迁移服务中使用自定义生成器

## 故障排除

### 常见问题

1. **表不存在**: 检查表名是否正确
2. **权限不足**: 检查数据库连接权限
3. **生成失败**: 查看错误日志定位问题
4. **文件冲突**: 检查输出目录是否已存在文件

### 调试技巧

1. 使用预览模式检查生成内容
2. 查看迁移报告了解详细状态
3. 检查数据库连接和表结构
4. 查看应用日志获取错误信息