# WhaleTown Development Quality Checklist

快速参考检查清单，用于验证代码是否符合项目规范。

## 架构检查清单

### 文件位置
- [ ] 核心系统文件位于 `_Core/managers/` 或 `_Core/systems/`
- [ ] 游戏场景文件位于 `scenes/Maps/`, `scenes/Entities/`, `scenes/Components/`
- [ ] UI 组件文件位于 `scenes/ui/`
- [ ] 测试文件位于 `tests/unit/` 或 `tests/integration/`

### 通信方式
- [ ] 跨模块通信使用 EventSystem
- [ ] 新增事件定义在 `_Core/EventNames.gd` 中
- [ ] 遵循 "Signal Up, Call Down" 原则
- [ ] 父节点调用子节点方法（向下调用）
- [ ] 子节点发出信号通知父节点（向上信号）

### 依赖管理
- [ ] 仅使用允许的自动加载：GameManager, SceneManager, EventSystem, NetworkManager, ResponseHandler
- [ ] 底层实体（Player, NPC）不直接访问 GameManager
- [ ] 底层实体通过事件系统与全局管理器通信

---

## 代码规范检查清单

### 类型安全
- [ ] 所有变量都有类型注解：`var speed: float = 200.0`
- [ ] 所有函数都有参数和返回值类型：`func move(delta: float) -> void:`
- [ ] 常量都有类型注解：`const MAX_HEALTH: int = 100`

### Godot 4.2+ 语法
- [ ] 使用 `await` 代替 `yield()`
- [ ] 使用 `@onready` 缓存节点引用
- [ ] 避免在 `_process()` 中使用 `get_node()`
- [ ] 信号连接使用 `.connect()` 语法

### 资源设置
- [ ] 所有 Sprite2D 使用 Nearest 滤镜（不使用 Linear）
- [ ] 所有 TileMap 使用 Nearest 滤镜

---

## 命名规范检查清单

### 类名
- [ ] 使用 PascalCase：`class_name PlayerController`
- [ ] 文件名与类名一致：`PlayerController.gd`

### 变量
- [ ] 公共变量使用 camelCase：`var moveSpeed: float`
- [ ] 私有变量使用下划线前缀：`var _velocity: Vector2`
- [ ] 布尔变量使用 is/has/can 前缀：`var isJumping: bool`

### 函数
- [ ] 使用 camelCase：`func updateMovement()`
- [ ] 获取函数使用 `get` 前缀：`func getPlayerPosition()`
- [ ] 设置函数使用 `set` 前缀：`func setHealth(value: int)`
- [ ] 判断函数使用 `is/has/can` 前缀：`func isAlive()`, `func canJump()`
- [ ] 私有函数使用下划线前缀：`func _calculateDamage()`

### 常量
- [ ] 使用 UPPER_CASE：`const MAX_HEALTH: int = 100`
- [ ] 使用下划线分隔：`const JUMP_FORCE: float = -400.0`

### 枚举
- [ ] 枚举类型使用 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`)
- [ ] 资源文件：snake_case (`sprite_player_idle.png`)

---

## 注释规范检查清单

### 文件头注释
- [ ] 包含文件名
- [ ] 包含作用描述
- [ ] 列出主要功能
- [ ] 列出依赖的管理器/系统
- [ ] 包含作者和创建时间

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

### 函数注释
- [ ] 公共函数有完整注释
- [ ] 包含功能描述
- [ ] 列出参数说明（名称、类型、含义）
- [ ] 说明返回值（类型、含义）
- [ ] 提供使用示例（对于复杂函数）
- [ ] 标注注意事项（如果有）

示例：
```gdscript
# 处理玩家输入并更新移动状态
#
# 参数:
#   delta: float - 帧时间间隔
#
# 返回值: 无
#
# 注意事项:
# - 需要在 _physics_process 中调用
# - 会自动处理重力和碰撞
func handleMovement(delta: float) -> void:
```

### 行内注释
- [ ] 复杂逻辑有注释说明
- [ ] 注释解释 WHY（为什么），不解释 WHAT（是什么）
- [ ] 避免显而易见的注释
- [ ] 使用 TODO/FIXME/NOTE 等标记

---

## 测试规范检查清单

### 测试文件
- [ ] _Core/ 中的管理器/系统都有对应测试文件
- [ ] 测试文件位于 `tests/unit/` 或 `tests/integration/`
- [ ] 测试文件命名：`test_[name].gd`
- [ ] 测试文件继承自 GutTest：`extends GutTest`

### 测试结构
- [ ] 包含测试类注释
- [ ] 实现 `before_each()` 进行测试前置设置
- [ ] 实现 `after_each()` 进行测试清理
- [ ] 测试方法命名：`test_[功能名称]()`

### 测试覆盖
- [ ] 测试核心功能的正常流程
- [ ] 测试错误处理和边界条件
- [ ] 测试初始化和清理逻辑
- [ ] 所有测试都能通过

示例：
```gdscript
extends GutTest

