refactor：重构项目架构为分层结构 #3

Merged

moyin merged 3 commits from qbb0530/whale-town-front:refactor/项目结构重构 into main

2025-12-31 16:35:25 +08:00

Author	SHA1	Message	Date
王浩	b9182bbc2e	docs：完善 CLAUDE.md 为 AI 开发规范文档 ## 🎯 主要改进 ### 1. 明确项目定位 - 清晰定义 "WhaleTown" 为 2D 俯视像素风 RPG - 指定 Godot 4.2+ 引擎（禁止 3.x 语法） - 强调分层架构：`_Core`（框架）、`Scenes`（玩法）、`UI`（界面） ### 2. 完善开发规范 - ✅ 添加 Input Map 配置（WASD、交互键、暂停键） - ✅ 明确文件路径规则（STRICT LOWERCASE） - ✅ 添加 EventNames.gd 示例代码 - ✅ 完善测试代码示例（GUT 框架） - ✅ 优化代码模板（分区注释） ### 3. 强化技术约束 - 📋 严格类型系统（强制静态类型） - 🏛 事件驱动架构（EventSystem 解耦） - 🚫 禁止模式列表（yield、Linear Filter 等） - ✅ 必须测试覆盖（所有 Core 管理器） ### 4. 代码模板改进 - 添加结构化注释（Exports、References、Lifecycle、Methods） - 展示最佳实践（@onready、%UniqueName、私有方法前缀） - 包含完整的玩家移动示例 ### 5. AI 指令优化 - 直接对 AI 说话（"Claude: Root folders MUST be lowercase"） - 明确的优先级（STRICT、The Law、MANDATORY） - 提供决策指南（Area2D vs Body、Enum vs StateChart） ## 📊 文档结构 - 90 行，精炼完整 - Emoji 视觉层级（🛠 命令、📂 文件、📋 标准、🏛 架构） - 覆盖：文件组织、编码标准、架构设计、测试要求、代码模板 ## ✨ 质量提升 - 统一路径大小写（tests/ 而非 Tests/） - 添加 EventNames.gd 完整示例 - 完善测试代码（watch_signals、assert_signal_emitted） - 明确 Godot 版本约束（4.2+） ## 🎯 目标为 AI 提供清晰、严格、可执行的开发规范，确保代码质量和架构一致性。 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>	2025-12-31 16:32:54 +08:00
王浩	642a99970c	docs：添加项目开发规范文档 CLAUDE.md ## 📋 新增内容添加了完整的 Claude Code 开发规范文档，包括： ### 核心规范 - 项目概述: 2D 俯视像素风 RPG 游戏架构 - 编码标准: - 严格类型系统 - 统一命名规范（PascalCase, snake_case, SCREAMING_SNAKE_CASE） - 节点访问规范（@onready, %UniqueName） - 最佳实践（await, Callable, Signal Up/Call Down） ### 架构规则 - 解耦原则: 低层级实体通过 EventSystem 通信 - 场景管理: 统一使用 SceneManager.change_scene() - 组件化: 可复用逻辑封装到 Scenes/Components/ ### 实现规范 - 实体结构: - Player: CharacterBody2D + Camera2D - NPC: StaticBody2D/CharacterBody2D + InteractionArea - Interactables: 共享 InteractableComponent - 交互系统: 通过 EventSystem.notify_interaction_triggered() - TileMap 规则: 分层设计（地面、障碍、装饰） ### 文件组织 - 地图: Scenes/Maps/[map_name].tscn - 实体: Scenes/Entities/[entity_name]/[entity_name].tscn - 脚本: 与场景文件同目录 - 资源: res://Assets/Sprites/ ### 测试标准 - 使用 GUT 测试框架 - 测试文件位置: res://test/unit/ 或 res://test/integration/ - 文件命名: test_*.gd - 核心逻辑必须有单元测试 - 玩家移动和 NPC 交互需要集成测试 ### 开发理念 - 简约至上：函数单一职责 - "栅栏后规则": 即使不可见的代码也要干净优美 - 反馈循环：每个交互都要有特效/音效占位 - 零硬编码：所有路径和配置使用常量或 @export - "自动工作"的相机：自动检测 TileMap 边界 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>	2025-12-31 16:07:54 +08:00
王浩	0b533189ec	refactor：重构项目架构为分层结构 ## 🏗️ 主要变更 ### 目录结构重构 - 将 core/ 迁移到 _Core/（框架层） - 将 scenes/ 重构为 Scenes/（玩法层）和 UI/（界面层） - 将 data/ 迁移到 Config/（配置层） - 添加 Assets/ 资源层和 Utils/ 工具层 - 将 scripts/ 迁移到 tools/（开发工具） ### 架构分层 - _Core/: 框架层 - 全局单例和管理器 - Scenes/: 玩法层 - 游戏场景和实体 - UI/: 界面层 - HUD、窗口、对话系统 - Assets/: 资源层 - 精灵图、音频、字体 - Config/: 配置层 - 游戏配置和本地化 - Utils/: 工具层 - 通用辅助脚本 ### 文件更新 - 更新 project.godot 中的所有路径引用 - 更新自动加载脚本路径 - 更新测试文件的引用路径 - 添加 REFACTORING.md 详细说明 - 添加 MIGRATION_COMPLETE.md 迁移完成标记 - 更新 README.md 反映新架构 ### 设计原则 - ✅ 清晰的分层（框架/玩法/界面） - ✅ 场景内聚（脚本紧邻场景文件） - ✅ 组件化设计（可复用组件） - ✅ 职责单一（每个目录职责明确） ## 📋 详细信息查看 REFACTORING.md 了解完整的重构说明和迁移映射表 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>	2025-12-31 11:36:01 +08:00

