docs: 生成完整项目文档

创建以下文档: - INDEX.md - 项目索引和概览 - ARCHITECTURE.md - 系统架构设计文档 - INTERFACES.md - 接口和类型定义文档 - DEVELOPER_GUIDE.md - 开发者指南文档覆盖内容: - 项目结构和模块说明 - 技术栈和依赖 - 核心组件设计 - API 接口定义 - 数据模型 - 开发环境配置 - 代码规范 - 测试指南 - 调试技巧 - Git 工作流 Co-authored-by: monkeycode-ai <monkeycode-ai@chaitin.com>
2026-06-03 04:17:14 +00:00
parent ae4de8a116
commit 80b4718568
4 changed files with 1639 additions and 0 deletions
@@ -0,0 +1,373 @@
 # CodePlay 系统架构
 ## 系统概览
 CodePlay 采用分层架构设计，将解析、转换、生成和验证流程分离，确保系统的可扩展性和可维护性。
 ## 架构图
 ```mermaid
 graph TB
    subgraph "客户端层"
        Web[Web 界面]
        CLI[CLI 工具]
        API[API 客户端]
    end
    subgraph "API 层 - CodePlay.Web"
        Controllers[API 控制器]
        Middleware[中间件]
    end
    subgraph "核心层 - CodePlay.Core"
        ConversionService[转换服务]
        subgraph "解析器"
            CSharpParser[C# 解析器]
            JavaParser[Java 解析器]
            CppParser[C++ 解析器]
        end
        subgraph "转换器"
            CSharpJava[C#→Java]
            JavaCSharp[Java→C#]
            CSharpCpp[C#→C++]
            CppCSharp[C++→C#]
            JavaCpp[Java→C++]
            CppJava[C++→Java]
        end
        subgraph "生成器"
            JavaGen[Java 生成器]
            CSharpGen[C# 生成器]
            CppGen[C++ 生成器]
        end
        subgraph "验证器"
            CSharpValidator[C# 验证器]
            JavaValidator[Java 验证器]
            CppValidator[C++ 验证器]
        end
    end
    subgraph "数据层"
        Models[数据模型]
        Storage[存储服务]
    end
    Web --> Controllers
    CLI --> Controllers
    API --> Controllers
    Controllers --> ConversionService
    ConversionService --> CSharpParser
    ConversionService --> JavaParser
    ConversionService --> CppParser
    ConversionService --> CSharpJava
    ConversionService --> JavaCSharp
    ConversionService --> JavaGen
    ConversionService --> CSharpValidator
    ConversionService --> JavaValidator
 ```
 ## 技术栈
 ### 后端框架
 | 组件 | 技术选型 | 说明 |
 |------|---------|------|
 | 主要语言 | C# | .NET 8.0 |
 | Web 框架 | ASP.NET Core | Web API + MVC |
 | 测试框架 | xUnit | 单元测试和集成测试 |
 ### 核心依赖
 | 库 | 版本 | 用途 |
 |---|------|------|
 | Microsoft.CodeAnalysis.CSharp (Roslyn) | 4.8.0 | C# 代码解析 |
 | TreeSitter | 1.0.0 | 多语言解析支持 |
 ### 解析器技术
 | 语言 | 解析器 | 状态 |
 |------|--------|------|
 | C# | Roslyn | ✅ 已实现 |
 | Java | TreeSitter/Text Processing | 🔄 计划中 |
 | C++ | TreeSitter/libclang | 🔄 计划中 |
 ## 目录结构
 ```
 /workspace/
 ├── CodePlay.sln                 # 解决方案文件
 ├── CodePlay.Core/               # 核心类库
 │   ├── Common/                  # 公共类型
 │   │   └── Enums.cs             # 枚举定义
 │   ├── Models/                  # 数据模型
 │   │   ├── ConversionModels.cs  # 转换相关模型
 │   │   └── ProjectModels.cs     # 项目相关模型
 │   ├── Interfaces/              # 接口定义
 │   │   └── IInterfaces.cs       # 核心接口
 │   ├── Parsers/                 # 解析器
 │   │   ├── BaseParser.cs        # 解析器基类
 │   │   └── CSharpParser.cs      # C# 解析器
 │   ├── Converters/              # 转换器
 │   │   ├── CSharpToJavaConverter.cs
 │   │   ├── CSharpToJavaStrategy.cs
 │   │   └── JavaCodeGenerator.cs
 │   └── Services/                # 服务层
 │       └── ConversionService.cs
 ├── CodePlay.Web/                # Web API 项目
 │   ├── Controllers/             # API 控制器
 │   │   ├── ConversionController.cs
 │   │   └── WeatherForecastController.cs
 │   └── Program.cs               # 入口文件
 ├── CodePlay.CLI/                # CLI 工具
 │   ├── Commands/                # 命令定义
 │   └── Program.cs               # 入口文件
 └── CodePlay.Tests/              # 测试项目
    ├── Parsers/                 # 解析器测试
    │   └── CSharpParserTests.cs
    └── Converters/              # 转换器测试
        └── CSharpToJavaConverterTests.cs
 ```
 ## 核心组件说明
 ### 1. 解析器（Parsers）
 负责将源代码解析为抽象语法树（AST）。
 **接口**：`IParser`
 ```csharp
 public interface IParser
 {
    Task<SyntaxTree> ParseAsync(string sourceCode, CancellationToken cancellationToken = default);
 }
 ```
 **实现**：
 - `CSharpParser` - 基于 Roslyn 实现 C# 代码解析
 - 支持提取注释、文档字符串、类、方法、属性等
 ### 2. 转换器（Converters）
 负责将源语言的 AST 转换为目标语言的 AST。
 **接口**：`IConverter`
 ```csharp
 public interface IConverter
 {
    Task<ConversionResult> ConvertAsync(
        SyntaxTree syntaxTree, 
        LanguageType targetLanguage, 
        ConversionOptions? options = null, 
        CancellationToken cancellationToken = default);
 }
 ```
 **实现**：
 - `CSharpToJavaConverter` - C# → Java 转换
 - 使用策略模式：`CSharpToJavaStrategy`
 ### 3. 代码生成器（Generators）
 负责从 AST 生成目标语言的源代码。
 **接口**：`ICodeGenerator`
 ```csharp
 public interface ICodeGenerator
 {
    string Generate(SyntaxTree syntaxTree);
 }
 ```
 **实现**：
 - `JavaCodeGenerator` - Java 代码生成
 - 支持格式化、缩进处理、文档生成
 ### 4. 转换服务（ConversionService）
 提供统一的转换入口，协调解析、转换、生成和验证流程。
 ```csharp
 public class ConversionService
 {
    public async Task<ConversionResult> ConvertAsync(
        ConversionRequest request, 
        CancellationToken cancellationToken = default);
 }
 ```
 ## 数据流
 ### 转换流程
 ```
 1. 接收请求 (ConversionRequest)
   ↓
 2. 解析源代码 → SyntaxTree
   ↓
 3. 转换 AST → Converted SyntaxTree
   ↓
 4. 生成代码 → Target Code
   ↓
 5. 编译验证 → ValidationResult
   ↓
 6. 返回结果 (ConversionResult)
 ```
 ### 核心数据模型
 **ConversionRequest** - 转换请求
 ```csharp
 - SourceCode: string
 - SourceLanguage: LanguageType
 - TargetLanguage: LanguageType
 - ValidationRounds: int (1-3)
 - Options: ConversionOptions
 ```
 **ConversionResult** - 转换结果
 ```csharp
 - Success: bool
 - TransformedCode: string
 - Report: ConversionReport
 - Warnings: List<ConversionWarning>
 - ValidationSummary: ValidationSummary
 ```
 **SyntaxTree** - 语法树
 ```csharp
 - Language: LanguageType
 - Root: SyntaxNode
 - Comments: List<SyntaxComment>
 - Documentation: List<SyntaxDocumentation>
 ```
 ## API 设计
 ### REST API 端点
 **POST /api/conversion** - 执行代码转换
 请求示例：
 ```json
 {
  "sourceCode": "public class Test { }",
  "sourceLanguage": 1,
  "targetLanguage": 2,
  "validationRounds": 2
 }
 ```
 响应示例：
 ```json
 {
  "success": true,
  "transformedCode": "public class Test { }",
  "report": {
    "linesConverted": 1,
    "classesConverted": 1,
    "methodsConverted": 0
  }
 }
 ```
 **GET /api/conversion/supported** - 获取支持的转换列表
 **GET /api/conversion/supported/{source}/{target}** - 检查是否支持指定转换
 ## 扩展性设计
 ### 添加新的语言支持
 1. 在 `LanguageType` 枚举中添加新语言
 2. 实现 `IParser` 接口创建新解析器
 3. 实现 `ICodeGenerator` 接口创建新生成器
 4. 实现 `IConversionStrategy` 接口创建转换策略
 5. 在 `ConversionService` 中注册
 ### 添加新的转换对
 1. 创建新的 `IConverter` 实现
 2. 创建对应的 `IConversionStrategy` 实现
 3. 在 `ConversionService` 构造函数中注册
 ## 验证流程
 ### 编译验证器（Compiler Validator）
 **接口**：`ICompilerValidator`
 ```csharp
 public interface ICompilerValidator
 {
    Task<ValidationResult> ValidateAsync(
        string code, 
        LanguageType language, 
        CancellationToken cancellationToken = default);
 }
 ```
 ### 自动修复引擎（Auto Fix Engine）
 **接口**：`IAutoFixEngine`
 ```csharp
 public interface IAutoFixEngine
 {
    Task<FixResult> FixAsync(
        string code, 
        List<CompilationError> errors, 
        int round, 
        CancellationToken cancellationToken = default);
 }
 ```
 **修复轮次策略**：
 1. 第 1 轮：修复导入/using 语句
 2. 第 2 轮：修复类型映射
 3. 第 3 轮：修复 API 调用
 ## 配置管理
 ### 转换选项（ConversionOptions）
 ```csharp
 - KeepComments: bool
 - KeepDocStrings: bool
 - KeepFormatting: bool
 - IndentSize: int
 - UseTabs: bool
 - EnableAutoFix: bool
 ```
 ## 错误处理
 ### 错误分类
 | 类型 | 错误码前缀 | 说明 |
 |------|----------|------|
 | 解析错误 | ERR_PARSE_* | 源代码语法错误 |
 | 转换错误 | ERR_CONVERT_* | 转换过程错误 |
 | 验证错误 | ERR_VALIDATE_* | 编译验证失败 |
 | 系统错误 | ERR_SYSTEM_* | 内部系统错误 |
 ## 日志系统
 使用结构化日志记录关键操作：
 - 转换开始/结束
 - 验证结果
 - 错误详情
 - 性能指标
 ## 安全考虑
 - 输入验证：检查源代码长度、语言类型
 - 资源限制：限制单次转换的最大代码量
 - 超时控制：设置转换和验证的超时时间
 - 错误信息：不暴露内部实现细节
