monkeycode-ai
80b4718568
创建以下文档: - INDEX.md - 项目索引和概览 - ARCHITECTURE.md - 系统架构设计文档 - INTERFACES.md - 接口和类型定义文档 - DEVELOPER_GUIDE.md - 开发者指南 文档覆盖内容: - 项目结构和模块说明 - 技术栈和依赖 - 核心组件设计 - API 接口定义 - 数据模型 - 开发环境配置 - 代码规范 - 测试指南 - 调试技巧 - Git 工作流 Co-authored-by: monkeycode-ai <monkeycode-ai@chaitin.com>
632 lines
13 KiB
Markdown
632 lines
13 KiB
Markdown
# 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");
|
||
}
|
||
```
|