refactor：实现新的项目结构组织

- 添加 _Core/components/ 和 _Core/utils/ 目录 - 重新组织 scenes/ 目录结构，按功能分类 - 迁移 StringUtils.gd 到新的 _Core/utils/ 位置 - 迁移 AuthScene.gd 到新的 scenes/ui/ 位置 - 添加 AI 文档支持目录 docs/AI_docs/ - 添加开发参考文档 claude.md
2026-01-02 00:58:34 +08:00
parent a18c7a54b1
commit 3175c98ea3
21 changed files with 3130 additions and 0 deletions
--- a/docs/AI_docs/workflows/feature_development.md
+++ b/docs/AI_docs/workflows/feature_development.md
@@ -0,0 +1,363 @@
+# 🚀 功能开发流程
+
+> AI编程助手专用：新功能开发的标准化工作流程
+
+## 🎯 开发流程概览
+
+### 阶段1: 需求分析 → 阶段2: 架构设计 → 阶段3: 代码实现 → 阶段4: 测试验证 → 阶段5: 文档更新
+
+---
+
+## 📋 阶段1: 需求分析
+
+### 1.1 理解需求
+```markdown
+**必须明确的问题:**
+- 功能的具体作用是什么？
+- 涉及哪些用户交互？
+- 需要哪些数据和状态管理？
+- 与现有功能的关系如何？
+```
+
+### 1.2 需求分类
+```gdscript
+# 功能类型分类
+enum FeatureType {
+    CORE_SYSTEM,     # 核心系统功能 → 放在 _Core/
+    GAME_SCENE,      # 游戏场景功能 → 放在 scenes/
+    UI_COMPONENT,    # UI组件功能 → 放在 scenes/ui/
+    ASSET_RELATED,   # 资源相关功能 → 涉及 assets/
+    CONFIG_DRIVEN    # 配置驱动功能 → 涉及 Config/
+}
+```
+
+### 1.3 依赖分析
+- 需要哪些现有管理器？
+- 需要创建新的管理器吗？
+- 需要新的事件定义吗？
+- 需要新的配置文件吗？
+
+---
+
+## 🏗️ 阶段2: 架构设计
+
+### 2.1 确定文件位置
+```gdscript
+# 根据功能类型确定文件位置
+match feature_type:
+    FeatureType.CORE_SYSTEM:
+        # _Core/managers/ 或 _Core/systems/
+        var file_path = "_Core/managers/YourManager.gd"
+    
+    FeatureType.GAME_SCENE:
+        # scenes/maps/, scenes/characters/, scenes/effects/
+        var file_path = "scenes/characters/YourCharacter.gd"
+    
+    FeatureType.UI_COMPONENT:
+        # scenes/ui/
+        var file_path = "scenes/ui/YourWindow.gd"
+```
+
+### 2.2 设计接口
+```gdscript
+# 定义公共接口
+class_name YourFeature
+
+# 信号定义（对外通信）
+signal feature_initialized()
+signal feature_state_changed(new_state: String)
+
+# 公共方法（供其他模块调用）
+func initialize(config: Dictionary) -> bool
+func get_state() -> String
+func cleanup() -> void
+```
+
+### 2.3 事件设计
+```gdscript
+# 在 _Core/EventNames.gd 中添加新事件
+const YOUR_FEATURE_STARTED: String = "your_feature_started"
+const YOUR_FEATURE_COMPLETED: String = "your_feature_completed"
+const YOUR_FEATURE_ERROR: String = "your_feature_error"
+```
+
+---
+
+## 💻 阶段3: 代码实现
+
+### 3.1 创建基础结构
+```gdscript
+# 使用标准模板创建文件
+# 参考: docs/AI_docs/templates/components.md
+
+extends Node  # 或其他合适的基类
+
+## [功能描述]
+## 负责[具体职责]
+
+# 信号定义
+signal feature_ready()
+
+# 枚举定义
+enum FeatureState {
+    UNINITIALIZED,
+    INITIALIZING,
+    READY,
+    ERROR
+}
+
+# 常量定义
+const CONFIG_PATH: String = "res://Config/your_feature_config.json"
+
+# 导出变量
+@export var debug_mode: bool = false
+
+# 公共变量
+var current_state: FeatureState = FeatureState.UNINITIALIZED
+
+# 私有变量
+var _config_data: Dictionary = {}
+
+func _ready() -> void:
+    initialize()
+```
+
+### 3.2 实现核心逻辑
+```gdscript
+## 初始化功能
+func initialize() -> bool:
+    if current_state != FeatureState.UNINITIALIZED:
+        push_warning("Feature already initialized")
+        return false
+    
+    current_state = FeatureState.INITIALIZING
+    
+    # 加载配置
+    if not _load_config():
+        current_state = FeatureState.ERROR
+        return false
+    
+    # 连接事件
+    _connect_events()
+    
+    # 执行初始化逻辑
+    _perform_initialization()
+    
+    current_state = FeatureState.READY
+    feature_ready.emit()
+    return true
+
+func _load_config() -> bool:
+    # 配置加载逻辑
+    return true
+
+func _connect_events() -> void:
+    # 事件连接逻辑
+    EventSystem.connect_event("related_event", _on_related_event)
+
+func _perform_initialization() -> void:
+    # 具体初始化逻辑
+    pass
+```
+
+### 3.3 错误处理
+```gdscript
+func _handle_error(error_message: String) -> void:
+    push_error("[YourFeature] %s" % error_message)
+    current_state = FeatureState.ERROR
+    
+    # 发送错误事件
+    EventSystem.emit_event(EventNames.YOUR_FEATURE_ERROR, {
+        "message": error_message,
+        "timestamp": Time.get_unix_time_from_system()
+    })
+```
+
+---
+
+## 🧪 阶段4: 测试验证
+
+### 4.1 创建测试文件
+```gdscript
+# tests/unit/test_your_feature.gd
+extends "res://addons/gut/test.gd"
+
+## YourFeature 单元测试
+
+var your_feature: YourFeature
+
+func before_each():
+    your_feature = preload("res://_Core/managers/YourFeature.gd").new()
+    add_child(your_feature)
+
+func after_each():
+    your_feature.queue_free()
+
+func test_initialization():
+    # 测试初始化
+    var result = your_feature.initialize()
+    assert_true(result, "Feature should initialize successfully")
+    assert_eq(your_feature.current_state, YourFeature.FeatureState.READY)
+
+func test_error_handling():
+    # 测试错误处理
+    # 模拟错误条件
+    pass
+```
+
+### 4.2 集成测试
+```gdscript
+# tests/integration/test_your_feature_integration.gd
+extends "res://addons/gut/test.gd"
+
+## YourFeature 集成测试
+
+func test_feature_with_event_system():
+    # 测试与事件系统的集成
+    var event_received = false
+    
+    EventSystem.connect_event("your_feature_started", func(data): event_received = true)
+    
+    # 触发功能
+    # 验证事件是否正确发送
+    assert_true(event_received, "Event should be emitted")
+```
+
+### 4.3 性能测试
+```gdscript
+# tests/performance/test_your_feature_performance.gd
+extends "res://addons/gut/test.gd"
+
+## YourFeature 性能测试
+
+func test_initialization_performance():
+    var start_time = Time.get_time_dict_from_system()
+    
+    # 执行功能
+    your_feature.initialize()
+    
+    var end_time = Time.get_time_dict_from_system()
+    var duration = _calculate_duration(start_time, end_time)
+    
+    # 验证性能要求（例如：初始化应在100ms内完成）
+    assert_lt(duration, 0.1, "Initialization should complete within 100ms")
+```
+
+---
+
+## 📚 阶段5: 文档更新
+
+### 5.1 更新API文档
+```markdown
+# 在 docs/AI_docs/quick_reference/api_reference.md 中添加
+
+## YourFeature API
+
+### 初始化
+```gdscript
+var feature = YourFeature.new()
+feature.initialize(config_dict)
+```
+
+### 主要方法
+- `initialize(config: Dictionary) -> bool` - 初始化功能
+- `get_state() -> FeatureState` - 获取当前状态
+- `cleanup() -> void` - 清理资源
+
+### 事件
+- `feature_ready` - 功能准备就绪
+- `feature_state_changed(new_state)` - 状态改变
+```
+
+### 5.2 更新使用示例
+```gdscript
+# 在 docs/AI_docs/quick_reference/code_snippets.md 中添加
+
+## YourFeature 使用示例
+
+### 基本使用
+```gdscript
+# 创建和初始化
+var feature = YourFeature.new()
+add_child(feature)
+
+# 连接信号
+feature.feature_ready.connect(_on_feature_ready)
+
+# 初始化
+var config = {"setting1": "value1"}
+feature.initialize(config)
+
+func _on_feature_ready():
+    print("Feature is ready to use")
+```
+```
+
+### 5.3 更新架构文档
+```markdown
+# 在 docs/AI_docs/architecture_guide.md 中更新
+
+## 新增功能: YourFeature
+
+### 位置
+- 文件路径: `_Core/managers/YourFeature.gd`
+- AutoLoad: 是/否
+- 依赖: EventSystem, ConfigManager
+
+### 职责
+- 负责[具体职责描述]
+- 管理[相关数据/状态]
+- 提供[对外接口]
+```
+
+---
+
+## ✅ 开发检查清单
+
+### 代码质量检查
+- [ ] 遵循命名规范（PascalCase类名，snake_case变量名）
+- [ ] 所有变量和函数都有类型注解
+- [ ] 添加了适当的注释和文档字符串
+- [ ] 实现了错误处理和边界检查
+- [ ] 使用事件系统进行模块间通信
+
+### 架构一致性检查
+- [ ] 文件放在正确的目录中
+- [ ] 如果是管理器，已配置AutoLoad
+- [ ] 事件名称已添加到EventNames.gd
+- [ ] 配置文件已放在Config/目录
+- [ ] 遵循项目的架构原则
+
+### 测试覆盖检查
+- [ ] 编写了单元测试
+- [ ] 编写了集成测试（如果需要）
+- [ ] 编写了性能测试（如果是核心功能）
+- [ ] 所有测试都能通过
+- [ ] 测试覆盖了主要功能和边界情况
+
+### 文档更新检查
+- [ ] 更新了API参考文档
+- [ ] 添加了使用示例
+- [ ] 更新了架构文档
+- [ ] 更新了相关的工作流程文档
+
+---
+
+## 🔄 迭代优化
+
+### 代码审查要点
+1. **功能完整性**: 是否满足所有需求？
+2. **性能表现**: 是否存在性能瓶颈？
+3. **错误处理**: 是否处理了所有可能的错误情况？
+4. **代码可读性**: 代码是否清晰易懂？
+5. **测试覆盖**: 测试是否充分？
+
+### 持续改进
+- 收集用户反馈
+- 监控性能指标
+- 定期重构优化
+- 更新文档和示例
+
+---
+
+**🎯 记住**: 这个流程确保了功能开发的质量和一致性。严格遵循每个阶段的要求，将大大提高开发效率和代码质量。