# WhaleTown 标准开发工作流

> **AI 编程助手专用**：本文档定义了 WhaleTown 项目的标准化开发流程，确保所有开发者遵循统一的规范和质量标准。

---

## 🎯 工作流概览

```
┌─────────────────────────────────────────────────────────────────┐
│                    WhaleTown 7步标准开发流程                      │
└─────────────────────────────────────────────────────────────────┘

Step 1: 架构分析        →  读取架构规范，确定文件位置和通信方式
   ↓
Step 2: 功能实现        →  按规范编码，遵循类型安全和事件驱动
   ↓
Step 3: 注释规范检查     →  验证文件头、函数注释的完整性
   ↓
Step 4: 命名规范检查     →  验证PascalCase/camelCase/UPPER_CASE
   ↓
Step 5: 测试代码编写     →  创建GUT单元测试，覆盖核心功能
   ↓
Step 6: 测试验证        →  运行测试，确保所有测试通过
   ↓
Step 7: Git 提交        →  生成符合规范的提交信息并提交

总耗时：约 20-40 分钟（根据功能复杂度）
```

---

## 📖 使用方式

### 方式一：使用 Skill（推荐）⭐

最简单、最高效的方式是使用 `whaletown-developer` skill：

```bash
/whaletown-developer 实现玩家二段跳功能
```

Skill 会自动执行全部 7 步流程，确保不遗漏任何步骤。

### 方式二：手动执行流程

如果需要手动控制流程，请按照以下步骤逐步执行，并参考本文档的详细说明。

---

## 📋 详细步骤说明

### Step 1: 架构分析（5分钟）

**目标**: 理解功能在项目中的位置和通信方式

**规范文档**: `docs/02-开发规范/架构与通信规范.md`

#### 执行清单

- [ ] 读取架构规范文档
- [ ] 确定文件位置（_Core, scenes, UI）
- [ ] 确定通信方式（EventSystem）
- [ ] 列出依赖的管理器/系统
- [ ] 设计事件定义（如需要）

#### 分层架构决策树

```
功能是核心系统（管理器/全局系统）？
├─ 是 → 放在 _Core/managers/ 或 _Core/systems/
└─ 否 → 功能是游戏场景相关？
    ├─ 是 → 放在 scenes/Maps/, scenes/Entities/, scenes/Components/
    └─ 否 → 功能是UI界面？
        ├─ 是 → 放在 scenes/ui/
        └─ 否 → 重新分析功能定位
```

#### 通信方式决策

- **同模块内通信**: 父调用子方法（向下），子发出信号（向上）
- **跨模块通信**: MUST 使用 EventSystem
- **事件定义位置**: 所有事件名称定义在 `_Core/EventNames.gd`

#### 示例：玩家二段跳功能

```gdscript
# 架构分析结果
文件位置: scenes/Entities/Player/Player.gd  # 游戏场景层
通信方式: EventSystem.emit_event()          # 跨模块通信
依赖: EventSystem, Input                     # 系统依赖
事件: PLAYER_DOUBLE_JUMPED                  # 需要在 EventNames.gd 中定义
```

---

### Step 2: 功能实现（10-20分钟）

**目标**: 按照规范实现功能代码

**规范文档**: `docs/02-开发规范/架构与通信规范.md`, `claude.md`

#### 执行清单

- [ ] 创建或修改文件在正确位置
- [ ] 所有变量和函数有类型注解
- [ ] 使用 Godot 4.2+ 语法（await, @onready）
- [ ] 通过 EventSystem 进行跨模块通信
- [ ] 如有新事件，添加到 EventNames.gd
- [ ] 使用 Nearest 滤镜（Sprite2D/TileMap）

#### 核心规范要点

**1. 严格类型安全**
```gdscript
# ✅ 正确
var speed: float = 200.0
var currentHealth: int = 100
func move(delta: float) -> void:
func getHealth() -> int:

# ❌ 错误
var speed = 200.0           # 缺少类型注解
func move(delta):           # 缺少参数和返回值类型
```

**2. Godot 4.2+ 语法**
```gdscript
# ✅ 正确
await get_tree().create_timer(1.0).timeout
@onready var sprite: Sprite2D = $Sprite2D

# ❌ 错误
yield(get_tree().create_timer(1.0), "timeout")  # Godot 3.x
var sprite = get_node("Sprite2D")               # 应在 _ready 外缓存
```

