codeplay/.monkeycode/specs/codeplay-conversion-platform/design.md

# CodePlay 代码转换平台

Feature Name: codeplay-conversion-platform
Updated: 2026-06-03

## Description

CodePlay 是一个基于 .NET 开发的多语言代码转换平台，支持 C#、Java、C++ 三种编程语言之间的双向转换。平台采用 AST（抽象语法树）解析和转换引擎，提供 Web 界面、CLI 工具和 REST API 三种访问方式。对于无法直接转换的语法，采用注释保留 + TODO 说明的策略，并通过 1-3 轮自动编译验证确保转换质量。

## Architecture

```mermaid
graph TB
    subgraph Client Layer
        Web[Web 界面]
        CLI[CLI 工具]
        API[API 客户端]
    end
    
    subgraph API Gateway
        Gateway[API 网关]
        Auth[认证中间件]
        RateLimit[限流中间件]
    end
    
    subgraph Core Services
        ProjectService[项目管理服务]
        ConversionService[转换服务]
        ValidationService[验证服务]
        ReportService[报告服务]
    end
    
    subgraph Conversion Engine
        Parser[语言解析器]
        Transformer[代码转换器]
        Generator[代码生成器]
    end
    
    subgraph Validation Engine
        Compiler[编译器接口]
        TestRunner[测试运行器]
        FixEngine[自动修复引擎]
    end
    
    subgraph Storage
        ProjectDB[(项目数据库)]
        CodeStorage[代码存储]
        ConfigStorage[配置存储]
    end
    
    Web --> Gateway
    CLI --> Gateway
    API --> Gateway
    Gateway --> Auth
    Gateway --> RateLimit
    Gateway --> ProjectService
    Gateway --> ConversionService
    Gateway --> ReportService
    ConversionService --> Parser
    ConversionService --> Transformer
    ConversionService --> Generator
    ConversionService --> ValidationService
    ValidationService --> Compiler
    ValidationService --> TestRunner
    ValidationService --> FixEngine
    ProjectService --> ProjectDB
    ProjectService --> CodeStorage
    ProjectService --> ConfigStorage
```

## Components and Interfaces

### 语言解析器模块

| 解析器类 | 说明 | 依赖 |
|---------|------|------|
| CSharpParser | 解析 C# 代码并生成 AST | Microsoft.CodeAnalysis (Roslyn) |
| JavaParser | 解析 Java 代码并生成 AST | JavaParser (第三方库) |
| CPlusPlusParser | 解析 C++ 代码并生成 AST | clang-sharp / libclang |

### 代码转换器模块

| 转换器 | 说明 | 策略类 |
|-------|------|-------|
| CSharpToJavaConverter | C# → Java 转换 | CSharpJavaConversionStrategy |
| JavaToCSharpConverter | Java → C# 转换 | JavaCSharpConversionStrategy |
| CSharpToCPlusPlusConverter | C# → C++ 转换 | CSharpCppConversionStrategy |
| CPlusPlusToCSharpConverter | C++ → C# 转换 | CppCSharpConversionStrategy |
| JavaToCPlusPlusConverter | Java → C++ 转换 | JavaCppConversionStrategy |
| CPlusPlusToJavaConverter | C++ → Java 转换 | CppJavaConversionStrategy |

### 不可转换语法处理

| 语法特性 | 源语言 | 目标语言 | 处理策略 |
|---------|--------|---------|---------|
| LINQ | C# | Java | 保留原代码 + TODO + Stream API 建议 |
| async/await | C# | Java | 转换为 CompletableFuture + TODO 说明 |
| Lambda | C# | C++ | 转换为 std::function + TODO说明 |
| Stream API | Java | C# | 保留原代码 + TODO + LINQ 建议 |
| 模板 | C++ | C#/Java | 转换为泛型 + TODO 说明限制 |
| 多继承 | C++ | C#/Java | 转换为接口 + TODO 说明 |
| 指针操作 | C++ | C#/Java | 转换为引用/unsafe + TODO 警告 |

### 数据模型

