a_git_test/codeplay
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

feat: 创建 CodePlay 代码转换平台需求和技术设计文档

Browse Source 
Co-authored-by: monkeycode-ai <monkeycode-ai@chaitin.com>
This commit is contained in:
monkeycode-ai
2026-06-03 02:18:26 +00:00
parent 2eec296639
commit 9c7ba42e52
2 changed files with 414 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.monkeycode/specs/codeplay-conversion-platform/design.md
+262
View File
@@ -0,0 +1,262 @@
# 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/)
.monkeycode/specs/codeplay-conversion-platform/requirements.md
+152
View File
@@ -0,0 +1,152 @@
# Requirements Document
## Introduction
CodePlay 是一个代码转换工具平台，支持 C#、Java、C++ 三种编程语言之间的双向转换。平台提供 Web 界面、CLI 工具和 API 接口三种使用方式，主要服务于个人开发者和团队内部的代码迁移和多语言项目维护场景。转换后的代码会进行 1-3 轮自动编译和测试验证，确保转换质量。
## Glossary
- **CodePlay**: 代码转换工具平台名称
- **源语言**: 待转换的原始代码所使用的编程语言（C#、Java、C++）
- **目标语言**: 转换后代码所使用的编程语言（C#、Java、C++）
- **转换引擎**: 执行代码语法分析和转换的核心组件
- **验证轮次**: 对转换后代码进行编译/测试验证的迭代次数（1-3 轮）
- **不可转换语法**: 源语言特有的语法特性在目标语言中无直接等价实现（如 C# LINQ、Java Stream）
## Requirements
### Requirement 1: 代码转换功能
**User Story:** AS 开发者，I WANT 将源代码从一种语言自动转换到另一种语言，SO THAT 我可以进行代码迁移和多语言项目维护
#### Acceptance Criteria
1. WHEN 用户选择 C# 转 Java，CodePlay SHALL 调用 com.aspose.ms.jdk.NetFramework 类库作为转换基础
2. WHEN 用户选择 C# 转 C++，CodePlay SHALL 将 C#代码转换为等效的C++代码
3. WHEN 用户选择 Java 转 C#，CodePlay SHALL 将 Java代码转换为等效的C#代码
4. WHEN 用户选择 Java 转 C++，CodePlay SHALL 将 Java代码转换为等效的C++代码
5. WHEN 用户选择 C++ 转 C#，CodePlay SHALL 将 C++代码转换为等效的C#代码
6. WHEN 用户选择 C++ 转 Java，CodePlay SHALL 将 C++代码转换为等效的 Java 代码
7. WHILE 转换过程中遇到无法直接转换的语法，CodePlay SHALL 保留原代码并添加注释说明
8. WHILE 转换过程中遇到无法直接转换的语法，CodePlay SHALL 添加 TODO 详细说明和原代码逻辑解析及操作建议
9. WHILE 转换过程，CodePlay SHALL 保留源代码中的所有注释
10. WHILE 转换过程，CodePlay SHALL 保留源代码的格式结构
11. WHILE 转换过程，CodePlay SHALL 保留源代码中的文档字符串（XML Doc/JavaDoc/Doxygen）
12. THE CodePlay SHALL 支持完整的语法转换，包括泛型、Lambda 表达式、异步代码等高级特性
### Requirement 2: Web 界面
**User Story:** AS 开发者，I WANT 通过 Web 界面上传代码并查看转换结果，SO THAT 我可以方便地进行可视化的代码转换操作
#### Acceptance Criteria
1. WHEN 用户访问 Web 界面，CodePlay SHALL 提供代码输入编辑区域
2. WHEN 用户在 Web 界面选择源语言和目标语言，CodePlay SHALL 显示可选的编程语言组合
3. WHEN 用户点击转换按钮，CodePlay SHALL 执行代码转换并显示结果
4. WHILE 转换完成后，CodePlay SHALL 在 Web 界面展示转换后的代码
5. WHILE 转换完成后，CodePlay SHALL 在 Web 界面展示转换报告和验证结果
6. IF 转换过程中遇到不可转换语法，CodePlay SHALL 在 Web 界面高亮显示并展示 TODO 说明
7. WHILE 用户查看转换结果，CodePlay SHALL 提供代码对比视图（Diff View）
8. WHILE 用户在 Web 界面查看结果，CodePlay SHALL 提供下载转换后代码的功能
### Requirement 3: CLI 工具
**User Story:** AS 开发者，I WANT 通过命令行工具批量转换代码文件，SO THAT 我可以集成到本地开发工作流中
#### Acceptance Criteria
1. WHEN 用户在命令行执行 codeplay 命令，CodePlay SHALL 显示帮助信息和可用命令列表
2. WHEN 用户指定输入文件路径和输出文件路径，CodePlay SHALL 转换指定文件
3. WHEN 用户指定整个目录，CodePlay SHALL 递归转换目录下所有符合条件的源文件
4. WHILE 用户执行 CLI 命令，CodePlay SHALL 支持指定源语言和目标语言参数
5. WHILE 用户执行 CLI 命令，CodePlay SHALL 支持指定验证轮次参数（1-3 轮）
6. IF 转换成功，CodePlay SHALL 在命令行输出成功消息和转换统计信息
7. IF 转换失败，CodePlay SHALL 在命令行输出错误详情和建议
8. WHILE 转换过程中遇到不可转换语法，CodePlay SHALL 在命令行输出警告并列出文件位置
### Requirement 4: API 接口
**User Story:** AS 开发者，I WANT 通过 REST API 调用转换服务，SO THAT 我可以将转换功能集成到其他工具或系统中
#### Acceptance Criteria
1. WHEN 客户端发送 POST 请求到转换端点，CodePlay SHALL 接收包含源代码、源语言、目标语言的请求体
2. WHEN API 收到转换请求，CodePlay SHALL 返回包含转换后代码、转换报告、验证结果的响应
3. WHILE 客户端调用 API，CodePlay SHALL 支持异步任务模式，提供任务查询接口
4. IF API 请求参数不完整，CodePlay SHALL 返回 400 错误和详细的参数校验信息
5. IF API 请求处理超时，CodePlay SHALL 返回 504 错误和建议重试信息
6. WHILE 客户端调用 API，CodePlay SHALL 提供 API 认证机制（API Key）
### Requirement 5: 自动编译验证
**User Story:** AS 开发者，I WANT 转换后的代码自动进行编译验证，SO THAT 我可以确认转换结果的正确性
#### Acceptance Criteria
1. WHEN 代码转换完成，CodePlay SHALL 自动对转换后的代码进行编译验证
2. WHILE 编译失败，CodePlay SHALL 执行最多 3 轮自动修复和重试
3. WHILE 每轮验证失败，CodePlay SHALL 记录失败原因并尝试自动修复
4. IF 3 轮验证后仍然失败，CodePlay SHALL 标记转换结果为"需要人工检查"并输出详细错误报告
5. WHILE 验证通过，CodePlay SHALL 在报告中显示"验证通过"状态
6. WHILE 验证过程中，CodePlay SHALL 提供编译输出日志供用户查阅
### Requirement 6: 转换报告
**User Story:** AS 开发者，I WANT 查看详细的转换报告，SO THAT 我可以了解转换过程和需要人工处理的问题
#### Acceptance Criteria
1. WHEN 转换完成，CodePlay SHALL 生成转换报告
2. WHILE 生成报告，CodePlay SHALL 显示转换统计信息（转换行数、类数量、方法数量等）
3. WHILE 生成报告，CodePlay SHALL 列出所有不可转换语法的位置和说明
4. WHILE 生成报告，CodePlay SHALL 显示验证轮次和每轮的结果
5. WHILE 生成报告，CodePlay SHALL 提供需要人工审查的 TODO 列表
6. IF 转换过程中有警告或错误，CodePlay SHALL 在报告中分类展示
### Requirement 7: 项目管理
**User Story:** AS 开发者，I WANT 管理多个转换项目，SO THAT 我可以跟踪不同项目的转换进度和历史
#### Acceptance Criteria
1. WHEN 用户创建新项目，CodePlay SHALL 允许指定项目名称、源语言、目标语言
2. WHILE 用户查看项目列表，CodePlay SHALL 显示每个项目的状态（进行中、已完成、已验证）
3. WHILE 用户查看项目详情，CodePlay SHALL 显示项目下的所有转换任务和结果
4. IF 用户需要重新转换，CodePlay SHALL 允许基于历史项目进行再次转换
5. WHILE 用户管理项目，CodePlay SHALL 提供项目导出功能（包含源代码、转换结果、报告）
### Requirement 8: 配置管理
**User Story:** AS 开发者，I WANT 自定义转换配置，SO THAT 我可以根据项目需求调整转换行为
#### Acceptance Criteria
1. WHEN 用户创建配置文件，CodePlay SHALL 支持配置验证轮次（1-3 轮）
2. WHEN 用户创建配置文件，CodePlay SHALL 支持配置代码格式选项（缩进、换行等）
3. WHILE 用户配置转换规则，CodePlay SHALL 允许指定特定语法结构的处理方式
4. IF 用户没有提供配置，CodePlay SHALL 使用默认配置进行转换
5. WHILE 用户保存配置，CodePlay SHALL 将配置保存到项目目录或全局配置目录
### Requirement 9: 错误处理
**User Story:** AS 开发者，I WANT 在转换遇到问题时获得清晰的错误提示，SO THAT 我可以快速定位和解决问题
#### Acceptance Criteria
1. IF 源代码语法错误，CodePlay SHALL 指出错误位置和详情
2. IF 源语言或目标语言不支持，CodePlay SHALL 返回不支持的语言列表
3. IF 转换过程中发生内部错误，CodePlay SHALL 提供错误日志和恢复建议
4. WHILE 编译验证失败，CodePlay SHALL 提供编译器输出的完整错误信息
5. IF API 调用失败，CodePlay SHALL 返回结构化的错误响应（错误代码、消息、建议）
### Requirement 10: 性能和并发
**User Story:** AS 开发者，I WANT 转换工具具有良好的性能表现，SO THAT 我可以高效地处理大型代码库
#### Acceptance Criteria
1. WHILE 转换单个文件（1000 行以内），CodePlay SHALL 在 10 秒内完成转换和验证
2. WHILE 转换整个项目，CodePlay SHALL 支持并发处理多个文件
3. IF 同时有多个转换请求，CodePlay SHALL 提供请求队列和进度显示
4. WHILE 处理大型项目，CodePlay SHALL 提供增量转换能力（仅转换变更的文件）
5. WHILE 系统资源不足，CodePlay SHALL 排队处理请求并通知用户预计等待时间