**3. EventSystem 通信**
```gdscript
# 发送事件
EventSystem.emit_event(EventNames.PLAYER_DOUBLE_JUMPED, {
    "position": global_position,
    "direction": velocity.normalized()
})

# 监听事件
func _ready() -> void:
    EventSystem.connect_event(EventNames.INTERACT_PRESSED, _on_interact_pressed)

func _on_interact_pressed(data: Dictionary = {}) -> void:
    # 处理交互逻辑
    pass
```

**4. 自动加载限制**
```gdscript
# ✅ 正确：在高层组件中访问
func _ready() -> void:
    var current_state = GameManager.get_game_state()

# ❌ 错误：在底层实体（Player, NPC）中直接访问
func _ready() -> void:
    GameManager.register_player(self)  # 不应该这样做

# ✅ 正确：底层实体使用事件
func _ready() -> void:
    EventSystem.emit_event(EventNames.PLAYER_SPAWNED, {"player": self})
```

---

### Step 3: 注释规范检查（3-5分钟）

**目标**: 确保代码注释完整且符合规范

**规范文档**: `docs/02-开发规范/代码注释规范.md`

#### 执行清单

- [ ] 文件头注释完整
- [ ] 所有公共函数有完整注释
- [ ] 复杂逻辑有行内注释
- [ ] 使用 TODO/FIXME/NOTE 标记（如需要）

#### 文件头注释模板

```gdscript
# ============================================================================
# 文件名: PlayerController.gd
# 作用: 玩家角色控制器，处理玩家输入和移动逻辑
#
# 主要功能:
# - 处理键盘和手柄输入
# - 控制角色移动和跳跃
# - 管理角色状态切换
# - 实现二段跳功能
#
# 依赖: EventSystem, InputManager
# 作者: [开发者名称]
# 创建时间: 2025-01-03
# ============================================================================

extends CharacterBody2D
class_name PlayerController
```

#### 函数注释模板

```gdscript
# 执行二段跳
#
# 在玩家空中时允许执行一次额外的跳跃
# 二段跳的力度为普通跳跃的80%
#
# 参数: 无
#
# 返回值: 无
#
# 使用示例:
#   if Input.is_action_just_pressed("jump") and canDoubleJump:
#       performDoubleJump()
#
# 注意事项:
# - 只能在空中且 canDoubleJump 为 true 时调用
# - 执行后会将 canDoubleJump 设置为 false
# - 落地时会重置 canDoubleJump 为 true
func performDoubleJump() -> void:
    velocity.y = JUMP_FORCE * 0.8
    canDoubleJump = false
    EventSystem.emit_event(EventNames.PLAYER_DOUBLE_JUMPED, {
        "position": global_position
    })
```

---

### Step 4: 命名规范检查（2-3分钟）

**目标**: 验证所有命名符合项目规范

**规范文档**: `docs/02-开发规范/命名规范.md`

#### 执行清单

- [ ] 类名使用 PascalCase
- [ ] 变量/函数使用 camelCase
- [ ] 常量使用 UPPER_CASE
- [ ] 私有成员使用下划线前缀
- [ ] 文件命名符合规范

#### 命名规范速查表

| 元素类型 | 命名规范 | 示例 |
|---------|---------|------|
| **类名** | PascalCase | `class_name PlayerController` |
| **变量** | camelCase | `var moveSpeed: float` |
| **私有变量** | _camelCase | `var _velocity: Vector2` |
| **函数** | camelCase | `func updateMovement()` |
| **私有函数** | _camelCase | `func _calculateDamage()` |
| **常量** | UPPER_CASE | `const MAX_HEALTH: int = 100` |
| **枚举类型** | PascalCase | `enum PlayerState` |
| **枚举值** | UPPER_CASE | `IDLE, WALKING, RUNNING` |
| **脚本文件** | PascalCase.gd | `PlayerController.gd` |
| **场景文件** | snake_case_scene.tscn | `main_scene.tscn` |
| **预制体** | snake_case_prefab.tscn | `player_prefab.tscn` |

#### 常见错误检查