## PlayerController 单元测试

var player: PlayerController

func before_each():
    player = preload("res://scenes/Entities/Player/PlayerController.gd").new()
    add_child(player)

func after_each():
    player.queue_free()

func test_initialization():
    var result = player.initialize()
    assert_true(result, "Player should initialize successfully")

func test_movement():
    # 测试移动功能
    pass
```

---

## Git 提交规范检查清单

### 提交类型
- [ ] 使用正确的提交类型：
  - `feat` - 新功能
  - `fix` - Bug 修复
  - `docs` - 文档更新
  - `refactor` - 代码重构
  - `test` - 测试相关
  - `scene` - 场景文件
  - `ui` - UI 相关

### 提交格式
- [ ] 使用中文冒号（：）
- [ ] 描述简洁明了（< 50 字符）
- [ ] 使用动词开头（添加、修复、更新）
- [ ] 一次提交只包含一种类型的改动

### 提交原则
- [ ] 一次提交只做一件事
- [ ] 提交的代码能够正常运行
- [ ] 避免 fix + feat 混合提交
- [ ] 如需多种改动，拆分成多次提交

示例：
```bash
# ✅ 正确
git commit -m "feat：实现玩家二段跳功能"
git commit -m "fix：修复角色跳跃时的碰撞检测问题"
git commit -m "test：添加角色控制器单元测试"

# ❌ 错误
git commit -m "fix + feat：修复Bug并添加新功能"  # 混合类型
git commit -m "update player"                    # 描述不清晰，使用英文
git commit -m "fix: 修复Bug"                     # 使用英文冒号
```

---

## 完整工作流检查清单

使用此清单验证开发任务是否完整执行 7 步工作流：

### Step 1: 架构分析
- [ ] 已读取 `docs/02-开发规范/架构与通信规范.md`
- [ ] 已确定文件位置（_Core, scenes, UI）
- [ ] 已确定通信方式（EventSystem）
- [ ] 已列出依赖的管理器/系统
- [ ] 已设计事件定义（如需要）

### Step 2: 功能实现
- [ ] 代码遵循分层架构
- [ ] 所有变量和函数有类型注解
- [ ] 使用 Godot 4.2+ 语法
- [ ] 使用 EventSystem 进行跨模块通信
- [ ] 使用 @onready 缓存节点引用

### Step 3: 注释规范检查
- [ ] 已读取 `docs/02-开发规范/代码注释规范.md`
- [ ] 文件头注释完整
- [ ] 公共函数有完整注释
- [ ] 复杂逻辑有行内注释

### Step 4: 命名规范检查
- [ ] 已读取 `docs/02-开发规范/命名规范.md`
- [ ] 类名使用 PascalCase
- [ ] 变量/函数使用 camelCase
- [ ] 常量使用 UPPER_CASE
- [ ] 私有成员使用下划线前缀

### Step 5: 测试代码编写
- [ ] 已读取 `docs/03-技术实现/测试指南.md`
- [ ] 创建了测试文件 `tests/unit/test_[name].gd`
- [ ] 测试文件继承自 GutTest
- [ ] 编写了核心功能测试

### Step 6: 测试验证
- [ ] 运行了 GUT 测试命令
- [ ] 所有测试通过
- [ ] 如有失败，已修复并重新测试

### Step 7: Git 提交
- [ ] 已读取 `docs/02-开发规范/Git提交规范.md`
- [ ] 生成了符合规范的提交信息
- [ ] 提交类型正确
- [ ] 使用中文冒号
- [ ] 遵循"一次提交只做一件事"原则

---

## 快速自检问题

在提交代码前，问自己以下问题：

1. **架构**: 文件放在正确的位置了吗？
2. **通信**: 是否使用 EventSystem 进行跨模块通信？
3. **类型**: 所有变量和函数都有类型注解吗？
4. **命名**: 命名是否符合规范（PascalCase/camelCase/UPPER_CASE）？
5. **注释**: 文件头和公共函数有完整注释吗？
6. **测试**: 创建并运行测试了吗？所有测试都通过了吗？
7. **提交**: Git 提交信息符合规范吗？

如果以上问题都能回答"是"，那么代码已经符合 WhaleTown 项目的质量标准！✅