Author

SHA1

Message

Date

王浩

b9182bbc2e

docs：完善 CLAUDE.md 为 AI 开发规范文档

## 🎯 主要改进

### 1. 明确项目定位
- 清晰定义 "WhaleTown" 为 2D 俯视像素风 RPG
- 指定 Godot 4.2+ 引擎（禁止 3.x 语法）
- 强调分层架构：`_Core`（框架）、`Scenes`（玩法）、`UI`（界面）

### 2. 完善开发规范
- ✅ 添加 Input Map 配置（WASD、交互键、暂停键）
- ✅ 明确文件路径规则（STRICT LOWERCASE）
- ✅ 添加 EventNames.gd 示例代码
- ✅ 完善测试代码示例（GUT 框架）
- ✅ 优化代码模板（分区注释）

### 3. 强化技术约束
- 📋 严格类型系统（强制静态类型）
- 🏛 事件驱动架构（EventSystem 解耦）
- 🚫 禁止模式列表（yield、Linear Filter 等）
- ✅ 必须测试覆盖（所有 Core 管理器）

### 4. 代码模板改进
- 添加结构化注释（Exports、References、Lifecycle、Methods）
- 展示最佳实践（@onready、%UniqueName、私有方法前缀）
- 包含完整的玩家移动示例

### 5. AI 指令优化
- 直接对 AI 说话（"Claude: Root folders MUST be lowercase"）
- 明确的优先级（STRICT、The Law、MANDATORY）
- 提供决策指南（Area2D vs Body、Enum vs StateChart）

## 📊 文档结构
- 90 行，精炼完整
- Emoji 视觉层级（🛠 命令、📂 文件、📋 标准、🏛 架构）
- 覆盖：文件组织、编码标准、架构设计、测试要求、代码模板

## ✨ 质量提升
- 统一路径大小写（tests/ 而非 Tests/）
- 添加 EventNames.gd 完整示例
- 完善测试代码（watch_signals、assert_signal_emitted）
- 明确 Godot 版本约束（4.2+）

## 🎯 目标
为 AI 提供清晰、严格、可执行的开发规范，
确保代码质量和架构一致性。

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

2025-12-31 16:32:54 +08:00

王浩

642a99970c

docs：添加项目开发规范文档 CLAUDE.md

## 📋 新增内容

添加了完整的 Claude Code 开发规范文档，包括：

### 核心规范
- **项目概述**: 2D 俯视像素风 RPG 游戏架构
- **编码标准**:
  - 严格类型系统
  - 统一命名规范（PascalCase, snake_case, SCREAMING_SNAKE_CASE）
  - 节点访问规范（@onready, %UniqueName）
  - 最佳实践（await, Callable, Signal Up/Call Down）

### 架构规则
- **解耦原则**: 低层级实体通过 EventSystem 通信
- **场景管理**: 统一使用 SceneManager.change_scene()
- **组件化**: 可复用逻辑封装到 Scenes/Components/

### 实现规范
- **实体结构**:
  - Player: CharacterBody2D + Camera2D
  - NPC: StaticBody2D/CharacterBody2D + InteractionArea
  - Interactables: 共享 InteractableComponent
- **交互系统**: 通过 EventSystem.notify_interaction_triggered()
- **TileMap 规则**: 分层设计（地面、障碍、装饰）

### 文件组织
- 地图: Scenes/Maps/[map_name].tscn
- 实体: Scenes/Entities/[entity_name]/[entity_name].tscn
- 脚本: 与场景文件同目录
- 资源: res://Assets/Sprites/

### 测试标准
- 使用 GUT 测试框架
- 测试文件位置: res://test/unit/ 或 res://test/integration/
- 文件命名: test_*.gd
- 核心逻辑必须有单元测试
- 玩家移动和 NPC 交互需要集成测试

### 开发理念
- 简约至上：函数单一职责
- "栅栏后规则": 即使不可见的代码也要干净优美
- 反馈循环：每个交互都要有特效/音效占位
- 零硬编码：所有路径和配置使用常量或 @export
- "自动工作"的相机：自动检测 TileMap 边界

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

2025-12-31 16:07:54 +08:00

王浩

0b533189ec

refactor：重构项目架构为分层结构

## 🏗️ 主要变更

### 目录结构重构
- 将 core/ 迁移到 _Core/（框架层）
- 将 scenes/ 重构为 Scenes/（玩法层）和 UI/（界面层）
- 将 data/ 迁移到 Config/（配置层）
- 添加 Assets/ 资源层和 Utils/ 工具层
- 将 scripts/ 迁移到 tools/（开发工具）

### 架构分层
- **_Core/**: 框架层 - 全局单例和管理器
- **Scenes/**: 玩法层 - 游戏场景和实体
- **UI/**: 界面层 - HUD、窗口、对话系统
- **Assets/**: 资源层 - 精灵图、音频、字体
- **Config/**: 配置层 - 游戏配置和本地化
- **Utils/**: 工具层 - 通用辅助脚本

### 文件更新
- 更新 project.godot 中的所有路径引用
- 更新自动加载脚本路径
- 更新测试文件的引用路径
- 添加 REFACTORING.md 详细说明
- 添加 MIGRATION_COMPLETE.md 迁移完成标记
- 更新 README.md 反映新架构

### 设计原则
- ✅ 清晰的分层（框架/玩法/界面）
- ✅ 场景内聚（脚本紧邻场景文件）
- ✅ 组件化设计（可复用组件）
- ✅ 职责单一（每个目录职责明确）

## 📋 详细信息
查看 REFACTORING.md 了解完整的重构说明和迁移映射表

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

2025-12-31 11:36:01 +08:00

refactor：重构项目架构为分层结构 #3

3 Commits