codeplay/.monkeycode/docs/ARCHITECTURE.md

# 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_* | 内部系统错误 |

## 日志系统

使用结构化日志记录关键操作：

- 转换开始/结束
- 验证结果
- 错误详情
- 性能指标

## 安全考虑

- 输入验证：检查源代码长度、语言类型
- 资源限制：限制单次转换的最大代码量
- 超时控制：设置转换和验证的超时时间
- 错误信息：不暴露内部实现细节