```csharp
// 转换请求模型
public class ConversionRequest
{
    public string SourceCode { get; set; }
    public string SourceLanguage { get; set; } // CSharp, Java, CPlusPlus
    public string TargetLanguage { get; set; } // CSharp, Java, CPlusPlus
    public string ProjectId { get; set; }
    public int ValidationRounds { get; set; } // 1-3
    public ConversionOptions Options { get; set; }
}

// 转换结果模型
public class ConversionResult
{
    public bool Success { get; set; }
    public string TransformedCode { get; set; }
    public ConversionReport Report { get; set; }
    public List<ConversionWarning> Warnings { get; set; }
    public ValidationSummary ValidationSummary { get; set; }
}

// 转换报告
public class ConversionReport
{
    public int LinesConverted { get; set; }
    public int ClassesConverted { get; set; }
    public int MethodsConverted { get; set; }
    public TimeSpan Duration { get; set; }
    public List<ConversionIssue> Issues { get; set; }
    public List<TransformationLog> TransformationLog { get; set; }
}

// 项目模型
public class Project
{
    public string Id { get; set; }
    public string Name { get; set; }
    public string SourceLanguage { get; set; }
    public string TargetLanguage { get; set; }
    public ProjectStatus Status { get; set; }
    public DateTime CreatedAt { get; set; }
    public DateTime UpdatedAt { get; set; }
    public List<ConversionTask> Tasks { get; set; }
}
```

## Correctness Properties

### 1. 语法一致性
- 转换后的代码必须是目标语言的有效语法
- 转换后的代码必须能够通过目标语言编译器编译（无语法错误）

### 2. 语义等价性
- 转换前后的代码逻辑行为应保持一致
- 变量名、类名、方法名应保持语义一致性
- 访问修饰符应转换为目标语言的等价修饰符

### 3. 注释保留
- 所有源代码注释必须保留在转换后的代码中
- 文档注释应转换为目标语言的文档格式
  - C# XML Doc → Java JavaDoc
  - Java JavaDoc → C# XML Doc
  - C++ Doxygen → 目标语言文档格式

### 4. TODO 完整性
- 任何不可直接转换的语法必须添加 TODO 注释
- TODO 必须包含：
  - 原语法说明
  - 为什么无法直接转换
  - 推荐的替代方案
  - 参考代码位置

## Error Handling

### 错误分类

| 错误类型 | 错误码 | 处理策略 |
|---------|-------|---------|
| 语法错误 | ERR_PARSE_001 | 返回解析错误位置和详情 |
| 不支持的语言对 | ERR_LANG_001 | 返回支持的语言列表 |
| 转换超时 | ERR_TIMEOUT_001 | 返回已转换部分并建议分批处理 |
| 编译验证失败 | ERR_VALIDATE_001 | 执行自动修复，3 轮失败后标记人工检查 |
| 资源不足 | ERR_RESOURCE_001 | 加入队列并通知预计等待时间 |
| API 认证失败 | ERR_AUTH_001 | 返回 401 和认证指南 |

### 自动修复策略

```csharp
public class AutoFixStrategy
{
    // 第 1 轮：常见导入/using 语句修复
    public Task<FixResult> FixRound1(CompilationError error);
    
    // 第 2 轮：类型映射修复
    public Task<FixResult> FixRound2(CompilationError error);
    
    // 第 3 轮：API 调用替换
    public Task<FixResult> FixRound3(CompilationError error);
}
```

## Test Strategy

### 单元测试

- 每个转换器的独立单元测试
- 语法解析器的单元测试
- 不可转换语法处理的单元测试

### 集成测试

- 端到端转换流程测试
- 多轮验证流程测试
- API 接口集成测试

### 测试用例库

建立测试用例库，包含：
- C#、Java、C++ 各种语法特性的示例代码
- 边界情况和复杂场景的测试代码
- 已知问题的回归测试代码

### 验证策略

```csharp
public class ValidationPipeline
{
    public async Task<ValidationResult> Validate(
        string code, 
        string language, 
        int maxRounds = 3)
    {
        for (int round = 1; round <= maxRounds; round++)
        {
            var result = await CompileAndTest(code, language);
            if (result.Success)
                return result;
            
            var fix = await AutoFix(result.Errors, round);
            if (!fix.CanFix)
                break;
            
            code = fix.FixedCode;
        }
        return new ValidationResult { NeedsManualReview = true };
    }
}
```

## References

[^1]: (Microsoft Roslyn) - C# 编译器平台 [.NET Documentation](https://docs.microsoft.com/en-us/dotnet/csharp/roslyn-sdk/)
[^2]: (JavaParser) - Java 代码解析库 [https://javaparser.org/](https://javaparser.org/)
[^3]: (clang-sharp) - C++ Clang 绑定 [https://github.com/SimonFussel/clang-sharp](https://github.com/SimonFussel/clang-sharp)
[^4]: (com.aspose.ms.jdk.NetFramework) - Java 版 .NET Framework 兼容库 [Aspose 文档](https://docs.aspose.com/)
[^5]: (ANTLR) - 语言解析器生成工具 [https://www.antlr.org/](https://www.antlr.org/)