# 批量转换功能使用指南

## 概述

CodePlay 现在支持批量文件和目录转换，可以一次性转换整个项目或目录下的所有源代码文件。

## 核心功能

### 1. 目录转换
自动递归转换指定目录下的所有符合条件的源文件。

### 2. 保持目录结构
转换后的文件保持原始目录结构，方便项目整体迁移。

### 3. 详细报告
提供批量转换统计信息，包括成功/失败文件列表和详细错误信息。

## CLI 命令参考

### 基本语法
```bash
dotnet run --project CodePlay.CLI -- convert \
  -s <源语言> -t <目标语言> \
  -i <输入目录> \
  -o <输出目录> \
  -b [选项]
```

### 常用参数

| 参数 | 简写 | 说明 | 默认值 |
|------|------|------|--------|
| `--source-language` | `-s` | 源语言 (CSharp, Java) | 必填 |
| `--target-language` | `-t` | 目标语言 (CSharp, Java) | 必填 |
| `--input` | `-i` | 输入目录路径 | 必填 |
| `--output` | `-o` | 输出目录路径 | 自动生成 |
| `--batch` | `-b` | 启用批量模式 | false |
| `--recursive` | `-r` | 递归子目录 | true |
| `--verbose` | | 显示详细信息 | false |
| `--validation-rounds` | `-v` | 验证轮次 (1-3) | 2 |

## 使用示例

### 示例 1: 转换 C# 项目到 Java
```bash
# 转换整个 C# 项目目录
dotnet run --project CodePlay.CLI -- \
  convert -s CSharp -t Java \
  -i ./MyCSharpProject \
  -o ./MyJavaProject \
  -b
```

### 示例 2: 带详细输出的转换
```bash
# 显示每个文件的转换详情
dotnet run --project CodePlay.CLI -- \
  convert -s CSharp -t Java \
  -i ./src \
  -b --verbose
```

### 示例 3: 不递归子目录
```bash
# 仅转换当前目录，不处理子目录
dotnet run --project CodePlay.CLI -- \
  convert -s CSharp -t Java \
  -i ./src \
  -b -r false
```

### 示例 4: 指定输出目录
```bash
# 转换到指定输出目录
dotnet run --project CodePlay.CLI -- \
  convert -s Java -t CSharp \
  -i ./java-src \
  -o ./csharp-output \
  -b
```

### 示例 5: 单文件转换（向后兼容）
```bash
# 批量模式和单文件模式自动检测
dotnet run --project CodePlay.CLI -- \
  convert -s CSharp -t Java \
  -i ./Program.cs \
  -o ./Program.java
```

## 输出示例

成功转换时：
```
📁 批量转换模式启动
源目录：./MyCSharpProject
目标目录：./MyJavaProject
递归：True

==== 批量转换完成 ====
源目录：./MyCSharpProject
目标目录：./MyJavaProject
总文件数：15
成功：15
失败：0
耗时：3.45 秒

成功转换的文件:
  ✅ UserService.cs → UserService.java
     行数：120, 类：1, 方法：8
  ✅ OrderController.cs → OrderController.java
     行数：85, 类：1, 方法：5
  ...

🎉 所有文件转换成功!
```

部分失败时：
```
==== 批量转换完成 ====
总文件数：15
成功：13
失败：2
耗时：3.45 秒

转换失败的文件:
  ❌ LegacyCode.cs
     错误：Unsupported syntax pattern detected
  ❌ OldStyle.cs
     错误：Compilation validation failed after 3 rounds

⚠️  2 个文件转换失败
```

## 批量转换结果详情

### BatchConversionResult
- `Success`: 是否全部成功
- `TotalFiles`: 总文件数
- `SuccessfulFiles`: 成功文件数
- `FailedFiles`: 失败文件数
- `Duration`: 转换耗时
- `ConvertedFiles`: 成功文件详情列表
- `FailedFileList`: 失败文件详情列表

### ConvertedFileInfo
- `SourceFile`: 源文件路径
- `TargetFile`: 目标文件路径
- `LinesConverted`: 转换行数
- `ClassesConverted`: 转换类数
- `MethodsConverted`: 转换方法数
- `Warnings`: 警告数量
- `Issues`: 问题数量

## 报告存储

批量转换会自动创建报告并存储：
- `ProjectId`: 格式为 `batch-YYYYMMDD`
- 可通过 `list` 命令查看历史转换记录
- 可通过 `report` API 查询详细报告

## 最佳实践

1. **先小批量测试**：先用少量文件测试转换效果
2. **使用详细模式**：首次转换使用 `--verbose` 查看细节
3. **检查失败文件**：转换后查看失败文件列表
4. **保留原始代码**：输出目录不要覆盖原始目录

## API 集成

也可以通过 Web API 调用批量转换：

```csharp
var batchService = new BatchConversionService(
    new ConversionService(),
    new ReportStorageService()
);

var result = await batchService.ConvertDirectoryAsync(
    "./src", "./output",
    LanguageType.CSharp, LanguageType.Java
);
```

## 故障排查

**Q: 找不到某些文件？**
A: 确保文件扩展名正确（.cs, .java 等），默认只转换对应语言的文件。

**Q: 转换失败如何修复？**
A: 使用 `--verbose` 查看详细错误，手动修复后重新转换单个文件。

**Q: 如何跳过某些目录？**
A: 当前版本不支持目录过滤，可将需要转换的文件复制到其他目录。

## 后续计划

- [ ] 支持文件白名单/黑名单
- [ ] 支持并行转换加速
- [ ] 支持断点续传
- [ ] 支持自定义转换规则配置

---

**更新日期**: 2025-06-03  
**测试状态**: 40 个测试全部通过 ✅