```gdscript
# ✅ 正确
class_name PlayerController
const MAX_JUMPS: int = 2
var moveSpeed: float = 200.0
var canDoubleJump: bool = true
var _velocity: Vector2 = Vector2.ZERO
func performDoubleJump() -> void:
func _calculateJumpForce() -> float:

# ❌ 错误
class_name player_controller      # 应使用 PascalCase
const maxJumps: int = 2           # 常量应使用 UPPER_CASE
var MoveSpeed: float = 200.0      # 变量应使用 camelCase
var can_double_jump: bool = true  # 不要使用 snake_case
func PerformDoubleJump():         # 函数应使用 camelCase
```

---

### Step 5: 测试代码编写（5-10分钟）

**目标**: 为实现的功能创建单元测试

**规范文档**: `docs/03-技术实现/测试指南.md`

#### 执行清单

- [ ] 创建测试文件 `tests/unit/test_[name].gd`
- [ ] 测试文件继承自 GutTest
- [ ] 实现 before_each 和 after_each
- [ ] 编写核心功能测试
- [ ] 编写边界条件测试

#### 测试文件模板

```gdscript
# tests/unit/test_player_double_jump.gd
extends GutTest

## PlayerController 二段跳功能单元测试

var player: PlayerController

func before_each():
    # 每个测试前创建新的 Player 实例
    player = preload("res://scenes/Entities/Player/PlayerController.gd").new()
    add_child(player)
    player.initialize()

func after_each():
    # 每个测试后清理
    player.queue_free()

func test_can_double_jump_after_first_jump():
    # 测试：第一次跳跃后可以二段跳
    player.performJump()
    assert_true(player.canDoubleJump, "Should be able to double jump after first jump")

func test_cannot_triple_jump():
    # 测试：不能三段跳
    player.performJump()
    player.performDoubleJump()
    assert_false(player.canDoubleJump, "Should not be able to triple jump")

func test_reset_double_jump_on_ground():
    # 测试：落地后重置二段跳
    player.performJump()
    player.performDoubleJump()
    player._on_landed()  # 模拟落地
    assert_true(player.canDoubleJump, "Double jump should reset when landing")

func test_double_jump_emits_event():
    # 测试：二段跳发出事件
    watch_signals(EventSystem)
    player.performDoubleJump()
    assert_signal_emitted(EventSystem, "event_raised")
```

#### 测试覆盖建议

1. **正常流程**: 功能的标准使用场景
2. **边界条件**: 极限值、特殊输入
3. **错误处理**: 异常情况、错误输入
4. **事件通信**: 验证事件正确发送和接收
5. **状态管理**: 状态转换的正确性

---

### Step 6: 测试验证（2-3分钟）

**目标**: 运行测试确保代码质量

**规范文档**: `docs/03-技术实现/测试指南.md`

#### 执行清单

- [ ] 运行 GUT 测试命令
- [ ] 所有测试通过
- [ ] 如有失败，修复并重新测试
- [ ] 确认测试覆盖核心功能

#### 运行测试

```bash
# 运行所有测试
godot --headless -s addons/gut/gut_cmdline.gd -gdir=res://tests/ -ginclude_subdirs

# 运行特定测试文件
godot --headless -s addons/gut/gut_cmdline.gd -gtest=res://tests/unit/test_player_double_jump.gd
```

#### 测试结果分析

**所有测试通过**：
```
========================
= PASSED: 4 of 4 tests =
========================
```
✅ 进入下一步

**部分测试失败**：
```
==========================
= FAILED: 1 of 4 tests  =
==========================
FAILED: test_cannot_triple_jump
  Expected: false
  Got: true
```
❌ 修复问题后重新测试

---

### Step 7: Git 提交（3-5分钟）

**目标**: 生成符合规范的 Git 提交信息

**规范文档**: `docs/02-开发规范/Git提交规范.md`

#### 执行清单

- [ ] 确定提交类型（feat/fix/docs/refactor等）
- [ ] 生成规范的提交信息
- [ ] 使用中文冒号（：）
- [ ] 描述简洁明了
- [ ] 遵循"一次提交只做一件事"

#### 提交类型选择

