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,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");
+}
+```