@@ -0,0 +1,519 @@
 # CodePlay 开发者指南
 ## 开发环境要求
 ### 必需工具
 | 工具 | 版本 | 说明 |
 |------|------|------|
 | .NET SDK | 8.0+ | 开发和构建工具 |
 | IDE | 推荐 Visual Studio 2022 / Rider | C# 开发环境 |
 | Git | 任意版本 | 版本控制 |
 ### 可选工具
 | 工具 | 说明 |
 |------|------|
 | Swagger UI | 访问 `http://localhost:5000/swagger` 查看 API 文档 |
 | Postman | API 测试工具 |
 ## 快速开始
 ### 1. 克隆仓库
 ```bash
 cd /workspace
 ```
 ### 2. 还原依赖
 ```bash
 dotnet restore CodePlay.sln
 ```
 ### 3. 构建项目
 ```bash
 dotnet build CodePlay.sln
 ```
 ### 4. 运行测试
 ```bash
 dotnet test CodePlay.Tests/CodePlay.Tests.csproj --logger "console;verbosity=normal"
 ```
 ### 5. 启动 Web API
 ```bash
 dotnet run --project CodePlay.Web/CodePlay.Web.csproj
 ```
 默认监听地址：
 - HTTP: `http://localhost:5000`
 - HTTPS: `https://localhost:5001`
 ### 6. 启动 CLI（开发中）
 ```bash
 dotnet run --project CodePlay.CLI/CodePlay.CLI.csproj -- --help
 ```
 ## 项目结构
 参见 [ARCHITECTURE.md](./ARCHITECTURE.md) 了解详细架构。
 ## 代码规范
 ### 命名约定
 #### C# 类和接口
 - **类名**: PascalCase
 - **接口名**: IPascalCase
 - **方法名**: PascalCase
 - **属性名**: PascalCase
 - **私有字段**: _camelCase
 - **局部变量**: camelCase
 - **常量**: PASCAL_CASE
 #### 文件和目录
 - **文件名**: PascalCase.cs
 - **目录名**: PascalCase
 ### 注释规范
 #### 文档注释
 所有公共成员必须有 XML 文档注释：
 ```csharp
 /// <summary>
 /// 方法的功能描述
 /// </summary>
 /// <param name="param">参数说明</param>
 /// <returns>返回值说明</returns>
 public string Method(string param)
 ```
 #### 行内注释
 ```csharp
 // 使用单行注释解释复杂的逻辑
 var result = CalculateComplexLogic(); // 这里是为什么需要这样计算
 /*
 多行注释用于说明代码块的整体逻辑
 */
 ```
 ### 异常处理
 #### 抛出异常
 ```csharp
 if (string.IsNullOrWhiteSpace(sourceCode))
 {
    throw new ArgumentException("Source code is required", nameof(sourceCode));
 }
 ```
 #### 捕获异常
 ```csharp
 try
 {
    // 可能抛出异常的代码
 }
 catch (Exception ex) when (!Debugger.IsAttached)
 {
    // 记录日志
    _logger.LogError(ex, "操作失败");
    throw;
 }
 ```
 ### 异步编程
 #### 异步方法命名
 - 异步方法以 `Async` 结尾
 - 返回 `Task` 或 `Task<T>`
 ```csharp
 public async Task<ConversionResult> ConvertAsync(
    ConversionRequest request, 
    CancellationToken cancellationToken)
 ```
 #### 取消令牌
 所有异步操作都应该支持取消：
 ```csharp
 public async Task<Result> ExecuteAsync(CancellationToken cancellationToken = default)
 {
    await DoWorkAsync(cancellationToken);
 }
 ```
 ### 依赖注入
 遵循 ASP.NET Core 的依赖注入模式：
 ```csharp
 // 注册服务
 builder.Services.AddSingleton<ConversionService>();
 builder.Services.AddScoped<IConverter, CSharpToJavaConverter>();
 // 注入到类
 public class MyService
 {
    private readonly ConversionService _service;
    public MyService(ConversionService service)
    {
        _service = service;
    }
 }
 ```
 ## 测试指南
 ### 测试项目结构
 ```
 CodePlay.Tests/
 ├── Parsers/
 │   └── CSharpParserTests.cs
 └── Converters/
    └── CSharpToJavaConverterTests.cs
 ```
 ### 单元测试最佳实践
 #### 测试类命名
 - `{被测试类}Tests` 格式
 #### 测试方法命名
 - `{方法名}_{场景}_{期望结果}` 格式
 ```csharp
 [Fact]
 public void ParseAsync_SimpleClass_ShouldParseSuccessfully()
 ```
 #### 使用 Arrange-Act-Assert 模式
 ```csharp
 [Fact]
 public void Test_Method()
 {
    // Arrange（准备）
    var parser = new CSharpParser();
    var code = "public class Test { }";
    // Act（执行）
    var result = await parser.ParseAsync(code);
    // Assert（断言）
    Assert.NotNull(result);
    Assert.Equal(LanguageType.CSharp, result.Language);
 }
 ```
 ### 运行测试
 #### 运行所有测试
 ```bash
 dotnet test
 ```
 #### 运行特定测试类
 ```bash
 dotnet test --filter "FullyQualifiedName~CSharpParserTests"
 ```
 #### 查看详细信息
 ```bash
 dotnet test --logger "console;verbosity=detailed"
 ```
 ## 调试技巧
 ### 日志调试
 使用 `ILogger` 进行调试：
 ```csharp
 _logger.LogDebug("当前状态：{State}", state);
 _logger.LogInformation("操作成功完成");
 _logger.LogWarning("潜在问题：{Issue}", issue);
 _logger.LogError(ex, "操作失败：{Error}", error);
 ```
 ### 断点调试
 在 IDE 中设置断点：
 1. 在代码行号左侧点击设置断点
 2. 按 F5 启动调试
 3. 使用 F10/F11 单步执行
 ### 调试输出
 使用 `Debug.WriteLine` 输出调试信息：
 ```csharp
 Debug.WriteLine($"当前节点类型：{node.Type}");
 ```
 ## 添加新的转换支持
 ### 1. 添加语言枚举
 在 `Enums.cs` 中添加：
 ```csharp
 public enum LanguageType
 {
    // ...现有语言
    Python = 4  // 新语言
 }
 ```
 ### 2. 实现解析器
 创建 `{Language}Parser.cs`：
 ```csharp
 public class PythonParser : BaseParser
 {
    public override LanguageType SupportedLanguage => LanguageType.Python;
    public override Task<SyntaxTree> ParseAsync(string sourceCode, CancellationToken cancellationToken)
    {
        // 实现解析逻辑
    }
 }
 ```
 ### 3. 实现转换器
 创建 `{Source}To{Target}Converter.cs`：
 ```csharp
 public class CSharpToPythonConverter : IConverter
 {
    public async Task<ConversionResult> ConvertAsync(
        SyntaxTree syntaxTree, 
        LanguageType targetLanguage, 
        ConversionOptions? options = null, 
        CancellationToken cancellationToken = default)
    {
        // 实现转换逻辑
    }
 }
 ```
 ### 4. 实现生成器
 创建 `{Language}CodeGenerator.cs`：
 ```csharp
 public class PythonCodeGenerator : ICodeGenerator
 {
    public string Generate(SyntaxTree syntaxTree)
    {
        // 实现代码生成
    }
 }
 ```
 ### 5. 注册服务
 在 `ConversionService` 中注册：
 ```csharp
 public ConversionService()
 {
    RegisterConverter(LanguageType.CSharp, LanguageType.Python, new CSharpToPythonConverter());
 }
 ```
 ## 添加新的 API 端点
 ### 1. 创建控制器
 ```csharp
 [ApiController]
 [Route("api/[controller]")]
 public class ProjectController : ControllerBase
 {
    [HttpGet("{id}")]
    public async Task<ActionResult<Project>> GetProject(string id)
    {
        // 实现逻辑
    }
 }
 ```
 ### 2. 配置路由
 在 `Program.cs` 中：
 ```csharp
 app.MapControllers();
 ```
 ### 3. 添加 Swagger 文档
 ```csharp
 builder.Services.AddSwaggerGen(c =>
 {
    c.SwaggerDoc("v1", new OpenApiInfo
    {
        Title = "CodePlay API",
        Version = "v1"
    });
 });
 ```
 ## 常见问题
 ### Q: 编译失败
 **A**: 检查 .NET SDK 版本：
 ```bash
 dotnet --version
 ```
 应该是 8.0 或更高版本。
 ### Q: 测试失败
 **A**: 查看测试输出，确认是否是因为：
 - 依赖未还原
 - 代码变更导致测试用例失效
 - 环境问题
 ### Q: Web API 无法启动
 **A**: 检查端口占用情况：
 ```bash
 netstat -ano | findstr :5000
 ```
 ### Q: 转换器不支持某语言对
 **A**: 检查 `ConversionService` 中是否已注册该转换对：
 ```csharp
 var supported = service.GetSupportedConversions();
 ```
 ## Git 工作流
 ### 分支命名
 - 功能分支：`{YYMMDD}-feat-{feature-name}`
 - 修复分支：`{YYMMDD}-fix-{issue-id}`
 ### 提交消息
 使用以下格式：
 ```
 feat: 添加新功能
 fix: 修复问题
 docs: 更新文档
 test: 添加测试
 refactor: 代码重构
 chore: 日常维护
 ```
 ### 推送代码
 ```bash
 git add .
 git commit -m "feat: 描述你的更改"
 git push origin {branch-name}
 ```
 ## 发布流程
 ### 1. 更新版本号
 在所有 `.csproj` 文件中更新版本号。
 ### 2. 生成 NuGet 包
 ```bash
 dotnet pack CodePlay.Core/CodePlay.Core.csproj -c Release
 ```
 ### 3. 创建 Docker 镜像（Web 服务）
 ```bash
 docker build -t codeplay-web:latest -f CodePlay.Web/Dockerfile .
 ```
 ### 4. 生成发布说明
 在 GitHub Releases 中创建新版本，包含：
 - 版本号
 - 更新内容
 - 已知问题
 - 升级指南
 ## 性能优化建议
 1. **缓存**：缓存已解析的语法树
 2. **并行处理**：对多个文件使用并行转换
 3. **内存管理**：及时释放大对象
 4. **异步 I/O**：使用异步文件读写
 ## 安全建议
 1. **输入验证**：检查所有输入参数
 2. **资源限制**：限制单次转换的代码量
 3. **超时控制**：设置操作超时时间
 4. **错误处理**：不暴露敏感信息
 ## 资源链接
 - [.NET 文档](https://docs.microsoft.com/en-us/dotnet/)
 - [ASP.NET Core 文档](https://docs.microsoft.com/en-us/aspnet/core/)
 - [xUnit 测试框架](https://xunit.net/)
 - [Swagger 文档](https://swagger.io/docs/)
 ## 贡献指南
 ### 提交代码前检查清单
 - [ ] 代码通过编译
 - [ ] 所有测试通过
 - [ ] 代码格式符合规范
 - [ ] 添加了必要的注释
 - [ ] 更新了相关文档
 - [ ] 提交了任务列表（如适用）
 ### 代码审查要点
 1. 功能是否正确实现
 2. 代码是否可读
 3. 是否有足够的测试覆盖
 4. 是否遵循了架构设计
 5. 是否有性能问题
 ## 联系方式
 - 项目仓库：[GitHub](https://github.com/your-org/codeplay)
 - 问题反馈：[Issues](https://github.com/your-org/codeplay/issues)
@@ -0,0 +1,116 @@
 # CodePlay 项目文档索引
 ## 项目概述
 CodePlay 是一个代码转换工具平台，支持 C#、Java、C++ 三种编程语言之间的双向转换。平台提供 Web 界面、CLI 工具和 API 接口三种使用方式。
 ## 文档结构
 | 文档名称 | 说明 |
 |---------|------|
 | [ARCHITECTURE.md](./ARCHITECTURE.md) | 系统架构设计文档 |
 | [INTERFACES.md](./INTERFACES.md) | 接口和类型定义文档 |
 | [DEVELOPER_GUIDE.md](./DEVELOPER_GUIDE.md) | 开发者指南 |
 ## 核心模块
 ### 1. CodePlay.Core - 核心转换引擎
 [查看 Core 模块文档](./modules/CodePlay.Core.md)
 **主要功能**：
 - 代码解析（Parser）
 - 代码转换（Converter）
 - 代码生成（Generator）
 - 编译验证（Validator）
 **命名空间**：
 - `CodePlay.Core.Common` - 公共类型和枚举
 - `CodePlay.Core.Models` - 数据模型
 - `CodePlay.Core.Interfaces` - 核心接口定义
 - `CodePlay.Core.Parsers` - 语言解析器
 - `CodePlay.Core.Converters` - 代码转换器
 - `CodePlay.Core.Generators` - 代码生成器
 - `CodePlay.Core.Services` - 服务层
 - `CodePlay.Core.Validators` - 验证器
 ### 2. CodePlay.Web - Web API 服务
 [查看 Web 模块文档](./modules/CodePlay.Web.md)
 **主要功能**：
 - REST API 端点
 - Swagger 文档
 - 依赖注入配置
 **命名空间**：
 - `CodePlay.Web.Controllers` - API 控制器
 ### 3. CodePlay.CLI - 命令行工具
 [查看 CLI 模块文档](./modules/CodePlay.CLI.md)
 **主要功能**：
 - 命令行参数解析
 - 批量文件转换
 - 配置管理
 **命名空间**：
 - `CodePlay.CLI.Commands` - 命令定义
 - `CodePlay.CLI.Services` - CLI 服务
 ### 4. CodePlay.Tests - 测试项目
 [查看测试模块文档](./modules/CodePlay.Tests.md)
 **主要功能**：
 - 单元测试（xUnit）
 - 集成测试
 - 测试用例库
 **命名空间**：
 - `CodePlay.Tests.Parsers` - 解析器测试
 - `CodePlay.Tests.Converters` - 转换器测试
 ## 快速开始
 ### 构建项目
 ```bash
 dotnet build CodePlay.sln
 ```
 ### 运行测试
 ```bash
 dotnet test CodePlay.Tests/CodePlay.Tests.csproj
 ```
 ### 启动 Web API
 ```bash
 dotnet run --project CodePlay.Web/CodePlay.Web.csproj
 ```
 ## 支持的转换
 | 源语言 | 目标语言 | 状态 |
 |-------|---------|------|
 | C# | Java | ✅ 已实现 |
 | Java | C# | 🔄 计划中 |
 | C# | C++ | 🔄 计划中 |
 | C++ | C# | 🔄 计划中 |
 | Java | C++ | 🔄 计划中 |
 | C++ | Java | 🔄 计划中 |
 ## 项目状态
 - **当前版本**: 0.1.0-alpha
 - **开发阶段**: MVP 开发中
 - **测试覆盖率**: 13 个测试用例，全部通过
 ## 相关链接
 - [需求文档](../specs/codeplay-conversion-platform/requirements.md)
 - [设计文档](../specs/codeplay-conversion-platform/design.md)
 - [任务列表](../specs/codeplay-conversion-platform/tasklist.md)
@@ -0,0 +1,631 @@
 # CodePlay 接口和类型定义
 ## 命名空间概览
 ### CodePlay.Core.Common
 包含公共枚举类型。
 ### CodePlay.Core.Models
 包含数据模型类。
 ### CodePlay.Core.Interfaces
 包含核心接口定义。
 ## 枚举类型
 ### LanguageType
 定义支持的编程语言。
 ```csharp
 public enum LanguageType
 {
    None = 0,          // 未指定
    CSharp = 1,        // C#
    Java = 2,          // Java
    CPlusPlus = 3      // C++
 }
 ```
 ### ConversionStatus
 定义转换任务的状态。
 ```csharp
 public enum ConversionStatus
 {
    Pending = 0,              // 等待中
    InProgress = 1,           // 进行中
    Completed = 2,            // 已完成
    PartiallyCompleted = 3,   // 部分完成（需要人工检查）
    Failed = 4,               // 失败
    Cancelled = 5             // 已取消
 }
 ```
 ### ProjectStatus
 定义项目的状态。
 ```csharp
 public enum ProjectStatus
 {
    InProgress = 0,      // 进行中
    Completed = 1,       // 已完成
    Verified = 2,        // 已验证
    Archived = 3         // 已归档
 }
 ```
 ### ValidationResult
 定义验证结果的状态。
 ```csharp
 public enum ValidationResult
 {
    NotValidated = 0,                    // 未验证
    Passed = 1,                          // 验证通过
    Failed_NeedsManualReview = 2,        // 验证失败 - 需要人工检查
    Failed_CompilationError = 3,         // 验证失败 - 编译错误
    Failed_TestFailed = 4                // 验证失败 - 测试失败
 }
 ```
 ### SyntaxNodeType
 定义语法节点的类型。
 ```csharp
 public enum SyntaxNodeType
 {
    Unknown = 0,
    CompilationUnit = 1,      // 编译单元
    Namespace = 2,            // 命名空间
    Class = 3,                // 类
    Interface = 4,            // 接口
    Method = 5,               // 方法
    Property = 6,             // 属性
    Field = 7,                // 字段
    Constructor = 8,          // 构造函数
    Statement = 9,            // 语句
    Expression = 10,          // 表达式
    Type = 11,                // 类型
    Parameter = 12,           // 参数
    Comment = 13,             // 注释
    DocumentationComment = 14 // 文档注释
 }
 ```
 ### CommentType
 定义注释的类型。
 ```csharp
 public enum CommentType
 {
    SingleLine = 0,           // 单行注释 //
    MultiLine = 1,            // 多行注释 /* */
    XmlDoc = 2,               // XML 文档注释 ///
    JavaDoc = 3,              // JavaDoc /** */
    Doxygen = 4               // Doxygen /// 或 /** */
 }
 ```
 ### DocFormat
 定义文档格式。
 ```csharp
 public enum DocFormat
 {
    XmlDoc = 0,      // C# XML Doc
    JavaDoc = 1,     // Java JavaDoc
    Doxygen = 2      // C++ Doxygen
 }
 ```
 ### IssueType
 定义转换问题的类型。
 ```csharp
 public enum IssueType
 {
    UnconvertibleSyntax = 0,       // 不可转换语法
    TypeMappingWarning = 1,        // 类型映射警告
    ApiDifference = 2,             // API 差异
    SemanticDifference = 3,        // 语义差异
    PerformanceConsideration = 4   // 性能考虑
 }
 ```
 ### LogLevel
 定义日志级别。
 ```csharp
 public enum LogLevel
 {
    Info = 0,
    Warning = 1,
    Error = 2,
    Debug = 3
 }
 ```
 ## 核心模型类
 ### ConversionRequest
 转换请求模型。
 ```csharp
 public class ConversionRequest
 {
    public string SourceCode { get; set; }
    public LanguageType SourceLanguage { get; set; }
    public LanguageType TargetLanguage { get; set; }
    public string? ProjectId { get; set; }
    public int ValidationRounds { get; set; } = 2;
    public ConversionOptions? Options { get; set; }
 }
 ```
 ### ConversionOptions
 转换配置选项。
 ```csharp
 public class ConversionOptions
 {
    public bool KeepComments { get; set; } = true;
    public bool KeepDocStrings { get; set; } = true;
    public bool KeepFormatting { get; set; } = true;
    public int IndentSize { get; set; } = 4;
    public bool UseTabs { get; set; } = false;
    public bool EnableAutoFix { get; set; } = true;
 }
 ```
 ### ConversionResult
 转换结果模型。
 ```csharp
 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 string? ErrorMessage { get; set; }
 }
 ```
 ### ConversionReport
 转换报告。
 ```csharp
 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 List<TodoItem> TodoItems { get; set; }
 }
 ```
 ### ConversionWarning
 转换警告。
 ```csharp
 public class ConversionWarning
 {
    public string Code { get; set; }
    public string Message { get; set; }
    public int LineNumber { get; set; }
    public int ColumnNumber { get; set; }
    public string? Suggestion { get; set; }
 }
 ```
 ### ValidationSummary
 验证摘要。
 ```csharp
 public class ValidationSummary
 {
    public bool Passed { get; set; }
    public int RoundsExecuted { get; set; }
    public bool NeedsManualReview { get; set; }
    public List<CompilationError> CompilationErrors { get; set; }
    public List<string> ValidationLog { get; set; }
 }
 ```
 ### ConversionIssue
 转换问题。
 ```csharp
 public class ConversionIssue
 {
    public IssueType Type { get; set; }
    public string Description { get; set; }
    public int LineNumber { get; set; }
    public string? OriginalCode { get; set; }
    public string? Suggestion { get; set; }
 }
 ```
 ### TransformationLog
 转换日志。
 ```csharp
 public class TransformationLog
 {
    public DateTime Timestamp { get; set; }
    public string Operation { get; set; }
    public string Details { get; set; }
    public LogLevel Level { get; set; }
 }
 ```
 ### TodoItem
 TODO 项（用于不可转换的语法）。
 ```csharp
 public class TodoItem
 {
    public string Description { get; set; }
    public int LineNumber { get; set; }
    public string OriginalSyntax { get; set; }
    public string WhyNotDirect { get; set; }
    public string RecommendedAlternative { get; set; }
    public string? ReferenceLocation { get; set; }
 }
 ```
 ### CompilationError
 编译错误。
 ```csharp
 public class CompilationError
 {
    public string ErrorId { get; set; }
    public string Message { get; set; }
    public int LineNumber { get; set; }
    public int ColumnNumber { get; set; }
    public bool IsError { get; set; } = true;
 }
 ```
 ### Project
 项目模型。
 ```csharp
 public class Project
 {
    public string Id { get; set; } = Guid.NewGuid().ToString("N");
    public string Name { get; set; }
    public LanguageType SourceLanguage { get; set; }
    public LanguageType TargetLanguage { get; set; }
    public ProjectStatus Status { get; set; }
    public DateTime CreatedAt { get; set; }
    public DateTime UpdatedAt { get; set; }
    public List<ConversionTask> Tasks { get; set; }
    public ProjectConfiguration? Configuration { get; set; }
 }
 ```
 ### ConversionTask
 转换任务。
 ```csharp
 public class ConversionTask
 {
    public string Id { get; set; } = Guid.NewGuid().ToString("N");
    public string SourceFilePath { get; set; }
    public string TargetFilePath { get; set; }
    public string? SourceCode { get; set; }
    public string? TransformedCode { get; set; }
    public ConversionStatus Status { get; set; }
    public DateTime CreatedAt { get; set; }
    public DateTime? CompletedAt { get; set; }
    public ConversionResult? Result { get; set; }
 }
 ```
 ### ProjectConfiguration
 项目配置。
 ```csharp
 public class ProjectConfiguration
 {
    public int ValidationRounds { get; set; } = 2;
    public bool EnableAutoFix { get; set; } = true;
    public bool KeepComments { get; set; } = true;
    public bool KeepDocStrings { get; set; } = true;
    public int IndentSize { get; set; } = 4;
    public string? OutputDirectory { get; set; }
 }
 ```
 ## 语法树模型
 ### SyntaxTree
 语法树模型。
 ```csharp
 public class SyntaxTree
 {
    public LanguageType Language { get; set; }
    public SyntaxNode Root { get; set; }
    public string? SourceFilePath { get; set; }
    public string? SourceCode { get; set; }
    public List<SyntaxComment> Comments { get; set; }
    public List<SyntaxDocumentation> Documentation { get; set; }
 }
 ```
 ### SyntaxNode
 语法节点。
 ```csharp
 public class SyntaxNode
 {
    public SyntaxNodeType Type { get; set; }
    public string Text { get; set; }
    public List<SyntaxNode> Children { get; set; }
    public Dictionary<string, object?> Metadata { get; set; }
    public SyntaxNode? Parent { get; set; }
    public bool IsUnconvertible { get; set; }
    public string? TodoDescription { get; set; }
 }
 ```
 ### SyntaxComment
 语法注释。
 ```csharp
 public class SyntaxComment
 {
    public CommentType Type { get; set; }
    public string Text { get; set; }
    public int LineNumber { get; set; }
 }
 ```
 ### SyntaxDocumentation
 语法文档。
 ```csharp
 public class SyntaxDocumentation
 {
    public string ElementName { get; set; }
    public string Content { get; set; }
    public DocFormat Format { get; set; }
 }
 ```
 ## 核心接口
 ### IParser
 语言解析器接口。
 ```csharp
 public interface IParser
 {
    Task<SyntaxTree> ParseAsync(string sourceCode, CancellationToken cancellationToken = default);
 }
 ```
 **实现**：
 - `BaseParser` - 抽象基类
 - `CSharpParser` - C# 解析器
 ### IConverter
 代码转换器接口。
 ```csharp
 public interface IConverter
 {
    Task<ConversionResult> ConvertAsync(
        SyntaxTree syntaxTree, 
        LanguageType targetLanguage, 
        ConversionOptions? options = null, 
        CancellationToken cancellationToken = default);
 }
 ```
 **实现**：
 - `CSharpToJavaConverter` - C# → Java 转换器
 ### ICodeGenerator
 代码生成器接口。
 ```csharp
 public interface ICodeGenerator
 {
    string Generate(SyntaxTree syntaxTree);
 }
 ```
 **实现**：
 - `JavaCodeGenerator` - Java 代码生成器
 ### IConversionStrategy
 转换策略接口。
 ```csharp
 public interface IConversionStrategy
 {
    LanguageType SourceLanguage { get; }
    LanguageType TargetLanguage { get; }
    SyntaxNode ConvertNode(SyntaxNode node, ConversionContext context);
    string MapType(string sourceType);
 }
 ```
 **实现**：
 - `CSharpToJavaStrategy` - C# → Java 转换策略
 ### ICompilerValidator
 编译验证器接口。
 ```csharp
 public interface ICompilerValidator
 {
    Task<ValidationResult> ValidateAsync(string code, LanguageType language, CancellationToken cancellationToken = default);
 }
 ```
 ### IAutoFixEngine
 自动修复引擎接口。
 ```csharp
 public interface IAutoFixEngine
 {
    Task<FixResult> FixAsync(string code, List<CompilationError> errors, int round, CancellationToken cancellationToken = default);
 }
 ```
 ## 辅助类
 ### TypeMapping
 类型映射。
 ```csharp
 public class TypeMapping
 {
    public string SourceType { get; set; }
    public string TargetType { get; set; }
 }
 ```
 ### ConversionContext
 转换上下文。
 ```csharp
 public class ConversionContext
 {
    public LanguageType SourceLanguage { get; set; }
    public LanguageType TargetLanguage { get; set; }
    public ConversionOptions? Options { get; set; }
    public List<ConversionIssue> Issues { get; set; }
    public List<TodoItem> TodoItems { get; set; }
    public List<TransformationLog> Logs { get; set; }
 }
 ```
 ### FixResult
 修复结果。
 ```csharp
 public class FixResult
 {
    public bool CanFix { get; set; }
    public string? FixedCode { get; set; }
    public string? FixDescription { get; set; }
    public List<CompilationError> RemainingErrors { get; set; }
 }
 ```
 ### CompilationResult
 编译结果。
 ```csharp
 public class CompilationResult
 {
    public bool Success { get; set; }
    public string Output { get; set; }
    public List<CompilationError> Errors { get; set; }
    public List<CompilationError> Warnings { get; set; }
 }
 ```
 ## API DTO 类
 ### LanguagePairDto
 语言对数据传输对象。
 ```csharp
 public class LanguagePairDto
 {
    public string SourceLanguage { get; set; }
    public string TargetLanguage { get; set; }
    public bool Supported { get; set; }
 }
 ```
 ## 使用示例
 ### 创建转换请求
 ```csharp
 var request = new ConversionRequest
 {
    SourceCode = "public class Test { }",
    SourceLanguage = LanguageType.CSharp,
    TargetLanguage = LanguageType.Java,
    ValidationRounds = 2,
    Options = new ConversionOptions
    {
        KeepComments = true,
        KeepDocStrings = true
    }
 };
 ```
 ### 使用转换服务
 ```csharp
 var service = new ConversionService();
 var result = await service.ConvertAsync(request);
 if (result.Success)
 {
    Console.WriteLine(result.TransformedCode);
 }
 ```
 ### 检查转换支持
 ```csharp
 if (service.IsConversionSupported(LanguageType.CSharp, LanguageType.Java))
 {
    Console.WriteLine("C# to Java conversion is supported");
 }
 ```