| 改动类型 | 提交类型 | 示例 |
|---------|---------|------|
| 新功能 | `feat` | `feat：实现玩家二段跳功能` |
| Bug修复 | `fix` | `fix：修复跳跃碰撞检测问题` |
| 文档更新 | `docs` | `docs：更新架构规范文档` |
| 代码重构 | `refactor` | `refactor：重构移动系统逻辑` |
| 性能优化 | `perf` | `perf：优化物理计算性能` |
| 测试相关 | `test` | `test：添加二段跳单元测试` |
| 场景文件 | `scene` | `scene：创建战斗场景` |
| UI界面 | `ui` | `ui：设计暂停菜单界面` |

#### 提交示例

```bash
# 示例1：新功能（完整流程）
git add scenes/Entities/Player/PlayerController.gd
git add _Core/EventNames.gd
git add tests/unit/test_player_double_jump.gd
git commit -m "feat：实现玩家二段跳功能"

# 示例2：Bug修复
git add scenes/Entities/Player/PlayerController.gd
git commit -m "fix：修复二段跳状态未重置的问题"

# 示例3：测试添加
git add tests/unit/test_player_movement.gd
git commit -m "test：添加玩家移动系统单元测试"

# 示例4：带详细描述的提交
git commit -m "feat：实现玩家二段跳功能

- 添加二段跳核心逻辑
- 在空中允许执行一次额外跳跃
- 二段跳力度为普通跳跃的80%
- 发送 PLAYER_DOUBLE_JUMPED 事件
- 落地时重置二段跳能力"
```

#### 多类型改动处理

**⚠️ 如果同时有多种类型改动，必须拆分提交：**

```bash
# ❌ 错误：混合提交
git commit -m "fix + feat：修复Bug并添加新功能"

# ✅ 正确：拆分提交
git add PlayerController.gd  # 只暂存 Bug 修复部分
git commit -m "fix：修复跳跃碰撞检测问题"

git add PlayerController.gd  # 暂存新功能部分
git commit -m "feat：实现玩家二段跳功能"
```

---

## ✅ 完整工作流检查清单

在完成开发任务后，使用此清单验证是否执行了全部流程：

### 总览检查
- [ ] ✅ Step 1: 架构分析完成
- [ ] ✅ Step 2: 功能实现完成
- [ ] ✅ Step 3: 注释规范检查通过
- [ ] ✅ Step 4: 命名规范检查通过
- [ ] ✅ Step 5: 测试代码编写完成
- [ ] ✅ Step 6: 测试验证通过
- [ ] ✅ Step 7: Git 提交完成

### 详细检查
- [ ] 文件位置符合分层架构（_Core, scenes, UI）
- [ ] 使用 EventSystem 进行跨模块通信
- [ ] 新事件已添加到 EventNames.gd
- [ ] 所有变量和函数有类型注解
- [ ] 使用 Godot 4.2+ 语法（await, @onready）
- [ ] 命名规范正确（PascalCase/camelCase/UPPER_CASE）
- [ ] 文件头注释完整
- [ ] 公共函数有完整文档注释
- [ ] 创建了单元测试文件
- [ ] 所有测试通过
- [ ] Git 提交信息符合规范
- [ ] Sprite2D/TileMap 使用 Nearest 滤镜
- [ ] 未违反自动加载限制

---

## 🚀 最佳实践

### 使用 TodoWrite 追踪进度

在执行工作流时，使用 TodoWrite 工具追踪每个步骤：

```gdscript
TodoWrite.create_todos([
  "Step 1: 架构分析 - 读取架构规范",
  "Step 2: 功能实现 - 按规范编码",
  "Step 3: 注释规范检查",
  "Step 4: 命名规范检查",
  "Step 5: 测试代码编写",
  "Step 6: 测试验证 - 运行测试",
  "Step 7: Git 提交 - 生成提交信息"
])
```

每完成一步，立即标记为 `completed`。

### 常见错误避免

1. **跳过测试**: 测试不是可选项，必须为核心功能编写测试
2. **混合提交**: 不要在一次提交中混合 fix 和 feat
3. **命名不一致**: 严格遵循 PascalCase/camelCase/UPPER_CASE
4. **缺少注释**: 公共函数必须有完整注释
5. **直接访问单例**: 底层实体使用事件，不直接访问 GameManager

