whale-town-front/docs/AI_docs/workflows/feature_development.md

🚀 功能开发流程

AI编程助手专用：新功能开发的标准化工作流程

🎯 开发流程概览

阶段1: 需求分析 → 阶段2: 架构设计 → 阶段3: 代码实现 → 阶段4: 测试验证 → 阶段5: 文档更新

---

📋 阶段1: 需求分析

1.1 理解需求

**必须明确的问题:**
- 功能的具体作用是什么？
- 涉及哪些用户交互？
- 需要哪些数据和状态管理？
- 与现有功能的关系如何？

1.2 需求分类

# 功能类型分类
enum FeatureType {
    CORE_SYSTEM,     # 核心系统功能 → 放在 _Core/
    GAME_SCENE,      # 游戏场景功能 → 放在 scenes/
    UI_COMPONENT,    # UI组件功能 → 放在 scenes/ui/
    ASSET_RELATED,   # 资源相关功能 → 涉及 assets/
    CONFIG_DRIVEN    # 配置驱动功能 → 涉及 Config/
}

1.3 依赖分析

• 需要哪些现有管理器？
• 需要创建新的管理器吗？
• 需要新的事件定义吗？
• 需要新的配置文件吗？

---

🏗️ 阶段2: 架构设计

2.1 确定文件位置

# 根据功能类型确定文件位置
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 设计接口

# 定义公共接口
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 事件设计

# 在 _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 创建基础结构

# 使用标准模板创建文件
# 参考: 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 实现核心逻辑

## 初始化功能
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 错误处理

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 创建测试文件

# 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 集成测试

# 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 性能测试

# 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文档

# 在 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. 测试覆盖: 测试是否充分？

持续改进

• 收集用户反馈
• 监控性能指标
• 定期重构优化
• 更新文档和示例

---

🎯 记住: 这个流程确保了功能开发的质量和一致性。严格遵循每个阶段的要求，将大大提高开发效率和代码质量。