whale-town-front/.claude/skills/whaletown-developer/references/checklist.md

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)

---

注释规范检查清单

文件头注释

• 包含文件名
• 包含作用描述
• 列出主要功能
• 列出依赖的管理器/系统
• 包含作者和创建时间

示例：

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

函数注释

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

示例：

# 处理玩家输入并更新移动状态
#
# 参数:
#   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_[功能名称]()

测试覆盖

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

示例：

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 混合提交
• 如需多种改动，拆分成多次提交

示例：

# ✅ 正确
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 项目的质量标准！✅