### 提升效率技巧

1. **使用 Skill**: 调用 `/whaletown-developer` 自动执行全流程
2. **模板复用**: 参考现有代码的结构和注释模板
3. **增量提交**: 不要等所有功能完成才提交，完成一个逻辑单元就提交
4. **快速参考**: 使用 `.claude/skills/whaletown-developer/references/checklist.md` 快速自检

---

## 📚 相关文档索引

### 核心规范文档
- **架构与通信**: `docs/02-开发规范/架构与通信规范.md`
- **代码注释**: `docs/02-开发规范/代码注释规范.md`
- **命名规范**: `docs/02-开发规范/命名规范.md`
- **Git 提交**: `docs/02-开发规范/Git提交规范.md`
- **测试指南**: `docs/03-技术实现/测试指南.md`
- **项目指令**: `claude.md` (根目录)

### 辅助文档
- **Skill 指令**: `.claude/skills/whaletown-developer/SKILL.md`
- **快速检查清单**: `.claude/skills/whaletown-developer/references/checklist.md`
- **功能开发流程**: `docs/AI_docs/workflows/feature_development.md`

---

## 💡 示例：完整开发流程

### 任务：实现玩家二段跳功能

#### Step 1: 架构分析 (3分钟)
```
读取: docs/02-开发规范/架构与通信规范.md
分析结果:
  - 文件位置: scenes/Entities/Player/PlayerController.gd
  - 通信方式: EventSystem
  - 依赖: EventSystem, Input
  - 事件: PLAYER_DOUBLE_JUMPED (需添加到 EventNames.gd)
```

#### Step 2: 功能实现 (15分钟)
```gdscript
# scenes/Entities/Player/PlayerController.gd
extends CharacterBody2D
class_name PlayerController

const JUMP_FORCE: float = -400.0
const MAX_DOUBLE_JUMPS: int = 1

var canDoubleJump: bool = true
var doubleJumpCount: int = 0

func performDoubleJump() -> void:
    if not canDoubleJump or doubleJumpCount >= MAX_DOUBLE_JUMPS:
        return

    velocity.y = JUMP_FORCE * 0.8
    doubleJumpCount += 1
    canDoubleJump = false

    EventSystem.emit_event(EventNames.PLAYER_DOUBLE_JUMPED, {
        "position": global_position
    })

func _on_landed() -> void:
    doubleJumpCount = 0
    canDoubleJump = true
```

#### Step 3-4: 注释和命名检查 (5分钟)
```
✅ 文件头注释完整
✅ 函数注释完整
✅ 类名 PascalCase: PlayerController
✅ 变量 camelCase: canDoubleJump
✅ 常量 UPPER_CASE: MAX_DOUBLE_JUMPS
```

#### Step 5: 编写测试 (8分钟)
```gdscript
# tests/unit/test_player_double_jump.gd
extends GutTest

var player: PlayerController

func before_each():
    player = PlayerController.new()
    add_child(player)

func test_can_double_jump():
    assert_true(player.canDoubleJump)

func test_double_jump_resets_on_landing():
    player.performDoubleJump()
    player._on_landed()
    assert_true(player.canDoubleJump)
```

#### Step 6: 测试验证 (2分钟)
```bash
$ godot --headless -s addons/gut/gut_cmdline.gd
========================
= PASSED: 2 of 2 tests =
========================
```

#### Step 7: Git 提交 (3分钟)
```bash
git add scenes/Entities/Player/PlayerController.gd
git add _Core/EventNames.gd
git add tests/unit/test_player_double_jump.gd
git commit -m "feat：实现玩家二段跳功能"
```

**总耗时**: 约 36 分钟
**结果**: ✅ 功能实现完整，符合所有规范

---

## 🎓 总结

遵循此 7 步标准开发工作流，可以确保：

1. **代码质量**: 符合项目的所有规范和标准
2. **团队一致**: 所有开发者使用相同的流程和规范
3. **可维护性**: 清晰的注释、规范的命名、完整的测试
4. **高效协作**: 规范的 Git 提交历史，便于追溯和回滚
5. **质量保证**: 测试驱动开发，确保功能正确性

**记住**: 使用 `/whaletown-developer` skill 可以自动化执行此流程！🚀