Merge pull request 'feature/auth-system-refactor' (#8) from feature/auth-system-refactor into main

Reviewed-on: datawhale/whale-town-front#8

README.md

@@ -1,301 +1,395 @@
-# 🐋 whaleTown
+# 🐋 WhaleTown - 现代化像素游戏
 
-一个使用 Godot 4.5 引擎开发的现代化像素游戏项目，集成了完整的用户认证系统和API接口。
+> 一个基于 Godot 4.5 引擎开发的企业级 2D 像素风游戏，采用模块化架构设计，集成完整的用户认证系统和游戏核心功能。
 
-## 🎮 项目信息
+[![Godot](https://img.shields.io/badge/Godot-4.5+-blue.svg)](https://godotengine.org/)
+[![GDScript](https://img.shields.io/badge/GDScript-Latest-green.svg)](https://docs.godotengine.org/en/stable/tutorials/scripting/gdscript/index.html)
+[![Documentation](https://img.shields.io/badge/Documentation-Complete-brightgreen.svg)](./docs/)
+[![Platform](https://img.shields.io/badge/Platform-Windows%20%7C%20Linux%20%7C%20macOS%20%7C%20Web-lightgrey.svg)](https://godotengine.org/download)
 
-- **引擎版本**: Godot 4.5.1
-- **渲染器**: Forward Plus
-- **项目类型**: 2D 像素游戏
-- **架构模式**: 模块化 + 事件驱动
-- **后端集成**: RESTful API + 用户认证
+## 🎯 项目简介
 
-## 🚀 快速开始
+WhaleTown 是一个功能完整的现代化像素游戏，具有以下特色：
 
-### 环境要求
-- [Godot Engine 4.5+](https://godotengine.org/download)
-- Python 3.7+ (用于API测试和Web服务器)
-
-### 运行项目
-```bash
-# 1. 克隆项目
-git clone <repository-url>
-cd whale-town
-
-# 2. 使用Godot编辑器打开项目
-# 3. 按F5运行或点击"运行"按钮
-
-# 4. 测试API接口（可选）
-python tests/api/simple_api_test.py
-```
-
-### Web版本部署
-```bash
-# Windows用户
-scripts\build_web.bat      # 导出Web版本
-scripts\serve_web.bat      # 启动本地测试服务器
-
-# Linux/macOS用户
-./scripts/build_web.sh     # 导出Web版本
-./scripts/serve_web.sh     # 启动本地测试服务器
-```
-
-详细部署指南请查看: [Web部署完整指南](docs/web_deployment_guide.md)
-
-## 🏗️ 项目架构
-
-### 核心设计理念
-- **场景独立性** - 每个场景都是独立的功能模块
-- **高度解耦** - 通过事件系统和管理器通信
-- **组件复用** - 可复用组件统一管理
-- **标准化** - 统一的命名规范和目录结构
-- **测试驱动** - 完整的测试体系和文档
-
-### 目录结构
-```
-whaleTown/
-├── 🎬 scenes/           # 游戏场景
-│   ├── auth_scene.tscn     # 用户认证场景
-│   ├── main_scene.tscn     # 主游戏场景
-│   └── prefabs/            # 预制体组件
-├── 🔧 core/             # 核心系统（自动加载）
-│   ├── managers/           # 全局管理器
-│   ├── systems/            # 系统组件
-│   └── utils/              # 工具类
-├── 📝 scripts/          # 业务逻辑脚本
-│   ├── scenes/             # 场景脚本
-│   ├── network/            # 网络相关
-│   ├── build_web.bat       # Windows Web导出脚本
-│   ├── build_web.sh        # Linux/macOS Web导出脚本
-│   ├── serve_web.bat       # Windows 本地服务器
-│   ├── serve_web.sh        # Linux/macOS 本地服务器
-│   └── ui/                 # UI组件脚本
-├── 🧩 module/           # 可复用模块
-│   ├── UI/                 # UI组件模块
-│   ├── Character/          # 角色模块
-│   ├── Combat/             # 战斗模块
-│   ├── Dialogue/           # 对话模块
-│   └── Inventory/          # 背包模块
-├── 🎨 assets/           # 游戏资源
-│   ├── sprites/            # 精灵图资源
-│   ├── audio/              # 音频文件
-│   ├── ui/                 # UI界面资源
-│   ├── fonts/              # 字体资源
-│   ├── materials/          # 材质资源
-│   └── shaders/            # 着色器资源
-├── 📊 data/             # 配置数据
-│   ├── configs/            # 游戏配置
-│   ├── localization/       # 本地化文件
-│   ├── characters/         # 角色数据
-│   ├── items/              # 物品数据
-│   ├── levels/             # 关卡数据
-│   └── dialogues/          # 对话数据
-├── 🧪 tests/            # 测试文件
-│   ├── api/                # API接口测试
-│   ├── auth/               # 认证UI测试
-│   ├── unit/               # 单元测试
-│   ├── integration/        # 集成测试
-│   └── performance/        # 性能测试
-└── 📚 docs/             # 项目文档
-    ├── auth/               # 认证相关文档
-    ├── api-documentation.md # API接口文档
-    ├── web_deployment_guide.md # Web部署完整指南
-    ├── web_deployment_changelog.md # Web部署更新日志
-    ├── project_structure.md # 项目结构说明
-    ├── naming_convention.md # 命名规范
-    ├── code_comment_guide.md # 代码注释规范
-    └── git_commit_guide.md  # Git提交规范
-```
-
-### 核心系统
-项目包含以下自动加载的核心系统：
-
-- **GameManager** - 全局游戏状态管理
-- **SceneManager** - 场景切换管理  
-- **EventSystem** - 事件通信系统
-
-使用示例：
-```gdscript
-# 状态管理
-GameManager.change_state(GameManager.GameState.IN_GAME)
-
-# 场景切换
-SceneManager.change_scene("battle")
-
-# 事件通信
-EventSystem.emit_event("player_health_changed", 80)
-EventSystem.connect_event("player_died", _on_player_died)
-```
-
-## ✨ 主要功能
-
-### 🔐 用户认证系统
-- **用户注册** - 支持邮箱验证码验证
-- **用户登录** - 多种登录方式（用户名/邮箱/手机号）
-- **密码管理** - 密码重置和修改功能
-- **GitHub OAuth** - 第三方登录集成
-- **错误处理** - 完整的错误提示和频率限制
-
-### 🌐 Web版本部署
-- **自动化导出** - 一键导出Web版本
-- **本地测试服务器** - 内置HTTP服务器用于测试
-- **生产环境配置** - 完整的服务器配置指南
-- **跨平台支持** - Windows、Linux、macOS全平台支持
-- **性能优化** - 资源压缩和加载优化
-
-### 🎮 游戏功能
-- **主场景** - 游戏主界面和菜单系统
-- **认证场景** - 完整的登录注册界面
-- **状态管理** - 用户状态和游戏状态管理
-- **网络通信** - RESTful API集成
-
-### 🧪 测试体系
-- **API测试** - 完整的接口测试脚本
-- **UI测试** - 认证界面的交互测试
-- **错误场景** - 边界条件和异常处理测试
-
-## 🔧 开发规范
-
-### 命名规范
-- **场景文件**: `snake_case_scene.tscn` (如: `auth_scene.tscn`)
-- **脚本文件**: `PascalCase.gd` (如: `AuthScene.gd`)
-- **节点名称**: `camelCase` (如: `loginButton`)
-- **变量/函数**: `camelCase` (如: `playerHealth`)
-- **常量**: `UPPER_CASE` (如: `MAX_HEALTH`)
-- **资源文件**: `snake_case` (如: `bg_auth_scene.png`)
-
-### 代码注释规范
-- **文件头注释**: 说明文件用途、主要功能和依赖关系
-- **函数注释**: 包含参数说明、返回值和使用示例
-- **复杂逻辑**: 添加行内注释解释业务逻辑和设计决策
-- **特殊标记**: 使用 TODO、FIXME、NOTE 等标准标记
-- **AI辅助**: 支持AI补充注释，提供详细的上下文信息
-
-### Git 提交规范
-使用格式：`<类型>：<描述>`
-
-常用类型：`feat` `fix` `docs` `refactor` `scene` `asset` `ui` `test`
-
-```bash
-git commit -m "feat：实现用户登录功能"
-git commit -m "fix：修复429错误处理"
-git commit -m "test：添加API接口测试"
-git commit -m "docs：更新项目文档"
-```
-
-## 📚 项目文档
-
-### 核心文档
-- 📋 [项目结构详解](docs/project_structure.md) - 完整的架构说明
-- 📝 [命名规范](docs/naming_convention.md) - 详细的命名规则
-- 💬 [代码注释规范](docs/code_comment_guide.md) - 注释标准和AI辅助指南
-- 🔀 [Git提交规范](docs/git_commit_guide.md) - 提交信息标准
-- 🌐 [Web部署指南](docs/web_deployment_guide.md) - 完整的Web部署文档
-
-### API和测试文档
-- 🔌 [API接口文档](docs/api-documentation.md) - 完整的API说明和测试指南
-- 🔐 [认证系统文档](docs/auth/) - 用户认证相关文档
-- 🧪 [API测试指南](tests/api/README.md) - API测试使用方法
-- 🎮 [认证UI测试](tests/auth/README.md) - UI测试场景说明
-
-## 🛠️ 开发指南
-
-### 添加新场景
-1. 在 `scenes/` 创建场景文件
-2. 在 `scripts/scenes/` 创建对应脚本
-3. 在 `SceneManager` 中注册场景路径
-4. 使用 `SceneManager.change_scene()` 切换
-
-### 创建可复用组件
-1. 在 `module/` 对应分类下创建组件
-2. 实现标准接口
-3. 通过 `EventSystem` 与其他模块通信
-4. 在 `scenes/prefabs/` 创建预制体
-
-### 资源管理
-- 图片资源放入 `assets/sprites/` 对应分类
-- 音频文件放入 `assets/audio/` 对应分类
-- UI资源放入 `assets/ui/` 对应分类
-- 配置文件放入 `data/configs/`
-- 遵循命名规范，使用英文小写+下划线
-
-### API接口测试
-项目提供了完整的Python测试脚本来验证API接口：
-
-```bash
-# 快速测试API连通性
-python tests/api/simple_api_test.py
-
-# 完整的API功能测试
-python tests/api/api_test.py --verbose
-
-# 自定义服务器地址测试
-python tests/api/simple_api_test.py https://your-api-server.com
-```
-
-测试脚本会验证：
-- ✅ 应用状态检查
-- ✅ 用户注册和登录功能
-- ✅ 邮箱验证码发送和验证
-- ✅ 错误处理和频率限制（429错误）
-- ✅ 管理员功能和权限控制
-- ✅ 用户状态管理
-- ✅ 安全功能测试
-
-📖 查看 [API测试文档](tests/api/README.md) 了解详细使用方法
-
-### 认证UI测试
-项目还提供了Godot内置的UI测试场景：
-
-1. 在Godot编辑器中打开 `tests/auth/auth_ui_test.tscn`
-2. 运行场景进行交互式测试
-3. 测试各种错误场景和边界条件
-
-📖 查看 [认证UI测试文档](tests/auth/README.md) 了解详细使用方法
-
-## 🔧 技术栈
-
-- **游戏引擎**: Godot 4.5.1
-- **脚本语言**: GDScript
-- **架构模式**: 模块化 + 事件驱动
-- **状态管理**: 单例管理器模式
-- **通信机制**: 全局事件系统
-- **API集成**: RESTful API + JSON
-- **测试框架**: Python + Godot内置测试
-
-## 🤝 贡献指南
-
-1. Fork 项目
-2. 创建功能分支 (`git checkout -b feature/AmazingFeature`)
-3. 遵循项目的命名规范和架构设计
-4. 添加相应的测试用例
-5. 更新相关文档
-6. 提交更改 (`git commit -m 'feat：添加某个功能'`)
-7. 推送到分支 (`git push origin feature/AmazingFeature`)
-8. 开启 Pull Request
-
-### 贡献类型
-- 🐛 Bug修复
-- ✨ 新功能开发
-- 📚 文档改进
-- 🧪 测试用例
-- 🎨 UI/UX改进
-- ⚡ 性能优化
-
-## 📄 许可证
-
-本项目采用 MIT 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情
+- 🏗️ **企业级架构** - 模块化设计，高度解耦，易于扩展
+- 🔐 **完整认证系统** - 登录、注册、邮箱验证、密码管理
+- 🎮 **丰富游戏功能** - 角色系统、场景管理、事件通信
+- 🌐 **网络通信** - RESTful API集成，支持实时数据交互
+- 📚 **企业级文档** - 18个文档，覆盖开发全流程
+- 🧪 **完整测试体系** - API测试、UI测试、性能测试
+- 🚀 **一键部署** - 支持Web、桌面多平台发布
 
 ---
 
-## 🎯 项目状态
+## 🚀 5分钟快速体验
 
-- ✅ 基础架构搭建完成
-- ✅ 用户认证系统完成
-- ✅ API接口集成完成
-- ✅ 测试体系建立完成
-- ✅ 文档体系完善
-- 🚧 游戏核心玩法开发中
-- 🚧 更多功能模块开发中
+### 📋 准备工作
 
-**最后更新**: 2025-12-24
+**你需要安装：**
+- [Godot Engine 4.5+](https://godotengine.org/download) - 游戏引擎
+- [Git](https://git-scm.com/) - 版本控制工具
+
+### 🛠️ 启动项目
+
+```bash
+# 1️⃣ 获取项目
+git clone <repository-url>
+cd whale-town
+
+# 2️⃣ 打开项目
+# 双击 project.godot 文件，或在Godot编辑器中选择"导入项目"
+
+# 3️⃣ 运行游戏
+# 在Godot编辑器中按 F5 或点击"运行项目"按钮
+```
+
+🎉 **成功！** 你应该看到游戏的认证界面
+
+### 🎮 体验功能
+
+1. **注册新用户** - 体验完整的邮箱验证流程
+2. **登录系统** - 尝试用户名/邮箱登录
+3. **游戏界面** - 探索主游戏场景
+
+### 🧪 测试API（可选）
+
+```bash
+# 安装Python依赖
+pip install requests
+
+# 快速API测试
+python tests/api/quick_test.py
+
+# 完整功能测试
+python tests/api/api_client_test.py
+```
+
+---
+
+## 📚 新手开发指南
+
+### 🎯 第一步：了解项目
+
+**⚠️ 重要：开始开发前必读**
+
+1. **[📖 项目入门总览](docs/01-项目入门/README.md)** - 5分钟了解项目
+2. **[🏗️ 项目结构说明](docs/01-项目入门/项目结构说明.md)** - 理解架构设计
+3. **[⚙️ 项目设置指南](docs/01-项目入门/项目设置指南.md)** - 配置开发环境
+4. **[🤖 AI开发指南](docs/AI_docs/README.md)** - AI编程助手专用文档
+
+### 🎯 第二步：学习规范
+
+**代码质量保证**
+
+1. **[📝 命名规范](docs/02-开发规范/命名规范.md)** - 统一命名标准
+2. **[🏛️ 架构与通信规范](docs/02-开发规范/架构与通信规范.md)** - 组件通信方式
+3. **[💬 代码注释规范](docs/02-开发规范/代码注释规范.md)** - 注释标准
+4. **[🔄 Git提交规范](docs/02-开发规范/Git提交规范.md)** - 版本控制规范
+
+### 🎯 第三步：开始开发
+
+**技术实现指导**
+
+1. **[🔧 实现细节规范](docs/03-技术实现/实现细节规范.md)** - 游戏对象实现
+2. **[🌐 API接口文档](docs/03-技术实现/API接口文档.md)** - 后端接口使用
+3. **[🧪 测试指南](docs/03-技术实现/测试指南.md)** - 测试方法和工具
+
+### 🎯 第四步：高级开发
+
+**进阶技能**
+
+1. **[🚀 性能优化指南](docs/04-高级开发/性能优化指南.md)** - 性能调优
+2. **[🎬 场景设计规范](docs/04-高级开发/场景设计规范.md)** - 场景架构
+3. **[🧩 模块开发指南](docs/04-高级开发/模块开发指南.md)** - 模块化开发
+
+### 🎯 第五步：项目发布
+
+**部署和运维**
+
+1. **[🌐 Web部署指南](docs/05-部署运维/Web部署指南.md)** - 完整部署流程
+
+---
+
+## 🏗️ 项目架构一览
+
+### 📁 目录结构
+
+```
+WhaleTown/                    # 🐋 项目根目录
+├── 📚 docs/                  # 📖 完整文档系统（18个文档）
+│   ├── 01-项目入门/           # 👋 新人必读
+│   ├── 02-开发规范/           # 📋 编码标准
+│   ├── 03-技术实现/           # 🔧 开发指导
+│   ├── 04-高级开发/           # 🚀 进阶技巧
+│   ├── 05-部署运维/           # 🌐 发布部署
+│   ├── 06-功能模块/           # 🎮 功能文档
+│   └── AI_docs/              # 🤖 AI专用文档（执行规范、代码模板）
+├── 🔧 _Core/                 # ⚙️ 核心底层实现
+│   ├── managers/             # 🎯 全局管理器（游戏状态、场景、网络等）
+│   ├── systems/              # 🔄 系统组件（事件系统、输入系统等）
+│   ├── components/           # 🧩 基础组件实现
+│   ├── utils/                # <20> 核件心工具类（字符串处理、数学计算等）
+│   ├── EventNames.gd         # 📝 事件名称定义
+│   └── ProjectPaths.gd       # <20> 路径组统一管理
+├── 🎬 scenes/                # 🎭 场景与视觉呈现
+│   ├── maps/                 # <20>️ 地图一场景（游戏关卡、世界地图）
+│   ├── characters/           # 👤 人物场景（角色、NPC、敌人）
+│   ├── ui/                   # 🖼️ UI界面场景（菜单、HUD、对话框）
+│   ├── effects/              # ✨ 特效场景（粒子效果、动画）
+│   └── prefabs/              # 🧩 预制体组件
+├── 🎨 assets/                # 🖼️ 静态资源存储
+│   ├── sprites/              # 🎨 精灵图片（角色、物品、环境）
+│   ├── audio/                # 🎵 音频资源（音乐、音效）
+│   ├── fonts/                # 🔤 字体文件
+│   ├── materials/            # 🎭 材质资源
+│   ├── shaders/              # 🌈 着色器文件
+│   ├── ui/                   # 🖼️ UI素材（按钮、图标、背景）
+│   └── icon/                 # 📱 应用图标
+├── ⚙️ Config/                # 📋 配置文件管理
+│   ├── game_config.json      # 🎮 游戏配置（难度、设置等）
+│   ├── zh_CN.json            # 🌐 本地化配置
+│   └── environment/          # 🔧 环境配置（开发、测试、生产）
+├── 🧪 tests/                 # 🔬 测试文件系统
+│   ├── unit/                 # 🔍 单元测试（组件功能测试）
+│   ├── integration/          # 🔗 集成测试（系统交互测试）
+│   ├── performance/          # ⚡ 性能测试（帧率、内存优化）
+│   └── api/                  # 🌐 API接口测试
+└── 🌐 web_assets/            # 🌍 Web导出资源
+    ├── html/                 # 📄 HTML模板文件
+    ├── css/                  # 🎨 样式文件
+    └── js/                   # 📜 JavaScript脚本
+```
+
+### 🔧 核心架构说明
+
+| 目录 | 作用 | 详细说明 |
+|------|------|----------|
+| **_Core** | 🔧 功能实现与组件实现 | 项目最基本的底层实现，包含所有核心系统和基础组件 |
+| **scenes** | 🎭 场景与视觉呈现 | 包含地图场景、人物场景等一系列视觉呈现部分，主要是UI的实现 |
+| **assets** | 🎨 静态资源存储 | 所有静态资源的存储，包括图片、音乐、视频、贴图等素材 |
+| **Config** | ⚙️ 配置文件管理 | 主要用来配置各类环境，包括游戏设置、本地化等配置 |
+| **tests** | 🧪 测试文件系统 | 放置所有对应组件的测试代码，方便快速进行功能性与性能测试 |
+| **web_assets** | 🌐 Web导出资源 | 专门用于Web平台导出的相关资源和配置文件 |
+| **docs/AI_docs** | 🤖 AI专用文档 | 专门为AI编程助手准备的执行规范和代码模板，提升vibe coding效率 |
+
+### 🎮 核心组件
+
+| 组件 | 位置 | 作用 | 文档链接 |
+|------|------|------|----------|
+| **EventSystem** | _Core/systems/ | 全局事件通信系统 | [架构规范](docs/02-开发规范/架构与通信规范.md) |
+| **GameManager** | _Core/managers/ | 游戏状态管理器 | [实现细节](docs/03-技术实现/实现细节规范.md) |
+| **SceneManager** | _Core/managers/ | 场景切换管理器 | [场景设计](docs/04-高级开发/场景设计规范.md) |
+| **NetworkManager** | _Core/managers/ | 网络请求管理器 | [网络管理器](docs/03-技术实现/网络管理器设置.md) |
+| **ProjectPaths** | _Core/ | 路径统一管理工具 | [项目结构](docs/01-项目入门/项目结构说明.md) |
+
+---
+
+## 🎮 核心功能
+
+### 🔐 用户认证系统
+
+**完整的用户管理功能**
+- ✅ 用户注册（用户名+邮箱验证）
+- ✅ 多方式登录（用户名/邮箱/验证码）
+- ✅ 密码管理（修改/重置）
+- ✅ 表单验证（实时验证+友好提示）
+- ✅ 错误处理（网络异常+业务错误）
+
+**技术特色**
+- 📱 响应式UI设计
+- 🔄 实时表单验证
+- ⏰ 验证码冷却机制
+- 🎨 流畅动画效果
+
+### 🎮 游戏核心系统
+
+**模块化游戏架构**
+- 🎭 场景管理系统
+- 🔄 事件通信系统
+- 🎯 状态管理系统
+- 🌐 网络通信系统
+
+**开发友好特性**
+- 🧩 高度模块化
+- 📝 完整文档覆盖
+- 🧪 测试用例齐全
+- 🔧 开发工具完善
+
+---
+
+## 🧪 测试系统
+
+### 🔬 测试类型
+
+| 测试类型 | 工具 | 覆盖范围 | 文档 |
+|----------|------|----------|------|
+| **API测试** | Python脚本 | 17个接口全覆盖 | [测试指南](docs/03-技术实现/测试指南.md) |
+| **UI测试** | Godot场景 | 认证流程完整测试 | [认证测试](docs/06-功能模块/auth/认证测试指南.md) |
+| **单元测试** | GUT框架 | 核心组件测试 | [测试指南](docs/03-技术实现/测试指南.md) |
+
+### 🚀 快速测试
+
+```bash
+# 🔌 API接口测试（30秒）
+python tests/api/quick_test.py
+
+# 🔍 完整功能测试（2-3分钟）
+python tests/api/api_client_test.py
+
+# 🎮 UI交互测试（在Godot中运行）
+# 打开 tests/auth/auth_ui_test.tscn 场景
+```
+
+---
+
+## 🚀 部署发布
+
+### 🖥️ 桌面版本
+
+```bash
+# Windows
+godot --export "Windows Desktop" build/WhaleTown.exe
+
+# Linux
+godot --export "Linux/X11" build/WhaleTown.x86_64
+
+# macOS
+godot --export "macOS" build/WhaleTown.app
+```
+
+### 🌐 Web版本
+
+```bash
+# 使用自动化脚本
+scripts/build_web.bat        # Windows
+scripts/build_web.sh         # Linux/macOS
+
+# 本地测试
+scripts/serve_web.bat        # 启动本地服务器
+```
+
+**详细部署流程**: [Web部署指南](docs/05-部署运维/Web部署指南.md)
+
+---
+
+## 📊 项目统计
+
+### 📚 文档系统
+
+| 类别 | 文档数 | 完成度 |
+|------|--------|--------|
+| 项目入门 | 3 | 100% |
+| 开发规范 | 5 | 100% |
+| 技术实现 | 4 | 100% |
+| 高级开发 | 3 | 100% |
+| 部署运维 | 1 | 100% |
+| 功能模块 | 2 | 100% |
+| **总计** | **18** | **100%** |
+
+### 🧪 测试覆盖
+
+- **API接口**: 17个接口 ✅
+- **认证流程**: 完整测试 ✅
+- **错误处理**: 边界测试 ✅
+- **性能监控**: 帧率/内存 ✅
+
+---
+
+## 🤝 参与贡献
+
+### 🌟 贡献方式
+
+1. **🐛 Bug修复** - 发现并修复问题
+2. **✨ 新功能** - 添加有价值的功能
+3. **📚 文档改进** - 完善项目文档
+4. **🧪 测试用例** - 提高代码覆盖率
+5. **🎨 UI/UX改进** - 提升用户体验
+
+### 📋 贡献流程
+
+```bash
+# 1️⃣ Fork项目到你的账户
+
+# 2️⃣ 克隆到本地
+git clone <your-fork-url>
+cd whale-town
+
+# 3️⃣ 创建功能分支
+git checkout -b feature/your-feature
+
+# 4️⃣ 开发功能（遵循项目规范）
+# 参考: docs/02-开发规范/
+
+# 5️⃣ 添加测试用例
+# 参考: docs/03-技术实现/测试指南.md
+
+# 6️⃣ 提交代码
+git commit -m "feat：添加新功能"
+# 参考: docs/02-开发规范/Git提交规范.md
+
+# 7️⃣ 推送分支
+git push origin feature/your-feature
+
+# 8️⃣ 创建Pull Request
+```
+
+### 📖 开发规范
+
+**必读文档**：
+- [命名规范](docs/02-开发规范/命名规范.md) - 代码命名标准
+- [Git提交规范](docs/02-开发规范/Git提交规范.md) - 提交信息格式
+- [代码注释规范](docs/02-开发规范/代码注释规范.md) - 注释标准
+
+### 🙏 贡献者致谢
+
+感谢所有为 WhaleTown 项目做出贡献的开发者们！详细的贡献者信息和统计请查看：
+
+**[📖 贡献者详细信息](docs/CONTRIBUTORS.md)**
+
+---
+
+## 📞 获取帮助
+
+### 🔍 问题解决
+
+| 问题类型 | 解决方案 |
+|----------|----------|
+| **🤔 不知道从哪开始** | [项目入门总览](docs/01-项目入门/README.md) |
+| **🏗️ 不理解项目架构** | [项目结构说明](docs/01-项目入门/项目结构说明.md) |
+| **🔧 开发环境问题** | [项目设置指南](docs/01-项目入门/项目设置指南.md) |
+| **📝 不知道怎么命名** | [命名规范](docs/02-开发规范/命名规范.md) |
+| **🔄 组件通信问题** | [架构与通信规范](docs/02-开发规范/架构与通信规范.md) |
+| **🌐 API调用问题** | [API接口文档](docs/03-技术实现/API接口文档.md) |
+| **🧪 测试相关问题** | [测试指南](docs/03-技术实现/测试指南.md) |
+| **🚀 部署发布问题** | [Web部署指南](docs/05-部署运维/Web部署指南.md) |
+
+### 📚 文档导航
+
+- **[📖 完整文档中心](docs/README.md)** - 所有文档的导航页面
+- **[📋 文档更新日志](docs/CHANGELOG.md)** - 文档版本变更记录
+
+### 💬 联系方式
+
+- **项目地址**: [Gitea Repository](https://gitea.xinghangee.icu/datawhale/whale-town)
+- **问题反馈**: [Issues](https://gitea.xinghangee.icu/datawhale/whale-town/issues)
+- **功能建议**: [Discussions](https://gitea.xinghangee.icu/datawhale/whale-town/discussions)
+
+---
+
+## 📄 许可证
+
+本项目采用 [MIT License](./LICENSE) 开源协议。
+
+---
+
+<div align="center">
+
+**🐋 WhaleTown - 企业级像素游戏开发框架**
+
+*让游戏开发更简单，让代码质量更优秀*
+
+[⭐ Star](https://gitea.xinghangee.icu/datawhale/whale-town) | [🍴 Fork](https://gitea.xinghangee.icu/datawhale/whale-town/fork) | [📖 文档](./docs/) | [🐛 反馈](https://gitea.xinghangee.icu/datawhale/whale-town/issues)
+
+**文档版本**: v1.2.0 | **最后更新**: 2025-12-31
+
+</div>

_Core/EventNames.gd

@@ -0,0 +1,58 @@
+# ============================================================================
+# 事件名称定义 - EventNames.gd
+# 
+# 定义项目中所有事件的名称常量，确保事件名称的一致性和可维护性
+# 
+# 使用方式:
+#   EventSystem.emit_event(EventNames.PLAYER_MOVED, data)
+#   EventSystem.connect_event(EventNames.INTERACT_PRESSED, callback)
+# ============================================================================
+
+class_name EventNames
+
+# ============================================================================
+# 玩家相关事件
+# ============================================================================
+const PLAYER_MOVED = "player_moved"
+const PLAYER_SPAWNED = "player_spawned"
+const PLAYER_HEALTH_CHANGED = "player_health_changed"
+const PLAYER_DIED = "player_died"
+const PLAYER_RESPAWNED = "player_respawned"
+const PLAYER_ATTACK = "player_attack"
+
+# ============================================================================
+# 交互事件
+# ============================================================================
+const INTERACT_PRESSED = "interact_pressed"
+const NPC_TALKED = "npc_talked"
+const ITEM_COLLECTED = "item_collected"
+const OBJECT_INTERACTED = "object_interacted"
+
+# ============================================================================
+# UI事件
+# ============================================================================
+const UI_BUTTON_CLICKED = "ui_button_clicked"
+const DIALOG_OPENED = "dialog_opened"
+const DIALOG_CLOSED = "dialog_closed"
+const MENU_OPENED = "menu_opened"
+const MENU_CLOSED = "menu_closed"
+
+# ============================================================================
+# 游戏状态事件
+# ============================================================================
+const GAME_PAUSED = "game_paused"
+const GAME_RESUMED = "game_resumed"
+const SCENE_CHANGED = "scene_changed"
+const SCENE_DATA_TRANSFER = "scene_data_transfer"
+
+# ============================================================================
+# 系统事件
+# ============================================================================
+const TILEMAP_READY = "tilemap_ready"
+const COMPONENT_MESSAGE = "component_message"
+const POSITION_UPDATE = "position_update"
+
+# ============================================================================
+# 测试事件
+# ============================================================================
+const TEST_EVENT = "test_event"

_Core/EventNames.gd.uid

@@ -0,0 +1 @@
+uid://qn0imbklx1m0

_Core/ProjectPaths.gd

@@ -0,0 +1,109 @@
+# ============================================================================
+# 项目路径配置 - ProjectPaths.gd
+# 
+# 统一管理项目中所有路径常量，确保路径的一致性和可维护性
+# 
+# 使用方式:
+#   var scene_path = ProjectPaths.SCENES_COMPONENTS + "ui/Button.tscn"
+#   var config_path = ProjectPaths.DATA_CONFIG + "game_config.json"
+# ============================================================================
+
+class_name ProjectPaths
+
+# ============================================================================
+# 核心系统路径
+# ============================================================================
+const CORE_ROOT = "res://_Core/"
+const CORE_MANAGERS = CORE_ROOT + "managers/"
+const CORE_SYSTEMS = CORE_ROOT + "systems/"
+const CORE_COMPONENTS = CORE_ROOT + "components/"
+const CORE_UTILS = CORE_ROOT + "utils/"
+
+# ============================================================================
+# 场景路径
+# ============================================================================
+const SCENES_ROOT = "res://scenes/"
+const SCENES_MAPS = SCENES_ROOT + "Maps/"
+const SCENES_COMPONENTS = SCENES_ROOT + "Components/"
+const SCENES_UI_COMPONENTS = SCENES_COMPONENTS + "ui/"
+const SCENES_CHARACTER_COMPONENTS = SCENES_COMPONENTS + "characters/"
+const SCENES_EFFECT_COMPONENTS = SCENES_COMPONENTS + "effects/"
+const SCENES_ITEM_COMPONENTS = SCENES_COMPONENTS + "items/"
+
+# ============================================================================
+# UI路径
+# ============================================================================
+const UI_ROOT = "res://scenes/ui/"
+const UI_WINDOWS = UI_ROOT
+
+# ============================================================================
+# 资源路径
+# ============================================================================
+const ASSETS_ROOT = "res://assets/"
+const ASSETS_SPRITES = ASSETS_ROOT + "sprites/"
+const ASSETS_AUDIO = ASSETS_ROOT + "audio/"
+const ASSETS_FONTS = ASSETS_ROOT + "fonts/"
+const ASSETS_MATERIALS = ASSETS_ROOT + "materials/"
+const ASSETS_SHADERS = ASSETS_ROOT + "shaders/"
+
+# ============================================================================
+# 数据路径
+# ============================================================================
+const DATA_ROOT = "res://data/"
+const DATA_CONFIG = "res://Config/"
+const DATA_SCENES = DATA_ROOT + "scenes/"
+const DATA_LEVELS = DATA_ROOT + "levels/"
+const DATA_DIALOGUES = DATA_ROOT + "dialogues/"
+
+# ============================================================================
+# Web资源路径
+# ============================================================================
+const WEB_ASSETS = "res://web_assets/"
+
+# ============================================================================
+# 测试路径
+# ============================================================================
+const TESTS_ROOT = "res://tests/"
+const TESTS_UNIT = TESTS_ROOT + "unit/"
+const TESTS_INTEGRATION = TESTS_ROOT + "integration/"
+const TESTS_AUTH = TESTS_ROOT + "auth/"
+
+# ============================================================================
+# 工具路径
+# ============================================================================
+const UTILS_ROOT = "res://_Core/utils/"
+
+# ============================================================================
+# 模块路径
+# ============================================================================
+const MODULES_ROOT = "res://module/"
+
+# ============================================================================
+# 辅助方法
+# ============================================================================
+
+# 获取场景组件路径
+static func get_component_path(category: String, component_name: String) -> String:
+	match category:
+		"ui":
+			return SCENES_UI_COMPONENTS + component_name + ".tscn"
+		"characters":
+			return SCENES_CHARACTER_COMPONENTS + component_name + ".tscn"
+		"effects":
+			return SCENES_EFFECT_COMPONENTS + component_name + ".tscn"
+		"items":
+			return SCENES_ITEM_COMPONENTS + component_name + ".tscn"
+		_:
+			return SCENES_COMPONENTS + component_name + ".tscn"
+
+# 获取模块路径
+static func get_module_path(module_name: String) -> String:
+	return MODULES_ROOT + module_name + "/"
+
+# 获取模块配置路径
+static func get_module_config_path(module_name: String) -> String:
+	return get_module_path(module_name) + "data/module_config.json"
+
+# 获取场景数据路径
+static func get_scene_data_path(scene_name: String) -> String:
+	return DATA_SCENES + scene_name.to_lower() + ".json"

_Core/ProjectPaths.gd.uid

@@ -0,0 +1 @@
+uid://dybcuscku7tyl

_Core/components/.gitkeep

@@ -0,0 +1,2 @@
+# 基础组件实现目录
+# 存放项目的基础组件类

_Core/managers/AuthManager.gd

@@ -0,0 +1,589 @@
+class_name AuthManager
+
+# ============================================================================
+# AuthManager.gd - 认证管理器
+# ============================================================================
+# 认证系统的业务逻辑管理器，负责处理所有认证相关的业务逻辑
+# 
+# 核心职责:
+# - 用户登录业务逻辑（密码登录 + 验证码登录）
+# - 用户注册业务逻辑
+# - 表单验证逻辑
+# - 验证码管理逻辑
+# - 网络请求管理
+# - 响应处理和状态管理
+#
+# 使用方式:
+#   var auth_manager = AuthManager.new()
+#   auth_manager.login_success.connect(_on_login_success)
+#   auth_manager.execute_password_login(username, password)
+#
+# 注意事项:
+# - 这是业务逻辑层，不包含任何UI相关代码
+# - 通过信号与UI层通信
+# - 所有验证逻辑都在这里实现
+# ============================================================================
+
+extends RefCounted
+
+# ============ 信号定义 ============
+
+# 登录成功信号
+signal login_success(username: String)
+
+# 登录失败信号
+signal login_failed(message: String)
+
+# 注册成功信号
+signal register_success(message: String)
+
+# 注册失败信号
+signal register_failed(message: String)
+
+# 验证码发送成功信号
+signal verification_code_sent(message: String)
+
+# 验证码发送失败信号
+signal verification_code_failed(message: String)
+
+# 表单验证失败信号
+signal form_validation_failed(field: String, message: String)
+
+# 网络状态变化信号
+signal network_status_changed(is_connected: bool, message: String)
+
+# 按钮状态变化信号
+signal button_state_changed(button_name: String, is_loading: bool, text: String)
+
+# Toast消息信号
+signal show_toast_message(message: String, is_success: bool)
+
+# ============ 枚举定义 ============
+
+# 登录模式枚举
+enum LoginMode {
+	PASSWORD,      # 密码登录模式
+	VERIFICATION   # 验证码登录模式
+}
+
+# ============ 成员变量 ============
+
+# 登录状态
+var current_login_mode: LoginMode = LoginMode.PASSWORD
+var is_processing: bool = false
+
+# 验证码管理
+var verification_codes_sent: Dictionary = {}
+var code_cooldown: float = 60.0
+var current_email: String = ""
+
+# 网络请求管理
+var active_request_ids: Array = []
+
+# ============ 生命周期方法 ============
+
+# 初始化管理器
+func _init():
+	print("AuthManager 初始化完成")
+
+# 清理资源
+func cleanup():
+	# 取消所有活动的网络请求
+	for request_id in active_request_ids:
+		NetworkManager.cancel_request(request_id)
+	active_request_ids.clear()
+
+# ============ 登录相关方法 ============
+
+# 执行密码登录
+# 
+# 参数:
+#   username: String - 用户名/邮箱
+#   password: String - 密码
+# 
+# 功能:
+# - 验证输入参数
+# - 发送登录请求
+# - 处理响应结果
+func execute_password_login(username: String, password: String):
+	if is_processing:
+		show_toast_message.emit("请等待当前操作完成", false)
+		return
+	
+	# 验证输入
+	var validation_result = validate_login_inputs(username, password)
+	if not validation_result.valid:
+		form_validation_failed.emit(validation_result.field, validation_result.message)
+		return
+	
+	# 设置处理状态
+	is_processing = true
+	button_state_changed.emit("main_btn", true, "登录中...")
+	show_toast_message.emit("正在验证登录信息...", true)
+	
+	# 发送网络请求
+	var request_id = NetworkManager.login(username, password, _on_login_response)
+	if request_id != "":
+		active_request_ids.append(request_id)
+	else:
+		_reset_login_state()
+		show_toast_message.emit("网络请求失败", false)
+
+# 执行验证码登录
+# 
+# 参数:
+#   identifier: String - 用户标识符
+#   verification_code: String - 验证码
+func execute_verification_login(identifier: String, verification_code: String):
+	if is_processing:
+		show_toast_message.emit("请等待当前操作完成", false)
+		return
+	
+	# 验证输入
+	if identifier.is_empty():
+		form_validation_failed.emit("username", "请输入用户名/手机/邮箱")
+		return
+	
+	if verification_code.is_empty():
+		form_validation_failed.emit("verification", "请输入验证码")
+		return
+	
+	# 设置处理状态
+	is_processing = true
+	button_state_changed.emit("main_btn", true, "登录中...")
+	show_toast_message.emit("正在验证验证码...", true)
+	
+	# 发送网络请求
+	var request_id = NetworkManager.verification_code_login(identifier, verification_code, _on_verification_login_response)
+	if request_id != "":
+		active_request_ids.append(request_id)
+	else:
+		_reset_login_state()
+		show_toast_message.emit("网络请求失败", false)
+
+# 切换登录模式
+func toggle_login_mode():
+	if current_login_mode == LoginMode.PASSWORD:
+		current_login_mode = LoginMode.VERIFICATION
+	else:
+		current_login_mode = LoginMode.PASSWORD
+
+# 获取当前登录模式
+func get_current_login_mode() -> LoginMode:
+	return current_login_mode
+
+# ============ 注册相关方法 ============
+
+# 执行用户注册
+# 
+# 参数:
+#   username: String - 用户名
+#   email: String - 邮箱
+#   password: String - 密码
+#   confirm_password: String - 确认密码
+#   verification_code: String - 邮箱验证码
+func execute_register(username: String, email: String, password: String, confirm_password: String, verification_code: String):
+	if is_processing:
+		show_toast_message.emit("请等待当前操作完成", false)
+		return
+	
+	# 验证注册表单
+	var validation_result = validate_register_form(username, email, password, confirm_password, verification_code)
+	if not validation_result.valid:
+		form_validation_failed.emit(validation_result.field, validation_result.message)
+		return
+	
+	# 设置处理状态
+	is_processing = true
+	button_state_changed.emit("register_btn", true, "注册中...")
+	show_toast_message.emit("正在创建账户...", true)
+	
+	# 发送注册请求
+	var request_id = NetworkManager.register(username, password, username, email, verification_code, _on_register_response)
+	if request_id != "":
+		active_request_ids.append(request_id)
+	else:
+		_reset_register_state()
+		show_toast_message.emit("网络请求失败", false)
+
+# ============ 验证码相关方法 ============
+
+# 发送邮箱验证码
+# 
+# 参数:
+#   email: String - 邮箱地址
+func send_email_verification_code(email: String):
+	# 验证邮箱格式
+	var email_validation = validate_email(email)
+	if not email_validation.valid:
+		form_validation_failed.emit("email", email_validation.message)
+		return
+	
+	# 检查冷却时间
+	if not _can_send_verification_code(email):
+		var remaining = get_remaining_cooldown_time(email)
+		show_toast_message.emit("该邮箱请等待 %d 秒后再次发送" % remaining, false)
+		return
+	
+	# 记录发送状态
+	_record_verification_code_sent(email)
+	
+	# 发送请求
+	var request_id = NetworkManager.send_email_verification(email, _on_send_code_response)
+	if request_id != "":
+		active_request_ids.append(request_id)
+	else:
+		_reset_verification_code_state(email)
+		show_toast_message.emit("网络请求失败", false)
+
+# 发送登录验证码
+# 
+# 参数:
+#   identifier: String - 用户标识符
+func send_login_verification_code(identifier: String):
+	if identifier.is_empty():
+		form_validation_failed.emit("username", "请先输入用户名/手机/邮箱")
+		return
+	
+	button_state_changed.emit("get_code_btn", true, "发送中...")
+	show_toast_message.emit("正在发送登录验证码...", true)
+	
+	var request_id = NetworkManager.send_login_verification_code(identifier, _on_send_login_code_response)
+	if request_id != "":
+		active_request_ids.append(request_id)
+	else:
+		button_state_changed.emit("get_code_btn", false, "获取验证码")
+		show_toast_message.emit("网络请求失败", false)
+
+# 发送密码重置验证码
+# 
+# 参数:
+#   identifier: String - 用户标识符
+func send_password_reset_code(identifier: String):
+	if identifier.is_empty():
+		show_toast_message.emit("请先输入邮箱或手机号", false)
+		return
+	
+	if not _is_valid_identifier(identifier):
+		show_toast_message.emit("请输入有效的邮箱或手机号", false)
+		return
+	
+	button_state_changed.emit("forgot_password_btn", true, "发送中...")
+	show_toast_message.emit("正在发送密码重置验证码...", true)
+	
+	var request_id = NetworkManager.forgot_password(identifier, _on_forgot_password_response)
+	if request_id != "":
+		active_request_ids.append(request_id)
+	else:
+		button_state_changed.emit("forgot_password_btn", false, "忘记密码")
+		show_toast_message.emit("网络请求失败", false)
+
+# ============ 验证方法 ============
+
+# 验证登录输入
+func validate_login_inputs(username: String, password: String) -> Dictionary:
+	var result = {"valid": false, "field": "", "message": ""}
+	
+	if username.is_empty():
+		result.field = "username"
+		result.message = "用户名不能为空"
+		return result
+	
+	if password.is_empty():
+		result.field = "password"
+		result.message = "密码不能为空"
+		return result
+	
+	result.valid = true
+	return result
+
+# 验证注册表单
+func validate_register_form(username: String, email: String, password: String, confirm_password: String, verification_code: String) -> Dictionary:
+	var result = {"valid": false, "field": "", "message": ""}
+	
+	# 验证用户名
+	var username_validation = validate_username(username)
+	if not username_validation.valid:
+		result.field = "username"
+		result.message = username_validation.message
+		return result
+	
+	# 验证邮箱
+	var email_validation = validate_email(email)
+	if not email_validation.valid:
+		result.field = "email"
+		result.message = email_validation.message
+		return result
+	
+	# 验证密码
+	var password_validation = validate_password(password)
+	if not password_validation.valid:
+		result.field = "password"
+		result.message = password_validation.message
+		return result
+	
+	# 验证确认密码
+	var confirm_validation = validate_confirm_password(password, confirm_password)
+	if not confirm_validation.valid:
+		result.field = "confirm"
+		result.message = confirm_validation.message
+		return result
+	
+	# 验证验证码
+	var code_validation = validate_verification_code(verification_code)
+	if not code_validation.valid:
+		result.field = "verification"
+		result.message = code_validation.message
+		return result
+	
+	# 检查是否已发送验证码
+	if not _has_sent_verification_code(email):
+		result.field = "verification"
+		result.message = "请先获取邮箱验证码"
+		return result
+	
+	result.valid = true
+	return result
+
+# 验证用户名
+func validate_username(username: String) -> Dictionary:
+	var result = {"valid": false, "message": ""}
+	
+	if username.is_empty():
+		result.message = "用户名不能为空"
+		return result
+	
+	if not StringUtils.is_valid_username(username):
+		if username.length() > 50:
+			result.message = "用户名长度不能超过50字符"
+		else:
+			result.message = "用户名只能包含字母、数字和下划线"
+		return result
+	
+	result.valid = true
+	return result
+
+# 验证邮箱
+func validate_email(email: String) -> Dictionary:
+	var result = {"valid": false, "message": ""}
+	
+	if email.is_empty():
+		result.message = "邮箱不能为空"
+		return result
+	
+	if not StringUtils.is_valid_email(email):
+		result.message = "请输入有效的邮箱地址"
+		return result
+	
+	result.valid = true
+	return result
+
+# 验证密码
+func validate_password(password: String) -> Dictionary:
+	return StringUtils.validate_password_strength(password)
+
+# 验证确认密码
+func validate_confirm_password(password: String, confirm: String) -> Dictionary:
+	var result = {"valid": false, "message": ""}
+	
+	if confirm.is_empty():
+		result.message = "确认密码不能为空"
+		return result
+	
+	if password != confirm:
+		result.message = "两次输入的密码不一致"
+		return result
+	
+	result.valid = true
+	return result
+
+# 验证验证码
+func validate_verification_code(code: String) -> Dictionary:
+	var result = {"valid": false, "message": ""}
+	
+	if code.is_empty():
+		result.message = "验证码不能为空"
+		return result
+	
+	if code.length() != 6:
+		result.message = "验证码必须是6位数字"
+		return result
+	
+	for i in range(code.length()):
+		var character = code[i]
+		if not (character >= '0' and character <= '9'):
+			result.message = "验证码必须是6位数字"
+			return result
+	
+	result.valid = true
+	return result
+
+# ============ 网络响应处理 ============
+
+# 处理登录响应
+func _on_login_response(success: bool, data: Dictionary, error_info: Dictionary):
+	_reset_login_state()
+	
+	var result = ResponseHandler.handle_login_response(success, data, error_info)
+	
+	if result.should_show_toast:
+		show_toast_message.emit(result.message, result.success)
+	
+	if result.success:
+		var username = ""
+		if data.has("data") and data.data.has("user") and data.data.user.has("username"):
+			username = data.data.user.username
+		
+		# 延迟发送登录成功信号
+		await Engine.get_main_loop().create_timer(1.0).timeout
+		login_success.emit(username)
+	else:
+		login_failed.emit(result.message)
+
+# 处理验证码登录响应
+func _on_verification_login_response(success: bool, data: Dictionary, error_info: Dictionary):
+	_reset_login_state()
+	
+	var result = ResponseHandler.handle_verification_code_login_response(success, data, error_info)
+	
+	if result.should_show_toast:
+		show_toast_message.emit(result.message, result.success)
+	
+	if result.success:
+		var username = ""
+		if data.has("data") and data.data.has("user") and data.data.user.has("username"):
+			username = data.data.user.username
+		
+		await Engine.get_main_loop().create_timer(1.0).timeout
+		login_success.emit(username)
+	else:
+		login_failed.emit(result.message)
+
+# 处理注册响应
+func _on_register_response(success: bool, data: Dictionary, error_info: Dictionary):
+	_reset_register_state()
+	
+	var result = ResponseHandler.handle_register_response(success, data, error_info)
+	
+	if result.should_show_toast:
+		show_toast_message.emit(result.message, result.success)
+	
+	if result.success:
+		register_success.emit(result.message)
+	else:
+		register_failed.emit(result.message)
+
+# 处理发送验证码响应
+func _on_send_code_response(success: bool, data: Dictionary, error_info: Dictionary):
+	var result = ResponseHandler.handle_send_verification_code_response(success, data, error_info)
+	
+	if result.should_show_toast:
+		show_toast_message.emit(result.message, result.success)
+	
+	if result.success:
+		verification_code_sent.emit(result.message)
+	else:
+		verification_code_failed.emit(result.message)
+		_reset_verification_code_state(current_email)
+
+# 处理发送登录验证码响应
+func _on_send_login_code_response(success: bool, data: Dictionary, error_info: Dictionary):
+	button_state_changed.emit("get_code_btn", false, "获取验证码")
+	
+	var result = ResponseHandler.handle_send_login_code_response(success, data, error_info)
+	
+	if result.should_show_toast:
+		show_toast_message.emit(result.message, result.success)
+
+# 处理忘记密码响应
+func _on_forgot_password_response(success: bool, data: Dictionary, error_info: Dictionary):
+	button_state_changed.emit("forgot_password_btn", false, "忘记密码")
+	
+	var result = ResponseHandler.handle_send_login_code_response(success, data, error_info)
+	
+	if result.should_show_toast:
+		show_toast_message.emit(result.message, result.success)
+
+# ============ 网络测试 ============
+
+# 测试网络连接
+func test_network_connection():
+	var request_id = NetworkManager.get_app_status(_on_network_test_response)
+	if request_id != "":
+		active_request_ids.append(request_id)
+
+# 处理网络测试响应
+func _on_network_test_response(success: bool, data: Dictionary, error_info: Dictionary):
+	var result = ResponseHandler.handle_network_test_response(success, data, error_info)
+	network_status_changed.emit(result.success, result.message)
+
+# ============ 私有辅助方法 ============
+
+# 重置登录状态
+func _reset_login_state():
+	is_processing = false
+	button_state_changed.emit("main_btn", false, "进入小镇")
+
+# 重置注册状态
+func _reset_register_state():
+	is_processing = false
+	button_state_changed.emit("register_btn", false, "注册")
+
+# 检查是否可以发送验证码
+func _can_send_verification_code(email: String) -> bool:
+	if not verification_codes_sent.has(email):
+		return true
+	
+	var email_data = verification_codes_sent[email]
+	if not email_data.sent:
+		return true
+	
+	var current_time = Time.get_time_dict_from_system()
+	var current_timestamp = current_time.hour * 3600 + current_time.minute * 60 + current_time.second
+	
+	return (current_timestamp - email_data.time) >= code_cooldown
+
+# 获取剩余冷却时间
+func get_remaining_cooldown_time(email: String) -> int:
+	if not verification_codes_sent.has(email):
+		return 0
+	
+	var email_data = verification_codes_sent[email]
+	var current_time = Time.get_time_dict_from_system()
+	var current_timestamp = current_time.hour * 3600 + current_time.minute * 60 + current_time.second
+	
+	return int(code_cooldown - (current_timestamp - email_data.time))
+
+# 记录验证码发送状态
+func _record_verification_code_sent(email: String):
+	var current_time = Time.get_time_dict_from_system()
+	var current_timestamp = current_time.hour * 3600 + current_time.minute * 60 + current_time.second
+	
+	if not verification_codes_sent.has(email):
+		verification_codes_sent[email] = {}
+	
+	verification_codes_sent[email].sent = true
+	verification_codes_sent[email].time = current_timestamp
+	current_email = email
+
+# 重置验证码状态
+func _reset_verification_code_state(email: String):
+	if verification_codes_sent.has(email):
+		verification_codes_sent[email].sent = false
+
+# 检查是否已发送验证码
+func _has_sent_verification_code(email: String) -> bool:
+	if not verification_codes_sent.has(email):
+		return false
+	
+	return verification_codes_sent[email].get("sent", false)
+
+# 验证标识符格式
+func _is_valid_identifier(identifier: String) -> bool:
+	return StringUtils.is_valid_email(identifier) or _is_valid_phone(identifier)
+
+# 验证手机号格式
+func _is_valid_phone(phone: String) -> bool:
+	var regex = RegEx.new()
+	regex.compile("^\\+?[1-9]\\d{1,14}$")
+	return regex.search(phone) != null

_Core/managers/AuthManager.gd.uid

@@ -0,0 +1 @@
+uid://bpdyraefv0yta

_Core/managers/GameManager.gd

@@ -0,0 +1,142 @@
+extends Node
+
+# ============================================================================
+# GameManager.gd - 游戏管理器
+# ============================================================================
+# 全局单例管理器，负责游戏状态管理和生命周期控制
+# 
+# 核心职责:
+# - 游戏状态切换 (加载、认证、游戏中、暂停等)
+# - 用户信息管理
+# - 全局配置访问
+# - 系统初始化和清理
+#
+# 使用方式:
+#   GameManager.change_state(GameManager.GameState.IN_GAME)
+#   GameManager.set_current_user("player123")
+#
+# 注意事项:
+# - 作为自动加载单例，全局可访问
+# - 状态变更会触发 game_state_changed 信号
+# - 状态切换应该通过 change_state() 方法进行
+# ============================================================================
+
+# ============ 信号定义 ============
+
+# 游戏状态变更信号
+# 参数: new_state - 新的游戏状态
+signal game_state_changed(new_state: GameState)
+
+# ============ 枚举定义 ============
+
+# 游戏状态枚举
+# 定义了游戏的各种运行状态
+enum GameState {
+	LOADING,    # 加载中 - 游戏启动时的初始化状态
+	AUTH,       # 认证状态 - 用户登录/注册界面
+	MAIN_MENU,  # 主菜单 - 游戏主界面
+	IN_GAME,    # 游戏中 - 正在进行游戏
+	PAUSED,     # 暂停 - 游戏暂停状态
+	SETTINGS    # 设置 - 设置界面
+}
+
+# ============ 成员变量 ============
+
+# 状态管理
+var current_state: GameState = GameState.LOADING    # 当前游戏状态
+var previous_state: GameState = GameState.LOADING   # 上一个游戏状态
+
+# 用户信息
+var current_user: String = ""                       # 当前登录用户名
+
+# 游戏配置
+var game_version: String = "1.0.0"                  # 游戏版本号
+
+# ============ 生命周期方法 ============
+
+# 初始化游戏管理器
+# 在节点准备就绪时调用，设置初始状态
+func _ready():
+	print("GameManager 初始化完成")
+	change_state(GameState.AUTH)  # 启动时进入认证状态
+
+# ============ 状态管理方法 ============
+
+# 切换游戏状态
+# 
+# 参数:
+#   new_state: GameState - 要切换到的新状态
+# 
+# 功能:
+# - 检查状态是否需要切换
+# - 记录状态变更历史
+# - 发送状态变更信号
+# - 输出状态变更日志
+func change_state(new_state: GameState):
+	# 避免重复切换到相同状态
+	if current_state == new_state:
+		return
+	
+	# 记录状态变更
+	previous_state = current_state
+	current_state = new_state
+	
+	# 输出状态变更日志
+	print("游戏状态变更: ", GameState.keys()[previous_state], " -> ", GameState.keys()[current_state])
+	
+	# 发送状态变更信号
+	game_state_changed.emit(new_state)
+
+# 获取当前游戏状态
+# 
+# 返回值:
+#   GameState - 当前的游戏状态
+func get_current_state() -> GameState:
+	return current_state
+
+# 获取上一个游戏状态
+# 
+# 返回值:
+#   GameState - 上一个游戏状态
+# 
+# 使用场景:
+# - 从暂停状态恢复时，返回到之前的状态
+# - 错误处理时回退到安全状态
+func get_previous_state() -> GameState:
+	return previous_state
+
+# ============ 用户管理方法 ============
+
+# 设置当前登录用户
+# 
+# 参数:
+#   username: String - 用户名
+# 
+# 功能:
+# - 存储当前登录用户信息
+# - 输出用户设置日志
+# 
+# 注意事项:
+# - 用户登录成功后调用此方法
+# - 用户登出时应传入空字符串
+func set_current_user(username: String):
+	current_user = username
+	print("当前用户设置为: ", username)
+
+# 获取当前登录用户
+# 
+# 返回值:
+#   String - 当前登录的用户名，未登录时为空字符串
+func get_current_user() -> String:
+	return current_user
+
+# 检查用户是否已登录
+# 
+# 返回值:
+#   bool - true表示已登录，false表示未登录
+# 
+# 使用场景:
+# - 进入需要登录的功能前检查
+# - UI显示逻辑判断
+func is_user_logged_in() -> bool:
+	return not current_user.is_empty()

_Core/managers/GameManager.gd.uid

@@ -0,0 +1 @@
+uid://cd8fn73ysjxh8

_Core/managers/NetworkManager.gd

@@ -1,45 +1,96 @@
 extends Node
 
-# 网络请求管理器 - 统一处理所有HTTP请求
+# ============================================================================
+# NetworkManager.gd - 网络请求管理器
+# ============================================================================
+# 全局单例管理器，统一处理所有HTTP请求
+# 
+# 核心职责:
+# - 统一的HTTP请求接口 (GET, POST, PUT, DELETE, PATCH)
+# - 认证相关API封装 (登录、注册、验证码等)
+# - 请求状态管理和错误处理
+# - 支持API v1.1.1规范的响应处理
+#
+# 使用方式:
+#   NetworkManager.login("user@example.com", "password", callback)
+#   var request_id = NetworkManager.get_request("/api/data", callback)
+#
+# 注意事项:
+# - 作为自动加载单例，全局可访问
+# - 所有请求都是异步的，通过回调函数或信号处理结果
+# - 支持请求超时和取消功能
+# - 自动处理JSON序列化和反序列化
+# ============================================================================
 
-# 信号定义
+# ============ 信号定义 ============
+
+# 请求完成信号
+# 参数: 
+#   request_id: String - 请求唯一标识符
+#   success: bool - 请求是否成功
+#   data: Dictionary - 响应数据
 signal request_completed(request_id: String, success: bool, data: Dictionary)
+
+# 请求失败信号
+# 参数:
+#   request_id: String - 请求唯一标识符
+#   error_type: String - 错误类型名称
+#   message: String - 错误消息
 signal request_failed(request_id: String, error_type: String, message: String)
 
-# API配置
+# ============ 常量定义 ============
+
+# API基础URL - 所有请求的根地址
 const API_BASE_URL = "https://whaletownend.xinghangee.icu"
+
+# 默认请求超时时间（秒）
 const DEFAULT_TIMEOUT = 30.0
 
-# 请求类型枚举
+# ============ 枚举定义 ============
+
+# HTTP请求方法枚举
 enum RequestType {
-	GET,
-	POST,
-	PUT,
-	DELETE,
-	PATCH
+	GET,     # 获取数据
+	POST,    # 创建数据
+	PUT,     # 更新数据
+	DELETE,  # 删除数据
+	PATCH    # 部分更新数据
 }
 
 # 错误类型枚举
+# 用于分类不同类型的网络错误
 enum ErrorType {
-	NETWORK_ERROR,      # 网络连接错误
-	TIMEOUT_ERROR,      # 请求超时
-	PARSE_ERROR,        # JSON解析错误
-	HTTP_ERROR,         # HTTP状态码错误
-	BUSINESS_ERROR      # 业务逻辑错误
+	NETWORK_ERROR,      # 网络连接错误 - 无法连接到服务器
+	TIMEOUT_ERROR,      # 请求超时 - 服务器响应时间过长
+	PARSE_ERROR,        # JSON解析错误 - 服务器返回格式错误
+	HTTP_ERROR,         # HTTP状态码错误 - 4xx, 5xx状态码
+	BUSINESS_ERROR      # 业务逻辑错误 - API返回的业务错误
 }
 
-# 请求状态
+# ============ 请求信息类 ============
+
+# 请求信息封装类
+# 存储单个HTTP请求的所有相关信息
 class RequestInfo:
-	var id: String
-	var url: String
-	var method: RequestType
-	var headers: PackedStringArray
-	var body: String
-	var timeout: float
-	var start_time: float
-	var http_request: HTTPRequest
-	var callback: Callable
+	var id: String                    # 请求唯一标识符
+	var url: String                   # 完整的请求URL
+	var method: RequestType           # HTTP请求方法
+	var headers: PackedStringArray    # 请求头数组
+	var body: String                  # 请求体内容
+	var timeout: float                # 超时时间（秒）
+	var start_time: float             # 请求开始时间戳
+	var http_request: HTTPRequest     # Godot HTTPRequest节点引用
+	var callback: Callable            # 完成时的回调函数
 	
+	# 构造函数
+	# 
+	# 参数:
+	#   request_id: String - 请求唯一标识符
+	#   request_url: String - 请求URL
+	#   request_method: RequestType - HTTP方法
+	#   request_headers: PackedStringArray - 请求头（可选）
+	#   request_body: String - 请求体（可选）
+	#   request_timeout: float - 超时时间（可选，默认使用DEFAULT_TIMEOUT）
 	func _init(request_id: String, request_url: String, request_method: RequestType, 
 			   request_headers: PackedStringArray = [], request_body: String = "", 
 			   request_timeout: float = DEFAULT_TIMEOUT):
@@ -49,40 +100,107 @@ class RequestInfo:
 		headers = request_headers
 		body = request_body
 		timeout = request_timeout
+		# 记录请求开始时间（简化版时间戳）
 		start_time = Time.get_time_dict_from_system().hour * 3600 + Time.get_time_dict_from_system().minute * 60 + Time.get_time_dict_from_system().second
 
-# 活动请求管理
-var active_requests: Dictionary = {}
-var request_counter: int = 0
+# ============ 成员变量 ============
 
+# 活动请求管理
+var active_requests: Dictionary = {}                 # 存储所有活动请求 {request_id: RequestInfo}
+var request_counter: int = 0                         # 请求计数器，用于生成唯一ID
+
+# ============ 生命周期方法 ============
+
+# 初始化网络管理器
+# 在节点准备就绪时调用
 func _ready():
 	print("NetworkManager 已初始化")
 
 # ============ 公共API接口 ============
 
 # 发送GET请求
+# 
+# 参数:
+#   endpoint: String - API端点路径（如: "/api/users"）
+#   callback: Callable - 完成时的回调函数（可选）
+#   timeout: float - 超时时间（可选，默认30秒）
+# 
+# 返回值:
+#   String - 请求ID，可用于取消请求或跟踪状态
+# 
+# 使用示例:
+#   var request_id = NetworkManager.get_request("/api/users", my_callback)
 func get_request(endpoint: String, callback: Callable = Callable(), timeout: float = DEFAULT_TIMEOUT) -> String:
 	return send_request(endpoint, RequestType.GET, [], "", callback, timeout)
 
 # 发送POST请求
+# 
+# 参数:
+#   endpoint: String - API端点路径
+#   data: Dictionary - 要发送的数据（将自动转换为JSON）
+#   callback: Callable - 完成时的回调函数（可选）
+#   timeout: float - 超时时间（可选）
+# 
+# 返回值:
+#   String - 请求ID
+# 
+# 使用示例:
+#   var data = {"name": "张三", "age": 25}
+#   var request_id = NetworkManager.post_request("/api/users", data, my_callback)
 func post_request(endpoint: String, data: Dictionary, callback: Callable = Callable(), timeout: float = DEFAULT_TIMEOUT) -> String:
 	var body = JSON.stringify(data)
 	var headers = ["Content-Type: application/json"]
 	return send_request(endpoint, RequestType.POST, headers, body, callback, timeout)
 
 # 发送PUT请求
+# 
+# 参数:
+#   endpoint: String - API端点路径
+#   data: Dictionary - 要更新的数据
+#   callback: Callable - 完成时的回调函数（可选）
+#   timeout: float - 超时时间（可选）
+# 
+# 返回值:
+#   String - 请求ID
 func put_request(endpoint: String, data: Dictionary, callback: Callable = Callable(), timeout: float = DEFAULT_TIMEOUT) -> String:
 	var body = JSON.stringify(data)
 	var headers = ["Content-Type: application/json"]
 	return send_request(endpoint, RequestType.PUT, headers, body, callback, timeout)
 
 # 发送DELETE请求
+# 
+# 参数:
+#   endpoint: String - API端点路径
+#   callback: Callable - 完成时的回调函数（可选）
+#   timeout: float - 超时时间（可选）
+# 
+# 返回值:
+#   String - 请求ID
 func delete_request(endpoint: String, callback: Callable = Callable(), timeout: float = DEFAULT_TIMEOUT) -> String:
 	return send_request(endpoint, RequestType.DELETE, [], "", callback, timeout)
 
 # ============ 认证相关API ============
 
 # 用户登录
+# 
+# 参数:
+#   identifier: String - 用户标识符（邮箱或手机号）
+#   password: String - 用户密码
+#   callback: Callable - 完成时的回调函数（可选）
+# 
+# 返回值:
+#   String - 请求ID
+# 
+# 回调函数签名:
+#   func callback(success: bool, data: Dictionary, error_info: Dictionary)
+# 
+# 使用示例:
+#   NetworkManager.login("user@example.com", "password123", func(success, data, error):
+#       if success:
+#           print("登录成功: ", data)
+#       else:
+#           print("登录失败: ", error.message)
+#   )
 func login(identifier: String, password: String, callback: Callable = Callable()) -> String:
 	var data = {
 		"identifier": identifier,
@@ -91,6 +209,18 @@ func login(identifier: String, password: String, callback: Callable = Callable()
 	return post_request("/auth/login", data, callback)
 
 # 验证码登录
+# 
+# 参数:
+#   identifier: String - 用户标识符（邮箱或手机号）
+#   verification_code: String - 验证码
+#   callback: Callable - 完成时的回调函数（可选）
+# 
+# 返回值:
+#   String - 请求ID
+# 
+# 使用场景:
+# - 用户忘记密码时的替代登录方式
+# - 提供更安全的登录选项
 func verification_code_login(identifier: String, verification_code: String, callback: Callable = Callable()) -> String:
 	var data = {
 		"identifier": identifier,
@@ -99,11 +229,39 @@ func verification_code_login(identifier: String, verification_code: String, call
 	return post_request("/auth/verification-code-login", data, callback)
 
 # 发送登录验证码
+# 
+# 参数:
+#   identifier: String - 用户标识符（邮箱或手机号）
+#   callback: Callable - 完成时的回调函数（可选）
+# 
+# 返回值:
+#   String - 请求ID
+# 
+# 功能:
+# - 向已注册用户发送登录验证码
+# - 支持邮箱和手机号
+# - 有频率限制保护
 func send_login_verification_code(identifier: String, callback: Callable = Callable()) -> String:
 	var data = {"identifier": identifier}
 	return post_request("/auth/send-login-verification-code", data, callback)
 
 # 用户注册
+# 
+# 参数:
+#   username: String - 用户名
+#   password: String - 密码
+#   nickname: String - 昵称
+#   email: String - 邮箱地址（可选）
+#   email_verification_code: String - 邮箱验证码（可选）
+#   callback: Callable - 完成时的回调函数（可选）
+# 
+# 返回值:
+#   String - 请求ID
+# 
+# 注意事项:
+# - 如果提供邮箱，建议同时提供验证码
+# - 用户名和邮箱必须唯一
+# - 密码需要符合安全要求
 func register(username: String, password: String, nickname: String, email: String = "", 
 			  email_verification_code: String = "", callback: Callable = Callable()) -> String:
 	var data = {
@@ -112,6 +270,7 @@ func register(username: String, password: String, nickname: String, email: Strin
 		"nickname": nickname
 	}
 	
+	# 可选参数处理
 	if email != "":
 		data["email"] = email
 	if email_verification_code != "":
@@ -120,11 +279,35 @@ func register(username: String, password: String, nickname: String, email: Strin
 	return post_request("/auth/register", data, callback)
 
 # 发送邮箱验证码
+# 
+# 参数:
+#   email: String - 邮箱地址
+#   callback: Callable - 完成时的回调函数（可选）
+# 
+# 返回值:
+#   String - 请求ID
+# 
+# 功能:
+# - 向指定邮箱发送验证码
+# - 用于注册时的邮箱验证
+# - 支持测试模式（开发环境）
 func send_email_verification(email: String, callback: Callable = Callable()) -> String:
 	var data = {"email": email}
 	return post_request("/auth/send-email-verification", data, callback)
 
 # 验证邮箱
+# 
+# 参数:
+#   email: String - 邮箱地址
+#   verification_code: String - 验证码
+#   callback: Callable - 完成时的回调函数（可选）
+# 
+# 返回值:
+#   String - 请求ID
+# 
+# 功能:
+# - 验证邮箱验证码的有效性
+# - 通常在注册流程中使用
 func verify_email(email: String, verification_code: String, callback: Callable = Callable()) -> String:
 	var data = {
 		"email": email,
@@ -133,20 +316,66 @@ func verify_email(email: String, verification_code: String, callback: Callable =
 	return post_request("/auth/verify-email", data, callback)
 
 # 获取应用状态
+# 
+# 参数:
+#   callback: Callable - 完成时的回调函数（可选）
+# 
+# 返回值:
+#   String - 请求ID
+# 
+# 功能:
+# - 检查API服务器状态
+# - 获取应用基本信息
+# - 用于网络连接测试
 func get_app_status(callback: Callable = Callable()) -> String:
 	return get_request("/", callback)
 
 # 重新发送邮箱验证码
+# 
+# 参数:
+#   email: String - 邮箱地址
+#   callback: Callable - 完成时的回调函数（可选）
+# 
+# 返回值:
+#   String - 请求ID
+# 
+# 使用场景:
+# - 用户未收到验证码时重新发送
+# - 验证码过期后重新获取
 func resend_email_verification(email: String, callback: Callable = Callable()) -> String:
 	var data = {"email": email}
 	return post_request("/auth/resend-email-verification", data, callback)
 
 # 忘记密码 - 发送重置验证码
+# 
+# 参数:
+#   identifier: String - 用户标识符（邮箱或手机号）
+#   callback: Callable - 完成时的回调函数（可选）
+# 
+# 返回值:
+#   String - 请求ID
+# 
+# 功能:
+# - 向用户发送密码重置验证码
+# - 用于密码找回流程的第一步
 func forgot_password(identifier: String, callback: Callable = Callable()) -> String:
 	var data = {"identifier": identifier}
 	return post_request("/auth/forgot-password", data, callback)
 
 # 重置密码
+# 
+# 参数:
+#   identifier: String - 用户标识符
+#   verification_code: String - 重置验证码
+#   new_password: String - 新密码
+#   callback: Callable - 完成时的回调函数（可选）
+# 
+# 返回值:
+#   String - 请求ID
+# 
+# 功能:
+# - 使用验证码重置用户密码
+# - 密码找回流程的第二步
 func reset_password(identifier: String, verification_code: String, new_password: String, callback: Callable = Callable()) -> String:
 	var data = {
 		"identifier": identifier,
@@ -156,6 +385,19 @@ func reset_password(identifier: String, verification_code: String, new_password:
 	return post_request("/auth/reset-password", data, callback)
 
 # 修改密码
+# 
+# 参数:
+#   user_id: String - 用户ID
+#   old_password: String - 旧密码
+#   new_password: String - 新密码
+#   callback: Callable - 完成时的回调函数（可选）
+# 
+# 返回值:
+#   String - 请求ID
+# 
+# 功能:
+# - 已登录用户修改密码
+# - 需要验证旧密码
 func change_password(user_id: String, old_password: String, new_password: String, callback: Callable = Callable()) -> String:
 	var data = {
 		"user_id": user_id,
@@ -165,6 +407,21 @@ func change_password(user_id: String, old_password: String, new_password: String
 	return put_request("/auth/change-password", data, callback)
 
 # GitHub OAuth登录
+# 
+# 参数:
+#   github_id: String - GitHub用户ID
+#   username: String - GitHub用户名
+#   nickname: String - 显示昵称
+#   email: String - GitHub邮箱
+#   avatar_url: String - 头像URL（可选）
+#   callback: Callable - 完成时的回调函数（可选）
+# 
+# 返回值:
+#   String - 请求ID
+# 
+# 功能:
+# - 通过GitHub账号登录或注册
+# - 支持第三方OAuth认证
 func github_login(github_id: String, username: String, nickname: String, email: String, avatar_url: String = "", callback: Callable = Callable()) -> String:
 	var data = {
 		"github_id": github_id,
@@ -173,6 +430,7 @@ func github_login(github_id: String, username: String, nickname: String, email:
 		"email": email
 	}
 	
+	# 可选头像URL
 	if avatar_url != "":
 		data["avatar_url"] = avatar_url
 	
@@ -206,8 +464,8 @@ func send_request(endpoint: String, method: RequestType, headers: PackedStringAr
 	active_requests[request_id] = request_info
 	
 	# 连接信号
-	http_request.request_completed.connect(func(result: int, response_code: int, headers: PackedStringArray, body: PackedByteArray):
-		_on_request_completed(request_id, result, response_code, headers, body)
+	http_request.request_completed.connect(func(result: int, response_code: int, response_headers: PackedStringArray, response_body: PackedByteArray):
+		_on_request_completed(request_id, result, response_code, response_headers, response_body)
 	)
 	
 	# 发送请求
@@ -243,7 +501,7 @@ func _on_request_completed(request_id: String, result: int, response_code: int,
 		print("警告: 未找到请求ID ", request_id)
 		return
 	
-	var request_info = active_requests[request_id]
+	var _request_info = active_requests[request_id]
 	var response_text = body.get_string_from_utf8()
 	
 	print("响应体长度: ", body.size(), " 字节")

_Core/managers/NetworkManager.gd.uid

@@ -0,0 +1 @@
+uid://dr7v30wheetca

_Core/managers/ResponseHandler.gd

@@ -84,7 +84,7 @@ const HTTP_STATUS_MESSAGES = {
 # ============ 主要处理方法 ============
 
 # 处理登录响应
-static func handle_login_response(success: bool, data: Dictionary, error_info: Dictionary = {}) -> ResponseResult:
+func handle_login_response(success: bool, data: Dictionary, error_info: Dictionary = {}) -> ResponseResult:
 	var result = ResponseResult.new()
 	
 	if success:
@@ -103,7 +103,7 @@ static func handle_login_response(success: bool, data: Dictionary, error_info: D
 	return result
 
 # 处理验证码登录响应
-static func handle_verification_code_login_response(success: bool, data: Dictionary, error_info: Dictionary = {}) -> ResponseResult:
+func handle_verification_code_login_response(success: bool, data: Dictionary, error_info: Dictionary = {}) -> ResponseResult:
 	var result = ResponseResult.new()
 	
 	if success:
@@ -121,7 +121,7 @@ static func handle_verification_code_login_response(success: bool, data: Diction
 	return result
 
 # 处理发送验证码响应 - 支持邮箱冲突检测
-static func handle_send_verification_code_response(success: bool, data: Dictionary, error_info: Dictionary = {}) -> ResponseResult:
+func handle_send_verification_code_response(success: bool, data: Dictionary, error_info: Dictionary = {}) -> ResponseResult:
 	var result = ResponseResult.new()
 	
 	if success:
@@ -149,7 +149,7 @@ static func handle_send_verification_code_response(success: bool, data: Dictiona
 	return result
 
 # 处理发送登录验证码响应
-static func handle_send_login_code_response(success: bool, data: Dictionary, error_info: Dictionary = {}) -> ResponseResult:
+func handle_send_login_code_response(success: bool, data: Dictionary, error_info: Dictionary = {}) -> ResponseResult:
 	var result = ResponseResult.new()
 	
 	if success:
@@ -174,7 +174,7 @@ static func handle_send_login_code_response(success: bool, data: Dictionary, err
 	return result
 
 # 处理注册响应
-static func handle_register_response(success: bool, data: Dictionary, error_info: Dictionary = {}) -> ResponseResult:
+func handle_register_response(success: bool, data: Dictionary, error_info: Dictionary = {}) -> ResponseResult:
 	var result = ResponseResult.new()
 	
 	if success:
@@ -193,7 +193,7 @@ static func handle_register_response(success: bool, data: Dictionary, error_info
 	return result
 
 # 处理邮箱验证响应
-static func handle_verify_email_response(success: bool, data: Dictionary, error_info: Dictionary = {}) -> ResponseResult:
+func handle_verify_email_response(success: bool, data: Dictionary, error_info: Dictionary = {}) -> ResponseResult:
 	var result = ResponseResult.new()
 	
 	if success:
@@ -207,7 +207,7 @@ static func handle_verify_email_response(success: bool, data: Dictionary, error_
 	return result
 
 # 处理重新发送邮箱验证码响应
-static func handle_resend_email_verification_response(success: bool, data: Dictionary, error_info: Dictionary = {}) -> ResponseResult:
+func handle_resend_email_verification_response(success: bool, data: Dictionary, error_info: Dictionary = {}) -> ResponseResult:
 	var result = ResponseResult.new()
 	
 	if success:
@@ -232,7 +232,7 @@ static func handle_resend_email_verification_response(success: bool, data: Dicti
 	return result
 
 # 处理忘记密码响应
-static func handle_forgot_password_response(success: bool, data: Dictionary, error_info: Dictionary = {}) -> ResponseResult:
+func handle_forgot_password_response(success: bool, data: Dictionary, error_info: Dictionary = {}) -> ResponseResult:
 	var result = ResponseResult.new()
 	
 	if success:
@@ -257,7 +257,7 @@ static func handle_forgot_password_response(success: bool, data: Dictionary, err
 	return result
 
 # 处理重置密码响应
-static func handle_reset_password_response(success: bool, data: Dictionary, error_info: Dictionary = {}) -> ResponseResult:
+func handle_reset_password_response(success: bool, data: Dictionary, error_info: Dictionary = {}) -> ResponseResult:
 	var result = ResponseResult.new()
 	
 	if success:
@@ -273,7 +273,7 @@ static func handle_reset_password_response(success: bool, data: Dictionary, erro
 # ============ 错误处理方法 ============
 
 # 处理登录错误
-static func _handle_login_error(data: Dictionary, error_info: Dictionary) -> ResponseResult:
+func _handle_login_error(data: Dictionary, error_info: Dictionary) -> ResponseResult:
 	var result = ResponseResult.new()
 	var error_code = data.get("error_code", "")
 	var message = data.get("message", "登录失败")
@@ -297,7 +297,7 @@ static func _handle_login_error(data: Dictionary, error_info: Dictionary) -> Res
 	return result
 
 # 处理验证码登录错误
-static func _handle_verification_code_login_error(data: Dictionary, error_info: Dictionary) -> ResponseResult:
+func _handle_verification_code_login_error(data: Dictionary, error_info: Dictionary) -> ResponseResult:
 	var result = ResponseResult.new()
 	var error_code = data.get("error_code", "")
 	var message = data.get("message", "验证码登录失败")
@@ -317,7 +317,7 @@ static func _handle_verification_code_login_error(data: Dictionary, error_info:
 	return result
 
 # 处理发送验证码错误 - 支持邮箱冲突检测和频率限制
-static func _handle_send_code_error(data: Dictionary, error_info: Dictionary) -> ResponseResult:
+func _handle_send_code_error(data: Dictionary, error_info: Dictionary) -> ResponseResult:
 	var result = ResponseResult.new()
 	var error_code = data.get("error_code", "")
 	var message = data.get("message", "发送验证码失败")
@@ -361,7 +361,7 @@ static func _handle_send_code_error(data: Dictionary, error_info: Dictionary) ->
 	return result
 
 # 处理发送登录验证码错误
-static func _handle_send_login_code_error(data: Dictionary, error_info: Dictionary) -> ResponseResult:
+func _handle_send_login_code_error(data: Dictionary, error_info: Dictionary) -> ResponseResult:
 	var result = ResponseResult.new()
 	var error_code = data.get("error_code", "")
 	var message = data.get("message", "发送登录验证码失败")
@@ -382,7 +382,7 @@ static func _handle_send_login_code_error(data: Dictionary, error_info: Dictiona
 	return result
 
 # 处理注册错误 - 支持409冲突状态码
-static func _handle_register_error(data: Dictionary, error_info: Dictionary) -> ResponseResult:
+func _handle_register_error(data: Dictionary, error_info: Dictionary) -> ResponseResult:
 	var result = ResponseResult.new()
 	var error_code = data.get("error_code", "")
 	var message = data.get("message", "注册失败")
@@ -416,7 +416,7 @@ static func _handle_register_error(data: Dictionary, error_info: Dictionary) ->
 	return result
 
 # 处理邮箱验证错误
-static func _handle_verify_email_error(data: Dictionary, error_info: Dictionary) -> ResponseResult:
+func _handle_verify_email_error(data: Dictionary, error_info: Dictionary) -> ResponseResult:
 	var result = ResponseResult.new()
 	var error_code = data.get("error_code", "")
 	var message = data.get("message", "邮箱验证失败")
@@ -439,7 +439,7 @@ static func _handle_verify_email_error(data: Dictionary, error_info: Dictionary)
 	return result
 
 # 处理网络测试响应
-static func handle_network_test_response(success: bool, data: Dictionary, error_info: Dictionary = {}) -> ResponseResult:
+func handle_network_test_response(success: bool, _data: Dictionary, _error_info: Dictionary = {}) -> ResponseResult:
 	var result = ResponseResult.new()
 	
 	if success:
@@ -454,7 +454,7 @@ static func handle_network_test_response(success: bool, data: Dictionary, error_
 	return result
 
 # 处理重新发送邮箱验证码错误
-static func _handle_resend_email_verification_error(data: Dictionary, error_info: Dictionary) -> ResponseResult:
+func _handle_resend_email_verification_error(data: Dictionary, error_info: Dictionary) -> ResponseResult:
 	var result = ResponseResult.new()
 	var error_code = data.get("error_code", "")
 	var message = data.get("message", "重新发送验证码失败")
@@ -471,7 +471,7 @@ static func _handle_resend_email_verification_error(data: Dictionary, error_info
 	return result
 
 # 处理忘记密码错误
-static func _handle_forgot_password_error(data: Dictionary, error_info: Dictionary) -> ResponseResult:
+func _handle_forgot_password_error(data: Dictionary, error_info: Dictionary) -> ResponseResult:
 	var result = ResponseResult.new()
 	var error_code = data.get("error_code", "")
 	var message = data.get("message", "发送重置验证码失败")
@@ -490,7 +490,7 @@ static func _handle_forgot_password_error(data: Dictionary, error_info: Dictiona
 	return result
 
 # 处理重置密码错误
-static func _handle_reset_password_error(data: Dictionary, error_info: Dictionary) -> ResponseResult:
+func _handle_reset_password_error(data: Dictionary, error_info: Dictionary) -> ResponseResult:
 	var result = ResponseResult.new()
 	var error_code = data.get("error_code", "")
 	var message = data.get("message", "重置密码失败")
@@ -509,7 +509,7 @@ static func _handle_reset_password_error(data: Dictionary, error_info: Dictionar
 # ============ 工具方法 ============
 
 # 获取错误消息 - 支持更多状态码和错误处理
-static func _get_error_message(error_code: String, original_message: String, error_info: Dictionary) -> String:
+func _get_error_message(error_code: String, original_message: String, error_info: Dictionary) -> String:
 	# 优先使用错误码映射
 	if ERROR_CODE_MESSAGES.has(error_code):
 		return ERROR_CODE_MESSAGES[error_code]
@@ -544,17 +544,17 @@ static func _get_error_message(error_code: String, original_message: String, err
 	return original_message if original_message != "" else "操作失败"
 
 # 处理频率限制消息
-static func _handle_rate_limit_message(message: String, error_info: Dictionary) -> String:
+func _handle_rate_limit_message(message: String, _error_info: Dictionary) -> String:
 	# 可以根据throttle_info提供更详细的信息
 	return message + "，请稍后再试"
 
 # 处理维护模式消息
-static func _handle_maintenance_message(message: String, error_info: Dictionary) -> String:
+func _handle_maintenance_message(_message: String, _error_info: Dictionary) -> String:
 	# 可以根据maintenance_info提供更详细的信息
 	return "系统维护中，请稍后再试"
 
 # 通用响应处理器 - 支持更多操作类型
-static func handle_response(operation_type: String, success: bool, data: Dictionary, error_info: Dictionary = {}) -> ResponseResult:
+func handle_response(operation_type: String, success: bool, data: Dictionary, error_info: Dictionary = {}) -> ResponseResult:
 	match operation_type:
 		"login":
 			return handle_login_response(success, data, error_info)

_Core/managers/ResponseHandler.gd.uid

@@ -0,0 +1 @@
+uid://nseguk2ytiw6

_Core/managers/SceneManager.gd

@@ -0,0 +1,187 @@
+extends Node
+
+# ============================================================================
+# SceneManager.gd - 场景管理器
+# ============================================================================
+# 全局单例管理器，负责场景切换和管理
+# 
+# 核心职责:
+# - 场景切换的统一接口
+# - 场景路径映射管理
+# - 场景切换过渡效果
+# - 场景状态跟踪
+#
+# 使用方式:
+#   SceneManager.change_scene("main")
+#   SceneManager.register_scene("custom", "res://scenes/custom.tscn")
+#
+# 注意事项:
+# - 作为自动加载单例，全局可访问
+# - 场景切换是异步操作，支持过渡效果
+# - 场景名称必须在 scene_paths 中注册
+# ============================================================================
+
+# ============ 信号定义 ============
+
+# 场景切换完成信号
+# 参数: scene_name - 切换到的场景名称
+signal scene_changed(scene_name: String)
+
+# 场景切换开始信号
+# 参数: scene_name - 即将切换到的场景名称
+signal scene_change_started(scene_name: String)
+
+# ============ 成员变量 ============
+
+# 场景状态
+var current_scene_name: String = ""                 # 当前场景名称
+var is_changing_scene: bool = false                 # 是否正在切换场景
+
+# 场景路径映射表
+# 将场景名称映射到实际的文件路径
+# 便于统一管理和修改场景路径
+var scene_paths: Dictionary = {
+	"main": "res://scenes/MainScene.tscn",           # 主场景 - 游戏入口
+	"auth": "res://scenes/ui/LoginWindow.tscn",      # 认证场景 - 登录窗口
+	"game": "res://scenes/maps/game_scene.tscn",     # 游戏场景 - 主要游戏内容
+	"battle": "res://scenes/maps/battle_scene.tscn", # 战斗场景 - 战斗系统
+	"inventory": "res://scenes/ui/InventoryWindow.tscn", # 背包界面
+	"shop": "res://scenes/ui/ShopWindow.tscn",       # 商店界面
+	"settings": "res://scenes/ui/SettingsWindow.tscn" # 设置界面
+}
+
+# ============ 生命周期方法 ============
+
+# 初始化场景管理器
+# 在节点准备就绪时调用
+func _ready():
+	print("SceneManager 初始化完成")
+
+# ============ 场景切换方法 ============
+
+# 切换到指定场景
+# 
+# 参数:
+#   scene_name: String - 要切换到的场景名称（必须在scene_paths中注册）
+#   use_transition: bool - 是否使用过渡效果，默认为true
+# 
+# 返回值:
+#   bool - 切换是否成功
+# 
+# 功能:
+# - 检查场景切换状态和场景是否存在
+# - 显示过渡效果（可选）
+# - 执行场景切换
+# - 更新当前场景状态
+# - 发送相关信号
+# 
+# 使用示例:
+#   var success = SceneManager.change_scene("main", true)
+#   if success:
+#       print("场景切换成功")
+# 
+# 注意事项:
+# - 场景切换是异步操作
+# - 切换过程中会阻止新的切换请求
+# - 场景名称必须预先注册
+func change_scene(scene_name: String, use_transition: bool = true):
+	# 防止重复切换
+	if is_changing_scene:
+		print("场景切换中，忽略新的切换请求")
+		return false
+	
+	# 检查场景是否存在
+	if not scene_paths.has(scene_name):
+		print("错误: 未找到场景 ", scene_name)
+		return false
+	
+	var scene_path = scene_paths[scene_name]
+	print("开始切换场景: ", current_scene_name, " -> ", scene_name)
+	
+	# 设置切换状态
+	is_changing_scene = true
+	scene_change_started.emit(scene_name)
+	
+	# 显示过渡效果
+	if use_transition:
+		await show_transition()
+	
+	# 执行场景切换
+	var error = get_tree().change_scene_to_file(scene_path)
+	if error != OK:
+		print("场景切换失败: ", error)
+		is_changing_scene = false
+		return false
+	
+	# 更新状态
+	current_scene_name = scene_name
+	is_changing_scene = false
+	scene_changed.emit(scene_name)
+	
+	# 隐藏过渡效果
+	if use_transition:
+		await hide_transition()
+	
+	print("场景切换完成: ", scene_name)
+	return true
+
+# ============ 查询方法 ============
+
+# 获取当前场景名称
+# 
+# 返回值:
+#   String - 当前场景的名称
+func get_current_scene_name() -> String:
+	return current_scene_name
+
+# ============ 场景注册方法 ============
+
+# 注册新场景
+# 
+# 参数:
+#   scene_name: String - 场景名称（用于切换时引用）
+#   scene_path: String - 场景文件路径
+# 
+# 功能:
+# - 将场景名称和路径添加到映射表
+# - 支持运行时动态注册场景
+# 
+# 使用示例:
+#   SceneManager.register_scene("boss_battle", "res://scenes/boss/boss_battle.tscn")
+func register_scene(scene_name: String, scene_path: String):
+	scene_paths[scene_name] = scene_path
+	print("注册场景: ", scene_name, " -> ", scene_path)
+
+# ============ 过渡效果方法 ============
+
+# 显示场景切换过渡效果
+# 
+# 功能:
+# - 显示场景切换时的过渡动画
+# - 为用户提供视觉反馈
+# 
+# 注意事项:
+# - 这是异步方法，需要await等待完成
+# - 当前实现为简单的延时，可扩展为复杂动画
+# 
+# TODO: 实现淡入淡出、滑动等过渡效果
+func show_transition():
+	# TODO: 实现场景切换过渡效果
+	print("显示场景切换过渡效果")
+	await get_tree().create_timer(0.2).timeout
+
+# 隐藏场景切换过渡效果
+# 
+# 功能:
+# - 隐藏场景切换完成后的过渡动画
+# - 恢复正常的游戏显示
+# 
+# 注意事项:
+# - 这是异步方法，需要await等待完成
+# - 与show_transition()配对使用
+# 
+# TODO: 实现与show_transition()对应的隐藏效果
+func hide_transition():
+	# TODO: 隐藏场景切换过渡效果
+	print("隐藏场景切换过渡效果")
+	await get_tree().create_timer(0.2).timeout

_Core/managers/SceneManager.gd.uid

@@ -0,0 +1 @@
+uid://d3l286ti5gqhw

_Core/managers/ToastManager.gd

@@ -0,0 +1,234 @@
+class_name ToastManager
+
+# ============================================================================
+# ToastManager.gd - Toast消息管理器
+# ============================================================================
+# 负责创建和管理Toast消息的显示
+# 
+# 核心功能:
+# - 创建Toast消息实例
+# - 管理Toast动画和生命周期
+# - 支持多个Toast同时显示
+# - 自动排列和清理Toast
+# - 支持中文字体显示
+#
+# 使用方式:
+#   var toast_manager = ToastManager.new()
+#   toast_manager.setup(toast_container)
+#   toast_manager.show_toast("消息内容", true)
+#
+# 注意事项:
+# - 需要提供一个容器节点来承载Toast
+# - 自动处理Toast的位置计算和动画
+# - 支持Web平台的字体处理
+# ============================================================================
+
+extends RefCounted
+
+# ============ 成员变量 ============
+
+# Toast容器和管理
+var toast_container: Control                    # Toast消息容器
+var active_toasts: Array = []                  # 当前显示的Toast消息列表
+var toast_counter: int = 0                     # Toast计数器，用于生成唯一ID
+
+# ============ 初始化方法 ============
+
+# 设置Toast管理器
+# 
+# 参数:
+#   container: Control - Toast消息的容器节点
+func setup(container: Control):
+	toast_container = container
+	print("ToastManager 初始化完成")
+
+# ============ 公共方法 ============
+
+# 显示Toast消息
+# 
+# 参数:
+#   message: String - 消息内容
+#   is_success: bool - 是否为成功消息（影响颜色）
+func show_toast(message: String, is_success: bool = true):
+	if toast_container == null:
+		print("错误: toast_container 节点不存在")
+		return
+	
+	print("显示Toast消息: ", message, " 成功: ", is_success)
+	_create_toast_instance(message, is_success)
+
+# 清理所有Toast
+func clear_all_toasts():
+	for toast in active_toasts:
+		if is_instance_valid(toast):
+			toast.queue_free()
+	active_toasts.clear()
+
+# ============ 私有方法 ============
+
+# 创建Toast实例
+func _create_toast_instance(message: String, is_success: bool):
+	toast_counter += 1
+	
+	# Web平台字体处理
+	var is_web = OS.get_name() == "Web"
+	
+	# 1. 创建Toast Panel（方框UI）
+	var toast_panel = Panel.new()
+	toast_panel.name = "Toast_" + str(toast_counter)
+	
+	# 设置Toast样式
+	var style = StyleBoxFlat.new()
+	if is_success:
+		style.bg_color = Color(0.15, 0.7, 0.15, 0.95)
+		style.border_color = Color(0.2, 0.9, 0.2, 0.9)
+	else:
+		style.bg_color = Color(0.7, 0.15, 0.15, 0.95)
+		style.border_color = Color(0.9, 0.2, 0.2, 0.9)
+	
+	style.border_width_left = 3
+	style.border_width_top = 3
+	style.border_width_right = 3
+	style.border_width_bottom = 3
+	style.corner_radius_top_left = 12
+	style.corner_radius_top_right = 12
+	style.corner_radius_bottom_left = 12
+	style.corner_radius_bottom_right = 12
+	style.shadow_color = Color(0, 0, 0, 0.3)
+	style.shadow_size = 4
+	style.shadow_offset = Vector2(2, 2)
+	
+	toast_panel.add_theme_stylebox_override("panel", style)
+	
+	# 设置Toast基本尺寸
+	var toast_width = 320
+	toast_panel.size = Vector2(toast_width, 60)
+	
+	# 2. 创建VBoxContainer
+	var vbox = VBoxContainer.new()
+	vbox.add_theme_constant_override("separation", 0)
+	vbox.set_anchors_and_offsets_preset(Control.PRESET_FULL_RECT)
+	vbox.alignment = BoxContainer.ALIGNMENT_CENTER
+	
+	# 3. 创建CenterContainer
+	var center_container = CenterContainer.new()
+	center_container.size_flags_horizontal = Control.SIZE_EXPAND_FILL
+	center_container.size_flags_vertical = Control.SIZE_SHRINK_CENTER
+	
+	# 4. 创建Label（文字控件）
+	var text_label = Label.new()
+	text_label.text = message
+	text_label.add_theme_color_override("font_color", Color(1, 1, 1, 1))
+	text_label.add_theme_font_size_override("font_size", 14)
+	
+	# 平台特定的字体处理
+	if is_web:
+		print("Web平台Toast字体处理")
+		# Web平台使用主题文件
+		var chinese_theme = load("res://assets/ui/chinese_theme.tres")
+		if chinese_theme:
+			text_label.theme = chinese_theme
+			print("Web平台应用中文主题")
+		else:
+			print("Web平台中文主题加载失败")
+	else:
+		print("桌面平台Toast字体处理")
+		# 桌面平台直接加载中文字体
+		var desktop_chinese_font = load("res://assets/fonts/msyh.ttc")
+		if desktop_chinese_font:
+			text_label.add_theme_font_override("font", desktop_chinese_font)
+			print("桌面平台使用中文字体")
+	
+	text_label.autowrap_mode = TextServer.AUTOWRAP_WORD_SMART
+	text_label.custom_minimum_size = Vector2(280, 0)
+	text_label.horizontal_alignment = HORIZONTAL_ALIGNMENT_CENTER
+	text_label.vertical_alignment = VERTICAL_ALIGNMENT_CENTER
+	
+	# 组装控件层级
+	center_container.add_child(text_label)
+	vbox.add_child(center_container)
+	toast_panel.add_child(vbox)
+	
+	# 计算位置
+	var margin = 20
+	var start_x = toast_container.get_viewport().get_visible_rect().size.x
+	var final_x = toast_container.get_viewport().get_visible_rect().size.x - toast_width - margin
+	
+	# 计算Y位置
+	var y_position = margin
+	for existing_toast in active_toasts:
+		if is_instance_valid(existing_toast):
+			y_position += existing_toast.size.y + 15
+	
+	# 设置初始位置
+	toast_panel.position = Vector2(start_x, y_position)
+	
+	# 添加到容器
+	toast_container.add_child(toast_panel)
+	active_toasts.append(toast_panel)
+	
+	# 等待一帧让布局系统计算尺寸
+	await toast_container.get_tree().process_frame
+	
+	# 让Toast高度自适应内容
+	var content_size = vbox.get_combined_minimum_size()
+	var final_height = max(60, content_size.y + 20)  # 最小60，加20像素边距
+	toast_panel.size.y = final_height
+	
+	# 重新排列所有Toast
+	_rearrange_toasts()
+	
+	# 开始动画
+	_animate_toast_in(toast_panel, final_x)
+
+# Toast入场动画
+func _animate_toast_in(toast_panel: Panel, final_x: float):
+	var tween = toast_container.create_tween()
+	tween.set_ease(Tween.EASE_OUT)
+	tween.set_trans(Tween.TRANS_BACK)
+	
+	tween.parallel().tween_property(toast_panel, "position:x", final_x, 0.6)
+	tween.parallel().tween_property(toast_panel, "modulate:a", 1.0, 0.4)
+	
+	toast_panel.modulate.a = 0.0
+	
+	# 等待3秒后开始退场动画
+	await toast_container.get_tree().create_timer(3.0).timeout
+	_animate_toast_out(toast_panel)
+
+# Toast退场动画
+func _animate_toast_out(toast_panel: Panel):
+	if not is_instance_valid(toast_panel):
+		return
+	
+	var tween = toast_container.create_tween()
+	tween.set_ease(Tween.EASE_IN)
+	tween.set_trans(Tween.TRANS_QUART)
+	
+	var end_x = toast_container.get_viewport().get_visible_rect().size.x + 50
+	tween.parallel().tween_property(toast_panel, "position:x", end_x, 0.4)
+	tween.parallel().tween_property(toast_panel, "modulate:a", 0.0, 0.3)
+	
+	await tween.finished
+	_cleanup_toast(toast_panel)
+
+# 清理Toast
+func _cleanup_toast(toast_panel: Panel):
+	if not is_instance_valid(toast_panel):
+		return
+	
+	active_toasts.erase(toast_panel)
+	_rearrange_toasts()
+	toast_panel.queue_free()
+
+# 重新排列Toast位置
+func _rearrange_toasts():
+	var margin = 20
+	var current_y = margin
+	
+	for i in range(active_toasts.size()):
+		var toast = active_toasts[i]
+		if is_instance_valid(toast):
+			var tween = toast_container.create_tween()
+			tween.tween_property(toast, "position:y", current_y, 0.2)
+			current_y += toast.size.y + 15

_Core/managers/ToastManager.gd.uid

@@ -0,0 +1 @@
+uid://buk7d21cag262

_Core/systems/EventSystem.gd

@@ -0,0 +1,195 @@
+extends Node
+
+# ============================================================================
+# EventSystem.gd - 全局事件系统
+# ============================================================================
+# 全局单例管理器，提供解耦的事件通信机制
+# 
+# 核心职责:
+# - 事件监听器注册和管理
+# - 事件发送和分发
+# - 自动清理无效监听器
+# - 支持带参数的事件通信
+#
+# 使用方式:
+#   EventSystem.connect_event("player_moved", _on_player_moved)
+#   EventSystem.emit_event("player_moved", {"position": Vector2(100, 200)})
+#
+# 注意事项:
+# - 作为自动加载单例，全局可访问
+# - 监听器会自动检查目标节点的有效性
+# - 建议使用EventNames类中定义的事件名称常量
+# ============================================================================
+
+# ============ 成员变量 ============
+
+# 事件监听器存储
+# 结构: {event_name: [{"callback": Callable, "target": Node}, ...]}
+var event_listeners: Dictionary = {}
+
+# ============ 生命周期方法 ============
+
+# 初始化事件系统
+# 在节点准备就绪时调用
+func _ready():
+	print("EventSystem 初始化完成")
+
+# ============ 事件监听器管理 ============
+
+# 注册事件监听器
+# 
+# 参数:
+#   event_name: String - 事件名称（建议使用EventNames中的常量）
+#   callback: Callable - 回调函数
+#   target: Node - 目标节点（可选，用于自动清理）
+# 
+# 功能:
+# - 将回调函数注册到指定事件
+# - 支持同一事件多个监听器
+# - 自动管理监听器生命周期
+# 
+# 使用示例:
+#   EventSystem.connect_event(EventNames.PLAYER_MOVED, _on_player_moved, self)
+# 
+# 注意事项:
+# - 如果提供target参数，当target节点被销毁时会自动清理监听器
+# - 同一个callback可以监听多个事件
+func connect_event(event_name: String, callback: Callable, target: Node = null):
+	# 初始化事件监听器数组
+	if not event_listeners.has(event_name):
+		event_listeners[event_name] = []
+	
+	# 创建监听器信息
+	var listener_info = {
+		"callback": callback,
+		"target": target
+	}
+	
+	# 添加到监听器列表
+	event_listeners[event_name].append(listener_info)
+	print("注册事件监听器: ", event_name, " -> ", callback)
+
+# 移除事件监听器
+# 
+# 参数:
+#   event_name: String - 事件名称
+#   callback: Callable - 要移除的回调函数
+#   target: Node - 目标节点（可选，用于精确匹配）
+# 
+# 功能:
+# - 从指定事件中移除特定的监听器
+# - 支持精确匹配（callback + target）
+# 
+# 使用示例:
+#   EventSystem.disconnect_event(EventNames.PLAYER_MOVED, _on_player_moved, self)
+func disconnect_event(event_name: String, callback: Callable, target: Node = null):
+	if not event_listeners.has(event_name):
+		return
+	
+	var listeners = event_listeners[event_name]
+	# 从后往前遍历，避免删除元素时索引问题
+	for i in range(listeners.size() - 1, -1, -1):
+		var listener = listeners[i]
+		# 匹配callback和target
+		if listener.callback == callback and listener.target == target:
+			listeners.remove_at(i)
+			print("移除事件监听器: ", event_name, " -> ", callback)
+			break
+
+# ============ 事件发送 ============
+
+# 发送事件
+# 
+# 参数:
+#   event_name: String - 事件名称
+#   data: Variant - 事件数据（可选）
+# 
+# 功能:
+# - 向所有注册的监听器发送事件
+# - 自动跳过无效的监听器
+# - 支持任意类型的事件数据
+# 
+# 使用示例:
+#   EventSystem.emit_event(EventNames.PLAYER_MOVED, {"position": Vector2(100, 200)})
+#   EventSystem.emit_event(EventNames.GAME_PAUSED)  # 无数据事件
+# 
+# 注意事项:
+# - 事件发送是同步的，所有监听器会立即执行
+# - 如果监听器执行出错，不会影响其他监听器
+func emit_event(event_name: String, data: Variant = null):
+	print("发送事件: ", event_name, " 数据: ", data)
+	
+	# 检查是否有监听器
+	if not event_listeners.has(event_name):
+		return
+	
+	var listeners = event_listeners[event_name]
+	for listener_info in listeners:
+		var target = listener_info.target
+		var callback = listener_info.callback
+		
+		# 检查目标节点是否仍然有效
+		if target != null and not is_instance_valid(target):
+			continue
+		
+		# 调用回调函数
+		if data != null:
+			callback.call(data)
+		else:
+			callback.call()
+
+# ============ 维护方法 ============
+
+# 清理无效的监听器
+# 
+# 功能:
+# - 遍历所有监听器，移除已销毁节点的监听器
+# - 防止内存泄漏
+# - 建议定期调用或在场景切换时调用
+# 
+# 使用场景:
+# - 场景切换时清理
+# - 定期维护（如每分钟一次）
+# - 内存优化时调用
+func cleanup_invalid_listeners():
+	for event_name in event_listeners.keys():
+		var listeners = event_listeners[event_name]
+		# 从后往前遍历，避免删除元素时索引问题
+		for i in range(listeners.size() - 1, -1, -1):
+			var listener = listeners[i]
+			var target = listener.target
+			# 如果目标节点无效，移除监听器
+			if target != null and not is_instance_valid(target):
+				listeners.remove_at(i)
+				print("清理无效监听器: ", event_name)
+
+# ============ 查询方法 ============
+
+# 获取事件监听器数量
+# 
+# 参数:
+#   event_name: String - 事件名称
+# 
+# 返回值:
+#   int - 监听器数量
+# 
+# 使用场景:
+# - 调试时检查监听器数量
+# - 性能分析
+func get_listener_count(event_name: String) -> int:
+	if not event_listeners.has(event_name):
+		return 0
+	return event_listeners[event_name].size()
+
+# 清空所有事件监听器
+# 
+# 功能:
+# - 移除所有已注册的事件监听器
+# - 通常在游戏重置或退出时使用
+# 
+# 警告:
+# - 这是一个危险操作，会影响所有模块
+# - 使用前请确保所有模块都能正确处理监听器丢失
+func clear_all_listeners():
+	event_listeners.clear()
+	print("清空所有事件监听器")

_Core/systems/EventSystem.gd.uid

@@ -0,0 +1 @@
+uid://bfheblucmti24

_Core/utils/.gitkeep

@@ -0,0 +1,2 @@
+# 核心工具类目录
+# 存放字符串处理、数学计算等工具类

_Core/utils/StringUtils.gd

@@ -0,0 +1,386 @@
+class_name StringUtils
+
+# ============================================================================
+# StringUtils.gd - 字符串工具类
+# ============================================================================
+# 静态工具类，提供常用的字符串处理功能
+# 
+# 核心功能:
+# - 输入验证（邮箱、用户名、密码）
+# - 字符串格式化和转换
+# - 时间格式化和相对时间计算
+# - 文件大小格式化
+#
+# 使用方式:
+#   var is_valid = StringUtils.is_valid_email("user@example.com")
+#   var formatted_time = StringUtils.format_utc_to_local_time(utc_string)
+#
+# 注意事项:
+# - 所有方法都是静态的，无需实例化
+# - 验证方法返回布尔值或包含详细信息的字典
+# - 时间处理方法支持UTC到本地时间的转换
+# ============================================================================
+
+# ============ 输入验证方法 ============
+
+# 验证邮箱格式
+# 
+# 参数:
+#   email: String - 待验证的邮箱地址
+# 
+# 返回值:
+#   bool - true表示格式正确，false表示格式错误
+# 
+# 验证规则:
+# - 必须包含@符号
+# - @前后都必须有内容
+# - 域名部分必须包含至少一个点
+# - 顶级域名至少2个字符
+# 
+# 使用示例:
+#   if StringUtils.is_valid_email("user@example.com"):
+#       print("邮箱格式正确")
+static func is_valid_email(email: String) -> bool:
+	var regex = RegEx.new()
+	regex.compile("^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$")
+	return regex.search(email) != null
+
+# 验证用户名格式
+# 
+# 参数:
+#   username: String - 待验证的用户名
+# 
+# 返回值:
+#   bool - true表示格式正确，false表示格式错误
+# 
+# 验证规则:
+# - 只能包含字母、数字、下划线
+# - 长度不能为空且不超过50个字符
+# - 不能包含空格或特殊字符
+# 
+# 使用示例:
+#   if StringUtils.is_valid_username("user_123"):
+#       print("用户名格式正确")
+static func is_valid_username(username: String) -> bool:
+	# 检查长度
+	if username.is_empty() or username.length() > 50:
+		return false
+	
+	# 检查字符组成
+	var regex = RegEx.new()
+	regex.compile("^[a-zA-Z0-9_]+$")
+	return regex.search(username) != null
+
+# 验证密码强度
+# 
+# 参数:
+#   password: String - 待验证的密码
+# 
+# 返回值:
+#   Dictionary - 包含验证结果的详细信息
+#   {
+#     "valid": bool,      # 是否符合最低要求
+#     "message": String,  # 验证结果消息
+#     "strength": int     # 强度等级 (1-4)
+#   }
+# 
+# 验证规则:
+# - 最少8位，最多128位
+# - 必须包含字母和数字
+# - 强度评级：包含字母(+1)、数字(+1)、特殊字符(+1)、长度>=12(+1)
+# 
+# 使用示例:
+#   var result = StringUtils.validate_password_strength("MyPass123!")
+#   if result.valid:
+#       print("密码强度: ", result.message)
+static func validate_password_strength(password: String) -> Dictionary:
+	var result = {"valid": false, "message": "", "strength": 0}
+	
+	# 检查长度限制
+	if password.length() < 8:
+		result.message = "密码长度至少8位"
+		return result
+	
+	if password.length() > 128:
+		result.message = "密码长度不能超过128位"
+		return result
+	
+	# 检查字符类型
+	var has_letter = false    # 是否包含字母
+	var has_digit = false     # 是否包含数字
+	var has_special = false   # 是否包含特殊字符
+	
+	for i in range(password.length()):
+		var character = password[i]
+		if character >= 'a' and character <= 'z' or character >= 'A' and character <= 'Z':
+			has_letter = true
+		elif character >= '0' and character <= '9':
+			has_digit = true
+		elif character in "!@#$%^&*()_+-=[]{}|;:,.<>?":
+			has_special = true
+	
+	# 计算强度等级
+	var strength = 0
+	if has_letter:
+		strength += 1
+	if has_digit:
+		strength += 1
+	if has_special:
+		strength += 1
+	if password.length() >= 12:
+		strength += 1
+	
+	result.strength = strength
+	
+	# 检查最低要求
+	if not (has_letter and has_digit):
+		result.message = "密码必须包含字母和数字"
+		return result
+	
+	# 密码符合要求
+	result.valid = true
+	result.message = "密码强度: " + ["弱", "中", "强", "很强"][min(strength - 1, 3)]
+	return result
+
+# ============ 字符串格式化方法 ============
+
+# 截断字符串
+# 
+# 参数:
+#   text: String - 原始字符串
+#   max_length: int - 最大长度
+#   suffix: String - 截断后缀（默认为"..."）
+# 
+# 返回值:
+#   String - 截断后的字符串
+# 
+# 功能:
+# - 如果字符串长度超过限制，截断并添加后缀
+# - 如果字符串长度未超过限制，返回原字符串
+# 
+# 使用示例:
+#   var short_text = StringUtils.truncate("这是一个很长的文本", 10, "...")
+#   # 结果: "这是一个很长..."
+static func truncate(text: String, max_length: int, suffix: String = "...") -> String:
+	if text.length() <= max_length:
+		return text
+	return text.substr(0, max_length - suffix.length()) + suffix
+
+# 首字母大写
+# 
+# 参数:
+#   text: String - 原始字符串
+# 
+# 返回值:
+#   String - 首字母大写的字符串
+# 
+# 使用示例:
+#   var capitalized = StringUtils.capitalize_first("hello world")
+#   # 结果: "Hello world"
+static func capitalize_first(text: String) -> String:
+	if text.is_empty():
+		return text
+	return text[0].to_upper() + text.substr(1)
+
+# 转换为标题格式
+# 
+# 参数:
+#   text: String - 原始字符串
+# 
+# 返回值:
+#   String - 每个单词首字母大写的字符串
+# 
+# 功能:
+# - 将每个单词的首字母转换为大写
+# - 其余字母转换为小写
+# - 以空格分隔单词
+# 
+# 使用示例:
+#   var title = StringUtils.to_title_case("hello world game")
+#   # 结果: "Hello World Game"
+static func to_title_case(text: String) -> String:
+	var words = text.split(" ")
+	var result = []
+	for word in words:
+		if not word.is_empty():
+			result.append(capitalize_first(word.to_lower()))
+	return " ".join(result)
+
+# 移除HTML标签
+# 
+# 参数:
+#   html: String - 包含HTML标签的字符串
+# 
+# 返回值:
+#   String - 移除HTML标签后的纯文本
+# 
+# 功能:
+# - 使用正则表达式移除所有HTML标签
+# - 保留标签之间的文本内容
+# 
+# 使用示例:
+#   var plain_text = StringUtils.strip_html_tags("<p>Hello <b>World</b></p>")
+#   # 结果: "Hello World"
+static func strip_html_tags(html: String) -> String:
+	var regex = RegEx.new()
+	regex.compile("<[^>]*>")
+	return regex.sub(html, "", true)
+
+# 格式化文件大小
+# 
+# 参数:
+#   bytes: int - 文件大小（字节）
+# 
+# 返回值:
+#   String - 格式化后的文件大小字符串
+# 
+# 功能:
+# - 自动选择合适的单位（B, KB, MB, GB, TB）
+# - 保留一位小数（除了字节）
+# - 使用1024作为换算基数
+# 
+# 使用示例:
+#   var size_text = StringUtils.format_file_size(1536)
+#   # 结果: "1.5 KB"
+static func format_file_size(bytes: int) -> String:
+	var units = ["B", "KB", "MB", "GB", "TB"]
+	var size = float(bytes)
+	var unit_index = 0
+	
+	# 自动选择合适的单位
+	while size >= 1024.0 and unit_index < units.size() - 1:
+		size /= 1024.0
+		unit_index += 1
+	
+	# 格式化输出
+	if unit_index == 0:
+		return str(int(size)) + " " + units[unit_index]
+	else:
+		return "%.1f %s" % [size, units[unit_index]]
+
+# ============ 时间处理方法 ============
+
+# 将UTC时间字符串转换为本地时间显示
+# 
+# 参数:
+#   utc_time_str: String - UTC时间字符串（格式: 2025-12-25T11:23:52.175Z）
+# 
+# 返回值:
+#   String - 格式化的本地时间字符串
+# 
+# 功能:
+# - 解析ISO 8601格式的UTC时间
+# - 转换为本地时区时间
+# - 格式化为易读的中文时间格式
+# 
+# 使用示例:
+#   var local_time = StringUtils.format_utc_to_local_time("2025-12-25T11:23:52.175Z")
+#   # 结果: "2025年12月25日 19:23:52" (假设本地时区为UTC+8)
+static func format_utc_to_local_time(utc_time_str: String) -> String:
+	# 解析UTC时间字符串 (格式: 2025-12-25T11:23:52.175Z)
+	var regex = RegEx.new()
+	regex.compile("(\\d{4})-(\\d{2})-(\\d{2})T(\\d{2}):(\\d{2}):(\\d{2})")
+	var result = regex.search(utc_time_str)
+	
+	if result == null:
+		return utc_time_str  # 如果解析失败，返回原字符串
+	
+	# 提取时间组件
+	var year = int(result.get_string(1))
+	var month = int(result.get_string(2))
+	var day = int(result.get_string(3))
+	var hour = int(result.get_string(4))
+	var minute = int(result.get_string(5))
+	var second = int(result.get_string(6))
+	
+	# 创建UTC时间字典
+	var utc_dict = {
+		"year": year,
+		"month": month,
+		"day": day,
+		"hour": hour,
+		"minute": minute,
+		"second": second
+	}
+	
+	# 转换为Unix时间戳（UTC）
+	var utc_timestamp = Time.get_unix_time_from_datetime_dict(utc_dict)
+	
+	# 获取本地时间（Godot会自动处理时区转换）
+	var local_dict = Time.get_datetime_dict_from_unix_time(utc_timestamp)
+	
+	# 格式化为易读的本地时间
+	return "%04d年%02d月%02d日 %02d:%02d:%02d" % [
+		local_dict.year,
+		local_dict.month, 
+		local_dict.day,
+		local_dict.hour,
+		local_dict.minute,
+		local_dict.second
+	]
+
+# 获取相对时间描述
+# 
+# 参数:
+#   utc_time_str: String - UTC时间字符串
+# 
+# 返回值:
+#   String - 相对时间描述（如"5分钟后"、"2小时30分钟后"）
+# 
+# 功能:
+# - 计算指定时间与当前时间的差值
+# - 返回人性化的相对时间描述
+# - 支持秒、分钟、小时的组合显示
+# 
+# 使用示例:
+#   var relative_time = StringUtils.get_relative_time_until("2025-12-25T12:00:00Z")
+#   # 结果: "30分钟后" 或 "现在可以重试"
+static func get_relative_time_until(utc_time_str: String) -> String:
+	# 解析UTC时间字符串
+	var regex = RegEx.new()
+	regex.compile("(\\d{4})-(\\d{2})-(\\d{2})T(\\d{2}):(\\d{2}):(\\d{2})")
+	var result = regex.search(utc_time_str)
+	
+	if result == null:
+		return "时间格式错误"
+	
+	# 提取时间组件
+	var year = int(result.get_string(1))
+	var month = int(result.get_string(2))
+	var day = int(result.get_string(3))
+	var hour = int(result.get_string(4))
+	var minute = int(result.get_string(5))
+	var second = int(result.get_string(6))
+	
+	# 创建UTC时间字典
+	var utc_dict = {
+		"year": year,
+		"month": month,
+		"day": day,
+		"hour": hour,
+		"minute": minute,
+		"second": second
+	}
+	
+	# 转换为Unix时间戳
+	var target_timestamp = Time.get_unix_time_from_datetime_dict(utc_dict)
+	var current_timestamp = Time.get_unix_time_from_system()
+	
+	# 计算时间差（秒）
+	var diff_seconds = target_timestamp - current_timestamp
+	
+	# 格式化相对时间
+	if diff_seconds <= 0:
+		return "现在可以重试"
+	elif diff_seconds < 60:
+		return "%d秒后" % diff_seconds
+	elif diff_seconds < 3600:
+		var minutes = int(diff_seconds / 60)
+		return "%d分钟后" % minutes
+	else:
+		var hours = int(diff_seconds / 3600)
+		var minutes = int((diff_seconds % 3600) / 60)
+		if minutes > 0:
+			return "%d小时%d分钟后" % [hours, minutes]
+		else:
+			return "%d小时后" % hours

_Core/utils/StringUtils.gd.uid

@@ -0,0 +1 @@
+uid://bu8onmk6q8wic

assets/audio/audio/music/.gitkeep

@@ -0,0 +1 @@
+# 保持目录结构 - 音乐资源目录

assets/audio/audio/sounds/.gitkeep

@@ -0,0 +1 @@
+# 保持目录结构 - 音效资源目录

assets/audio/audio/voice/.gitkeep

@@ -0,0 +1 @@
+# 保持目录结构 - 语音资源目录

assets/sprites/materials/.gitkeep

@@ -0,0 +1 @@
+# 保持目录结构 - 材质资源目录

assets/sprites/shaders/.gitkeep

@@ -0,0 +1 @@
+# 保持目录结构 - 着色器资源目录

assets/sprites/sprites/characters/.gitkeep

@@ -0,0 +1 @@
+# 保持目录结构 - 角色精灵资源目录

assets/sprites/sprites/effects/.gitkeep

@@ -0,0 +1 @@
+# 保持目录结构 - 特效精灵资源目录

assets/sprites/sprites/environment/.gitkeep

@@ -0,0 +1 @@
+# 保持目录结构 - 环境精灵资源目录

claude.md

@@ -0,0 +1,96 @@
+# 🎯 CLAUDE.md - WhaleTown Project Instructions
+
+## 1. Project Vision & Context
+- **Project**: "WhaleTown" - A 2D top-down pixel art RPG.
+- **Engine**: Godot 4.2+ (Strictly NO Godot 3.x syntax).
+- **Architecture**: Strictly layered: `_Core` (Framework), `Scenes` (Gameplay), `UI` (Interface).
+- **Core Principle**: "Signal Up, Call Down". High decoupling via `EventSystem`.
+
+## 2. 🛠 Command Reference & Setup
+- **Input Map (Required Configuration)**:
+  - `move_left`, `move_right`, `move_up`, `move_down` (WASD / Arrows)
+  - `interact` (E Key / Space)
+  - `pause` (ESC)
+- **Run Game**: `godot --path .`
+- **Run Tests (GUT)**: `godot --headless -s addons/gut/gut_cmdline.gd -gdir=res://tests/ -ginclude_subdirs`
+- **Init Structure**: `mkdir -p _Core/managers _Core/systems Scenes/Maps Scenes/Entities Scenes/Components UI/Windows UI/HUD Assets/Sprites tests/unit tests/integration`
+
+## 3. 📂 File Path Rules (STRICT LOWERCASE)
+*Claude: Root folders MUST be lowercase. Scripts and Scenes MUST stay together.*
+- **Core Managers**: `_Core/managers/[Name].gd`
+- **Core Systems**: `_Core/systems/[Name].gd`
+- **Entities**: `Scenes/Entities/[EntityName]/[EntityName].tscn` (Script `.gd` in same folder).
+- **Maps**: `Scenes/Maps/[map_name].tscn`
+- **Components**: `Scenes/Components/[ComponentName].gd` (Reusable logic nodes).
+- **UI Windows**: `UI/Windows/[WindowName].tscn`
+- **Tests**: `tests/[unit|integration]/test_[name].gd` (Folder is lowercase `tests`).
+
+## 4. 📋 Coding Standards (The Law)
+- **Type Safety**: ALWAYS use strict static typing: `var speed: float = 100.0`, `func _ready() -> void`.
+- **Naming Conventions**: 
+  - `class_name PascalCase` at the top of every script.
+  - Variables/Functions: `snake_case`. Constants: `SCREAMING_SNAKE_CASE`.
+  - Private members: Prefix with underscore `_` (e.g., `var _health: int`).
+- **Node Access**: Use `%UniqueName` for UI and internal scene components.
+- **Signals**: Use "Signal Up, Call Down". Parent calls child methods; Child emits signals.
+- **Forbidden Patterns**:
+  - ❌ NO `yield()` -> Use `await`.
+  - ❌ NO `get_node()` in `_process` -> Cache with `@onready`.
+  - ❌ NO Linear Filter -> All Sprite2D/TileMap resources MUST use **Nearest** filter.
+
+## 5. 🏛 Architecture & Communication
+- **EventSystem**: Use `_Core/systems/EventSystem.gd` for cross-module messaging.
+- **Event Registry**: Use `class_name EventNames` in `_Core/EventNames.gd`. 
+  ```gdscript
+  class_name EventNames
+  const PLAYER_MOVED = "player_moved"
+  const INTERACT_PRESSED = "interact_pressed"
+  const NPC_TALKED = "npc_talked"
+Singletons: Only GameManager, SceneManager, EventSystem allowed as Autoloads.
+Decoupling: Low-level entities MUST NOT reference GameManager. Use events.
+6. 🏗 Implementation Details
+Player: CharacterBody2D. Must include Camera2D with position_smoothing_enabled = true.
+NPC/Interactables: Use Area2D named InteractionArea. Trigger via EventSystem.
+TileMap Layers:
+Layer 0: Ground (No collision).
+Layer 1: Obstacles (Physics Layer enabled).
+Layer 2: Decoration (Y-Sort enabled).
+Camera: Must auto-calculate limits via TileMap.get_used_rect().
+7. 🧪 Testing Requirements (MANDATORY)
+Coverage: Every Manager/System in _Core/ MUST have a GUT test.
+Naming: Test files must start with test_ and extend GutTest.
+Example:
+code
+Gdscript
+extends GutTest
+func test_event_emission():
+    var sender = Node.new()
+    watch_signals(EventSystem)
+    EventSystem.emit_event(EventNames.PLAYER_MOVED, {})
+    assert_signal_emitted(EventSystem, "event_raised")
+8. 🧘 The Zen of Development
+Juice or Death: Every interaction (UI popup, NPC talk) MUST have a Tween placeholder.
+Zero Magic Numbers: All speeds/timers MUST be @export or defined in Config/.
+Simplicity: If a function does two things, split it.
+Back of the Fence: Hidden logic (like ResponseHandler.gd) must be as clean as the HUD.
+9. 📝 Code Template (Entity Pattern)
+code
+Gdscript
+extends CharacterBody2D
+class_name Player
+
+# 1. Exports & Constants
+@export var move_speed: float = 200.0
+
+# 2. Node References
+@onready var sprite: Sprite2D = %Sprite2D
+
+# 3. Lifecycle
+func _physics_process(delta: float) -> void:
+    _move(delta)
+
+# 4. Private Methods
+func _move(_delta: float) -> void:
+    var dir := Input.get_vector("move_left", "move_right", "move_up", "move_down")
+    velocity = dir * move_speed
+    move_and_slide()

core/components/.gitkeep

@@ -1 +0,0 @@
-# 保持目录结构 - 组件脚本目录

core/input_box/.gitkeep

@@ -1 +0,0 @@
-# 保持目录结构 - 输入框组件目录

core/interfaces/.gitkeep

@@ -1 +0,0 @@
-# 保持目录结构 - 接口定义目录

core/managers/GameManager.gd

@@ -1,50 +0,0 @@
-extends Node
-
-# 游戏管理器 - 全局游戏状态管理
-# 单例模式，管理游戏的整体状态和生命周期
-
-signal game_state_changed(new_state: GameState)
-
-enum GameState {
-	LOADING,    # 加载中
-	AUTH,       # 认证状态
-	MAIN_MENU,  # 主菜单
-	IN_GAME,    # 游戏中
-	PAUSED,     # 暂停
-	SETTINGS    # 设置
-}
-
-var current_state: GameState = GameState.LOADING
-var previous_state: GameState = GameState.LOADING
-var current_user: String = ""
-var game_version: String = "1.0.0"
-
-func _ready():
-	print("GameManager 初始化完成")
-	change_state(GameState.AUTH)
-
-func change_state(new_state: GameState):
-	if current_state == new_state:
-		return
-	
-	previous_state = current_state
-	current_state = new_state
-	
-	print("游戏状态变更: ", GameState.keys()[previous_state], " -> ", GameState.keys()[current_state])
-	game_state_changed.emit(new_state)
-
-func get_current_state() -> GameState:
-	return current_state
-
-func get_previous_state() -> GameState:
-	return previous_state
-
-func set_current_user(username: String):
-	current_user = username
-	print("当前用户设置为: ", username)
-
-func get_current_user() -> String:
-	return current_user
-
-func is_user_logged_in() -> bool:
-	return not current_user.is_empty()

core/managers/GameManager.gd.uid

@@ -1 +0,0 @@
-uid://c6bl6k5kkfah6

core/managers/NetworkManager.gd.uid

@@ -1 +0,0 @@
-uid://cb040lxcf4smh

core/managers/ResponseHandler.gd.uid

@@ -1 +0,0 @@
-uid://ee8i4pdpdlsf

core/managers/SceneManager.gd

@@ -1,75 +0,0 @@
-extends Node
-
-# 场景管理器 - 负责场景切换和管理
-# 提供场景切换的统一接口
-
-signal scene_changed(scene_name: String)
-signal scene_change_started(scene_name: String)
-
-var current_scene_name: String = ""
-var is_changing_scene: bool = false
-
-# 场景路径映射
-var scene_paths: Dictionary = {
-	"main": "res://scenes/main_scene.tscn",
-	"auth": "res://scenes/auth_scene.tscn",
-	"game": "res://scenes/game_scene.tscn",
-	"battle": "res://scenes/battle_scene.tscn",
-	"inventory": "res://scenes/inventory_scene.tscn",
-	"shop": "res://scenes/shop_scene.tscn",
-	"settings": "res://scenes/settings_scene.tscn"
-}
-
-func _ready():
-	print("SceneManager 初始化完成")
-
-func change_scene(scene_name: String, use_transition: bool = true):
-	if is_changing_scene:
-		print("场景切换中，忽略新的切换请求")
-		return false
-	
-	if not scene_paths.has(scene_name):
-		print("错误: 未找到场景 ", scene_name)
-		return false
-	
-	var scene_path = scene_paths[scene_name]
-	print("开始切换场景: ", current_scene_name, " -> ", scene_name)
-	
-	is_changing_scene = true
-	scene_change_started.emit(scene_name)
-	
-	if use_transition:
-		await show_transition()
-	
-	var error = get_tree().change_scene_to_file(scene_path)
-	if error != OK:
-		print("场景切换失败: ", error)
-		is_changing_scene = false
-		return false
-	
-	current_scene_name = scene_name
-	is_changing_scene = false
-	scene_changed.emit(scene_name)
-	
-	if use_transition:
-		await hide_transition()
-	
-	print("场景切换完成: ", scene_name)
-	return true
-
-func get_current_scene_name() -> String:
-	return current_scene_name
-
-func register_scene(scene_name: String, scene_path: String):
-	scene_paths[scene_name] = scene_path
-	print("注册场景: ", scene_name, " -> ", scene_path)
-
-func show_transition():
-	# TODO: 实现场景切换过渡效果
-	print("显示场景切换过渡效果")
-	await get_tree().create_timer(0.2).timeout
-
-func hide_transition():
-	# TODO: 隐藏场景切换过渡效果
-	print("隐藏场景切换过渡效果")
-	await get_tree().create_timer(0.2).timeout

core/managers/SceneManager.gd.uid

@@ -1 +0,0 @@
-uid://bf5bmaqwstpuq

core/systems/EventSystem.gd

@@ -1,80 +0,0 @@
-extends Node
-
-# 全局事件系统 - 提供解耦的事件通信机制
-# 允许不同模块之间通过事件进行通信，避免直接依赖
-
-# 事件监听器存储
-var event_listeners: Dictionary = {}
-
-func _ready():
-	print("EventSystem 初始化完成")
-
-# 注册事件监听器
-func connect_event(event_name: String, callback: Callable, target: Node = null):
-	if not event_listeners.has(event_name):
-		event_listeners[event_name] = []
-	
-	var listener_info = {
-		"callback": callback,
-		"target": target
-	}
-	
-	event_listeners[event_name].append(listener_info)
-	print("注册事件监听器: ", event_name, " -> ", callback)
-
-# 移除事件监听器
-func disconnect_event(event_name: String, callback: Callable, target: Node = null):
-	if not event_listeners.has(event_name):
-		return
-	
-	var listeners = event_listeners[event_name]
-	for i in range(listeners.size() - 1, -1, -1):
-		var listener = listeners[i]
-		if listener.callback == callback and listener.target == target:
-			listeners.remove_at(i)
-			print("移除事件监听器: ", event_name, " -> ", callback)
-			break
-
-# 发送事件
-func emit_event(event_name: String, data: Variant = null):
-	print("发送事件: ", event_name, " 数据: ", data)
-	
-	if not event_listeners.has(event_name):
-		return
-	
-	var listeners = event_listeners[event_name]
-	for listener_info in listeners:
-		var target = listener_info.target
-		var callback = listener_info.callback
-		
-		# 检查目标节点是否仍然有效
-		if target != null and not is_instance_valid(target):
-			continue
-		
-		# 调用回调函数
-		if data != null:
-			callback.call(data)
-		else:
-			callback.call()
-
-# 清理无效的监听器
-func cleanup_invalid_listeners():
-	for event_name in event_listeners.keys():
-		var listeners = event_listeners[event_name]
-		for i in range(listeners.size() - 1, -1, -1):
-			var listener = listeners[i]
-			var target = listener.target
-			if target != null and not is_instance_valid(target):
-				listeners.remove_at(i)
-				print("清理无效监听器: ", event_name)
-
-# 获取事件监听器数量
-func get_listener_count(event_name: String) -> int:
-	if not event_listeners.has(event_name):
-		return 0
-	return event_listeners[event_name].size()
-
-# 清空所有事件监听器
-func clear_all_listeners():
-	event_listeners.clear()
-	print("清空所有事件监听器")

core/systems/EventSystem.gd.uid

@@ -1 +0,0 @@
-uid://csuxtwgni1dmf

core/utils/StringUtils.gd

@@ -1,199 +0,0 @@
-class_name StringUtils
-
-# 字符串工具类 - 提供常用的字符串处理功能
-
-# 验证邮箱格式
-static func is_valid_email(email: String) -> bool:
-	var regex = RegEx.new()
-	regex.compile("^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$")
-	return regex.search(email) != null
-
-# 验证用户名格式（字母、数字、下划线）
-static func is_valid_username(username: String) -> bool:
-	if username.is_empty() or username.length() > 50:
-		return false
-	
-	var regex = RegEx.new()
-	regex.compile("^[a-zA-Z0-9_]+$")
-	return regex.search(username) != null
-
-# 验证密码强度
-static func validate_password_strength(password: String) -> Dictionary:
-	var result = {"valid": false, "message": "", "strength": 0}
-	
-	if password.length() < 8:
-		result.message = "密码长度至少8位"
-		return result
-	
-	if password.length() > 128:
-		result.message = "密码长度不能超过128位"
-		return result
-	
-	var has_letter = false
-	var has_digit = false
-	var has_special = false
-	
-	for i in range(password.length()):
-		var char = password[i]
-		if char >= 'a' and char <= 'z' or char >= 'A' and char <= 'Z':
-			has_letter = true
-		elif char >= '0' and char <= '9':
-			has_digit = true
-		elif char in "!@#$%^&*()_+-=[]{}|;:,.<>?":
-			has_special = true
-	
-	var strength = 0
-	if has_letter:
-		strength += 1
-	if has_digit:
-		strength += 1
-	if has_special:
-		strength += 1
-	if password.length() >= 12:
-		strength += 1
-	
-	result.strength = strength
-	
-	if not (has_letter and has_digit):
-		result.message = "密码必须包含字母和数字"
-		return result
-	
-	result.valid = true
-	result.message = "密码强度: " + ["弱", "中", "强", "很强"][min(strength - 1, 3)]
-	return result
-
-# 截断字符串
-static func truncate(text: String, max_length: int, suffix: String = "...") -> String:
-	if text.length() <= max_length:
-		return text
-	return text.substr(0, max_length - suffix.length()) + suffix
-
-# 首字母大写
-static func capitalize_first(text: String) -> String:
-	if text.is_empty():
-		return text
-	return text[0].to_upper() + text.substr(1)
-
-# 转换为标题格式（每个单词首字母大写）
-static func to_title_case(text: String) -> String:
-	var words = text.split(" ")
-	var result = []
-	for word in words:
-		if not word.is_empty():
-			result.append(capitalize_first(word.to_lower()))
-	return " ".join(result)
-
-# 移除HTML标签
-static func strip_html_tags(html: String) -> String:
-	var regex = RegEx.new()
-	regex.compile("<[^>]*>")
-	return regex.sub(html, "", true)
-
-# 格式化文件大小
-static func format_file_size(bytes: int) -> String:
-	var units = ["B", "KB", "MB", "GB", "TB"]
-	var size = float(bytes)
-	var unit_index = 0
-	
-	while size >= 1024.0 and unit_index < units.size() - 1:
-		size /= 1024.0
-		unit_index += 1
-	
-	if unit_index == 0:
-		return str(int(size)) + " " + units[unit_index]
-	else:
-		return "%.1f %s" % [size, units[unit_index]]
-
-# 将UTC时间字符串转换为本地时间显示
-static func format_utc_to_local_time(utc_time_str: String) -> String:
-	# 解析UTC时间字符串 (格式: 2025-12-25T11:23:52.175Z)
-	var regex = RegEx.new()
-	regex.compile("(\\d{4})-(\\d{2})-(\\d{2})T(\\d{2}):(\\d{2}):(\\d{2})")
-	var result = regex.search(utc_time_str)
-	
-	if result == null:
-		return utc_time_str  # 如果解析失败，返回原字符串
-	
-	# 提取时间组件
-	var year = int(result.get_string(1))
-	var month = int(result.get_string(2))
-	var day = int(result.get_string(3))
-	var hour = int(result.get_string(4))
-	var minute = int(result.get_string(5))
-	var second = int(result.get_string(6))
-	
-	# 创建UTC时间字典
-	var utc_dict = {
-		"year": year,
-		"month": month,
-		"day": day,
-		"hour": hour,
-		"minute": minute,
-		"second": second
-	}
-	
-	# 转换为Unix时间戳（UTC）
-	var utc_timestamp = Time.get_unix_time_from_datetime_dict(utc_dict)
-	
-	# 获取本地时间（Godot会自动处理时区转换）
-	var local_dict = Time.get_datetime_dict_from_unix_time(utc_timestamp)
-	
-	# 格式化为易读的本地时间
-	return "%04d年%02d月%02d日 %02d:%02d:%02d" % [
-		local_dict.year,
-		local_dict.month, 
-		local_dict.day,
-		local_dict.hour,
-		local_dict.minute,
-		local_dict.second
-	]
-
-# 获取相对时间描述（多少分钟后）
-static func get_relative_time_until(utc_time_str: String) -> String:
-	# 解析UTC时间字符串
-	var regex = RegEx.new()
-	regex.compile("(\\d{4})-(\\d{2})-(\\d{2})T(\\d{2}):(\\d{2}):(\\d{2})")
-	var result = regex.search(utc_time_str)
-	
-	if result == null:
-		return "时间格式错误"
-	
-	# 提取时间组件
-	var year = int(result.get_string(1))
-	var month = int(result.get_string(2))
-	var day = int(result.get_string(3))
-	var hour = int(result.get_string(4))
-	var minute = int(result.get_string(5))
-	var second = int(result.get_string(6))
-	
-	# 创建UTC时间字典
-	var utc_dict = {
-		"year": year,
-		"month": month,
-		"day": day,
-		"hour": hour,
-		"minute": minute,
-		"second": second
-	}
-	
-	# 转换为Unix时间戳
-	var target_timestamp = Time.get_unix_time_from_datetime_dict(utc_dict)
-	var current_timestamp = Time.get_unix_time_from_system()
-	
-	# 计算时间差（秒）
-	var diff_seconds = target_timestamp - current_timestamp
-	
-	if diff_seconds <= 0:
-		return "现在可以重试"
-	elif diff_seconds < 60:
-		return "%d秒后" % diff_seconds
-	elif diff_seconds < 3600:
-		var minutes = int(diff_seconds / 60)
-		return "%d分钟后" % minutes
-	else:
-		var hours = int(diff_seconds / 3600)
-		var minutes = int((diff_seconds % 3600) / 60)
-		if minutes > 0:
-			return "%d小时%d分钟后" % [hours, minutes]
-		else:
-			return "%d小时后" % hours

core/utils/StringUtils.gd.uid

@@ -1 +0,0 @@
-uid://bturviv4bm4yk

data/characters/.gitkeep

@@ -1 +0,0 @@
-# 保持目录结构 - 角色数据目录

data/dialogues/.gitkeep

@@ -1 +0,0 @@
-# 保持目录结构 - 对话数据目录

data/items/.gitkeep

@@ -1 +0,0 @@
-# 保持目录结构 - 物品数据目录

data/levels/.gitkeep

@@ -1 +0,0 @@
-# 保持目录结构 - 关卡数据目录

docs/01-项目入门/README.md

@@ -0,0 +1,85 @@
+# 📖 项目入门
+
+> **适用人群**: 新加入项目的开发者  
+> **使用时机**: 项目开始前，环境搭建阶段  
+> **质量等级**: A级 ⭐⭐⭐⭐⭐
+
+这个目录包含了新人入门必读的基础文档，帮助你快速了解项目并搭建开发环境。
+
+## 📋 阅读顺序
+
+### 第一步：了解项目 🏗️
+**[项目结构说明.md](项目结构说明.md)**
+- 项目整体架构设计
+- 目录组织规则和命名规范
+- 各层级职责说明
+- 核心组件介绍
+
+### 第二步：配置环境 ⚙️
+**[项目设置指南.md](项目设置指南.md)**
+- Godot编辑器配置
+- AutoLoad单例设置
+- 输入映射配置（已预配置）
+- 开发环境验证
+
+## ✅ 完成检查
+
+阅读完本目录的文档后，你应该能够：
+- [ ] 理解项目的整体架构和设计理念
+- [ ] 成功配置Godot开发环境
+- [ ] 了解核心组件的作用和使用方式
+- [ ] 运行项目并进行基本测试
+- [ ] 验证所有AutoLoad单例正常工作
+- [ ] 确认游戏输入控制正常响应
+
+## 🎮 输入控制说明
+
+项目已预配置以下输入映射：
+- **移动控制**: `move_left` (A/←), `move_right` (D/→), `move_up` (W/↑), `move_down` (S/↓)
+- **交互控制**: `interact` (E键), `jump` (空格键)
+
+这些输入映射已经在 `project.godot` 中配置完成，无需额外设置。
+
+## 🚨 常见启动问题
+
+### 问题1: 游戏无法响应输入
+**原因**: 项目文件损坏或配置丢失  
+**解决**: 重新克隆项目，确保 `project.godot` 文件完整
+
+### 问题2: 控制台出现"Invalid action"错误
+**原因**: 输入映射配置丢失  
+**解决**: 检查 `project.godot` 文件中的 `[input]` 部分是否完整
+
+### 问题3: AutoLoad单例报错
+**原因**: AutoLoad配置不正确或文件路径错误  
+**解决**: 参考 [项目设置指南.md](项目设置指南.md) 验证配置
+
+### 问题4: EventSystem相关错误
+**原因**: 缺少 `_Core/EventNames.gd` 文件  
+**解决**: 确保项目包含完整的 `_Core` 目录结构
+
+## 🔗 下一步
+
+完成项目入门后，建议继续阅读：
+- [02-开发规范](../02-开发规范/) - 学习编码标准和架构规范
+- [03-技术实现](../03-技术实现/) - 开始具体功能开发
+
+## 💡 小贴士
+
+- **项目已预配置完成** - 输入映射和核心组件都已设置好
+- 遇到问题时，先查看对应文档的"常见问题"部分
+- 建议在实际操作中边读边做，加深理解
+- 可以将重要的配置信息做笔记备用
+- 完成每个步骤后，建议运行项目验证配置是否正确
+- 重点关注 `_Core` 目录中的核心组件，它们是项目的基础
+
+## 🛠️ 核心组件预览
+
+项目包含以下核心组件，在后续开发中会频繁使用：
+- **EventSystem** - 全局事件通信系统
+- **GameManager** - 游戏状态管理
+- **SceneManager** - 场景切换管理
+- **NetworkManager** - 网络请求管理
+- **ProjectPaths** - 统一路径管理
+
+详细使用方法请参考 [架构与通信规范](../02-开发规范/架构与通信规范.md)。

docs/01-项目入门/输入映射配置.md

@@ -0,0 +1,157 @@
+# 输入映射配置指南
+
+本文档说明了WhaleTown项目的输入映射配置要求和设置方法。
+
+## 🎮 必需的输入映射
+
+### 基础移动控制
+- **`move_left`** - 向左移动
+  - 推荐按键：A键、左方向键
+- **`move_right`** - 向右移动  
+  - 推荐按键：D键、右方向键
+- **`move_up`** - 向上移动
+  - 推荐按键：W键、上方向键
+- **`move_down`** - 向下移动
+  - 推荐按键：S键、下方向键
+
+### 交互控制
+- **`interact`** - 交互动作
+  - 推荐按键：E键、空格键
+- **`pause`** - 暂停游戏
+  - 推荐按键：ESC键
+
+## ⚙️ Godot编辑器配置步骤
+
+### 1. 打开输入映射设置
+1. 在Godot编辑器中打开 `Project` → `Project Settings`
+2. 切换到 `Input Map` 标签
+
+### 2. 添加输入动作
+对于每个必需的输入动作：
+
+1. 在 `Action` 输入框中输入动作名称（如 `move_left`）
+2. 点击 `Add` 按钮
+3. 点击新添加动作右侧的 `+` 按钮
+4. 按下对应的按键进行绑定
+5. 重复步骤3-4添加备用按键
+
+### 3. 配置示例
+
+```
+move_left:
+  - Key: A
+  - Key: Left Arrow
+
+move_right:
+  - Key: D  
+  - Key: Right Arrow
+
+move_up:
+  - Key: W
+  - Key: Up Arrow
+
+move_down:
+  - Key: S
+  - Key: Down Arrow
+
+interact:
+  - Key: E
+  - Key: Space
+
+pause:
+  - Key: Escape
+```
+
+## 🔧 代码中的使用方法
+
+### 移动输入检测
+```gdscript
+func _physics_process(delta: float) -> void:
+    # 获取移动向量
+    var direction := Input.get_vector(
+        "move_left", "move_right", 
+        "move_up", "move_down"
+    )
+    
+    # 应用移动
+    velocity = direction * move_speed
+    move_and_slide()
+```
+
+### 交互输入检测
+```gdscript
+func _input(event: InputEvent) -> void:
+    if event.is_action_pressed("interact"):
+        _handle_interaction()
+    
+    if event.is_action_pressed("pause"):
+        _toggle_pause()
+```
+
+### 连续输入检测
+```gdscript
+func _process(delta: float) -> void:
+    # 检测持续按下的按键
+    if Input.is_action_pressed("interact"):
+        _continuous_interaction(delta)
+```
+
+## 📱 手柄支持（可选）
+
+### 推荐手柄映射
+- **左摇杆** - 移动控制
+- **A按钮/X按钮** - 交互
+- **Start按钮** - 暂停
+
+### 配置方法
+1. 在Input Map中为每个动作添加手柄输入
+2. 使用 `Joypad Button` 或 `Joypad Axis` 进行绑定
+
+## ✅ 验证配置
+
+### 测试脚本
+创建一个简单的测试脚本验证输入配置：
+
+```gdscript
+extends Node
+
+func _ready() -> void:
+    print("输入映射测试开始...")
+    _test_input_actions()
+
+func _test_input_actions() -> void:
+    var required_actions = [
+        "move_left", "move_right", "move_up", "move_down",
+        "interact", "pause"
+    ]
+    
+    for action in required_actions:
+        if InputMap.has_action(action):
+            print("✅ ", action, " - 已配置")
+        else:
+            print("❌ ", action, " - 未配置")
+
+func _input(event: InputEvent) -> void:
+    # 实时显示输入事件
+    for action in InputMap.get_actions():
+        if event.is_action_pressed(action):
+            print("按下: ", action)
+```
+
+## 🚨 常见问题
+
+### Q: 输入没有响应怎么办？
+A: 检查以下几点：
+1. 确认输入动作名称拼写正确
+2. 验证按键是否正确绑定
+3. 检查代码中是否正确使用了动作名称
+
+### Q: 如何添加自定义输入？
+A: 按照相同步骤在Input Map中添加新的动作，并在代码中使用对应的动作名称。
+
+### Q: 手柄不工作怎么办？
+A: 确保手柄已连接，并在Input Map中正确配置了手柄按钮映射。
+
+---
+
+**注意：输入映射配置是游戏正常运行的基础，请确保所有必需的输入动作都已正确配置！**

docs/01-项目入门/项目结构说明.md

@@ -0,0 +1,393 @@
+# WhaleTown 项目结构说明
+
+本文档详细说明了 WhaleTown 项目的文件结构设计，采用分层架构模式，确保团队协作高效且代码结构清晰。
+
+## 🎯 设计理念
+
+### 核心原则
+- **分层架构**：框架层、游戏层、界面层明确分离
+- **团队协作**：策划、美术、开发三类角色各司其职
+- **高度解耦**：通过事件系统实现组件间通信
+- **组件复用**：可复用组件统一管理
+- **标准化**：统一的命名规范和目录结构
+
+### 团队协作模式
+- **🎮 开发团队** - 主要工作在 `_Core/`、`scenes/`、`UI/`、`Utils/`
+- **🎨 美术团队** - 主要工作在 `assets/`
+- **📋 策划团队** - 主要工作在 `Config/`
+
+## 🏗️ 项目架构概览
+
+```
+WhaleTown/
+├── 🔧 _Core/                   # [核心层] 功能实现与组件实现，项目最基本的底层实现
+├── 🎬 scenes/                  # [场景层] 场景与视觉呈现，包含地图、人物等视觉部分
+├── 🎨 assets/                  # [资源层] 静态资源存储，包括图片、音乐、视频、贴图等
+├── ⚙️ Config/                  # [配置层] 配置文件管理，用于配置各类环境
+├── 🧪 tests/                   # [测试层] 测试文件系统，放置所有组件的测试代码
+├── 🌐 web_assets/              # [发布层] Web导出资源，专门用于Web平台导出
+└── 📚 docs/                    # [文档层] 项目文档
+```
+
+---
+
+## 📁 详细目录结构
+
+### 1. 🔧 核心层 (_Core/)
+> **负责团队**: 开发团队  
+> **职责**: 功能实现与组件实现，项目最基本的底层实现
+
+```
+_Core/
+├── managers/                   # 全局管理器
+│   ├── GameManager.gd          # 游戏状态管理
+│   ├── SceneManager.gd         # 场景切换管理
+│   ├── NetworkManager.gd       # 网络通信管理
+│   └── ResponseHandler.gd      # API响应处理
+├── systems/                    # 核心系统
+│   └── EventSystem.gd          # 全局事件系统
+├── components/                 # 基础组件实现
+│   ├── BaseCharacter.gd        # 基础角色组件
+│   ├── BaseItem.gd             # 基础物品组件
+│   └── BaseUI.gd               # 基础UI组件
+├── utils/                      # 🔨 核心工具类
+│   ├── StringUtils.gd          # 字符串处理工具
+│   ├── MathUtils.gd            # 数学计算工具
+│   └── PixelUtils.gd           # 像素风游戏专用工具
+├── EventNames.gd               # 事件名称定义
+└── ProjectPaths.gd             # 路径统一管理
+```
+
+**特点**:
+- 自动加载 (AutoLoad) 单例
+- 全局可访问的核心功能
+- 与具体游戏逻辑无关的底层实现
+- 提供基础服务和组件框架
+
+**使用示例**:
+```gdscript
+# 游戏状态管理
+GameManager.change_state(GameManager.GameState.IN_GAME)
+
+# 场景切换
+SceneManager.change_scene("main")
+
+# 事件通信
+EventSystem.emit_event("player_moved", {"position": Vector2(100, 200)})
+```
+
+### 2. 🎬 场景层 (scenes/)
+> **负责团队**: 开发团队  
+> **职责**: 场景与视觉呈现，包含地图场景、人物场景等一系列视觉呈现的部分
+
+```
+scenes/
+├── MainScene.tscn              # 🎯 主入口场景 - 所有图像显示的入口文件
+├── MainScene.gd                # 主场景控制器脚本
+├── maps/                       # 地图场景
+│   ├── main_world.tscn         # 主世界地图
+│   ├── dungeon_01.tscn         # 地牢场景
+│   └── town_center.tscn        # 城镇中心
+├── characters/                 # 人物场景
+│   ├── player/                 # 玩家角色
+│   │   ├── Player.tscn         # 玩家场景
+│   │   └── Player.gd           # 玩家脚本
+│   ├── npcs/                   # NPC角色
+│   └── enemies/                # 敌人角色
+├── ui/                         # UI界面场景
+│   ├── menus/                  # 菜单界面
+│   ├── hud/                    # 游戏HUD
+│   └── dialogs/                # 对话框
+├── effects/                    # 特效场景
+│   ├── particles/              # 粒子效果
+│   └── animations/             # 动画效果
+└── prefabs/                    # 预制体组件
+    ├── items/                  # 物品预制体
+    └── interactive/            # 交互对象预制体
+```
+
+**设计原则**:
+- **场景内聚**: 脚本紧邻场景文件存放
+- **分类明确**: 按功能类型（地图、人物、UI、特效）分类
+- **模块化**: 可复用的预制体统一管理
+- **视觉导向**: 主要负责游戏的视觉呈现和UI实现
+
+### 3. 🎨 资源层 (assets/)
+> **负责团队**: 美术团队  
+> **职责**: 所有静态资源的存储，包括图片、音乐、视频、贴图等素材
+
+```
+assets/
+├── sprites/                    # 精灵图片资源
+│   ├── characters/             # 角色精灵（玩家、NPC、敌人）
+│   ├── environment/            # 环境精灵（地形、建筑、装饰）
+│   ├── items/                  # 物品精灵（道具、装备、收集品）
+│   ├── effects/                # 特效精灵（爆炸、魔法、粒子）
+│   └── ui/                     # UI精灵（按钮、图标、边框）
+├── audio/                      # 音频资源
+│   ├── music/                  # 背景音乐（BGM）
+│   ├── sounds/                 # 音效（SFX）
+│   └── voice/                  # 语音（对话、旁白）
+├── fonts/                      # 字体文件
+│   ├── pixel_fonts/            # 像素风字体
+│   └── ui_fonts/               # UI专用字体
+├── materials/                  # 材质资源
+│   ├── pixel_materials/        # 像素风材质
+│   └── shader_materials/       # 着色器材质
+├── shaders/                    # 着色器文件
+│   ├── pixel_shaders/          # 像素风着色器
+│   └── effect_shaders/         # 特效着色器
+├── ui/                         # UI专用资源
+│   ├── themes/                 # UI主题
+│   ├── icons/                  # 图标资源
+│   └── backgrounds/            # 背景图片
+└── icon/                       # 应用图标
+    ├── icon.svg                # 矢量图标
+    └── icon.png                # 位图图标
+```
+
+**像素风游戏资源特点**:
+- **像素完美**: 所有精灵使用像素完美设置（Filter: Off, Mipmaps: Off）
+- **统一风格**: 保持一致的像素密度和调色板
+- **分辨率标准**: 建议使用16x16、32x32等标准像素尺寸
+- **动画帧**: 角色动画使用精灵表（Sprite Sheet）组织
+
+### 4. ⚙️ 配置层 (Config/)
+> **负责团队**: 策划团队  
+> **职责**: 配置文件管理，主要用来配置各类环境
+
+```
+Config/
+├── game_config.json            # 游戏主配置
+├── zh_CN.json                  # 中文本地化
+├── environment/                # 环境配置
+│   ├── development.json        # 开发环境配置
+│   ├── testing.json            # 测试环境配置
+│   └── production.json         # 生产环境配置
+├── gameplay/                   # 游戏玩法配置
+│   ├── character_stats.json    # 角色属性配置
+│   ├── item_database.json      # 物品数据库
+│   └── level_config.json       # 关卡配置
+└── localization/               # 本地化配置
+    ├── en_US.json              # 英文本地化
+    ├── zh_CN.json              # 中文本地化
+    └── ja_JP.json              # 日文本地化
+```
+
+**配置文件特点**:
+- **环境分离**: 开发、测试、生产环境配置分离
+- **数据驱动**: 游戏数值通过配置文件控制
+- **本地化支持**: 多语言文本管理
+- **热更新**: 支持运行时配置更新
+
+### 5. 🧪 测试层 (tests/)
+> **负责团队**: 开发团队  
+> **职责**: 测试文件系统，放置所有对应组件的测试代码，方便快速进行功能性与性能测试
+
+```
+tests/
+├── unit/                       # 单元测试
+│   ├── core/                   # 核心组件测试
+│   ├── characters/             # 角色组件测试
+│   └── systems/                # 系统功能测试
+├── integration/                # 集成测试
+│   ├── scene_transitions/      # 场景切换测试
+│   ├── save_load/              # 存档系统测试
+│   └── network/                # 网络功能测试
+├── performance/                # 性能测试
+│   ├── framerate/              # 帧率测试
+│   ├── memory/                 # 内存使用测试
+│   └── loading_times/          # 加载时间测试
+├── api/                        # API接口测试
+│   ├── auth_tests.py           # 认证接口测试
+│   └── game_api_tests.py       # 游戏API测试
+└── ui/                         # UI功能测试
+    ├── menu_tests/             # 菜单测试
+    └── dialog_tests/           # 对话框测试
+```
+
+**测试类型说明**:
+- **单元测试**: 测试单个组件的功能正确性
+- **集成测试**: 测试组件间的交互和协作
+- **性能测试**: 监控游戏性能指标，确保流畅运行
+- **API测试**: 验证网络接口的正确性和稳定性
+- **UI测试**: 测试用户界面的交互和响应
+
+### 6. 🌐 Web导出层 (web_assets/)
+> **负责团队**: 自动生成  
+> **职责**: Web导出资源，专门用于Web平台导出的相关资源和配置文件
+
+```
+web_assets/
+├── html/                       # HTML模板文件
+│   ├── index.html              # Web版本入口页面
+│   └── loading.html            # 加载页面模板
+├── css/                        # 样式文件
+│   ├── game.css                # 游戏样式
+│   └── loading.css             # 加载样式
+├── js/                         # JavaScript脚本
+│   ├── game_loader.js          # 游戏加载器
+│   └── utils.js                # 工具函数
+├── icons/                      # Web应用图标
+│   ├── favicon.ico             # 网站图标
+│   └── app_icons/              # PWA应用图标
+└── config/                     # Web配置文件
+    ├── manifest.json           # PWA清单文件
+    └── service-worker.js       # 服务工作者
+```
+
+**Web导出特点**:
+- **PWA支持**: 支持渐进式Web应用功能
+- **响应式设计**: 适配不同屏幕尺寸
+- **加载优化**: 优化资源加载和缓存策略
+- **跨平台兼容**: 确保在各种浏览器中正常运行
+
+### 7. 📚 文档层 (docs/)
+> **负责团队**: 全体团队  
+> **职责**: 项目文档和开发指南
+
+```
+docs/
+├── 01-项目入门/                # 新人必读文档
+├── 02-开发规范/                # 编码标准文档
+├── 03-技术实现/                # 开发指导文档
+├── 04-高级开发/                # 进阶技巧文档
+├── 05-部署运维/                # 发布部署文档
+├── 06-功能模块/                # 功能文档
+└── AI_docs/                    # 🤖 AI专用文档
+    ├── README.md               # AI文档总览
+    ├── architecture_guide.md   # 架构执行指南
+    ├── coding_standards.md     # 代码风格规范
+    ├── templates/              # 代码模板库
+    │   ├── components.md       # 组件模板集合
+    │   ├── managers.md         # 管理器模板集合
+    │   └── ui_templates.md     # UI模板集合
+    ├── workflows/              # 工作流程指南
+    │   ├── feature_development.md # 功能开发流程
+    │   ├── bug_fixing.md       # Bug修复流程
+    │   └── testing_workflow.md # 测试执行流程
+    └── quick_reference/        # 快速参考手册
+        ├── code_snippets.md    # 常用代码片段
+        ├── api_reference.md    # API快速参考
+        └── troubleshooting.md  # 故障排除指南
+```
+
+**AI_docs特点**:
+- **结构化执行**: 每个文档都包含可直接执行的步骤和代码模板
+- **标准化规范**: 为AI编程助手提供统一的开发标准和最佳实践
+- **模板驱动**: 提供完整的代码模板，确保代码一致性和质量
+- **工作流导向**: 包含详细的开发工作流程，提升AI协作效率
+
+```
+docs/
+├── 01-项目入门/                # 新人必读
+├── 02-开发规范/                # 编码标准
+├── 03-技术实现/                # 开发指导
+├── 04-高级开发/                # 进阶技巧
+├── 05-部署运维/                # 发布部署
+└── 06-功能模块/                # 功能文档
+```
+
+---
+
+## 🤝 团队协作指南
+
+### 开发团队 🎮
+**主要工作区域**: `_Core/`, `scenes/`, `tests/`
+
+**日常工作流程**:
+1. 在 `_Core/` 中开发核心系统、管理器、基础组件和工具类
+2. 在 `scenes/` 中创建游戏场景、角色、UI界面和特效
+3. 在 `tests/` 中编写各类测试用例确保代码质量
+
+**协作要点**:
+- 遵循架构设计原则，使用事件系统进行模块通信
+- 保持代码模块化和可复用性
+- 将通用工具类放在 `_Core/utils/` 中统一管理
+- 针对像素风游戏特点优化性能
+- 及时编写测试和文档
+
+### 美术团队 🎨
+**主要工作区域**: `assets/`
+
+**日常工作流程**:
+1. 按分类整理美术资源到 `assets/` 对应目录
+2. 确保像素艺术风格的一致性和像素完美
+3. 配置正确的Godot导入设置（关闭过滤、禁用Mipmaps）
+4. 与开发团队协作调整UI和游戏资源
+
+**像素风游戏特殊要求**:
+- 严格遵循像素完美原则
+- 保持统一的像素密度和调色板
+- 使用标准像素尺寸（16x16、32x32等）
+- 精灵动画使用精灵表组织
+
+### 策划团队 📋
+**主要工作区域**: `Config/`
+
+**日常工作流程**:
+1. 在 `Config/` 中维护游戏配置和数值平衡
+2. 管理多环境配置（开发、测试、生产）
+3. 负责本地化文本的翻译和维护
+4. 设计游戏玩法和关卡数据
+
+**协作要点**:
+- 使用JSON格式编写配置文件
+- 保持配置文件的结构清晰和可维护性
+- 及时更新本地化文本
+- 与开发团队协作实现数据驱动的游戏功能
+
+---
+
+## 🔄 开发工作流
+
+### 新功能开发流程
+1. **需求分析** - 明确功能需求和设计方案
+2. **架构设计** - 确定涉及的模块和接口
+3. **资源准备** - 美术团队准备相关资源
+4. **配置设置** - 策划团队配置相关数据
+5. **代码实现** - 开发团队实现功能逻辑
+6. **测试验证** - 编写测试用例验证功能
+7. **文档更新** - 更新相关文档说明
+
+### 版本发布流程
+1. **功能完成** - 所有计划功能开发完成
+2. **测试通过** - 所有测试用例通过
+3. **资源整理** - 美术资源整理完成
+4. **配置确认** - 策划配置确认无误
+5. **构建发布** - 使用 `tools/` 中的脚本构建
+6. **部署上线** - 部署到目标环境
+
+---
+
+## 📋 最佳实践
+
+### 目录命名规范
+- **文件夹**: 使用 PascalCase (如: `Config/`, `Utils/`)
+- **文件**: 使用 snake_case (如: `main_scene.tscn`, `game_config.json`)
+- **脚本类**: 使用 PascalCase (如: `GameManager.gd`)
+
+### 资源管理规范
+- 所有资源必须放在 `assets/` 对应分类目录下
+- 使用描述性的文件名，避免使用数字编号
+- **像素艺术资源必须关闭过滤** (Filter: Off, Mipmaps: Off)
+- 保持统一的像素密度和调色板
+- 使用标准像素尺寸（16x16、32x32、64x64等）
+- 及时清理不使用的资源文件
+
+### 代码组织规范
+- 脚本文件与场景文件放在同一目录
+- 使用事件系统实现模块间通信，避免直接引用
+- 保持单一职责原则，避免过度耦合
+- 针对像素风游戏优化性能（避免浮点数位置、使用整数坐标）
+- 及时编写注释和文档
+
+### 像素风游戏特殊规范
+- **像素完美**: 确保所有精灵在整数坐标上渲染
+- **统一风格**: 保持一致的像素密度和艺术风格
+- **性能优化**: 使用对象池管理频繁创建销毁的对象
+- **分辨率适配**: 使用像素完美的缩放方式适配不同分辨率
+
+---
+
+**记住：良好的项目结构是团队协作成功的基础！**

docs/01-项目入门/项目设置指南.md

@@ -0,0 +1,142 @@
+# 项目设置指南
+
+本文档指导你完成WhaleTown项目的Godot编辑器配置，确保开发环境正确设置。
+
+## 🎯 AutoLoad 配置
+
+项目已经预配置了以下AutoLoad单例，你可以验证配置是否正确：
+
+### 1. 打开项目设置
+1. 在Godot编辑器中打开 `Project` → `Project Settings`
+2. 切换到 `AutoLoad` 标签
+
+### 2. 验证AutoLoad配置
+确认以下单例已正确配置：
+
+| 名称 | 路径 | 单例 |
+|------|------|------|
+| GameManager | `res://_Core/managers/GameManager.gd` | ✅ |
+| SceneManager | `res://_Core/managers/SceneManager.gd` | ✅ |
+| EventSystem | `res://_Core/systems/EventSystem.gd` | ✅ |
+| NetworkManager | `res://_Core/managers/NetworkManager.gd` | ✅ |
+| ResponseHandler | `res://_Core/managers/ResponseHandler.gd` | ✅ |
+
+### 3. 如果需要手动添加AutoLoad
+如果某个AutoLoad缺失，可以手动添加：
+
+1. 点击 `Add` 按钮
+2. 设置以下信息：
+   - **Path**: 对应的脚本路径
+   - **Name**: 单例名称
+   - **Singleton**: ✅ 勾选
+3. 点击 `Add` 确认
+
+## ⚙️ 其他重要设置
+
+### 主题配置
+项目使用自定义中文主题：
+- **路径**: `assets/ui/chinese_theme.tres`
+- **字体**: 微软雅黑 (`assets/fonts/msyh.ttc`)
+
+### 主场景设置
+- **主场景**: `res://Scenes/Maps/main_scene.tscn`
+- **窗口大小**: 1376x768
+- **窗口模式**: 全屏模式
+
+### 渲染设置
+- **渲染器**: GL Compatibility (兼容性优先)
+- **拉伸模式**: Canvas Items
+- **拉伸比例**: Expand
+
+## 🧪 验证设置
+
+### 1. 测试AutoLoad单例
+在任何脚本中可以直接使用：
+
+```gdscript
+func _ready():
+    # 测试GameManager
+    print("游戏状态: ", GameManager.get_current_state())
+    
+    # 测试SceneManager
+    print("当前场景: ", SceneManager.get_current_scene_name())
+    
+    # 测试EventSystem
+    EventSystem.emit_event("test_event", {"message": "Hello World"})
+    
+    # 测试NetworkManager
+    var request_id = NetworkManager.login("test_user", "test_password")
+    print("网络请求ID: ", request_id)
+```
+
+### 2. 检查控制台输出
+运行项目后，检查控制台是否有以下信息：
+- ✅ 没有AutoLoad相关错误
+- ✅ 各个管理器初始化成功
+- ✅ 主题和字体加载正常
+
+### 3. 测试场景切换
+```gdscript
+# 测试场景管理器
+func test_scene_manager():
+    # 切换到主场景
+    SceneManager.change_scene("main")
+```
+
+## 🔧 常见问题排查
+
+### 问题1: AutoLoad脚本找不到
+**症状**: 控制台显示"Cannot load script"错误
+
+**解决方案**:
+1. 检查脚本文件是否存在于指定路径
+2. 确认脚本文件没有语法错误
+3. 重新导入项目 (`Project` → `Reload Current Project`)
+
+### 问题2: 单例无法访问
+**症状**: 代码中无法访问GameManager等单例
+
+**解决方案**:
+1. 确认AutoLoad配置中勾选了"Singleton"
+2. 重启Godot编辑器
+3. 检查脚本中是否有拼写错误
+
+### 问题3: 主题显示异常
+**症状**: 界面字体或样式显示不正确
+
+**解决方案**:
+1. 检查 `assets/ui/chinese_theme.tres` 文件是否存在
+2. 确认字体文件 `assets/fonts/msyh.ttc` 已正确导入
+3. 在项目设置中重新设置自定义主题
+
+### 问题4: 网络请求失败
+**症状**: NetworkManager调用失败
+
+**解决方案**:
+1. 检查网络连接
+2. 确认API地址配置正确
+3. 查看ResponseHandler是否正常工作
+
+## 📋 配置检查清单
+
+完成设置后，请检查以下项目：
+
+- [ ] 所有AutoLoad单例配置正确
+- [ ] 主场景可以正常启动
+- [ ] 控制台没有错误信息
+- [ ] 自定义主题加载正常
+- [ ] 中文字体显示正确
+- [ ] 网络管理器可以正常调用
+- [ ] 事件系统工作正常
+- [ ] 场景管理器可以切换场景
+
+## 🚀 下一步
+
+配置完成后，建议继续阅读：
+- [输入映射配置](输入映射配置.md) - 设置游戏控制
+- [命名规范](../02-开发规范/命名规范.md) - 学习编码规范
+- [架构与通信规范](../02-开发规范/架构与通信规范.md) - 理解项目架构
+
+---
+
+**💡 提示**: 如果遇到问题，可以参考 [测试指南](../03-技术实现/测试指南.md) 进行更详细的功能验证。

docs/02-开发规范/README.md

@@ -0,0 +1,105 @@
+# 📋 开发规范
+
+> **适用人群**: 所有开发者  
+> **使用时机**: 编码过程中，代码审查时
+
+这个目录包含了项目的所有编码标准和开发规范，确保团队代码风格一致，架构设计统一。
+
+## 📚 规范文档
+
+### 基础规范 📝
+**[命名规范.md](命名规范.md)**
+- 文件、类、变量、函数命名标准
+- 资源文件命名规则
+- 目录结构命名约定
+
+**[代码注释规范.md](代码注释规范.md)**
+- 注释格式和标准
+- 文档生成规范
+- AI辅助开发指南
+
+**[Git提交规范.md](Git提交规范.md)**
+- 提交信息格式标准
+- 分支管理策略
+- 代码审查流程
+
+### 架构规范 🏗️
+**[架构与通信规范.md](架构与通信规范.md)**
+- 分层架构设计原则
+- EventSystem事件系统使用
+- 组件间通信标准
+- 单例管理规范
+
+### 质量标准 ⭐
+**[开发哲学与最佳实践.md](开发哲学与最佳实践.md)**
+- 项目开发理念
+- 代码质量标准
+- 最佳实践指导
+- 代码审查清单
+
+## 🎯 使用指南
+
+### 新人学习路径
+1. **命名规范** - 学会正确命名
+2. **架构与通信规范** - 理解项目架构
+3. **开发哲学与最佳实践** - 掌握质量标准
+4. **代码注释规范** - 学会写好注释
+5. **Git提交规范** - 规范版本控制
+
+### 日常开发参考
+- 编码时参考 **命名规范** 和 **架构规范**
+- 提交代码前检查 **最佳实践** 清单
+- 写注释时遵循 **注释规范**
+- 提交时遵循 **Git规范**
+
+### 代码审查要点
+- [ ] 命名是否符合规范
+- [ ] 架构设计是否合理
+- [ ] 代码质量是否达标
+- [ ] 注释是否完整清晰
+- [ ] 提交信息是否规范
+
+## ⚠️ 重要提醒
+
+### 强制性规范
+以下规范是**强制性**的，必须严格遵守：
+- 文件和目录命名规范
+- EventSystem通信规范
+- 类型安全要求
+- Git提交格式
+
+### 建议性规范
+以下规范是**建议性**的，推荐遵循：
+- 代码注释的详细程度
+- 函数长度和复杂度
+- 性能优化建议
+
+## 🔄 规范更新
+
+### 更新原则
+- 规范变更需要团队讨论
+- 重大变更需要文档化说明
+- 保持向后兼容性
+
+### 更新流程
+1. 提出规范变更建议
+2. 团队讨论和评审
+3. 更新相关文档
+4. 通知所有开发者
+
+## 🤝 团队协作
+
+### 规范执行
+- 代码审查时严格检查规范遵循情况
+- 定期进行规范培训和分享
+- 鼓励团队成员提出改进建议
+
+### 问题反馈
+如果发现规范问题或有改进建议：
+- 创建Issue讨论
+- 在团队会议中提出
+- 通过PR提交改进方案
+
+---
+
+**记住：规范不是束缚，而是团队协作的基础！**

docs/02-开发规范/开发哲学与最佳实践.md

@@ -0,0 +1,406 @@
+# 开发哲学与最佳实践
+
+本文档阐述了WhaleTown项目的开发哲学和编程最佳实践，旨在指导团队创造高质量、可维护的代码。
+
+## 🧘 开发哲学
+
+### 核心理念
+- **用户体验至上** - 每个功能都要考虑用户感受
+- **代码即文档** - 代码应该自解释，清晰易懂
+- **简洁胜于复杂** - 优先选择简单直接的解决方案
+- **质量重于速度** - 宁可慢一点，也要做对
+
+### 设计原则
+
+#### 1. 流畅体验 (Juice or Death)
+每个用户交互都必须有视觉反馈和动画效果：
+
+```gdscript
+# ✅ 正确：为UI交互添加动画
+func show_dialog() -> void:
+    dialog.modulate.a = 0.0
+    dialog.scale = Vector2(0.8, 0.8)
+    dialog.visible = true
+    
+    var tween = create_tween()
+    tween.parallel().tween_property(dialog, "modulate:a", 1.0, 0.3)
+    tween.parallel().tween_property(dialog, "scale", Vector2.ONE, 0.3)
+    tween.set_ease(Tween.EASE_OUT)
+    tween.set_trans(Tween.TRANS_BACK)
+
+# ❌ 错误：没有动画的生硬切换
+func show_dialog() -> void:
+    dialog.visible = true  # 突然出现，体验差
+```
+
+#### 2. 零魔法数字 (Zero Magic Numbers)
+所有数值都应该有明确的含义和来源：
+
+```gdscript
+# ✅ 正确：使用导出变量或配置文件
+@export var move_speed: float = 200.0
+@export var jump_height: float = 400.0
+@export var health_max: int = 100
+
+# 或从配置文件加载
+const CONFIG_PATH = "res://data/player_config.json"
+var config_data: Dictionary
+
+func _ready() -> void:
+    config_data = load_config(CONFIG_PATH)
+    move_speed = config_data.get("move_speed", 200.0)
+
+# ❌ 错误：硬编码的魔法数字
+func _physics_process(delta: float) -> void:
+    velocity.x = input_direction.x * 200  # 200是什么？
+    if position.y > 1000:  # 1000代表什么？
+        respawn()
+```
+
+#### 3. 函数单一职责
+每个函数只做一件事，做好一件事：
+
+```gdscript
+# ✅ 正确：职责分离
+func handle_player_input() -> void:
+    var input_direction = get_input_direction()
+    apply_movement(input_direction)
+    check_interaction_input()
+
+func get_input_direction() -> Vector2:
+    return Input.get_vector("move_left", "move_right", "move_up", "move_down")
+
+func apply_movement(direction: Vector2) -> void:
+    velocity = direction * move_speed
+    move_and_slide()
+
+func check_interaction_input() -> void:
+    if Input.is_action_just_pressed("interact"):
+        try_interact()
+
+# ❌ 错误：一个函数做太多事
+func handle_everything() -> void:
+    # 处理输入
+    var direction = Input.get_vector("move_left", "move_right", "move_up", "move_down")
+    # 处理移动
+    velocity = direction * move_speed
+    move_and_slide()
+    # 处理交互
+    if Input.is_action_just_pressed("interact"):
+        # 检查交互对象
+        var interactables = get_nearby_interactables()
+        # 执行交互
+        for obj in interactables:
+            obj.interact()
+    # 更新UI
+    update_health_bar()
+    # 播放音效
+    play_footstep_sound()
+```
+
+#### 4. 隐藏复杂性
+复杂的逻辑应该被封装，对外提供简洁的接口：
+
+```gdscript
+# ✅ 正确：封装复杂逻辑
+class_name NetworkManager
+
+func login(username: String, password: String, callback: Callable) -> int:
+    return _make_request("POST", "/auth/login", {
+        "username": username,
+        "password": password
+    }, callback)
+
+func _make_request(method: String, endpoint: String, data: Dictionary, callback: Callable) -> int:
+    # 复杂的网络请求逻辑被隐藏
+    var request = HTTPRequest.new()
+    var request_id = _generate_request_id()
+    
+    # 设置请求头、处理认证、错误重试等复杂逻辑
+    _setup_request_headers(request)
+    _handle_authentication(request)
+    _setup_retry_logic(request, callback)
+    
+    return request_id
+
+# 使用时非常简洁
+func _on_login_button_pressed() -> void:
+    NetworkManager.login(username_input.text, password_input.text, _on_login_response)
+```
+
+## 📋 编码最佳实践
+
+### 1. 类型安全
+始终使用严格的类型声明：
+
+```gdscript
+# ✅ 正确：明确的类型声明
+var player_health: int = 100
+var move_speed: float = 200.0
+var player_name: String = "Player"
+var inventory_items: Array[Item] = []
+var config_data: Dictionary = {}
+
+func calculate_damage(base_damage: int, multiplier: float) -> int:
+    return int(base_damage * multiplier)
+
+# ❌ 错误：缺少类型信息
+var health = 100  # 类型不明确
+var speed = 200   # 可能是int也可能是float
+
+func calculate_damage(base, mult):  # 参数类型不明确
+    return base * mult  # 返回类型不明确
+```
+
+### 2. 错误处理
+主动处理可能的错误情况：
+
+```gdscript
+# ✅ 正确：完善的错误处理
+func load_save_file(file_path: String) -> Dictionary:
+    if not FileAccess.file_exists(file_path):
+        push_warning("存档文件不存在: " + file_path)
+        return {}
+    
+    var file = FileAccess.open(file_path, FileAccess.READ)
+    if file == null:
+        push_error("无法打开存档文件: " + file_path)
+        return {}
+    
+    var json_string = file.get_as_text()
+    file.close()
+    
+    if json_string.is_empty():
+        push_warning("存档文件为空: " + file_path)
+        return {}
+    
+    var json = JSON.new()
+    var parse_result = json.parse(json_string)
+    if parse_result != OK:
+        push_error("存档文件JSON格式错误: " + file_path)
+        return {}
+    
+    return json.data
+
+# ❌ 错误：没有错误处理
+func load_save_file(file_path: String) -> Dictionary:
+    var file = FileAccess.open(file_path, FileAccess.READ)
+    var json_string = file.get_as_text()
+    file.close()
+    var json = JSON.new()
+    json.parse(json_string)
+    return json.data  # 任何步骤出错都会崩溃
+```
+
+### 3. 资源管理
+及时释放不需要的资源：
+
+```gdscript
+# ✅ 正确：资源管理
+class_name AudioManager
+
+var audio_players: Array[AudioStreamPlayer] = []
+var max_concurrent_sounds: int = 10
+
+func play_sound(sound: AudioStream, volume: float = 0.0) -> void:
+    # 清理已完成的音频播放器
+    _cleanup_finished_players()
+    
+    # 限制并发音频数量
+    if audio_players.size() >= max_concurrent_sounds:
+        _stop_oldest_player()
+    
+    var player = AudioStreamPlayer.new()
+    add_child(player)
+    player.stream = sound
+    player.volume_db = volume
+    player.finished.connect(_on_audio_finished.bind(player))
+    player.play()
+    
+    audio_players.append(player)
+
+func _cleanup_finished_players() -> void:
+    audio_players = audio_players.filter(func(player): return player.playing)
+
+func _on_audio_finished(player: AudioStreamPlayer) -> void:
+    audio_players.erase(player)
+    player.queue_free()
+```
+
+### 4. 性能优化
+编写高效的代码：
+
+```gdscript
+# ✅ 正确：性能优化的代码
+class_name EnemyManager
+
+var enemies: Array[Enemy] = []
+var update_timer: float = 0.0
+const UPDATE_INTERVAL: float = 0.1  # 每100ms更新一次
+
+func _process(delta: float) -> void:
+    update_timer += delta
+    if update_timer >= UPDATE_INTERVAL:
+        _update_enemies(update_timer)
+        update_timer = 0.0
+
+func _update_enemies(delta_time: float) -> void:
+    # 只更新屏幕附近的敌人
+    var camera_pos = get_viewport().get_camera_2d().global_position
+    var screen_size = get_viewport().get_visible_rect().size
+    
+    for enemy in enemies:
+        if _is_enemy_near_screen(enemy, camera_pos, screen_size):
+            enemy.update_ai(delta_time)
+
+func _is_enemy_near_screen(enemy: Enemy, camera_pos: Vector2, screen_size: Vector2) -> bool:
+    var distance = enemy.global_position.distance_to(camera_pos)
+    var max_distance = screen_size.length() * 0.6  # 屏幕对角线的60%
+    return distance <= max_distance
+
+# ❌ 错误：性能问题
+func _process(delta: float) -> void:
+    # 每帧更新所有敌人，无论是否可见
+    for enemy in enemies:
+        enemy.update_ai(delta)  # 可能有数百个敌人
+        # 每帧进行复杂计算
+        var path = enemy.find_path_to_player()
+        enemy.follow_path(path)
+```
+
+## 🎯 代码审查标准
+
+### 审查清单
+在提交代码前，请检查以下项目：
+
+#### 功能性
+- [ ] 代码实现了预期功能
+- [ ] 处理了边界情况和错误情况
+- [ ] 添加了必要的测试用例
+
+#### 可读性
+- [ ] 变量和函数名称清晰明确
+- [ ] 代码结构逻辑清晰
+- [ ] 添加了必要的注释
+
+#### 性能
+- [ ] 避免了不必要的计算
+- [ ] 正确管理了资源生命周期
+- [ ] 使用了合适的数据结构
+
+#### 规范性
+- [ ] 遵循了项目命名规范
+- [ ] 使用了正确的类型声明
+- [ ] 符合架构设计原则
+
+### 代码示例评分
+
+#### 优秀代码示例 (A级)
+```gdscript
+extends CharacterBody2D
+class_name Player
+
+## 玩家角色控制器
+## 
+## 负责处理玩家输入、移动和基础交互
+## 使用事件系统与其他组件通信
+
+@export_group("Movement")
+@export var move_speed: float = 200.0
+@export var acceleration: float = 1000.0
+@export var friction: float = 800.0
+
+@export_group("Interaction")
+@export var interaction_range: float = 50.0
+
+@onready var sprite: Sprite2D = %Sprite2D
+@onready var animation_player: AnimationPlayer = %AnimationPlayer
+@onready var interaction_area: Area2D = %InteractionArea
+
+var _current_interactable: Interactable = null
+
+func _ready() -> void:
+    _setup_interaction_area()
+    _connect_signals()
+
+func _physics_process(delta: float) -> void:
+    _handle_movement(delta)
+
+func _input(event: InputEvent) -> void:
+    if event.is_action_pressed("interact"):
+        _try_interact()
+
+func _handle_movement(delta: float) -> void:
+    var input_direction := _get_movement_input()
+    _apply_movement(input_direction, delta)
+    _update_animation(input_direction)
+
+func _get_movement_input() -> Vector2:
+    return Input.get_vector("move_left", "move_right", "move_up", "move_down")
+
+func _apply_movement(direction: Vector2, delta: float) -> void:
+    if direction != Vector2.ZERO:
+        velocity = velocity.move_toward(direction * move_speed, acceleration * delta)
+    else:
+        velocity = velocity.move_toward(Vector2.ZERO, friction * delta)
+    
+    move_and_slide()
+
+func _update_animation(direction: Vector2) -> void:
+    if direction.length() > 0.1:
+        animation_player.play("walk")
+        sprite.flip_h = direction.x < 0
+    else:
+        animation_player.play("idle")
+```
+
+#### 需要改进的代码 (C级)
+```gdscript
+extends CharacterBody2D
+
+var speed = 200
+var player
+var enemies = []
+
+func _ready():
+    player = self
+
+func _process(delta):
+    var dir = Vector2()
+    if Input.is_action_pressed("ui_left"):
+        dir.x -= 1
+    if Input.is_action_pressed("ui_right"):
+        dir.x += 1
+    if Input.is_action_pressed("ui_up"):
+        dir.y -= 1
+    if Input.is_action_pressed("ui_down"):
+        dir.y += 1
+    
+    velocity = dir * speed
+    move_and_slide()
+    
+    for enemy in enemies:
+        if position.distance_to(enemy.position) < 100:
+            print("near enemy")
+```
+
+## 🚀 持续改进
+
+### 重构指导原则
+1. **小步快跑** - 每次只重构一小部分
+2. **测试保护** - 重构前确保有测试覆盖
+3. **功能不变** - 重构不改变外部行为
+4. **逐步优化** - 持续改进代码质量
+
+### 技术债务管理
+```gdscript
+# 使用TODO注释标记技术债务
+# TODO: 重构这个函数，职责过多
+# FIXME: 这里有性能问题，需要优化
+# HACK: 临时解决方案，需要找到更好的方法
+# NOTE: 这里的逻辑比较复杂，需要详细注释
+```
+
+---
+
+**记住：优秀的代码不仅能工作，更要易于理解、维护和扩展。追求代码质量是每个开发者的责任！**

docs/02-开发规范/架构与通信规范.md

@@ -0,0 +1,280 @@
+# 架构与通信规范
+
+本文档定义了WhaleTown项目的架构设计原则和组件间通信规范。
+
+## 🏛️ 架构设计原则
+
+### 核心原则
+- **"信号向上，调用向下"** - 父节点调用子节点方法，子节点发出信号通知父节点
+- **高度解耦** - 通过事件系统实现组件间通信，避免直接依赖
+- **分层架构** - 严格的三层架构：框架层、游戏层、界面层
+- **单一职责** - 每个组件只负责一个明确的功能
+
+### 分层架构详解
+
+```
+┌─────────────────────────────────────┐
+│           UI Layer (界面层)           │
+│        UI/Windows/, UI/HUD/         │
+├─────────────────────────────────────┤
+│         Scenes Layer (游戏层)        │
+│   Scenes/Maps/, Scenes/Entities/    │
+├─────────────────────────────────────┤
+│         _Core Layer (框架层)         │
+│  _Core/managers/, _Core/systems/    │
+└─────────────────────────────────────┘
+```
+
+## 🔄 事件系统 (EventSystem)
+
+### 事件系统位置
+- **文件路径**: `_Core/systems/EventSystem.gd`
+- **自动加载**: 必须设置为AutoLoad单例
+- **作用**: 全局事件总线，实现跨模块通信
+
+### 事件命名规范
+所有事件名称必须在 `_Core/EventNames.gd` 中定义：
+
+```gdscript
+# _Core/EventNames.gd
+class_name EventNames
+
+# 玩家相关事件
+const PLAYER_MOVED = "player_moved"
+const PLAYER_HEALTH_CHANGED = "player_health_changed"
+const PLAYER_DIED = "player_died"
+
+# 交互事件
+const INTERACT_PRESSED = "interact_pressed"
+const NPC_TALKED = "npc_talked"
+const ITEM_COLLECTED = "item_collected"
+
+# UI事件
+const UI_BUTTON_CLICKED = "ui_button_clicked"
+const DIALOG_OPENED = "dialog_opened"
+const DIALOG_CLOSED = "dialog_closed"
+
+# 游戏状态事件
+const GAME_PAUSED = "game_paused"
+const GAME_RESUMED = "game_resumed"
+const SCENE_CHANGED = "scene_changed"
+```
+
+### 事件使用方法
+
+#### 发送事件
+```gdscript
+# 发送简单事件
+EventSystem.emit_event(EventNames.PLAYER_MOVED)
+
+# 发送带数据的事件
+EventSystem.emit_event(EventNames.PLAYER_HEALTH_CHANGED, {
+    "old_health": 80,
+    "new_health": 60,
+    "damage": 20
+})
+```
+
+#### 监听事件
+```gdscript
+func _ready() -> void:
+    # 连接事件监听
+    EventSystem.connect_event(EventNames.PLAYER_DIED, _on_player_died)
+    EventSystem.connect_event(EventNames.ITEM_COLLECTED, _on_item_collected)
+
+func _on_player_died(data: Dictionary = {}) -> void:
+    print("玩家死亡，游戏结束")
+    # 处理玩家死亡逻辑
+
+func _on_item_collected(data: Dictionary) -> void:
+    var item_name = data.get("item_name", "未知物品")
+    print("收集到物品: ", item_name)
+```
+
+#### 断开事件监听
+```gdscript
+func _exit_tree() -> void:
+    # 节点销毁时断开事件监听
+    EventSystem.disconnect_event(EventNames.PLAYER_DIED, _on_player_died)
+    EventSystem.disconnect_event(EventNames.ITEM_COLLECTED, _on_item_collected)
+```
+
+## 🎯 单例管理器
+
+### 允许的自动加载单例
+项目中允许以下五个核心单例：
+
+1. **GameManager** - 游戏状态管理
+   - 路径: `_Core/managers/GameManager.gd`
+   - 职责: 游戏状态、场景数据、全局配置
+
+2. **SceneManager** - 场景管理
+   - 路径: `_Core/managers/SceneManager.gd`
+   - 职责: 场景切换、场景生命周期
+
+3. **EventSystem** - 事件系统
+   - 路径: `_Core/systems/EventSystem.gd`
+   - 职责: 全局事件通信
+
+4. **NetworkManager** - 网络管理
+   - 路径: `_Core/managers/NetworkManager.gd`
+   - 职责: HTTP请求、API调用、网络状态管理
+
+5. **ResponseHandler** - 响应处理
+   - 路径: `_Core/managers/ResponseHandler.gd`
+   - 职责: 统一响应处理、错误处理、用户反馈
+
+### 单例使用规范
+```gdscript
+# ✅ 正确：高层组件可以访问单例
+func _ready() -> void:
+    var current_scene = SceneManager.get_current_scene()
+    var game_state = GameManager.get_game_state()
+
+# ❌ 错误：底层实体不应直接访问GameManager
+# 在Player.gd或NPC.gd中避免这样做：
+func _ready() -> void:
+    GameManager.register_player(self)  # 不推荐
+    
+# ✅ 正确：使用事件系统
+func _ready() -> void:
+    EventSystem.emit_event(EventNames.PLAYER_SPAWNED, {"player": self})
+```
+
+## 🔗 组件通信模式
+
+### 1. 父子通信
+```gdscript
+# 父节点调用子节点方法（向下调用）
+func _on_button_pressed() -> void:
+    child_component.activate()
+    child_component.set_data(some_data)
+
+# 子节点发出信号通知父节点（向上信号）
+# 在子节点中：
+signal component_activated(data: Dictionary)
+signal component_finished()
+
+func _some_action() -> void:
+    component_activated.emit({"status": "active"})
+```
+
+### 2. 兄弟组件通信
+```gdscript
+# 通过共同的父节点中转
+# 或使用事件系统
+func _notify_sibling() -> void:
+    EventSystem.emit_event(EventNames.COMPONENT_MESSAGE, {
+        "sender": self,
+        "message": "Hello sibling!"
+    })
+```
+
+### 3. 跨场景通信
+```gdscript
+# 使用事件系统进行跨场景通信
+func _change_scene_with_data() -> void:
+    EventSystem.emit_event(EventNames.SCENE_DATA_TRANSFER, {
+        "target_scene": "battle_scene",
+        "player_data": player_data
+    })
+```
+
+## 🚫 禁止的通信模式
+
+### 1. 直接节点引用
+```gdscript
+# ❌ 错误：直接获取其他场景的节点
+func _bad_communication() -> void:
+    var other_scene = get_tree().get_first_node_in_group("other_scene")
+    other_scene.do_something()  # 强耦合，难以维护
+```
+
+### 2. 全局变量传递
+```gdscript
+# ❌ 错误：使用全局变量传递状态
+# 在autoload中：
+var global_player_data = {}  # 避免这种做法
+```
+
+### 3. 循环依赖
+```gdscript
+# ❌ 错误：A依赖B，B又依赖A
+# ComponentA.gd
+var component_b: ComponentB
+
+# ComponentB.gd  
+var component_a: ComponentA  # 循环依赖
+```
+
+## 📋 通信最佳实践
+
+### 1. 事件数据结构
+```gdscript
+# 使用结构化的事件数据
+EventSystem.emit_event(EventNames.PLAYER_ATTACK, {
+    "attacker": self,
+    "target": target_enemy,
+    "damage": damage_amount,
+    "attack_type": "melee",
+    "timestamp": Time.get_time_dict_from_system()
+})
+```
+
+### 2. 错误处理
+```gdscript
+func _on_event_received(data: Dictionary) -> void:
+    # 验证数据完整性
+    if not data.has("required_field"):
+        push_error("事件数据缺少必需字段: required_field")
+        return
+    
+    # 安全地获取数据
+    var value = data.get("optional_field", default_value)
+```
+
+### 3. 性能考虑
+```gdscript
+# 避免在_process中频繁发送事件
+var last_position: Vector2
+func _process(delta: float) -> void:
+    if global_position.distance_to(last_position) > 10.0:
+        EventSystem.emit_event(EventNames.PLAYER_MOVED, {
+            "position": global_position
+        })
+        last_position = global_position
+```
+
+## 🧪 测试通信系统
+
+### 单元测试示例
+```gdscript
+extends GutTest
+
+func test_event_emission():
+    # 监听事件
+    watch_signals(EventSystem)
+    
+    # 发送事件
+    EventSystem.emit_event(EventNames.PLAYER_MOVED, {"x": 100, "y": 200})
+    
+    # 验证事件发送
+    assert_signal_emitted(EventSystem, "event_raised")
+
+func test_event_data():
+    var received_data: Dictionary
+    
+    # 连接事件监听
+    EventSystem.connect_event(EventNames.TEST_EVENT, func(data): received_data = data)
+    
+    # 发送测试数据
+    var test_data = {"test": "value"}
+    EventSystem.emit_event(EventNames.TEST_EVENT, test_data)
+    
+    # 验证数据传递
+    assert_eq(received_data, test_data)
+```
+
+---
+
+**记住：良好的架构设计是项目成功的基石！遵循这些通信规范可以确保代码的可维护性和扩展性。**

docs/03-技术实现/README.md

@@ -0,0 +1,120 @@
+# 🔧 技术实现
+
+> **适用人群**: 正在开发功能的程序员  
+> **使用时机**: 具体功能开发时
+
+这个目录包含了具体的技术实现指导，帮助开发者快速实现各种游戏功能和系统集成。
+
+## 📋 实现指南
+
+### 核心实现 🎮
+**[实现细节规范.md](实现细节规范.md)**
+- 玩家角色实现标准
+- NPC交互系统实现
+- TileMap图层配置规范
+- 交互物品实现模板
+- 性能优化要求
+
+### 网络集成 🌐
+**[API接口文档.md](API接口文档.md)**
+- 完整的后端API接口说明
+- 请求格式和响应格式
+- 错误码和处理方式
+- 认证和权限管理
+
+**[网络管理器设置.md](网络管理器设置.md)**
+- NetworkManager配置方法
+- 网络请求封装使用
+- 错误处理机制
+- 响应数据处理
+
+### 质量保证 🧪
+**[测试指南.md](测试指南.md)**
+- API接口测试方法
+- Python测试脚本使用
+- Godot内置测试
+- 测试用例编写
+
+## 🎯 开发流程
+
+### 功能开发标准流程
+1. **需求分析** - 明确功能需求和技术方案
+2. **架构设计** - 参考实现细节规范设计架构
+3. **编码实现** - 按照规范编写代码
+4. **接口集成** - 使用API文档进行后端集成
+5. **功能测试** - 使用测试指南验证功能
+6. **代码审查** - 检查规范遵循情况
+
+### 常见开发场景
+
+#### 🎮 实现新的游戏角色
+1. 阅读 [实现细节规范.md](实现细节规范.md) 中的角色实现部分
+2. 使用提供的代码模板创建角色
+3. 配置相机和交互系统
+4. 测试移动和交互功能
+
+#### 🌐 集成新的API接口
+1. 查看 [API接口文档.md](API接口文档.md) 了解接口规范
+2. 使用 [网络管理器设置.md](网络管理器设置.md) 配置网络请求
+3. 实现数据处理和错误处理
+4. 使用 [测试指南.md](测试指南.md) 验证接口功能
+
+#### 🗺️ 创建新的游戏场景
+1. 参考 [实现细节规范.md](实现细节规范.md) 中的TileMap配置
+2. 设置正确的图层结构和碰撞检测
+3. 配置相机边界和Y排序
+4. 添加交互物品和NPC
+
+## 🔍 问题排查
+
+### 常见问题类型
+
+#### 网络相关问题
+- **API调用失败** → 检查 [API接口文档.md](API接口文档.md) 中的接口格式
+- **网络超时** → 参考 [网络管理器设置.md](网络管理器设置.md) 的超时配置
+- **数据解析错误** → 查看响应格式和错误处理
+
+#### 游戏对象问题
+- **角色移动异常** → 检查 [实现细节规范.md](实现细节规范.md) 中的移动实现
+- **交互不响应** → 验证InteractionArea配置和事件系统
+- **相机边界错误** → 检查TileMap边界计算
+
+#### 性能问题
+- **帧率下降** → 参考性能优化要求
+- **内存泄漏** → 检查资源管理和对象生命周期
+
+### 调试技巧
+1. **使用Godot调试器** - 设置断点调试代码逻辑
+2. **查看控制台输出** - 关注错误和警告信息
+3. **使用测试脚本** - 编写简单测试验证功能
+4. **性能分析** - 使用Godot的性能分析工具
+
+## 📚 参考资源
+
+### 内部资源
+- [02-开发规范](../02-开发规范/) - 编码规范和架构设计
+- [04-高级开发](../04-高级开发/) - 进阶开发技巧
+- [06-功能模块](../06-功能模块/) - 特定功能实现
+
+### 外部资源
+- [Godot官方文档](https://docs.godotengine.org/)
+- [GDScript语言参考](https://docs.godotengine.org/en/stable/tutorials/scripting/gdscript/)
+- [Godot最佳实践](https://docs.godotengine.org/en/stable/tutorials/best_practices/)
+
+## 💡 开发建议
+
+### 效率提升
+- 使用代码模板快速创建标准结构
+- 善用Godot的场景实例化功能
+- 合理使用@export变量进行配置
+- 充分利用事件系统解耦组件
+
+### 质量保证
+- 每个功能都要编写对应测试
+- 定期进行代码审查
+- 关注性能指标和内存使用
+- 保持代码简洁和可读性
+
+---
+
+**记住：好的实现不仅要功能正确，更要易于维护和扩展！**

docs/03-技术实现/实现细节规范.md

@@ -0,0 +1,388 @@
+# 实现细节规范
+
+本文档详细说明了WhaleTown项目中各种游戏对象的具体实现要求和技术细节。
+
+## 🎮 玩家实现规范
+
+### 基础要求
+- **节点类型**: 必须使用 `CharacterBody2D`
+- **移动系统**: 使用 `move_and_slide()` 方法
+- **相机集成**: 必须包含 `Camera2D` 子节点
+
+### 玩家节点结构
+```
+Player (CharacterBody2D)
+├── Sprite2D                    # 玩家精灵
+├── CollisionShape2D            # 碰撞形状
+├── Camera2D                    # 玩家相机
+│   └── [相机配置]
+├── InteractionArea (Area2D)    # 交互检测区域
+│   └── CollisionShape2D
+└── AnimationPlayer             # 动画播放器
+```
+
+### 相机配置要求
+```gdscript
+# Player.gd 中的相机设置
+@onready var camera: Camera2D = $Camera2D
+
+func _ready() -> void:
+    # 必须启用位置平滑
+    camera.position_smoothing_enabled = true
+    camera.position_smoothing_speed = 5.0
+    
+    # 设置相机边界（基于TileMap）
+    _setup_camera_limits()
+
+func _setup_camera_limits() -> void:
+    # 获取当前场景的TileMap
+    var tilemap = get_tree().get_first_node_in_group("tilemap")
+    if tilemap and tilemap is TileMap:
+        var used_rect = tilemap.get_used_rect()
+        var tile_size = tilemap.tile_set.tile_size
+        
+        # 计算世界坐标边界
+        camera.limit_left = used_rect.position.x * tile_size.x
+        camera.limit_top = used_rect.position.y * tile_size.y
+        camera.limit_right = used_rect.end.x * tile_size.x
+        camera.limit_bottom = used_rect.end.y * tile_size.y
+```
+
+### 移动实现模板
+```gdscript
+extends CharacterBody2D
+class_name Player
+
+@export var move_speed: float = 200.0
+@export var acceleration: float = 1000.0
+@export var friction: float = 1000.0
+
+@onready var sprite: Sprite2D = $Sprite2D
+@onready var camera: Camera2D = $Camera2D
+
+func _ready() -> void:
+    # 设置相机
+    camera.position_smoothing_enabled = true
+    _setup_camera_limits()
+
+func _physics_process(delta: float) -> void:
+    _handle_movement(delta)
+
+func _handle_movement(delta: float) -> void:
+    # 获取输入方向
+    var input_direction := Input.get_vector(
+        "move_left", "move_right", 
+        "move_up", "move_down"
+    )
+    
+    # 应用移动
+    if input_direction != Vector2.ZERO:
+        velocity = velocity.move_toward(input_direction * move_speed, acceleration * delta)
+    else:
+        velocity = velocity.move_toward(Vector2.ZERO, friction * delta)
+    
+    move_and_slide()
+    
+    # 发送移动事件
+    if velocity.length() > 0:
+        EventSystem.emit_event(EventNames.PLAYER_MOVED, {
+            "position": global_position,
+            "velocity": velocity
+        })
+```
+
+## 🤖 NPC实现规范
+
+### 基础要求
+- **节点类型**: 使用 `CharacterBody2D` 或 `StaticBody2D`
+- **交互区域**: 必须包含名为 `InteractionArea` 的 `Area2D`
+- **事件通信**: 通过 `EventSystem` 触发交互
+
+### NPC节点结构
+```
+NPC (CharacterBody2D)
+├── Sprite2D                    # NPC精灵
+├── CollisionShape2D            # 物理碰撞
+├── InteractionArea (Area2D)    # 交互检测区域
+│   └── CollisionShape2D        # 交互碰撞形状
+├── DialogueComponent           # 对话组件
+└── AnimationPlayer             # 动画播放器
+```
+
+### NPC实现模板
+```gdscript
+extends CharacterBody2D
+class_name NPC
+
+@export var npc_name: String = "NPC"
+@export var dialogue_resource: DialogueResource
+
+@onready var interaction_area: Area2D = $InteractionArea
+@onready var sprite: Sprite2D = $Sprite2D
+
+signal interaction_available(npc: NPC)
+signal interaction_unavailable(npc: NPC)
+
+func _ready() -> void:
+    # 连接交互区域信号
+    interaction_area.body_entered.connect(_on_interaction_area_entered)
+    interaction_area.body_exited.connect(_on_interaction_area_exited)
+    
+    # 监听交互事件
+    EventSystem.connect_event(EventNames.INTERACT_PRESSED, _on_interact_pressed)
+
+func _on_interaction_area_entered(body: Node2D) -> void:
+    if body.is_in_group("player"):
+        interaction_available.emit(self)
+        # 显示交互提示
+        _show_interaction_hint()
+
+func _on_interaction_area_exited(body: Node2D) -> void:
+    if body.is_in_group("player"):
+        interaction_unavailable.emit(self)
+        # 隐藏交互提示
+        _hide_interaction_hint()
+
+func _on_interact_pressed(data: Dictionary = {}) -> void:
+    # 检查玩家是否在交互范围内
+    if _is_player_in_range():
+        start_dialogue()
+
+func start_dialogue() -> void:
+    EventSystem.emit_event(EventNames.NPC_TALKED, {
+        "npc": self,
+        "npc_name": npc_name,
+        "dialogue": dialogue_resource
+    })
+
+func _is_player_in_range() -> bool:
+    var bodies = interaction_area.get_overlapping_bodies()
+    for body in bodies:
+        if body.is_in_group("player"):
+            return true
+    return false
+```
+
+## 🗺️ TileMap图层规范
+
+### 图层配置要求
+TileMap必须按以下标准配置图层：
+
+#### 图层0：地面层 (Ground)
+- **用途**: 地面纹理、道路、草地等
+- **碰撞**: 禁用物理层
+- **渲染**: 最底层渲染
+- **Y排序**: 禁用
+
+```gdscript
+# 设置地面层
+var ground_layer = tilemap.get_layer(0)
+tilemap.set_layer_name(0, "Ground")
+tilemap.set_layer_enabled(0, true)
+tilemap.set_layer_y_sort_enabled(0, false)
+# 不设置物理层
+```
+
+#### 图层1：障碍层 (Obstacles)
+- **用途**: 墙壁、树木、建筑等不可通过的障碍
+- **碰撞**: 启用物理层
+- **渲染**: 中间层
+- **Y排序**: 禁用
+
+```gdscript
+# 设置障碍层
+tilemap.set_layer_name(1, "Obstacles")
+tilemap.set_layer_enabled(1, true)
+tilemap.set_layer_y_sort_enabled(1, false)
+# 设置物理层用于碰撞检测
+tilemap.set_layer_physics_enabled(1, true)
+```
+
+#### 图层2：装饰层 (Decoration)
+- **用途**: 装饰物、前景元素
+- **碰撞**: 根据需要设置
+- **渲染**: 最上层
+- **Y排序**: 启用（重要！）
+
+```gdscript
+# 设置装饰层
+tilemap.set_layer_name(2, "Decoration")
+tilemap.set_layer_enabled(2, true)
+tilemap.set_layer_y_sort_enabled(2, true)  # 启用Y排序
+tilemap.set_layer_y_sort_origin(2, 16)     # 设置排序原点
+```
+
+### TileMap设置模板
+```gdscript
+extends TileMap
+class_name GameTileMap
+
+func _ready() -> void:
+    # 设置TileMap为tilemap组
+    add_to_group("tilemap")
+    
+    # 配置图层
+    _setup_layers()
+    
+    # 通知相机系统更新边界
+    EventSystem.emit_event(EventNames.TILEMAP_READY, {
+        "tilemap": self,
+        "used_rect": get_used_rect()
+    })
+
+func _setup_layers() -> void:
+    # 确保有足够的图层
+    while get_layers_count() < 3:
+        add_layer(-1)
+    
+    # 配置地面层 (0)
+    set_layer_name(0, "Ground")
+    set_layer_y_sort_enabled(0, false)
+    
+    # 配置障碍层 (1)
+    set_layer_name(1, "Obstacles")
+    set_layer_y_sort_enabled(1, false)
+    set_layer_physics_enabled(1, true)
+    
+    # 配置装饰层 (2)
+    set_layer_name(2, "Decoration")
+    set_layer_y_sort_enabled(2, true)
+    set_layer_y_sort_origin(2, tile_set.tile_size.y / 2)
+```
+
+## 🎯 交互物实现规范
+
+### 可收集物品
+```gdscript
+extends Area2D
+class_name CollectibleItem
+
+@export var item_name: String = "Item"
+@export var item_value: int = 1
+
+@onready var sprite: Sprite2D = $Sprite2D
+@onready var collision: CollisionShape2D = $CollisionShape2D
+
+func _ready() -> void:
+    body_entered.connect(_on_body_entered)
+
+func _on_body_entered(body: Node2D) -> void:
+    if body.is_in_group("player"):
+        collect_item(body)
+
+func collect_item(collector: Node2D) -> void:
+    # 发送收集事件
+    EventSystem.emit_event(EventNames.ITEM_COLLECTED, {
+        "item_name": item_name,
+        "item_value": item_value,
+        "collector": collector,
+        "position": global_position
+    })
+    
+    # 播放收集动画
+    _play_collect_animation()
+
+func _play_collect_animation() -> void:
+    var tween = create_tween()
+    tween.parallel().tween_property(self, "scale", Vector2.ZERO, 0.3)
+    tween.parallel().tween_property(self, "modulate:a", 0.0, 0.3)
+    await tween.finished
+    queue_free()
+```
+
+### 可交互对象
+```gdscript
+extends StaticBody2D
+class_name InteractableObject
+
+@export var interaction_text: String = "按E交互"
+@export var can_interact: bool = true
+
+@onready var interaction_area: Area2D = $InteractionArea
+@onready var sprite: Sprite2D = $Sprite2D
+
+var player_in_range: bool = false
+
+func _ready() -> void:
+    interaction_area.body_entered.connect(_on_interaction_area_entered)
+    interaction_area.body_exited.connect(_on_interaction_area_exited)
+    EventSystem.connect_event(EventNames.INTERACT_PRESSED, _on_interact_pressed)
+
+func _on_interaction_area_entered(body: Node2D) -> void:
+    if body.is_in_group("player") and can_interact:
+        player_in_range = true
+        _show_interaction_prompt()
+
+func _on_interaction_area_exited(body: Node2D) -> void:
+    if body.is_in_group("player"):
+        player_in_range = false
+        _hide_interaction_prompt()
+
+func _on_interact_pressed(data: Dictionary = {}) -> void:
+    if player_in_range and can_interact:
+        interact()
+
+func interact() -> void:
+    # 子类重写此方法实现具体交互逻辑
+    print("与 ", name, " 交互")
+    
+    EventSystem.emit_event(EventNames.OBJECT_INTERACTED, {
+        "object": self,
+        "interaction_type": "default"
+    })
+```
+
+## 🎨 资源过滤设置
+
+### 纹理过滤规范
+所有像素艺术资源必须使用最近邻过滤：
+
+```gdscript
+# 在导入设置中或代码中设置
+func _setup_pixel_perfect_texture(texture: Texture2D) -> void:
+    if texture is ImageTexture:
+        var image = texture.get_image()
+        image.generate_mipmaps(false)
+        # 在导入设置中设置Filter为Off
+```
+
+### 导入设置模板
+对于所有精灵资源，在导入设置中：
+- **Filter**: Off (关闭)
+- **Mipmaps**: Off (关闭)
+- **Fix Alpha Border**: On (开启)
+
+## 🔧 性能优化要求
+
+### 节点缓存
+```gdscript
+# ✅ 正确：使用@onready缓存节点引用
+@onready var sprite: Sprite2D = $Sprite2D
+@onready var collision: CollisionShape2D = $CollisionShape2D
+
+func _process(delta: float) -> void:
+    sprite.modulate.a = 0.5  # 使用缓存的引用
+
+# ❌ 错误：在_process中重复获取节点
+func _process(delta: float) -> void:
+    $Sprite2D.modulate.a = 0.5  # 每帧都要查找节点
+```
+
+### 事件频率控制
+```gdscript
+# 控制事件发送频率
+var last_event_time: float = 0.0
+const EVENT_INTERVAL: float = 0.1  # 100ms间隔
+
+func _process(delta: float) -> void:
+    var current_time = Time.get_time_dict_from_system()
+    if current_time - last_event_time >= EVENT_INTERVAL:
+        EventSystem.emit_event(EventNames.POSITION_UPDATE, {
+            "position": global_position
+        })
+        last_event_time = current_time
+```
+
+---
+
+**记住：遵循这些实现细节规范可以确保游戏对象的一致性和性能！**

docs/03-技术实现/网络管理器设置.md

@@ -13,7 +13,7 @@ NetworkManager 是一个统一的网络请求管理器，提供了简洁的API
 1. 打开 `Project` → `Project Settings`
 2. 切换到 `AutoLoad` 标签
 3. 添加新的AutoLoad：
-   - **Path**: `res://core/managers/NetworkManager.gd`
+   - **Path**: `res://_Core/managers/NetworkManager.gd`
    - **Name**: `NetworkManager`
    - **Singleton**: ✅ 勾选
 
@@ -24,7 +24,7 @@ NetworkManager 是一个统一的网络请求管理器，提供了简洁的API
 ```ini
 [autoload]
 
-NetworkManager="*res://core/managers/NetworkManager.gd"
+NetworkManager="*res://_Core/managers/NetworkManager.gd"
 ```
 
 ### 3. 验证设置

docs/04-高级开发/场景设计规范.md

@@ -0,0 +1,617 @@
+# 场景设计规范
+
+本文档定义了 Whale Town 项目中场景设计的标准和最佳实践。
+
+## 🎯 设计原则
+
+### 核心原则
+1. **功能独立** - 每个场景都是独立的功能单元
+2. **职责单一** - 一个场景只负责一个主要功能
+3. **可复用性** - 场景组件应该能够在其他场景中复用
+4. **标准化** - 统一的场景结构和命名规范
+5. **性能优先** - 优化场景性能，避免不必要的资源消耗
+
+### 场景分类
+- **主要场景** - 游戏的核心功能场景（主菜单、游戏场景、设置等）
+- **UI场景** - 纯界面场景（对话框、HUD、菜单等）
+- **游戏场景** - 包含游戏逻辑的场景（关卡、战斗、探索等）
+- **工具场景** - 开发和测试用的场景
+
+## 🏗️ 场景结构
+
+### 标准目录结构
+```
+scenes/
+├── Maps/                       # 地图场景
+│   ├── main_scene.tscn         # 主场景
+│   └── game_scene.tscn         # 游戏场景
+├── Components/                 # 组件预制体
+│   ├── ui/                     # UI组件
+│   │   ├── button.tscn
+│   │   ├── dialog.tscn
+│   │   └── menu.tscn
+│   ├── characters/             # 角色组件
+│   │   ├── player.tscn
+│   │   └── npc.tscn
+│   ├── effects/                # 特效组件
+│   │   ├── particle_effect.tscn
+│   │   └── animation_effect.tscn
+│   └── items/                  # 物品组件
+│       ├── collectible.tscn
+│       └── interactive.tscn
+└── auth_scene.tscn             # 认证场景
+```
+
+### 场景命名规范
+- **主场景**: `SceneName.tscn` (PascalCase)
+- **组件预制体**: `ComponentName.tscn` (PascalCase)
+- **脚本文件**: `SceneName.gd` (PascalCase)
+- **节点名称**: `NodeName` (PascalCase) 或 `nodeName` (camelCase)
+
+## 📝 场景设计模板
+
+### 主场景结构模板
+
+```
+SceneName (Control/Node2D)
+├── Background (TextureRect/Sprite2D)     # 背景
+├── UI (CanvasLayer)                      # UI层
+│   ├── HUD (Control)                     # 游戏HUD
+│   ├── Menu (Control)                    # 菜单界面
+│   └── Dialog (Control)                  # 对话框
+├── Game (Node2D)                         # 游戏内容层
+│   ├── Player (CharacterBody2D)          # 玩家
+│   ├── NPCs (Node2D)                     # NPC容器
+│   ├── Items (Node2D)                    # 物品容器
+│   └── Effects (Node2D)                  # 特效容器
+├── Audio (Node)                          # 音频管理
+│   ├── BGM (AudioStreamPlayer)           # 背景音乐
+│   └── SFX (AudioStreamPlayer2D)         # 音效
+└── Systems (Node)                        # 系统组件
+    ├── CameraController (Node)           # 相机控制
+    ├── InputHandler (Node)               # 输入处理
+    └── StateManager (Node)               # 状态管理
+```
+
+### 场景脚本模板
+
+```gdscript
+# SceneName.gd
+extends Control  # 或 Node2D，根据场景类型选择
+class_name SceneName
+
+# 场景信息
+const SCENE_NAME = "SceneName"
+const SCENE_VERSION = "1.0.0"
+
+# 场景状态
+enum SceneState {
+	LOADING,
+	READY,
+	ACTIVE,
+	PAUSED,
+	TRANSITIONING
+}
+
+var current_state: SceneState = SceneState.LOADING
+
+# 节点引用
+@onready var background: TextureRect = $Background
+@onready var ui_layer: CanvasLayer = $UI
+@onready var game_layer: Node2D = $Game
+@onready var audio_manager: Node = $Audio
+@onready var systems: Node = $Systems
+
+# 场景数据
+var scene_data: Dictionary = {}
+var is_initialized: bool = false
+
+# 信号定义
+signal scene_ready
+signal scene_state_changed(old_state: SceneState, new_state: SceneState)
+signal scene_data_updated(key: String, value)
+
+func _ready():
+	"""场景初始化"""
+	print("初始化场景: ", SCENE_NAME)
+	
+	# 初始化场景
+	await initialize_scene()
+	
+	# 设置场景状态
+	change_state(SceneState.READY)
+	
+	# 发送场景就绪信号
+	scene_ready.emit()
+
+func initialize_scene():
+	"""初始化场景组件"""
+	# 加载场景数据
+	await load_scene_data()
+	
+	# 初始化UI
+	initialize_ui()
+	
+	# 初始化游戏组件
+	initialize_game_components()
+	
+	# 初始化音频
+	initialize_audio()
+	
+	# 初始化系统
+	initialize_systems()
+	
+	# 连接信号
+	connect_signals()
+	
+	is_initialized = true
+
+func load_scene_data():
+	"""加载场景数据"""
+	# 从配置文件或网络加载场景数据
+	var data_path = ProjectPaths.get_scene_data_path(SCENE_NAME)
+	if FileAccess.file_exists(data_path):
+		var file = FileAccess.open(data_path, FileAccess.READ)
+		if file:
+			var json_string = file.get_as_text()
+			file.close()
+			
+			var json = JSON.new()
+			if json.parse(json_string) == OK:
+				scene_data = json.data
+			else:
+				print("警告: 场景数据JSON格式错误: ", data_path)
+	
+	# 等待一帧确保所有节点都已初始化
+	await get_tree().process_frame
+
+func initialize_ui():
+	"""初始化UI组件"""
+	if ui_layer:
+		# 初始化UI组件
+		for child in ui_layer.get_children():
+			if child.has_method("initialize"):
+				child.initialize()
+
+func initialize_game_components():
+	"""初始化游戏组件"""
+	if game_layer:
+		# 初始化游戏组件
+		for child in game_layer.get_children():
+			if child.has_method("initialize"):
+				child.initialize()
+
+func initialize_audio():
+	"""初始化音频"""
+	if audio_manager:
+		# 设置背景音乐
+		if scene_data.has("bgm"):
+			play_bgm(scene_data.bgm)
+
+func initialize_systems():
+	"""初始化系统组件"""
+	if systems:
+		# 初始化系统组件
+		for child in systems.get_children():
+			if child.has_method("initialize"):
+				child.initialize()
+
+func connect_signals():
+	"""连接信号"""
+	# 连接场景内部信号
+	# 连接全局事件
+	EventSystem.connect_event("game_paused", _on_game_paused)
+	EventSystem.connect_event("game_resumed", _on_game_resumed)
+
+func change_state(new_state: SceneState):
+	"""改变场景状态"""
+	if current_state == new_state:
+		return
+	
+	var old_state = current_state
+	current_state = new_state
+	
+	print("场景状态变更: %s -> %s" % [SceneState.keys()[old_state], SceneState.keys()[new_state]])
+	
+	# 处理状态变更
+	_handle_state_change(old_state, new_state)
+	
+	# 发送状态变更信号
+	scene_state_changed.emit(old_state, new_state)
+
+func _handle_state_change(old_state: SceneState, new_state: SceneState):
+	"""处理状态变更"""
+	match new_state:
+		SceneState.LOADING:
+			_on_enter_loading_state()
+		SceneState.READY:
+			_on_enter_ready_state()
+		SceneState.ACTIVE:
+			_on_enter_active_state()
+		SceneState.PAUSED:
+			_on_enter_paused_state()
+		SceneState.TRANSITIONING:
+			_on_enter_transitioning_state()
+
+func _on_enter_loading_state():
+	"""进入加载状态"""
+	# 显示加载界面
+	pass
+
+func _on_enter_ready_state():
+	"""进入就绪状态"""
+	# 场景准备完成
+	pass
+
+func _on_enter_active_state():
+	"""进入活跃状态"""
+	# 开始游戏逻辑
+	pass
+
+func _on_enter_paused_state():
+	"""进入暂停状态"""
+	# 暂停游戏逻辑
+	get_tree().paused = true
+
+func _on_enter_transitioning_state():
+	"""进入转换状态"""
+	# 场景转换中
+	pass
+
+func play_bgm(bgm_path: String):
+	"""播放背景音乐"""
+	var bgm_player = audio_manager.get_node("BGM") as AudioStreamPlayer
+	if bgm_player and FileAccess.file_exists(bgm_path):
+		var audio_stream = load(bgm_path)
+		bgm_player.stream = audio_stream
+		bgm_player.play()
+
+func play_sfx(sfx_path: String, position: Vector2 = Vector2.ZERO):
+	"""播放音效"""
+	var sfx_player = audio_manager.get_node("SFX") as AudioStreamPlayer2D
+	if sfx_player and FileAccess.file_exists(sfx_path):
+		var audio_stream = load(sfx_path)
+		sfx_player.stream = audio_stream
+		if position != Vector2.ZERO:
+			sfx_player.global_position = position
+		sfx_player.play()
+
+func update_scene_data(key: String, value):
+	"""更新场景数据"""
+	scene_data[key] = value
+	scene_data_updated.emit(key, value)
+
+func get_scene_data(key: String, default_value = null):
+	"""获取场景数据"""
+	return scene_data.get(key, default_value)
+
+func cleanup():
+	"""清理场景资源"""
+	print("清理场景: ", SCENE_NAME)
+	
+	# 断开信号连接
+	EventSystem.disconnect_event("game_paused", _on_game_paused)
+	EventSystem.disconnect_event("game_resumed", _on_game_resumed)
+	
+	# 清理组件
+	if ui_layer:
+		for child in ui_layer.get_children():
+			if child.has_method("cleanup"):
+				child.cleanup()
+	
+	if game_layer:
+		for child in game_layer.get_children():
+			if child.has_method("cleanup"):
+				child.cleanup()
+	
+	if systems:
+		for child in systems.get_children():
+			if child.has_method("cleanup"):
+				child.cleanup()
+	
+	# 停止音频
+	if audio_manager:
+		var bgm_player = audio_manager.get_node("BGM") as AudioStreamPlayer
+		if bgm_player:
+			bgm_player.stop()
+
+# 事件处理
+func _on_game_paused():
+	"""游戏暂停事件"""
+	if current_state == SceneState.ACTIVE:
+		change_state(SceneState.PAUSED)
+
+func _on_game_resumed():
+	"""游戏恢复事件"""
+	if current_state == SceneState.PAUSED:
+		change_state(SceneState.ACTIVE)
+		get_tree().paused = false
+
+# 输入处理
+func _input(event):
+	"""处理输入事件"""
+	if current_state != SceneState.ACTIVE:
+		return
+	
+	# 处理场景特定的输入
+	_handle_scene_input(event)
+
+func _handle_scene_input(event):
+	"""处理场景特定输入"""
+	# 在子类中重写此方法
+	pass
+
+# 生命周期方法
+func _process(delta):
+	"""每帧更新"""
+	if current_state == SceneState.ACTIVE:
+		_update_scene(delta)
+
+func _update_scene(delta):
+	"""更新场景逻辑"""
+	# 在子类中重写此方法
+	pass
+
+func _physics_process(delta):
+	"""物理更新"""
+	if current_state == SceneState.ACTIVE:
+		_physics_update_scene(delta)
+
+func _physics_update_scene(delta):
+	"""物理更新场景逻辑"""
+	# 在子类中重写此方法
+	pass
+```
+
+## 🎨 UI设计规范
+
+### UI层级结构
+```
+UI (CanvasLayer)
+├── Background (Control)              # UI背景
+├── MainContent (Control)             # 主要内容
+│   ├── Header (Control)              # 头部区域
+│   ├── Body (Control)                # 主体区域
+│   └── Footer (Control)              # 底部区域
+├── Overlay (Control)                 # 覆盖层
+│   ├── Loading (Control)             # 加载界面
+│   ├── Dialog (Control)              # 对话框
+│   └── Toast (Control)               # 提示消息
+└── Debug (Control)                   # 调试信息
+```
+
+### UI组件规范
+1. **响应式设计** - 使用Anchor和Margin实现自适应布局
+2. **主题统一** - 使用统一的主题资源
+3. **动画效果** - 添加适当的过渡动画
+4. **无障碍支持** - 考虑键盘导航和屏幕阅读器
+
+### UI脚本模板
+```gdscript
+# UIComponent.gd
+extends Control
+class_name UIComponent
+
+signal ui_action(action_name: String, data: Dictionary)
+
+@export var auto_initialize: bool = true
+@export var animation_duration: float = 0.3
+
+var is_visible: bool = false
+var is_initialized: bool = false
+
+func _ready():
+	if auto_initialize:
+		initialize()
+
+func initialize():
+	"""初始化UI组件"""
+	if is_initialized:
+		return
+	
+	# 设置初始状态
+	modulate.a = 0.0
+	visible = false
+	
+	# 连接信号
+	_connect_signals()
+	
+	is_initialized = true
+
+func show_ui(animated: bool = true):
+	"""显示UI"""
+	if is_visible:
+		return
+	
+	visible = true
+	is_visible = true
+	
+	if animated:
+		var tween = create_tween()
+		tween.tween_property(self, "modulate:a", 1.0, animation_duration)
+	else:
+		modulate.a = 1.0
+
+func hide_ui(animated: bool = true):
+	"""隐藏UI"""
+	if not is_visible:
+		return
+	
+	is_visible = false
+	
+	if animated:
+		var tween = create_tween()
+		tween.tween_property(self, "modulate:a", 0.0, animation_duration)
+		await tween.finished
+		visible = false
+	else:
+		modulate.a = 0.0
+		visible = false
+
+func _connect_signals():
+	"""连接信号"""
+	# 在子类中重写
+	pass
+```
+
+## 🎮 游戏场景规范
+
+### 游戏场景结构
+```
+GameScene (Node2D)
+├── Background (ParallaxBackground)   # 背景层
+├── Environment (Node2D)              # 环境层
+│   ├── Terrain (TileMap)             # 地形
+│   ├── Props (Node2D)                # 道具
+│   └── Decorations (Node2D)          # 装饰
+├── Entities (Node2D)                 # 实体层
+│   ├── Player (CharacterBody2D)      # 玩家
+│   ├── NPCs (Node2D)                 # NPC
+│   ├── Enemies (Node2D)              # 敌人
+│   └── Items (Node2D)                # 物品
+├── Effects (Node2D)                  # 特效层
+│   ├── Particles (Node2D)            # 粒子效果
+│   └── Animations (Node2D)           # 动画效果
+└── Camera (Camera2D)                 # 相机
+```
+
+### 性能优化
+1. **对象池** - 重用频繁创建销毁的对象
+2. **视锥剔除** - 只渲染可见区域的对象
+3. **LOD系统** - 根据距离调整细节级别
+4. **批量处理** - 合并相似的渲染调用
+
+## 🔧 场景管理
+
+### 场景切换
+```gdscript
+# 使用SceneManager进行场景切换
+SceneManager.change_scene("game_scene", {
+	"level": 1,
+	"player_data": player_data
+})
+
+# 带过渡效果的场景切换
+SceneManager.change_scene_with_transition("battle_scene", {
+	"enemy_data": enemy_data
+}, "fade")
+```
+
+### 场景数据传递
+```gdscript
+# 发送场景数据
+var scene_data = {
+	"player_level": 10,
+	"inventory": player_inventory,
+	"quest_progress": quest_data
+}
+SceneManager.change_scene("next_scene", scene_data)
+
+# 接收场景数据
+func _on_scene_data_received(data: Dictionary):
+	if data.has("player_level"):
+		player_level = data.player_level
+	if data.has("inventory"):
+		load_inventory(data.inventory)
+```
+
+## 🧪 场景测试
+
+### 测试场景创建
+```gdscript
+# TestScene.gd
+extends "res://scenes/BaseScene.gd"
+
+func _ready():
+	super._ready()
+	
+	# 设置测试环境
+	setup_test_environment()
+	
+	# 运行测试用例
+	run_test_cases()
+
+func setup_test_environment():
+	"""设置测试环境"""
+	# 创建测试数据
+	# 设置测试状态
+	pass
+
+func run_test_cases():
+	"""运行测试用例"""
+	test_scene_initialization()
+	test_ui_interactions()
+	test_game_logic()
+
+func test_scene_initialization():
+	"""测试场景初始化"""
+	assert(is_initialized, "场景应该已初始化")
+	assert(current_state == SceneState.READY, "场景状态应该为READY")
+
+func test_ui_interactions():
+	"""测试UI交互"""
+	# 模拟用户输入
+	# 验证UI响应
+	pass
+
+func test_game_logic():
+	"""测试游戏逻辑"""
+	# 测试游戏规则
+	# 验证状态变化
+	pass
+```
+
+### 性能测试
+```gdscript
+# 性能监控
+func _process(delta):
+	super._process(delta)
+	
+	# 监控帧率
+	var fps = Engine.get_frames_per_second()
+	if fps < 30:
+		print("警告: 帧率过低: ", fps)
+	
+	# 监控内存使用
+	var memory_usage = OS.get_static_memory_usage_by_type()
+	if memory_usage > 100 * 1024 * 1024:  # 100MB
+		print("警告: 内存使用过高: ", memory_usage / 1024 / 1024, "MB")
+```
+
+## 📚 最佳实践
+
+### 代码组织
+1. **单一职责** - 每个场景只负责一个主要功能
+2. **模块化** - 将复杂功能拆分为独立组件
+3. **可测试** - 设计易于测试的场景结构
+4. **文档化** - 为场景添加详细的文档说明
+
+### 性能优化
+1. **延迟加载** - 按需加载资源和组件
+2. **对象复用** - 使用对象池管理频繁创建的对象
+3. **批量操作** - 合并相似的操作减少开销
+4. **内存管理** - 及时释放不需要的资源
+
+### 用户体验
+1. **响应式设计** - 支持不同分辨率和设备
+2. **流畅动画** - 添加适当的过渡效果
+3. **错误处理** - 优雅处理异常情况
+4. **加载提示** - 为长时间操作提供进度反馈
+
+## 🔍 常见问题
+
+### Q: 如何处理场景间的数据传递？
+A: 使用SceneManager的场景切换方法传递数据，或通过全局单例存储共享数据。
+
+### Q: 场景性能如何优化？
+A: 使用对象池、视锥剔除、LOD系统，避免在_process中执行重复计算。
+
+### Q: 如何调试场景问题？
+A: 使用Godot的远程调试器，添加性能监控，编写场景测试用例。
+
+### Q: 场景切换如何添加过渡效果？
+A: 使用SceneManager的过渡系统，或自定义Tween动画实现过渡效果。
+
+---
+
+**记住：良好的场景设计是游戏体验的基础！**

docs/04-高级开发/性能优化指南.md

@@ -0,0 +1,507 @@
+# 性能优化指南
+
+本文档提供 Whale Town 项目的性能优化策略和最佳实践。
+
+## 🎯 优化目标
+
+### 性能指标
+- **帧率**: 保持60FPS稳定运行
+- **内存使用**: 控制在合理范围内
+- **加载时间**: 场景切换<2秒
+- **响应时间**: UI交互<100ms
+
+### 优化原则
+1. **测量优先** - 先测量再优化
+2. **渐进优化** - 逐步改进性能
+3. **平衡取舍** - 在质量和性能间平衡
+4. **用户体验** - 优化用户感知性能
+
+## 🔧 渲染优化
+
+### 纹理优化
+```gdscript
+# 使用合适的纹理格式
+# 小图标使用 RGBA8
+# 大背景使用 DXT1/DXT5
+# UI元素使用 RGBA4444
+
+# 纹理压缩设置
+func optimize_texture_import():
+    # 在导入设置中启用压缩
+    # 设置合适的最大尺寸
+    # 启用Mipmaps（3D纹理）
+    pass
+```
+
+### 批处理优化
+```gdscript
+# 合并相同材质的对象
+# 使用MultiMesh渲染大量相同对象
+func create_multimesh_instances():
+    var multimesh = MultiMesh.new()
+    multimesh.transform_format = MultiMesh.TRANSFORM_2D
+    multimesh.instance_count = 100
+    
+    var mesh_instance = MeshInstance2D.new()
+    mesh_instance.multimesh = multimesh
+    add_child(mesh_instance)
+```
+
+### 视锥剔除
+```gdscript
+# 只渲染可见区域的对象
+func update_visibility():
+    var camera = get_viewport().get_camera_2d()
+    var screen_rect = get_viewport_rect()
+    
+    for child in get_children():
+        if child is Node2D:
+            var visible = screen_rect.intersects(child.get_rect())
+            child.visible = visible
+```
+
+## 💾 内存优化
+
+### 对象池模式
+```gdscript
+# ObjectPool.gd
+class_name ObjectPool
+extends Node
+
+var pools: Dictionary = {}
+
+func get_object(type: String) -> Node:
+    if not pools.has(type):
+        pools[type] = []
+    
+    var pool = pools[type]
+    if pool.size() > 0:
+        return pool.pop_back()
+    else:
+        return _create_new_object(type)
+
+func return_object(obj: Node, type: String):
+    obj.reset()  # 重置对象状态
+    pools[type].append(obj)
+
+func _create_new_object(type: String) -> Node:
+    match type:
+        "Bullet":
+            return preload(ProjectPaths.get_component_path("effects", "Bullet")).instantiate()
+        "Enemy":
+            return preload(ProjectPaths.get_component_path("characters", "Enemy")).instantiate()
+        _:
+            return null
+```
+
+### 资源管理
+```gdscript
+# ResourceManager.gd
+class_name ResourceManager
+extends Node
+
+var loaded_resources: Dictionary = {}
+var resource_usage: Dictionary = {}
+
+func load_resource(path: String) -> Resource:
+    if loaded_resources.has(path):
+        resource_usage[path] += 1
+        return loaded_resources[path]
+    
+    var resource = load(path)
+    loaded_resources[path] = resource
+    resource_usage[path] = 1
+    return resource
+
+func unload_resource(path: String):
+    if resource_usage.has(path):
+        resource_usage[path] -= 1
+        if resource_usage[path] <= 0:
+            loaded_resources.erase(path)
+            resource_usage.erase(path)
+```
+
+### 内存监控
+```gdscript
+# MemoryMonitor.gd
+extends Node
+
+func _ready():
+    # 每秒检查一次内存使用
+    var timer = Timer.new()
+    timer.wait_time = 1.0
+    timer.timeout.connect(_check_memory)
+    add_child(timer)
+    timer.start()
+
+func _check_memory():
+    var memory_usage = OS.get_static_memory_usage_by_type()
+    var total_memory = OS.get_static_memory_peak_usage()
+    
+    print("内存使用: ", memory_usage / 1024 / 1024, "MB")
+    print("峰值内存: ", total_memory / 1024 / 1024, "MB")
+    
+    # 内存使用过高时触发垃圾回收
+    if total_memory > 200 * 1024 * 1024:  # 200MB
+        print("触发垃圾回收")
+        # 清理不必要的资源
+        _cleanup_resources()
+
+func _cleanup_resources():
+    # 清理缓存
+    # 卸载未使用的资源
+    # 强制垃圾回收
+    pass
+```
+
+## ⚡ 脚本优化
+
+### 避免频繁计算
+```gdscript
+# ❌ 错误示例：每帧计算
+func _process(delta):
+    var distance = global_position.distance_to(target.global_position)
+    if distance < 100:
+        attack_target()
+
+# ✅ 正确示例：缓存计算结果
+var cached_distance: float = 0.0
+var distance_update_timer: float = 0.0
+
+func _process(delta):
+    distance_update_timer += delta
+    if distance_update_timer >= 0.1:  # 每100ms更新一次
+        cached_distance = global_position.distance_to(target.global_position)
+        distance_update_timer = 0.0
+    
+    if cached_distance < 100:
+        attack_target()
+```
+
+### 优化循环
+```gdscript
+# ❌ 错误示例：嵌套循环
+func find_nearest_enemy():
+    var nearest = null
+    var min_distance = INF
+    
+    for enemy in enemies:
+        for player in players:
+            var distance = enemy.global_position.distance_to(player.global_position)
+            if distance < min_distance:
+                min_distance = distance
+                nearest = enemy
+
+# ✅ 正确示例：优化算法
+func find_nearest_enemy():
+    var player_pos = player.global_position
+    var nearest = null
+    var min_distance = INF
+    
+    for enemy in enemies:
+        var distance = enemy.global_position.distance_squared_to(player_pos)
+        if distance < min_distance:
+            min_distance = distance
+            nearest = enemy
+```
+
+### 事件优化
+```gdscript
+# 使用信号代替轮询
+# ❌ 错误示例：轮询检查
+func _process(delta):
+    if player.health <= 0:
+        game_over()
+
+# ✅ 正确示例：事件驱动
+func _ready():
+    player.health_changed.connect(_on_health_changed)
+
+func _on_health_changed(new_health: int):
+    if new_health <= 0:
+        game_over()
+```
+
+## 🎮 游戏逻辑优化
+
+### 状态机优化
+```gdscript
+# StateMachine.gd
+class_name StateMachine
+extends Node
+
+var current_state: State
+var states: Dictionary = {}
+
+func change_state(state_name: String):
+    if current_state:
+        current_state.exit()
+    
+    current_state = states[state_name]
+    current_state.enter()
+
+func _process(delta):
+    if current_state:
+        current_state.update(delta)
+```
+
+### AI优化
+```gdscript
+# EnemyAI.gd
+extends Node
+
+var update_interval: float = 0.2  # 每200ms更新一次AI
+var update_timer: float = 0.0
+
+func _process(delta):
+    update_timer += delta
+    if update_timer >= update_interval:
+        update_ai()
+        update_timer = 0.0
+
+func update_ai():
+    # AI逻辑更新
+    # 路径寻找
+    # 决策制定
+    pass
+```
+
+### 碰撞检测优化
+```gdscript
+# 使用空间分区优化碰撞检测
+class_name SpatialGrid
+extends Node
+
+var grid_size: int = 64
+var grid: Dictionary = {}
+
+func add_object(obj: Node2D):
+    var grid_pos = Vector2(
+        int(obj.global_position.x / grid_size),
+        int(obj.global_position.y / grid_size)
+    )
+    
+    if not grid.has(grid_pos):
+        grid[grid_pos] = []
+    
+    grid[grid_pos].append(obj)
+
+func get_nearby_objects(pos: Vector2) -> Array:
+    var grid_pos = Vector2(
+        int(pos.x / grid_size),
+        int(pos.y / grid_size)
+    )
+    
+    var nearby = []
+    for x in range(-1, 2):
+        for y in range(-1, 2):
+            var check_pos = grid_pos + Vector2(x, y)
+            if grid.has(check_pos):
+                nearby.append_array(grid[check_pos])
+    
+    return nearby
+```
+
+## 🌐 网络优化
+
+### 数据压缩
+```gdscript
+# NetworkManager.gd
+func send_player_data(data: Dictionary):
+    # 只发送变化的数据
+    var delta_data = get_changed_data(data)
+    
+    # 压缩数据
+    var compressed = compress_data(delta_data)
+    
+    # 发送数据
+    send_to_server(compressed)
+
+func compress_data(data: Dictionary) -> PackedByteArray:
+    var json_string = JSON.stringify(data)
+    var bytes = json_string.to_utf8_buffer()
+    return bytes.compress(FileAccess.COMPRESSION_GZIP)
+```
+
+### 批量更新
+```gdscript
+# 批量发送网络更新
+var pending_updates: Array = []
+var update_timer: float = 0.0
+
+func _process(delta):
+    update_timer += delta
+    if update_timer >= 0.05:  # 每50ms发送一次
+        if pending_updates.size() > 0:
+            send_batch_updates(pending_updates)
+            pending_updates.clear()
+        update_timer = 0.0
+
+func queue_update(update_data: Dictionary):
+    pending_updates.append(update_data)
+```
+
+## 📊 性能监控
+
+### FPS监控
+```gdscript
+# FPSMonitor.gd
+extends Control
+
+@onready var fps_label: Label = $FPSLabel
+var fps_history: Array = []
+
+func _process(delta):
+    var current_fps = Engine.get_frames_per_second()
+    fps_history.append(current_fps)
+    
+    if fps_history.size() > 60:  # 保留60帧历史
+        fps_history.pop_front()
+    
+    var avg_fps = 0
+    for fps in fps_history:
+        avg_fps += fps
+    avg_fps /= fps_history.size()
+    
+    fps_label.text = "FPS: %d (平均: %d)" % [current_fps, avg_fps]
+    
+    # FPS过低时警告
+    if avg_fps < 30:
+        modulate = Color.RED
+    elif avg_fps < 50:
+        modulate = Color.YELLOW
+    else:
+        modulate = Color.WHITE
+```
+
+### 性能分析器
+```gdscript
+# Profiler.gd
+class_name Profiler
+extends Node
+
+var timers: Dictionary = {}
+
+func start_timer(name: String):
+    timers[name] = Time.get_time_dict_from_system()
+
+func end_timer(name: String) -> float:
+    if not timers.has(name):
+        return 0.0
+    
+    var start_time = timers[name]
+    var end_time = Time.get_time_dict_from_system()
+    
+    var duration = (end_time.hour * 3600 + end_time.minute * 60 + end_time.second) - \
+                  (start_time.hour * 3600 + start_time.minute * 60 + start_time.second)
+    
+    timers.erase(name)
+    return duration
+
+# 使用示例
+func expensive_function():
+    Profiler.start_timer("expensive_function")
+    
+    # 执行耗时操作
+    for i in range(10000):
+        pass
+    
+    var duration = Profiler.end_timer("expensive_function")
+    print("函数执行时间: ", duration, "秒")
+```
+
+## 🛠️ 调试工具
+
+### 性能调试面板
+```gdscript
+# DebugPanel.gd
+extends Control
+
+@onready var memory_label: Label = $VBox/MemoryLabel
+@onready var fps_label: Label = $VBox/FPSLabel
+@onready var objects_label: Label = $VBox/ObjectsLabel
+
+func _process(delta):
+    # 更新内存使用
+    var memory = OS.get_static_memory_usage_by_type()
+    memory_label.text = "内存: %.1f MB" % (memory / 1024.0 / 1024.0)
+    
+    # 更新FPS
+    fps_label.text = "FPS: %d" % Engine.get_frames_per_second()
+    
+    # 更新对象数量
+    var object_count = get_tree().get_node_count()
+    objects_label.text = "对象数: %d" % object_count
+```
+
+### 热点分析
+```gdscript
+# HotspotAnalyzer.gd
+extends Node
+
+var function_calls: Dictionary = {}
+var function_times: Dictionary = {}
+
+func profile_function(func_name: String, callable: Callable):
+    var start_time = Time.get_time_dict_from_system()
+    
+    callable.call()
+    
+    var end_time = Time.get_time_dict_from_system()
+    var duration = (end_time.hour * 3600 + end_time.minute * 60 + end_time.second) - \
+                  (start_time.hour * 3600 + start_time.minute * 60 + start_time.second)
+    
+    if not function_calls.has(func_name):
+        function_calls[func_name] = 0
+        function_times[func_name] = 0.0
+    
+    function_calls[func_name] += 1
+    function_times[func_name] += duration
+
+func print_profile_report():
+    print("=== 性能分析报告 ===")
+    for func_name in function_calls.keys():
+        var calls = function_calls[func_name]
+        var total_time = function_times[func_name]
+        var avg_time = total_time / calls
+        
+        print("%s: 调用%d次, 总时间%.3fs, 平均%.3fs" % [func_name, calls, total_time, avg_time])
+```
+
+## 📚 最佳实践
+
+### 开发阶段
+1. **早期优化** - 在设计阶段考虑性能
+2. **渐进开发** - 逐步添加功能并测试性能
+3. **定期测试** - 定期进行性能测试
+4. **文档记录** - 记录性能优化决策
+
+### 测试阶段
+1. **多设备测试** - 在不同性能设备上测试
+2. **压力测试** - 测试极限情况下的性能
+3. **长时间测试** - 测试内存泄漏和性能衰减
+4. **用户测试** - 收集真实用户的性能反馈
+
+### 发布阶段
+1. **性能监控** - 监控线上性能指标
+2. **快速响应** - 快速修复性能问题
+3. **持续优化** - 根据数据持续优化
+4. **版本对比** - 对比不同版本的性能表现
+
+## 🔍 常见问题
+
+### Q: 如何识别性能瓶颈？
+A: 使用Godot的内置分析器，添加自定义性能监控，分析FPS和内存使用情况。
+
+### Q: 内存使用过高怎么办？
+A: 检查资源加载，使用对象池，及时释放不需要的对象，优化纹理大小。
+
+### Q: 如何优化大量对象的渲染？
+A: 使用MultiMesh批处理，实现视锥剔除，使用LOD系统，合并相同材质的对象。
+
+### Q: 网络延迟如何优化？
+A: 减少网络请求频率，压缩传输数据，使用预测和插值，实现客户端预测。
+
+---
+
+**记住：性能优化是一个持续的过程，需要在开发的各个阶段都保持关注！**

docs/04-高级开发/模块开发指南.md

@@ -0,0 +1,464 @@
+# 模块开发指南
+
+本文档详细说明如何在 Whale Town 项目中开发新的游戏模块。
+
+## 🎯 模块设计原则
+
+### 核心原则
+1. **单一职责** - 每个模块只负责一个特定的游戏功能
+2. **高内聚低耦合** - 模块内部紧密相关，模块间松散耦合
+3. **可复用性** - 模块应该能在不同场景中复用
+4. **标准化接口** - 统一的模块接口和通信方式
+5. **测试友好** - 模块应该易于测试和调试
+
+### 模块分类
+- **UI模块** - 用户界面组件和交互逻辑
+- **游戏逻辑模块** - 角色、战斗、对话等核心功能
+- **系统模块** - 存档、设置、网络等系统功能
+- **工具模块** - 通用工具和辅助功能
+
+## 🏗️ 模块结构
+
+### 标准目录结构
+```
+module/YourModule/
+├── YourModule.gd           # 主模块脚本
+├── components/             # 子组件
+│   ├── Component1.gd
+│   └── Component2.gd
+├── data/                   # 模块数据
+│   ├── module_config.json
+│   └── default_data.json
+├── scenes/                 # 模块场景
+│   ├── YourModule.tscn
+│   └── components/
+├── tests/                  # 模块测试
+│   ├── test_your_module.gd
+│   └── test_components.gd
+└── README.md              # 模块文档
+```
+
+### 文件命名规范
+- **主模块脚本**: `ModuleName.gd` (PascalCase)
+- **组件脚本**: `ComponentName.gd` (PascalCase)
+- **场景文件**: `module_name.tscn` (snake_case)
+- **数据文件**: `snake_case.json`
+- **测试文件**: `test_module_name.gd`
+
+## 📝 模块开发步骤
+
+### 第一步：创建模块结构
+
+```bash
+# 创建模块目录
+mkdir module/YourModule
+cd module/YourModule
+
+# 创建子目录
+mkdir components data scenes tests
+
+# 创建主要文件
+touch YourModule.gd
+touch README.md
+touch data/module_config.json
+```
+
+### 第二步：实现模块接口
+
+每个模块都应该实现标准的模块接口：
+
+```gdscript
+# YourModule.gd
+extends Node
+class_name YourModule
+
+# 模块信息
+const MODULE_NAME = "YourModule"
+const MODULE_VERSION = "1.0.0"
+const MODULE_AUTHOR = "Your Name"
+
+# 模块状态
+enum ModuleState {
+	UNINITIALIZED,
+	INITIALIZING,
+	READY,
+	ERROR
+}
+
+var current_state: ModuleState = ModuleState.UNINITIALIZED
+var config: Dictionary = {}
+var is_enabled: bool = true
+
+# 必需接口方法
+func initialize() -> bool:
+	"""初始化模块"""
+	current_state = ModuleState.INITIALIZING
+	
+	# 加载配置
+	if not _load_config():
+		current_state = ModuleState.ERROR
+		return false
+	
+	# 初始化组件
+	if not _initialize_components():
+		current_state = ModuleState.ERROR
+		return false
+	
+	# 注册事件监听
+	_register_events()
+	
+	current_state = ModuleState.READY
+	return true
+
+func cleanup():
+	"""清理模块资源"""
+	_unregister_events()
+	_cleanup_components()
+	current_state = ModuleState.UNINITIALIZED
+
+func get_module_info() -> Dictionary:
+	"""获取模块信息"""
+	return {
+		"name": MODULE_NAME,
+		"version": MODULE_VERSION,
+		"author": MODULE_AUTHOR,
+		"state": current_state,
+		"enabled": is_enabled
+	}
+
+# 私有方法
+func _load_config() -> bool:
+	"""加载模块配置"""
+	var config_path = ProjectPaths.get_module_config_path(MODULE_NAME)
+	if not FileAccess.file_exists(config_path):
+		print("警告: 模块配置文件不存在: ", config_path)
+		return true  # 使用默认配置
+	
+	var file = FileAccess.open(config_path, FileAccess.READ)
+	if file == null:
+		print("错误: 无法读取配置文件: ", config_path)
+		return false
+	
+	var json_string = file.get_as_text()
+	file.close()
+	
+	var json = JSON.new()
+	var parse_result = json.parse(json_string)
+	if parse_result != OK:
+		print("错误: 配置文件JSON格式错误: ", config_path)
+		return false
+	
+	config = json.data
+	return true
+
+func _initialize_components() -> bool:
+	"""初始化子组件"""
+	# 在这里初始化模块的子组件
+	return true
+
+func _cleanup_components():
+	"""清理子组件"""
+	# 在这里清理模块的子组件
+	pass
+
+func _register_events():
+	"""注册事件监听"""
+	# 使用EventSystem注册需要监听的事件
+	# EventSystem.connect_event("event_name", _on_event_handler)
+	pass
+
+func _unregister_events():
+	"""取消事件监听"""
+	# 取消所有事件监听
+	# EventSystem.disconnect_event("event_name", _on_event_handler)
+	pass
+```
+
+### 第三步：创建模块配置
+
+```json
+// data/module_config.json
+{
+  "module_name": "YourModule",
+  "version": "1.0.0",
+  "enabled": true,
+  "dependencies": [],
+  "settings": {
+    "auto_initialize": true,
+    "debug_mode": false
+  },
+  "resources": {
+    "textures": [],
+    "sounds": [],
+    "data_files": []
+  }
+}
+```
+
+### 第四步：实现具体功能
+
+根据模块类型实现具体功能：
+
+#### UI模块示例
+```gdscript
+# UI模块应该继承Control或其子类
+extends Control
+class_name UIModule
+
+signal ui_event_triggered(event_name: String, data: Dictionary)
+
+func show_ui():
+	"""显示UI"""
+	visible = true
+	# 播放显示动画
+	_play_show_animation()
+
+func hide_ui():
+	"""隐藏UI"""
+	# 播放隐藏动画
+	_play_hide_animation()
+	await get_tree().create_timer(0.3).timeout
+	visible = false
+
+func _play_show_animation():
+	"""播放显示动画"""
+	var tween = create_tween()
+	modulate.a = 0.0
+	tween.tween_property(self, "modulate:a", 1.0, 0.3)
+
+func _play_hide_animation():
+	"""播放隐藏动画"""
+	var tween = create_tween()
+	tween.tween_property(self, "modulate:a", 0.0, 0.3)
+```
+
+#### 游戏逻辑模块示例
+```gdscript
+# 游戏逻辑模块
+extends Node
+class_name GameLogicModule
+
+signal state_changed(old_state: String, new_state: String)
+signal data_updated(data_type: String, new_data: Dictionary)
+
+var module_data: Dictionary = {}
+var current_state: String = "idle"
+
+func process_game_logic(delta: float):
+	"""处理游戏逻辑"""
+	match current_state:
+		"idle":
+			_process_idle_state(delta)
+		"active":
+			_process_active_state(delta)
+		"paused":
+			_process_paused_state(delta)
+
+func change_state(new_state: String):
+	"""改变模块状态"""
+	var old_state = current_state
+	current_state = new_state
+	state_changed.emit(old_state, new_state)
+
+func update_data(data_type: String, new_data: Dictionary):
+	"""更新模块数据"""
+	module_data[data_type] = new_data
+	data_updated.emit(data_type, new_data)
+```
+
+### 第五步：添加测试
+
+```gdscript
+# tests/test_your_module.gd
+extends GutTest
+
+var module: YourModule
+
+func before_each():
+	module = YourModule.new()
+	add_child(module)
+
+func after_each():
+	module.queue_free()
+
+func test_module_initialization():
+	assert_true(module.initialize(), "模块应该能够正确初始化")
+	assert_eq(module.current_state, YourModule.ModuleState.READY, "初始化后状态应该为READY")
+
+func test_module_cleanup():
+	module.initialize()
+	module.cleanup()
+	assert_eq(module.current_state, YourModule.ModuleState.UNINITIALIZED, "清理后状态应该为UNINITIALIZED")
+
+func test_module_info():
+	var info = module.get_module_info()
+	assert_true(info.has("name"), "模块信息应该包含名称")
+	assert_true(info.has("version"), "模块信息应该包含版本")
+	assert_eq(info.name, "YourModule", "模块名称应该正确")
+```
+
+### 第六步：编写文档
+
+```markdown
+# YourModule 模块
+
+## 功能描述
+简要描述模块的主要功能和用途。
+
+## 使用方法
+```gdscript
+# 创建和初始化模块
+var your_module = YourModule.new()
+add_child(your_module)
+your_module.initialize()
+
+# 使用模块功能
+your_module.some_function()
+```
+
+## API参考
+### 公共方法
+- `initialize() -> bool` - 初始化模块
+- `cleanup()` - 清理模块资源
+- `get_module_info() -> Dictionary` - 获取模块信息
+
+### 信号
+- `signal_name(param: Type)` - 信号描述
+
+## 配置选项
+描述模块的配置选项和默认值。
+
+## 依赖关系
+列出模块的依赖项。
+
+## 注意事项
+使用模块时需要注意的事项。
+```
+
+## 🔧 模块集成
+
+### 在场景中使用模块
+
+```gdscript
+# 在场景脚本中使用模块
+extends Control
+
+var inventory_module: InventoryModule
+var dialogue_module: DialogueModule
+
+func _ready():
+	# 创建并初始化模块
+	inventory_module = InventoryModule.new()
+	add_child(inventory_module)
+	inventory_module.initialize()
+	
+	dialogue_module = DialogueModule.new()
+	add_child(dialogue_module)
+	dialogue_module.initialize()
+	
+	# 连接模块事件
+	inventory_module.item_selected.connect(_on_item_selected)
+	dialogue_module.dialogue_finished.connect(_on_dialogue_finished)
+
+func _on_item_selected(item_data: Dictionary):
+	print("选中物品: ", item_data.name)
+
+func _on_dialogue_finished():
+	print("对话结束")
+```
+
+### 模块间通信
+
+推荐使用EventSystem进行模块间通信：
+
+```gdscript
+# 发送事件
+EventSystem.emit_event("inventory_item_used", {
+	"item_id": "potion_001",
+	"quantity": 1
+})
+
+# 监听事件
+EventSystem.connect_event("inventory_item_used", _on_item_used)
+
+func _on_item_used(data: Dictionary):
+	print("使用了物品: ", data.item_id)
+```
+
+## 🧪 测试和调试
+
+### 单元测试
+每个模块都应该有对应的单元测试：
+
+```bash
+# 运行模块测试
+godot --headless --script tests/test_your_module.gd
+```
+
+### 调试技巧
+1. **使用print语句** - 在关键位置添加调试输出
+2. **断点调试** - 在Godot编辑器中设置断点
+3. **状态监控** - 实时监控模块状态变化
+4. **事件追踪** - 记录事件的发送和接收
+
+### 性能监控
+```gdscript
+# 性能监控示例
+func _process(delta):
+	var start_time = Time.get_time_dict_from_system()
+	
+	# 执行模块逻辑
+	process_module_logic(delta)
+	
+	var end_time = Time.get_time_dict_from_system()
+	var execution_time = (end_time.hour * 3600 + end_time.minute * 60 + end_time.second) - \
+						(start_time.hour * 3600 + start_time.minute * 60 + start_time.second)
+	
+	if execution_time > 0.016:  # 超过16ms
+		print("警告: 模块执行时间过长: ", execution_time, "秒")
+```
+
+## 📚 最佳实践
+
+### 代码质量
+1. **遵循命名规范** - 使用清晰、一致的命名
+2. **添加详细注释** - 解释复杂逻辑和设计决策
+3. **错误处理** - 妥善处理各种异常情况
+4. **资源管理** - 及时释放不需要的资源
+
+### 性能优化
+1. **避免频繁的内存分配** - 重用对象和数据结构
+2. **合理使用信号** - 避免过多的信号连接
+3. **批量处理** - 将多个操作合并处理
+4. **延迟加载** - 按需加载资源和数据
+
+### 可维护性
+1. **模块化设计** - 保持模块的独立性
+2. **版本控制** - 记录模块的版本变化
+3. **文档更新** - 及时更新模块文档
+4. **向后兼容** - 考虑API的向后兼容性
+
+## 🔍 常见问题
+
+### Q: 如何处理模块依赖？
+A: 在模块配置中声明依赖，在初始化时检查依赖是否满足。
+
+### Q: 模块间如何共享数据？
+A: 使用EventSystem传递数据，或通过GameManager等全局管理器。
+
+### Q: 如何调试模块问题？
+A: 使用Godot的调试工具，添加日志输出，编写单元测试。
+
+### Q: 模块性能如何优化？
+A: 避免在_process中执行重复计算，使用对象池，合理管理资源。
+
+## 📖 参考资料
+
+- [Godot官方文档](https://docs.godotengine.org/)
+- [项目命名规范](./naming_convention.md)
+- [代码注释规范](./code_comment_guide.md)
+- [Git提交规范](./git_commit_guide.md)
+
+---
+
+**记住：好的模块设计是项目成功的关键！**

docs/05-部署运维/Web部署指南.md

@@ -66,13 +66,13 @@ Dedicated Server: ✗ 禁用
 Variant: release
 Vram Texture Compression: ✓ 启用
 Export Type: Regular
-Custom HTML Shell: res://assets/web/custom_shell.html
+Custom HTML Shell: res://web_assets/custom_shell.html
 Head Include: (留空，已在自定义模板中配置)
 ```
 
 #### 高级选项
 ```
-Custom HTML Shell: res://assets/web/custom_shell.html
+Custom HTML Shell: res://web_assets/custom_shell.html
 Progressive Web App: ✓ 启用（可选）
 Icon 144x144: res://icon.svg
 Icon 180x180: res://icon.svg

docs/AI_docs/quick_reference/troubleshooting.md

@@ -0,0 +1,238 @@
+# 🔧 故障排除指南
+
+> AI编程助手专用：常见问题的快速解决方案
+
+## 🚨 常见错误及解决方案
+
+### 1. UID无效警告
+
+**错误信息**:
+```
+WARNING: scene/resources/resource_format_text.cpp:444 - res://path/to/file.tscn:X - ext_resource, invalid UID: uid://xxxxx - using text path instead: res://path/to/script.gd
+```
+
+**原因**: 文件移动后，Godot的UID缓存没有更新，导致UID引用失效。
+
+**解决方案**:
+```gdscript
+# 方法1: 移除无效的UID，使用文本路径
+# 将这行：
+[ext_resource type="Script" uid="uid://invalid_uid" path="res://path/to/script.gd" id="1_script"]
+
+# 改为：
+[ext_resource type="Script" path="res://path/to/script.gd" id="1_script"]
+```
+
+**预防措施**:
+- 移动文件时使用Godot编辑器的文件系统面板
+- 避免直接在文件系统中移动.gd和.tscn文件
+- 移动文件后重新导入项目
+
+### 2. 脚本路径错误
+
+**错误信息**:
+```
+ERROR: Failed to load script "res://old/path/Script.gd" with error "File not found".
+```
+
+**解决方案**:
+```gdscript
+# 检查并更新所有.tscn文件中的脚本路径
+# 使用搜索替换功能批量更新：
+
+# 旧路径 → 新路径
+"res://UI/Windows/" → "res://scenes/ui/"
+"res://Utils/" → "res://_Core/utils/"
+"res://Scenes/Maps/" → "res://scenes/maps/"
+```
+
+### 3. AutoLoad路径错误
+
+**错误信息**:
+```
+ERROR: Cannot load autoload: res://old/path/Manager.gd
+```
+
+**解决方案**:
+```ini
+# 在 project.godot 中更新 AutoLoad 路径
+[autoload]
+GameManager="*res://_Core/managers/GameManager.gd"
+SceneManager="*res://_Core/managers/SceneManager.gd"
+EventSystem="*res://_Core/systems/EventSystem.gd"
+```
+
+### 4. 资源加载失败
+
+**错误信息**:
+```
+ERROR: Failed to load resource "res://old/path/resource.png".
+```
+
+**解决方案**:
+```gdscript
+# 检查资源路径是否正确
+# 使用 ResourceLoader.exists() 验证路径
+func load_resource_safely(path: String):
+    if not ResourceLoader.exists(path):
+        push_error("Resource not found: %s" % path)
+        return null
+    
+    return load(path)
+```
+
+## 🔍 调试技巧
+
+### 1. 路径验证
+```gdscript
+# 验证文件是否存在
+func verify_file_exists(file_path: String) -> bool:
+    return FileAccess.file_exists(file_path)
+
+# 验证资源是否存在
+func verify_resource_exists(resource_path: String) -> bool:
+    return ResourceLoader.exists(resource_path)
+
+# 打印当前工作目录
+func print_current_directory():
+    print("Current directory: ", OS.get_executable_path().get_base_dir())
+```
+
+### 2. 场景加载调试
+```gdscript
+# 安全的场景加载
+func load_scene_safely(scene_path: String) -> PackedScene:
+    if not ResourceLoader.exists(scene_path):
+        push_error("Scene file not found: %s" % scene_path)
+        return null
+    
+    var scene = load(scene_path) as PackedScene
+    if scene == null:
+        push_error("Failed to load scene: %s" % scene_path)
+        return null
+    
+    return scene
+```
+
+### 3. 节点引用调试
+```gdscript
+# 安全的节点获取
+func get_node_safely(node_path: String) -> Node:
+    var node = get_node_or_null(node_path)
+    if node == null:
+        push_warning("Node not found: %s" % node_path)
+    return node
+
+# 检查@onready变量是否正确初始化
+func _ready():
+    # 验证所有@onready节点
+    if not some_button:
+        push_error("some_button not found - check node path")
+    if not some_label:
+        push_error("some_label not found - check node path")
+```
+
+## 🛠️ 项目结构问题
+
+### 1. 文件移动后的检查清单
+- [ ] 更新.tscn文件中的脚本路径
+- [ ] 更新project.godot中的AutoLoad路径
+- [ ] 更新代码中的硬编码路径
+- [ ] 清理Godot缓存文件
+- [ ] 重新导入项目
+
+### 2. 缓存清理命令
+```bash
+# Windows PowerShell
+Remove-Item -Recurse -Force ".godot\uid_cache.bin"
+Remove-Item -Recurse -Force ".godot\global_script_class_cache.cfg"
+
+# Linux/macOS
+rm -rf .godot/uid_cache.bin
+rm -rf .godot/global_script_class_cache.cfg
+```
+
+### 3. 路径常量管理
+```gdscript
+# 在 _Core/ProjectPaths.gd 中定义所有路径
+class_name ProjectPaths
+
+# 核心路径
+const CORE_ROOT = "res://_Core/"
+const MANAGERS_PATH = CORE_ROOT + "managers/"
+const SYSTEMS_PATH = CORE_ROOT + "systems/"
+const UTILS_PATH = CORE_ROOT + "utils/"
+
+# 场景路径
+const SCENES_ROOT = "res://scenes/"
+const UI_PATH = SCENES_ROOT + "ui/"
+const MAPS_PATH = SCENES_ROOT + "maps/"
+
+# 使用示例
+var scene_path = ProjectPaths.UI_PATH + "LoginWindow.tscn"
+```
+
+## 🎯 性能问题
+
+### 1. 内存泄漏检测
+```gdscript
+# 监控节点数量
+func _ready():
+    print("Initial node count: ", get_tree().get_node_count())
+
+func _exit_tree():
+    print("Final node count: ", get_tree().get_node_count())
+
+# 检查未释放的资源
+func check_resource_leaks():
+    print("Resource count: ", ResourceLoader.get_resource_list().size())
+```
+
+### 2. 帧率监控
+```gdscript
+# 在 _Core/managers/PerformanceManager.gd
+extends Node
+
+var frame_count: int = 0
+var fps_timer: float = 0.0
+
+func _process(delta: float):
+    frame_count += 1
+    fps_timer += delta
+    
+    if fps_timer >= 1.0:
+        var fps = frame_count / fps_timer
+        if fps < 30:
+            push_warning("Low FPS detected: %.1f" % fps)
+        
+        frame_count = 0
+        fps_timer = 0.0
+```
+
+## 🔧 开发工具问题
+
+### 1. Godot编辑器崩溃
+**解决方案**:
+1. 备份项目文件
+2. 删除.godot文件夹
+3. 重新打开项目
+4. 重新导入所有资源
+
+### 2. 脚本编辑器问题
+**解决方案**:
+```gdscript
+# 检查脚本语法
+# 使用 Godot 内置的语法检查器
+# 或者在命令行中运行：
+# godot --check-only script.gd
+```
+
+### 3. 场景编辑器问题
+**解决方案**:
+- 检查场景文件是否损坏
+- 重新创建有问题的场景
+- 使用版本控制恢复到工作版本
+
+---
+
+**💡 提示**: 遇到问题时，首先检查Godot的输出面板和调试器，它们通常会提供详细的错误信息和解决建议。

docs/AI_docs/templates/managers.md

@@ -0,0 +1,617 @@
+# 🎯 管理器模板集合
+
+> AI编程助手专用：各类管理器的标准化代码模板
+
+## 🎮 游戏管理器模板
+
+### 基础游戏管理器
+```gdscript
+# _Core/managers/GameManager.gd
+extends Node
+
+## 游戏状态管理器
+## 负责管理游戏的全局状态、玩家数据和游戏流程
+
+# 信号定义
+signal game_state_changed(old_state: GameState, new_state: GameState)
+signal player_data_updated(data: Dictionary)
+signal game_paused()
+signal game_resumed()
+
+# 游戏状态枚举
+enum GameState {
+	LOADING,
+	MENU,
+	PLAYING,
+	PAUSED,
+	GAME_OVER,
+	SETTINGS
+}
+
+# 常量定义
+const SAVE_FILE_PATH: String = "user://game_save.dat"
+const CONFIG_FILE_PATH: String = "res://Config/game_config.json"
+
+# 导出变量
+@export var debug_mode: bool = false
+@export var auto_save_interval: float = 30.0
+
+# 公共变量
+var current_state: GameState = GameState.LOADING
+var is_paused: bool = false
+var game_time: float = 0.0
+
+# 玩家数据
+var player_data: Dictionary = {
+	"level": 1,
+	"experience": 0,
+	"coins": 100,
+	"health": 100,
+	"max_health": 100,
+	"energy": 100,
+	"max_energy": 100
+}
+
+# 私有变量
+var _auto_save_timer: Timer
+var _game_config: Dictionary = {}
+
+func _ready() -> void:
+	_initialize_manager()
+	_setup_auto_save()
+	_load_game_config()
+	change_state(GameState.MENU)
+
+func _process(delta: float) -> void:
+	if current_state == GameState.PLAYING and not is_paused:
+		game_time += delta
+
+## 改变游戏状态
+func change_state(new_state: GameState) -> void:
+	if current_state == new_state:
+		return
+	
+	var old_state = current_state
+	_exit_state(old_state)
+	current_state = new_state
+	_enter_state(new_state)
+	
+	game_state_changed.emit(old_state, new_state)
+	
+	if debug_mode:
+		print("[GameManager] State changed: %s -> %s" % [old_state, new_state])
+
+## 暂停游戏
+func pause_game() -> void:
+	if current_state != GameState.PLAYING:
+		return
+	
+	is_paused = true
+	get_tree().paused = true
+	game_paused.emit()
+
+## 恢复游戏
+func resume_game() -> void:
+	if not is_paused:
+		return
+	
+	is_paused = false
+	get_tree().paused = false
+	game_resumed.emit()
+
+## 更新玩家数据
+func update_player_data(key: String, value) -> void:
+	if not player_data.has(key):
+		push_warning("Unknown player data key: %s" % key)
+		return
+	
+	player_data[key] = value
+	player_data_updated.emit(player_data)
+	
+	if debug_mode:
+		print("[GameManager] Player data updated: %s = %s" % [key, value])
+
+## 获取玩家数据
+func get_player_data(key: String = ""):
+	if key.is_empty():
+		return player_data.duplicate()
+	
+	return player_data.get(key, null)
+
+## 保存游戏数据
+func save_game() -> bool:
+	var save_data = {
+		"player_data": player_data,
+		"game_time": game_time,
+		"current_state": current_state,
+		"timestamp": Time.get_unix_time_from_system()
+	}
+	
+	var file = FileAccess.open(SAVE_FILE_PATH, FileAccess.WRITE)
+	if file == null:
+		push_error("Failed to open save file for writing")
+		return false
+	
+	file.store_string(JSON.stringify(save_data))
+	file.close()
+	
+	if debug_mode:
+		print("[GameManager] Game saved successfully")
+	
+	return true
+
+## 加载游戏数据
+func load_game() -> bool:
+	if not FileAccess.file_exists(SAVE_FILE_PATH):
+		if debug_mode:
+			print("[GameManager] No save file found")
+		return false
+	
+	var file = FileAccess.open(SAVE_FILE_PATH, FileAccess.READ)
+	if file == null:
+		push_error("Failed to open save file for reading")
+		return false
+	
+	var json_text = file.get_as_text()
+	file.close()
+	
+	var json = JSON.new()
+	var parse_result = json.parse(json_text)
+	if parse_result != OK:
+		push_error("Failed to parse save file JSON")
+		return false
+	
+	var save_data = json.data
+	
+	# 恢复玩家数据
+	if save_data.has("player_data"):
+		player_data = save_data.player_data
+		player_data_updated.emit(player_data)
+	
+	# 恢复游戏时间
+	if save_data.has("game_time"):
+		game_time = save_data.game_time
+	
+	if debug_mode:
+		print("[GameManager] Game loaded successfully")
+	
+	return true
+
+# 私有方法
+func _initialize_manager() -> void:
+	# 设置进程模式为总是处理（即使暂停时也能工作）
+	process_mode = Node.PROCESS_MODE_ALWAYS
+
+func _setup_auto_save() -> void:
+	_auto_save_timer = Timer.new()
+	add_child(_auto_save_timer)
+	_auto_save_timer.wait_time = auto_save_interval
+	_auto_save_timer.timeout.connect(_on_auto_save_timeout)
+	_auto_save_timer.start()
+
+func _load_game_config() -> void:
+	if not FileAccess.file_exists(CONFIG_FILE_PATH):
+		push_warning("Game config file not found")
+		return
+	
+	var file = FileAccess.open(CONFIG_FILE_PATH, FileAccess.READ)
+	if file == null:
+		push_error("Failed to open game config file")
+		return
+	
+	var json_text = file.get_as_text()
+	file.close()
+	
+	var json = JSON.new()
+	var parse_result = json.parse(json_text)
+	if parse_result != OK:
+		push_error("Failed to parse game config JSON")
+		return
+	
+	_game_config = json.data
+
+func _enter_state(state: GameState) -> void:
+	match state:
+		GameState.LOADING:
+			# 加载游戏资源
+			pass
+		GameState.MENU:
+			# 显示主菜单
+			pass
+		GameState.PLAYING:
+			# 开始游戏逻辑
+			_auto_save_timer.start()
+		GameState.PAUSED:
+			# 暂停游戏
+			_auto_save_timer.stop()
+		GameState.GAME_OVER:
+			# 游戏结束处理
+			save_game()
+		GameState.SETTINGS:
+			# 显示设置界面
+			pass
+
+func _exit_state(state: GameState) -> void:
+	match state:
+		GameState.PLAYING:
+			# 退出游戏时自动保存
+			save_game()
+
+func _on_auto_save_timeout() -> void:
+	if current_state == GameState.PLAYING:
+		save_game()
+```
+
+## 🌐 网络管理器模板
+
+### HTTP请求管理器
+```gdscript
+# _Core/managers/NetworkManager.gd
+extends Node
+
+## 网络请求管理器
+## 负责处理所有HTTP请求和网络通信
+
+# 信号定义
+signal request_completed(request_id: String, success: bool, data: Dictionary)
+signal connection_status_changed(is_connected: bool)
+
+# 常量定义
+const BASE_URL: String = "https://api.example.com"
+const TIMEOUT_DURATION: float = 10.0
+const MAX_RETRIES: int = 3
+
+# 请求状态枚举
+enum RequestStatus {
+	PENDING,
+	SUCCESS,
+	FAILED,
+	TIMEOUT,
+	CANCELLED
+}
+
+# 公共变量
+var is_connected: bool = false
+var active_requests: Dictionary = {}
+
+# 私有变量
+var _http_client: HTTPClient
+var _request_counter: int = 0
+
+func _ready() -> void:
+	_initialize_network()
+	_check_connection()
+
+## 发送GET请求
+func send_get_request(endpoint: String, headers: Dictionary = {}) -> String:
+	return _send_request(HTTPClient.METHOD_GET, endpoint, "", headers)
+
+## 发送POST请求
+func send_post_request(endpoint: String, data: Dictionary, headers: Dictionary = {}) -> String:
+	var json_data = JSON.stringify(data)
+	return _send_request(HTTPClient.METHOD_POST, endpoint, json_data, headers)
+
+## 发送PUT请求
+func send_put_request(endpoint: String, data: Dictionary, headers: Dictionary = {}) -> String:
+	var json_data = JSON.stringify(data)
+	return _send_request(HTTPClient.METHOD_PUT, endpoint, json_data, headers)
+
+## 发送DELETE请求
+func send_delete_request(endpoint: String, headers: Dictionary = {}) -> String:
+	return _send_request(HTTPClient.METHOD_DELETE, endpoint, "", headers)
+
+## 取消请求
+func cancel_request(request_id: String) -> bool:
+	if not active_requests.has(request_id):
+		return false
+	
+	var request_data = active_requests[request_id]
+	if request_data.http_request:
+		request_data.http_request.cancel_request()
+	
+	_cleanup_request(request_id, RequestStatus.CANCELLED)
+	return true
+
+## 检查网络连接状态
+func check_connection() -> void:
+	_check_connection()
+
+# 私有方法
+func _initialize_network() -> void:
+	_http_client = HTTPClient.new()
+
+func _send_request(method: HTTPClient.Method, endpoint: String, data: String, headers: Dictionary) -> String:
+	var request_id = _generate_request_id()
+	var full_url = BASE_URL + endpoint
+	
+	# 创建HTTP请求节点
+	var http_request = HTTPRequest.new()
+	add_child(http_request)
+	
+	# 设置请求超时
+	http_request.timeout = TIMEOUT_DURATION
+	
+	# 连接完成信号
+	http_request.request_completed.connect(_on_request_completed.bind(request_id))
+	
+	# 准备请求头
+	var request_headers = ["Content-Type: application/json"]
+	for key in headers:
+		request_headers.append("%s: %s" % [key, headers[key]])
+	
+	# 存储请求信息
+	active_requests[request_id] = {
+		"http_request": http_request,
+		"method": method,
+		"url": full_url,
+		"status": RequestStatus.PENDING,
+		"retry_count": 0,
+		"start_time": Time.get_time_dict_from_system()
+	}
+	
+	# 发送请求
+	var error = http_request.request(full_url, request_headers, method, data)
+	if error != OK:
+		push_error("Failed to send HTTP request: %d" % error)
+		_cleanup_request(request_id, RequestStatus.FAILED)
+		return ""
+	
+	return request_id
+
+func _generate_request_id() -> String:
+	_request_counter += 1
+	return "req_%d_%d" % [Time.get_time_dict_from_system().hour * 3600 + Time.get_time_dict_from_system().minute * 60 + Time.get_time_dict_from_system().second, _request_counter]
+
+func _on_request_completed(request_id: String, result: int, response_code: int, headers: PackedStringArray, body: PackedByteArray) -> void:
+	if not active_requests.has(request_id):
+		return
+	
+	var request_data = active_requests[request_id]
+	var success = false
+	var response_data = {}
+	
+	# 解析响应
+	if response_code >= 200 and response_code < 300:
+		success = true
+		var body_text = body.get_string_from_utf8()
+		
+		if not body_text.is_empty():
+			var json = JSON.new()
+			var parse_result = json.parse(body_text)
+			if parse_result == OK:
+				response_data = json.data
+			else:
+				response_data = {"raw_response": body_text}
+	else:
+		# 处理错误响应
+		var body_text = body.get_string_from_utf8()
+		response_data = {
+			"error": "HTTP Error %d" % response_code,
+			"response_code": response_code,
+			"raw_response": body_text
+		}
+	
+	# 发送完成信号
+	request_completed.emit(request_id, success, response_data)
+	
+	# 清理请求
+	_cleanup_request(request_id, RequestStatus.SUCCESS if success else RequestStatus.FAILED)
+
+func _cleanup_request(request_id: String, status: RequestStatus) -> void:
+	if not active_requests.has(request_id):
+		return
+	
+	var request_data = active_requests[request_id]
+	
+	# 移除HTTP请求节点
+	if request_data.http_request:
+		request_data.http_request.queue_free()
+	
+	# 从活动请求中移除
+	active_requests.erase(request_id)
+
+func _check_connection() -> void:
+	# 简单的连接检查（可以改为ping服务器）
+	var old_status = is_connected
+	is_connected = true  # 这里可以实现实际的连接检查逻辑
+	
+	if old_status != is_connected:
+		connection_status_changed.emit(is_connected)
+```
+
+## 🎵 音频管理器模板
+
+### 音频系统管理器
+```gdscript
+# _Core/managers/AudioManager.gd
+extends Node
+
+## 音频管理器
+## 负责管理游戏中的音乐和音效播放
+
+# 信号定义
+signal music_finished()
+signal sound_effect_finished(sound_name: String)
+
+# 音频类型枚举
+enum AudioType {
+	MUSIC,
+	SOUND_EFFECT,
+	UI_SOUND,
+	VOICE
+}
+
+# 常量定义
+const MUSIC_PATH: String = "res://assets/audio/music/"
+const SOUND_PATH: String = "res://assets/audio/sounds/"
+const VOICE_PATH: String = "res://assets/audio/voice/"
+
+# 导出变量
+@export var master_volume: float = 1.0
+@export var music_volume: float = 0.7
+@export var sfx_volume: float = 0.8
+@export var voice_volume: float = 0.9
+
+# 音频播放器
+var music_player: AudioStreamPlayer
+var sfx_players: Array[AudioStreamPlayer] = []
+var voice_player: AudioStreamPlayer
+
+# 当前播放状态
+var current_music: String = ""
+var is_music_playing: bool = false
+var active_sounds: Dictionary = {}
+
+func _ready() -> void:
+	_initialize_audio_players()
+	_load_audio_settings()
+
+## 播放背景音乐
+func play_music(music_name: String, fade_in: bool = true) -> void:
+	var music_path = MUSIC_PATH + music_name + ".ogg"
+	
+	if not ResourceLoader.exists(music_path):
+		push_warning("Music file not found: %s" % music_path)
+		return
+	
+	# 停止当前音乐
+	if is_music_playing:
+		stop_music(fade_in)
+		await get_tree().create_timer(0.5).timeout
+	
+	# 加载并播放新音乐
+	var audio_stream = load(music_path)
+	music_player.stream = audio_stream
+	music_player.volume_db = linear_to_db(music_volume * master_volume)
+	
+	if fade_in:
+		_fade_in_music()
+	else:
+		music_player.play()
+	
+	current_music = music_name
+	is_music_playing = true
+
+## 停止背景音乐
+func stop_music(fade_out: bool = true) -> void:
+	if not is_music_playing:
+		return
+	
+	if fade_out:
+		_fade_out_music()
+	else:
+		music_player.stop()
+		is_music_playing = false
+		current_music = ""
+
+## 播放音效
+func play_sound_effect(sound_name: String, volume_override: float = -1.0) -> void:
+	var sound_path = SOUND_PATH + sound_name + ".ogg"
+	
+	if not ResourceLoader.exists(sound_path):
+		push_warning("Sound file not found: %s" % sound_path)
+		return
+	
+	# 获取可用的音效播放器
+	var player = _get_available_sfx_player()
+	if player == null:
+		push_warning("No available sound effect player")
+		return
+	
+	# 加载并播放音效
+	var audio_stream = load(sound_path)
+	player.stream = audio_stream
+	
+	var final_volume = volume_override if volume_override > 0 else sfx_volume
+	player.volume_db = linear_to_db(final_volume * master_volume)
+	
+	player.play()
+	active_sounds[sound_name] = player
+
+## 设置主音量
+func set_master_volume(volume: float) -> void:
+	master_volume = clamp(volume, 0.0, 1.0)
+	_update_all_volumes()
+
+## 设置音乐音量
+func set_music_volume(volume: float) -> void:
+	music_volume = clamp(volume, 0.0, 1.0)
+	if is_music_playing:
+		music_player.volume_db = linear_to_db(music_volume * master_volume)
+
+## 设置音效音量
+func set_sfx_volume(volume: float) -> void:
+	sfx_volume = clamp(volume, 0.0, 1.0)
+	_update_sfx_volumes()
+
+# 私有方法
+func _initialize_audio_players() -> void:
+	# 创建音乐播放器
+	music_player = AudioStreamPlayer.new()
+	add_child(music_player)
+	music_player.finished.connect(_on_music_finished)
+	
+	# 创建多个音效播放器（支持同时播放多个音效）
+	for i in range(8):
+		var sfx_player = AudioStreamPlayer.new()
+		add_child(sfx_player)
+		sfx_players.append(sfx_player)
+	
+	# 创建语音播放器
+	voice_player = AudioStreamPlayer.new()
+	add_child(voice_player)
+
+func _get_available_sfx_player() -> AudioStreamPlayer:
+	for player in sfx_players:
+		if not player.playing:
+			return player
+	return null
+
+func _fade_in_music() -> void:
+	music_player.volume_db = linear_to_db(0.01)
+	music_player.play()
+	
+	var tween = create_tween()
+	tween.tween_method(_set_music_volume_db, 0.01, music_volume * master_volume, 1.0)
+
+func _fade_out_music() -> void:
+	var tween = create_tween()
+	tween.tween_method(_set_music_volume_db, music_volume * master_volume, 0.01, 1.0)
+	tween.tween_callback(_stop_music_after_fade)
+
+func _set_music_volume_db(volume: float) -> void:
+	music_player.volume_db = linear_to_db(volume)
+
+func _stop_music_after_fade() -> void:
+	music_player.stop()
+	is_music_playing = false
+	current_music = ""
+
+func _update_all_volumes() -> void:
+	if is_music_playing:
+		music_player.volume_db = linear_to_db(music_volume * master_volume)
+	_update_sfx_volumes()
+
+func _update_sfx_volumes() -> void:
+	for player in sfx_players:
+		if player.playing:
+			player.volume_db = linear_to_db(sfx_volume * master_volume)
+
+func _load_audio_settings() -> void:
+	# 从配置文件加载音频设置
+	pass
+
+func _on_music_finished() -> void:
+	is_music_playing = false
+	current_music = ""
+	music_finished.emit()
+```
+
+---
+
+**🎯 使用说明**: 
+1. 选择合适的管理器模板
+2. 根据具体需求修改类名和功能
+3. 确保在project.godot中配置为AutoLoad
+4. 遵循项目的命名规范和代码风格
+5. 添加必要的错误处理和日志记录

docs/AI_docs/workflows/feature_development.md

@@ -0,0 +1,363 @@
+# 🚀 功能开发流程
+
+> AI编程助手专用：新功能开发的标准化工作流程
+
+## 🎯 开发流程概览
+
+### 阶段1: 需求分析 → 阶段2: 架构设计 → 阶段3: 代码实现 → 阶段4: 测试验证 → 阶段5: 文档更新
+
+---
+
+## 📋 阶段1: 需求分析
+
+### 1.1 理解需求
+```markdown
+**必须明确的问题:**
+- 功能的具体作用是什么？
+- 涉及哪些用户交互？
+- 需要哪些数据和状态管理？
+- 与现有功能的关系如何？
+```
+
+### 1.2 需求分类
+```gdscript
+# 功能类型分类
+enum FeatureType {
+    CORE_SYSTEM,     # 核心系统功能 → 放在 _Core/
+    GAME_SCENE,      # 游戏场景功能 → 放在 scenes/
+    UI_COMPONENT,    # UI组件功能 → 放在 scenes/ui/
+    ASSET_RELATED,   # 资源相关功能 → 涉及 assets/
+    CONFIG_DRIVEN    # 配置驱动功能 → 涉及 Config/
+}
+```
+
+### 1.3 依赖分析
+- 需要哪些现有管理器？
+- 需要创建新的管理器吗？
+- 需要新的事件定义吗？
+- 需要新的配置文件吗？
+
+---
+
+## 🏗️ 阶段2: 架构设计
+
+### 2.1 确定文件位置
+```gdscript
+# 根据功能类型确定文件位置
+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 设计接口
+```gdscript
+# 定义公共接口
+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 事件设计
+```gdscript
+# 在 _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 创建基础结构
+```gdscript
+# 使用标准模板创建文件
+# 参考: 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 实现核心逻辑
+```gdscript
+## 初始化功能
+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 错误处理
+```gdscript
+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 创建测试文件
+```gdscript
+# 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 集成测试
+```gdscript
+# 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 性能测试
+```gdscript
+# 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文档
+```markdown
+# 在 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. **测试覆盖**: 测试是否充分？
+
+### 持续改进
+- 收集用户反馈
+- 监控性能指标
+- 定期重构优化
+- 更新文档和示例
+
+---
+
+**🎯 记住**: 这个流程确保了功能开发的质量和一致性。严格遵循每个阶段的要求，将大大提高开发效率和代码质量。

docs/CHANGELOG.md

@@ -0,0 +1,65 @@
+# 文档更新日志
+
+本文档记录了WhaleTown项目文档的重要更新和修改。
+
+## 版本 1.1.0 (2025-12-31)
+
+### 🆕 新增内容
+- **新增**: `_Core/EventNames.gd` - 统一管理所有事件名称常量
+- **新增**: `_Core/ProjectPaths.gd` - 统一管理项目路径配置
+- **新增**: 输入映射配置到 `project.godot`
+- **新增**: 文档更新日志 `docs/CHANGELOG.md`
+
+### 🔧 修复问题
+- **修复**: 架构与通信规范中AutoLoad单例数量描述（从3个更新为5个）
+- **修复**: 网络管理器设置文档中的路径错误（`core/` → `_Core/`）
+- **修复**: Web部署指南中的资源路径（`assets/web/` → `web_assets/`）
+- **修复**: 场景设计规范中的目录结构（`prefabs/` → `Components/`）
+- **修复**: 性能优化指南中的预制体路径
+- **修复**: 模块开发指南中的测试基类路径（使用 `GutTest` 而非完整路径）
+
+### 📝 内容优化
+- **优化**: 场景命名规范，与实际项目结构保持一致
+- **优化**: 所有文档中的路径引用，使用 `ProjectPaths` 统一管理
+- **优化**: 代码示例的准确性和可用性
+
+### 🎯 质量提升
+- **提升**: 文档与实际代码的匹配度
+- **提升**: 路径配置的一致性和可维护性
+- **提升**: 开发者体验和文档可用性
+
+## 版本 1.0.0 (2025-12-24)
+
+### 📚 初始文档结构
+- **01-项目入门**: 项目介绍、结构说明、设置指南
+- **02-开发规范**: 命名规范、注释规范、Git提交规范、架构规范、开发哲学
+- **03-技术实现**: 实现细节、API文档、网络管理器、测试指南
+- **04-高级开发**: 场景设计、模块开发、性能优化
+- **05-部署运维**: Web部署指南
+- **06-功能模块**: 认证模块相关文档
+
+### 🏗️ 核心特性
+- 完整的开发规范体系
+- 详细的技术实现指导
+- 全面的测试和部署流程
+- 模块化的功能开发指南
+
+---
+
+## 维护说明
+
+### 文档更新原则
+1. **同步更新**: 代码变更时同步更新相关文档
+2. **版本记录**: 重要更新需要在此日志中记录
+3. **向后兼容**: 尽量保持API和配置的向后兼容性
+4. **质量保证**: 确保文档内容的准确性和可用性
+
+### 贡献指南
+- 发现文档问题请及时反馈
+- 提交文档更新时请更新此日志
+- 重大变更需要团队讨论确认
+
+### 相关链接
+- [项目结构说明](01-项目入门/项目结构说明.md)
+- [开发规范总览](02-开发规范/README.md)
+- [技术实现指南](03-技术实现/README.md)

docs/CONTRIBUTORS.md

@@ -0,0 +1,122 @@
+# 🤝 项目贡献者
+
+感谢所有为WhaleTown项目做出贡献的开发者！
+
+## 🏆 核心贡献者
+
+### 主要开发者
+
+#### 王浩
+- **贡献数量**: 3+ commits  
+- **主要贡献**:
+  - 🏗️ 项目架构分层结构重构
+  - 📚 AI开发规范文档制定
+  - 📖 项目开发规范文档完善
+
+#### moyin
+- **贡献数量**: 35+ commits
+- **主要贡献**:
+  - 🔧 项目功能开发和实现
+  - 📝 文档内容编写和维护
+  - 🧪 测试用例开发和验证
+  - 🌐 网络系统和部署配置
+
+## 📊 贡献统计
+
+### 按贡献类型
+
+| 贡献类型 | 主要贡献者 | 说明 |
+|----------|------------|------|
+| **架构设计** | 王浩, moyin | 分层结构重构，模块化架构 |
+| **开发规范** | 王浩 | AI开发规范、编码标准 |
+| **文档建设** | moyin, 王浩 | 18个完整文档，覆盖全开发流程 |
+| **网络系统** | moyin | NetworkManager、API集成 |
+| **测试框架** | moyin | API测试、UI测试、性能测试 |
+| **认证系统** | moyin | 用户认证流程实现 |
+| **部署系统** | moyin | Web部署、自动化脚本 |
+
+### 按时间线
+
+#### 2024年12月
+- **架构重构**: 王浩 实施分层架构重构
+- **规范制定**: 王浩 制定AI开发规范
+- **项目开发**: moyin 完成主要功能开发
+- **文档建设**: moyin, 王浩 建设文档系统
+- **测试集成**: moyin 完成API集成和测试
+
+## 🌟 贡献亮点
+
+### 🏗️ 架构设计
+- **分层结构**: 清晰的代码组织和职责分离
+- **模块化架构**: 高度解耦的组件系统
+- **事件驱动**: 基于EventSystem的通信机制
+
+### 📚 文档建设
+- **企业级文档**: 18个完整文档，100%覆盖
+- **分类组织**: 按开发阶段精心分类
+- **实用导向**: 大量可直接使用的代码模板
+
+### 🎯 开发规范
+- **AI开发规范**: AI辅助开发的最佳实践
+- **编码标准**: 统一的命名规范和代码风格
+- **质量保证**: 完善的代码审查流程
+
+### 🧪 测试体系
+- **多层测试**: API、UI、单元、集成测试
+- **自动化**: Python测试脚本和Godot测试场景
+- **完整覆盖**: 17个API接口全覆盖
+
+### 🌐 部署系统
+- **一键部署**: 自动化Web部署脚本
+- **跨平台**: 支持Windows、Linux、macOS
+- **配置完善**: 详细的服务器配置指南
+
+## 🎯 特别感谢
+
+### 技术贡献
+- **王浩**: 负责架构重构和开发规范制定
+- **moyin**: 负责主要功能开发和文档编写
+
+### 架构贡献
+- **分层结构**: 提升了项目的代码组织和可维护性
+- **模块化设计**: 为项目扩展奠定了良好基础
+- **开发规范**: 统一了团队的开发标准
+
+## 🚀 如何成为贡献者
+
+### 贡献方式
+1. **🐛 Bug修复** - 发现并修复问题
+2. **✨ 新功能** - 添加有价值的功能
+3. **📚 文档改进** - 完善项目文档
+4. **🧪 测试用例** - 提高代码覆盖率
+5. **🎨 UI/UX改进** - 提升用户体验
+6. **⚡ 性能优化** - 优化游戏性能
+
+### 贡献流程
+1. Fork项目到你的账户
+2. 创建功能分支：`git checkout -b feature/your-feature`
+3. 遵循项目规范开发
+4. 添加测试用例
+5. 提交代码：`git commit -m "feat：添加新功能"`
+6. 创建Pull Request
+
+### 规范要求
+- 遵循[命名规范](02-开发规范/命名规范.md)
+- 遵循[Git提交规范](02-开发规范/Git提交规范.md)
+- 遵循[代码注释规范](02-开发规范/代码注释规范.md)
+- 添加相应的测试用例
+- 更新相关文档
+
+## 📞 联系方式
+
+如果你想参与贡献或有任何问题：
+
+- **项目地址**: [Gitea Repository](https://gitea.xinghangee.icu/datawhale/whale-town)
+- **问题反馈**: [Issues](https://gitea.xinghangee.icu/datawhale/whale-town/issues)
+- **功能建议**: [Discussions](https://gitea.xinghangee.icu/datawhale/whale-town/discussions)
+
+---
+
+**感谢所有贡献者的辛勤付出！每个人的贡献都让WhaleTown项目变得更好。** 🙏
+
+*最后更新: 2025-12-31*

docs/README.md

@@ -0,0 +1,310 @@
+# 📚 WhaleTown 项目文档中心
+
+欢迎来到WhaleTown项目文档中心！这是一个完整的企业级文档系统，按开发阶段精心组织，帮助你快速找到所需的技术指导。
+
+## 🎯 文档特色
+
+- **📋 完整覆盖**: 从项目入门到部署运维的全生命周期
+- **🎨 结构清晰**: 按开发阶段和角色需求分类组织
+- **💻 实用导向**: 提供大量可直接使用的代码模板和配置示例
+- **🔄 持续更新**: 与项目代码保持同步，确保文档准确性
+- **🧪 测试完备**: 包含详细的测试指南和用例
+
+## 🗂️ 文档结构
+
+```
+docs/
+├── 📖 README.md                    # 本导航文档
+├── 📋 CHANGELOG.md                 # 文档更新日志
+├── 📁 01-项目入门/                  # 新人必读，项目基础
+├── 📁 02-开发规范/                  # 编码标准和规范
+├── 📁 03-技术实现/                  # 具体开发指导
+├── 📁 04-高级开发/                  # 进阶开发技巧
+├── 📁 05-部署运维/                  # 发布和部署
+└── 📁 06-功能模块/                  # 特定功能文档
+```
+
+## 📊 文档质量等级
+
+| 等级 | 说明 | 标识 |
+|------|------|------|
+| A级 | 企业级标准，内容完整准确 | ⭐⭐⭐⭐⭐ |
+| B级 | 内容详实，偶有更新需求 | ⭐⭐⭐⭐ |
+| C级 | 基础完备，持续完善中 | ⭐⭐⭐ |
+
+**当前整体质量**: **A级** ✨
+
+---
+
+## 🚀 快速开始指南
+
+### 👋 我是新人，从哪里开始？
+**推荐阅读顺序：**
+1. [项目入门总览](01-项目入门/README.md) - 快速了解项目
+2. [项目结构说明](01-项目入门/项目结构说明.md) - 深入了解项目架构
+3. [项目设置指南](01-项目入门/项目设置指南.md) - 配置开发环境
+4. [命名规范](02-开发规范/命名规范.md) - 学习编码规范
+
+### 💻 我要开始编码了
+**必读文档：**
+- [架构与通信规范](02-开发规范/架构与通信规范.md) - 组件通信方式 ⭐⭐⭐⭐⭐
+- [实现细节规范](03-技术实现/实现细节规范.md) - 具体实现要求 ⭐⭐⭐⭐⭐
+- [开发哲学与最佳实践](02-开发规范/开发哲学与最佳实践.md) - 代码质量标准 ⭐⭐⭐⭐
+
+### 🔧 我需要集成API
+**相关文档：**
+- [API接口文档](03-技术实现/API接口文档.md) - 完整的接口说明 ⭐⭐⭐⭐⭐
+- [网络管理器设置](03-技术实现/网络管理器设置.md) - 网络配置指南 ⭐⭐⭐⭐
+- [测试指南](03-技术实现/测试指南.md) - API测试方法 ⭐⭐⭐⭐
+
+### 🚀 我要发布项目
+**部署文档：**
+- [Web部署指南](05-部署运维/Web部署指南.md) - 完整的Web版本发布流程 ⭐⭐⭐⭐
+
+### 🔍 我需要调试和优化
+**高级文档：**
+- [性能优化指南](04-高级开发/性能优化指南.md) - 全面的性能优化策略 ⭐⭐⭐⭐⭐
+- [场景设计规范](04-高级开发/场景设计规范.md) - 场景架构最佳实践 ⭐⭐⭐⭐
+
+---
+
+## 📁 详细目录
+
+### 01-项目入门 📖
+> **适用人群**: 新加入项目的开发者  
+> **使用时机**: 项目开始前，环境搭建阶段  
+> **质量等级**: A级 ⭐⭐⭐⭐⭐
+
+| 文档 | 用途 | 重要程度 | 更新状态 |
+|------|------|----------|----------|
+| [README.md](01-项目入门/README.md) | 项目入门总览和快速导航 | ⭐⭐⭐⭐⭐ | ✅ 最新 |
+| [项目结构说明.md](01-项目入门/项目结构说明.md) | 了解项目整体架构和目录组织 | ⭐⭐⭐⭐⭐ | ✅ 最新 |
+| [项目设置指南.md](01-项目入门/项目设置指南.md) | Godot项目配置和AutoLoad设置 | ⭐⭐⭐⭐⭐ | ✅ 最新 |
+
+### 02-开发规范 📋
+> **适用人群**: 所有开发者  
+> **使用时机**: 编码过程中，代码审查时  
+> **质量等级**: A级 ⭐⭐⭐⭐⭐
+
+| 文档 | 用途 | 重要程度 | 更新状态 |
+|------|------|----------|----------|
+| [命名规范.md](02-开发规范/命名规范.md) | 统一的命名标准，包含完整示例 | ⭐⭐⭐⭐⭐ | ✅ 最新 |
+| [代码注释规范.md](02-开发规范/代码注释规范.md) | 注释格式和AI辅助注释指南 | ⭐⭐⭐⭐ | ✅ 最新 |
+| [Git提交规范.md](02-开发规范/Git提交规范.md) | 版本控制规范和最佳实践 | ⭐⭐⭐⭐ | ✅ 最新 |
+| [架构与通信规范.md](02-开发规范/架构与通信规范.md) | 事件系统和组件通信标准 | ⭐⭐⭐⭐⭐ | ✅ 最新 |
+| [开发哲学与最佳实践.md](02-开发规范/开发哲学与最佳实践.md) | 代码质量和开发理念 | ⭐⭐⭐⭐ | ✅ 最新 |
+
+### 03-技术实现 🔧
+> **适用人群**: 正在开发功能的程序员  
+> **使用时机**: 具体功能开发时  
+> **质量等级**: A级 ⭐⭐⭐⭐⭐
+
+| 文档 | 用途 | 重要程度 | 更新状态 |
+|------|------|----------|----------|
+| [实现细节规范.md](03-技术实现/实现细节规范.md) | 游戏对象具体实现要求和模板 | ⭐⭐⭐⭐⭐ | ✅ 最新 |
+| [API接口文档.md](03-技术实现/API接口文档.md) | 完整的后端接口说明和测试用例 | ⭐⭐⭐⭐⭐ | ✅ 最新 |
+| [网络管理器设置.md](03-技术实现/网络管理器设置.md) | 网络通信配置和使用指南 | ⭐⭐⭐⭐ | ✅ 最新 |
+| [测试指南.md](03-技术实现/测试指南.md) | 多种测试方法和工具使用 | ⭐⭐⭐⭐ | ✅ 最新 |
+
+### 04-高级开发 🚀
+> **适用人群**: 有经验的开发者，架构师  
+> **使用时机**: 复杂功能开发，性能优化时  
+> **质量等级**: A级 ⭐⭐⭐⭐⭐
+
+| 文档 | 用途 | 重要程度 | 更新状态 |
+|------|------|----------|----------|
+| [场景设计规范.md](04-高级开发/场景设计规范.md) | 场景架构和设计标准，包含完整模板 | ⭐⭐⭐⭐ | ✅ 最新 |
+| [模块开发指南.md](04-高级开发/模块开发指南.md) | 创建可复用模块的完整流程 | ⭐⭐⭐⭐ | ✅ 最新 |
+| [性能优化指南.md](04-高级开发/性能优化指南.md) | 全面的游戏性能优化策略 | ⭐⭐⭐⭐⭐ | ✅ 最新 |
+
+### 05-部署运维 🌐
+> **适用人群**: DevOps工程师，项目负责人  
+> **使用时机**: 项目发布，部署配置时  
+> **质量等级**: A级 ⭐⭐⭐⭐⭐
+
+| 文档 | 用途 | 重要程度 | 更新状态 |
+|------|------|----------|----------|
+| [Web部署指南.md](05-部署运维/Web部署指南.md) | 完整的Web版本导出和部署流程 | ⭐⭐⭐⭐⭐ | ✅ 最新 |
+
+### 06-功能模块 🎮
+> **适用人群**: 开发特定功能的程序员  
+> **使用时机**: 开发对应功能时  
+> **质量等级**: A级 ⭐⭐⭐⭐⭐
+
+| 目录/文档 | 用途 | 重要程度 | 更新状态 |
+|-----------|------|----------|----------|
+| [auth/](06-功能模块/auth/) | 用户认证系统完整文档 | ⭐⭐⭐⭐⭐ | ✅ 最新 |
+| └── [表单验证规范.md](06-功能模块/auth/表单验证规范.md) | 详细的表单验证规则和UI规范 | ⭐⭐⭐⭐ | ✅ 最新 |
+| └── [认证测试指南.md](06-功能模块/auth/认证测试指南.md) | 完整的认证功能测试用例 | ⭐⭐⭐⭐ | ✅ 最新 |
+
+---
+
+## 🎯 按角色推荐
+
+### 👨‍💻 前端开发者
+**学习路径**: 01-项目入门 → 02-开发规范 → 03-技术实现 → 06-功能模块  
+**核心文档**: 
+- [架构与通信规范](02-开发规范/架构与通信规范.md) - 掌握事件系统 ⭐⭐⭐⭐⭐
+- [实现细节规范](03-技术实现/实现细节规范.md) - 游戏对象实现 ⭐⭐⭐⭐⭐
+- [API接口文档](03-技术实现/API接口文档.md) - 后端接口调用 ⭐⭐⭐⭐⭐
+
+### 🏗️ 架构师/技术负责人
+**学习路径**: 01-项目入门 → 02-开发规范 → 04-高级开发 → 05-部署运维  
+**核心文档**: 
+- [开发哲学与最佳实践](02-开发规范/开发哲学与最佳实践.md) - 代码质量标准 ⭐⭐⭐⭐⭐
+- [场景设计规范](04-高级开发/场景设计规范.md) - 架构设计模式 ⭐⭐⭐⭐⭐
+- [性能优化指南](04-高级开发/性能优化指南.md) - 性能优化策略 ⭐⭐⭐⭐⭐
+
+### 🧪 测试工程师
+**学习路径**: 01-项目入门 → 03-技术实现/测试指南 → 06-功能模块  
+**核心文档**: 
+- [测试指南](03-技术实现/测试指南.md) - 测试方法和工具 ⭐⭐⭐⭐⭐
+- [认证测试指南](06-功能模块/auth/认证测试指南.md) - 功能测试用例 ⭐⭐⭐⭐
+
+### 🚀 DevOps工程师
+**学习路径**: 01-项目入门 → 05-部署运维 → 03-技术实现  
+**核心文档**: 
+- [Web部署指南](05-部署运维/Web部署指南.md) - 完整部署流程 ⭐⭐⭐⭐⭐
+- [项目设置指南](01-项目入门/项目设置指南.md) - 环境配置 ⭐⭐⭐⭐
+
+### 🎮 游戏设计师
+**学习路径**: 01-项目入门 → 04-高级开发/场景设计规范 → 06-功能模块  
+**核心文档**: 
+- [场景设计规范](04-高级开发/场景设计规范.md) - 场景设计标准 ⭐⭐⭐⭐⭐
+
+---
+
+## 🔍 快速查找
+
+### 按问题类型查找
+
+**🤔 "我不知道项目是怎么组织的"**
+→ [项目结构说明.md](01-项目入门/项目结构说明.md) - 完整的项目架构说明
+
+**🤔 "我不知道怎么配置开发环境"**
+→ [项目设置指南.md](01-项目入门/项目设置指南.md) - 详细的环境配置步骤
+
+**🤔 "我不知道怎么命名变量/函数"**
+→ [命名规范.md](02-开发规范/命名规范.md) - 统一的命名标准和示例
+
+**🤔 "我不知道怎么让组件之间通信"**
+→ [架构与通信规范.md](02-开发规范/架构与通信规范.md) - 事件系统使用指南
+
+**🤔 "我不知道怎么实现玩家/NPC"**
+→ [实现细节规范.md](03-技术实现/实现细节规范.md) - 游戏对象实现模板
+
+**🤔 "我不知道怎么调用API"**
+→ [API接口文档.md](03-技术实现/API接口文档.md) - 完整的接口说明和示例
+
+**🤔 "我不知道怎么测试功能"**
+→ [测试指南.md](03-技术实现/测试指南.md) - 多种测试方法和工具
+
+**🤔 "我不知道怎么优化性能"**
+→ [性能优化指南.md](04-高级开发/性能优化指南.md) - 全面的优化策略
+
+**🤔 "我不知道怎么发布项目"**
+→ [Web部署指南.md](05-部署运维/Web部署指南.md) - 完整的部署流程
+
+**🤔 "我不知道怎么开发模块"**
+→ [模块开发指南.md](04-高级开发/模块开发指南.md) - 模块化开发方法
+
+### 按开发阶段查找
+
+| 阶段 | 主要文档 | 说明 |
+|------|----------|------|
+| **项目启动** | 01-项目入门 | 环境搭建，项目了解 |
+| **需求分析** | 02-开发规范 | 规范制定，架构设计 |
+| **功能开发** | 03-技术实现 | 具体实现，API集成 |
+| **质量保证** | 03-技术实现/测试指南 | 测试验证，质量控制 |
+| **性能优化** | 04-高级开发 | 性能调优，架构优化 |
+| **项目发布** | 05-部署运维 | 部署配置，运维监控 |
+
+## 🛠️ 核心工具和配置
+
+### 已集成的核心组件
+- **EventSystem** - 全局事件通信系统 ([EventNames.gd](_Core/EventNames.gd))
+- **ProjectPaths** - 统一路径管理 ([ProjectPaths.gd](_Core/ProjectPaths.gd))
+- **NetworkManager** - 网络请求管理器
+- **ResponseHandler** - 统一响应处理器
+- **StringUtils** - 字符串工具类
+
+### 配置文件
+- **project.godot** - 项目配置，包含输入映射和AutoLoad设置
+- **Config/game_config.json** - 游戏配置文件
+- **web_assets/** - Web部署资源
+
+## 📈 文档统计
+
+| 类别 | 文档数量 | 完成度 | 质量等级 |
+|------|----------|--------|----------|
+| 项目入门 | 3 | 100% | A级 ⭐⭐⭐⭐⭐ |
+| 开发规范 | 5 | 100% | A级 ⭐⭐⭐⭐⭐ |
+| 技术实现 | 4 | 100% | A级 ⭐⭐⭐⭐⭐ |
+| 高级开发 | 3 | 100% | A级 ⭐⭐⭐⭐⭐ |
+| 部署运维 | 1 | 100% | A级 ⭐⭐⭐⭐⭐ |
+| 功能模块 | 2 | 100% | A级 ⭐⭐⭐⭐⭐ |
+| **总计** | **18** | **100%** | **A级** ⭐⭐⭐⭐⭐ |
+
+---
+
+## 📝 文档维护
+
+### 更新机制
+- **自动同步**: 代码变更时自动检查相关文档
+- **版本控制**: 重要更新记录在 [CHANGELOG.md](CHANGELOG.md)
+- **质量保证**: 定期校验文档与代码的一致性
+- **持续改进**: 根据用户反馈持续优化文档质量
+
+### 更新频率
+| 文档类别 | 更新触发条件 | 更新频率 |
+|----------|--------------|----------|
+| **01-项目入门** | 项目架构变更 | 按需更新 |
+| **02-开发规范** | 团队规范调整 | 季度评审 |
+| **03-技术实现** | API变更/新功能 | 实时更新 |
+| **04-高级开发** | 最佳实践演进 | 月度评审 |
+| **05-部署运维** | 部署流程变更 | 按需更新 |
+| **06-功能模块** | 功能开发完成 | 实时更新 |
+
+### 贡献指南
+如果你发现文档有问题或需要补充：
+
+1. **报告问题**: 创建Issue描述具体问题
+2. **提交改进**: 提交PR修改文档内容
+3. **遵循规范**: 按照[Git提交规范](02-开发规范/Git提交规范.md)提交
+4. **更新日志**: 重要变更需更新[CHANGELOG.md](CHANGELOG.md)
+
+### 文档质量标准
+- **准确性**: 与实际代码保持100%一致
+- **完整性**: 覆盖功能的完整生命周期
+- **实用性**: 提供可直接使用的代码示例
+- **可读性**: 结构清晰，表达简洁明了
+
+## 🎉 特别感谢
+
+感谢所有为WhaleTown项目文档贡献的开发者！
+
+### 文档贡献者
+- 项目架构设计和文档框架搭建
+- 开发规范制定和最佳实践总结
+- 技术实现指南和代码模板编写
+- 测试用例设计和质量保证
+
+### 持续改进
+我们致力于打造最好用的游戏开发文档系统，欢迎提供反馈和建议！
+
+---
+
+## 📞 获取帮助
+
+- **文档问题**: 查看 [CHANGELOG.md](CHANGELOG.md) 了解最新更新
+- **技术问题**: 参考对应的技术实现文档
+- **最佳实践**: 查阅开发规范和高级开发指南
+- **部署问题**: 参考部署运维文档
+
+**💡 提示**: 建议将本导航页面加入书签，方便随时查阅！
+
+---
+
+**文档版本**: v1.1.0  
+**最后更新**: 2025-12-31  
+**文档质量**: A级 ⭐⭐⭐⭐⭐

docs/api_update_log.md

@@ -1,332 +0,0 @@
-# API接口更新日志
-
-**更新日期**: 2025-12-25  
-**API版本**: v1.1.1  
-**更新内容**: 根据后端最新API文档更新前端接口逻辑和Toast显示
-
----
-
-## 🎯 更新概述
-
-根据后端API v1.1.1的最新文档，对前端的网络请求、响应处理和Toast显示系统进行了全面更新，以支持新的功能特性和错误处理机制。
-
----
-
-## 📋 主要更新内容
-
-### 1. **HTTP状态码支持**
-
-#### 新增状态码处理
-- **206 Partial Content**: 测试模式响应
-- **409 Conflict**: 资源冲突（用户名、邮箱已存在）
-- **429 Too Many Requests**: 频率限制
-
-#### 更新的状态码映射
-```gdscript
-const HTTP_STATUS_MESSAGES = {
-    200: "请求成功",
-    201: "创建成功", 
-    206: "测试模式",
-    400: "请求参数错误",
-    401: "认证失败",
-    403: "权限不足",
-    404: "资源不存在",
-    408: "请求超时",
-    409: "资源冲突",        # 新增
-    415: "不支持的媒体类型",
-    429: "请求过于频繁",    # 新增
-    500: "服务器内部错误",
-    503: "服务不可用"
-}
-```
-
-### 2. **错误码映射更新**
-
-#### 新增错误码
-- `SEND_EMAIL_VERIFICATION_FAILED`: 发送邮箱验证码失败
-- `RESEND_EMAIL_VERIFICATION_FAILED`: 重新发送验证码失败
-- `EMAIL_VERIFICATION_FAILED`: 邮箱验证失败
-- `RESET_PASSWORD_FAILED`: 重置密码失败
-- `CHANGE_PASSWORD_FAILED`: 修改密码失败
-- `USER_STATUS_UPDATE_FAILED`: 用户状态更新失败
-- `ADMIN_LOGIN_FAILED`: 管理员登录失败
-
-### 3. **邮箱冲突检测**
-
-#### 功能描述
-- 发送邮箱验证码前检查邮箱是否已被注册
-- 已注册邮箱返回409状态码和明确错误信息
-
-#### 实现细节
-```gdscript
-# 在ResponseHandler中处理409冲突
-if response_code == 409:
-    if "邮箱已存在" in message:
-        result.message = "📧 邮箱已被注册，请使用其他邮箱或直接登录"
-    elif "用户名已存在" in message:
-        result.message = "👤 用户名已被使用，请换一个"
-```
-
-### 4. **测试模式支持**
-
-#### 功能描述
-- 开发环境下邮件服务返回206状态码
-- 验证码在响应中返回，无需真实发送邮件
-
-#### 实现细节
-```gdscript
-# 处理206测试模式响应
-elif response_code == 206 and error_code == "TEST_MODE_ONLY":
-    is_success = true
-    print("🧪 测试模式响应: ", message)
-```
-
-#### Toast显示优化
-```gdscript
-if error_code == "TEST_MODE_ONLY":
-    result.message = "🧪 测试模式：验证码已生成，请查看控制台"
-    if data.has("data") and data.data.has("verification_code"):
-        print("🔑 测试模式验证码: ", data.data.verification_code)
-```
-
-### 5. **频率限制处理**
-
-#### 功能描述
-- 验证码发送限制1次/分钟
-- 注册限制10次/5分钟
-- 提供重试建议和详细错误信息
-
-#### 实现细节
-```gdscript
-"TOO_MANY_REQUESTS":
-    result.message = "⏰ 验证码发送过于频繁，请1分钟后再试"
-    # 显示详细的限制信息
-    if data.has("throttle_info"):
-        var throttle_info = data.throttle_info
-        var reset_time = throttle_info.get("reset_time", "")
-        if reset_time != "":
-            result.message += "\n重试时间: " + reset_time
-```
-
-### 6. **Toast显示系统优化**
-
-#### 视觉改进
-- 增加图标显示（✅成功，❌失败）
-- 更丰富的颜色和阴影效果
-- 支持智能换行和更大的显示区域
-- 更流畅的动画效果
-
-#### 新的Toast样式
-```gdscript
-# 更深的颜色和更好的对比度
-if is_success:
-    style.bg_color = Color(0.15, 0.7, 0.15, 0.95)  # 深绿色
-    style.border_color = Color(0.2, 0.9, 0.2, 0.9)  # 亮绿色边框
-else:
-    style.bg_color = Color(0.7, 0.15, 0.15, 0.95)  # 深红色
-    style.border_color = Color(0.9, 0.2, 0.2, 0.9)  # 亮红色边框
-
-# 添加阴影效果
-style.shadow_color = Color(0, 0, 0, 0.3)
-style.shadow_size = 4
-style.shadow_offset = Vector2(2, 2)
-```
-
-#### 动画优化
-- 增加透明度动画
-- 延长显示时间（2秒→3秒）
-- 更流畅的滑入滑出效果
-
-### 7. **新增API方法**
-
-#### NetworkManager新增方法
-```gdscript
-# 重新发送邮箱验证码
-func resend_email_verification(email: String, callback: Callable) -> String
-
-# 忘记密码 - 发送重置验证码
-func forgot_password(identifier: String, callback: Callable) -> String
-
-# 重置密码
-func reset_password(identifier: String, verification_code: String, new_password: String, callback: Callable) -> String
-
-# 修改密码
-func change_password(user_id: String, old_password: String, new_password: String, callback: Callable) -> String
-
-# GitHub OAuth登录
-func github_login(github_id: String, username: String, nickname: String, email: String, avatar_url: String, callback: Callable) -> String
-```
-
-#### ResponseHandler新增处理方法
-```gdscript
-# 处理重新发送邮箱验证码响应
-static func handle_resend_email_verification_response(success: bool, data: Dictionary, error_info: Dictionary) -> ResponseResult
-
-# 处理忘记密码响应
-static func handle_forgot_password_response(success: bool, data: Dictionary, error_info: Dictionary) -> ResponseResult
-
-# 处理重置密码响应
-static func handle_reset_password_response(success: bool, data: Dictionary, error_info: Dictionary) -> ResponseResult
-```
-
----
-
-## 🔧 技术改进
-
-### 1. **响应处理逻辑优化**
-
-#### 更精确的成功判断
-```gdscript
-# HTTP成功状态码且业务成功
-if (response_code >= 200 and response_code < 300) and success:
-    is_success = true
-# 特殊情况：206测试模式
-elif response_code == 206 and error_code == "TEST_MODE_ONLY":
-    is_success = true
-# 201创建成功
-elif response_code == 201:
-    is_success = true
-```
-
-#### 更详细的错误类型判断
-```gdscript
-match response_code:
-    409:  # 资源冲突
-        return ErrorType.BUSINESS_ERROR
-    206:  # 测试模式
-        return ErrorType.BUSINESS_ERROR
-    429:  # 频率限制
-        return ErrorType.BUSINESS_ERROR
-```
-
-### 2. **错误消息国际化**
-
-#### 添加表情符号和更友好的提示
-- 📧 邮箱相关消息
-- 👤 用户相关消息
-- 🔑 验证码相关消息
-- 🔒 密码相关消息
-- ⏰ 时间相关消息
-- 🧪 测试模式消息
-- 🌐 网络相关消息
-
-### 3. **代码结构优化**
-
-#### 更好的模块化
-- 分离不同类型的错误处理方法
-- 统一的响应处理接口
-- 更清晰的方法命名
-
-#### 更完善的注释
-- 详细的方法说明
-- 参数和返回值说明
-- 使用示例
-
----
-
-## 🧪 测试验证
-
-### 创建了API测试脚本
-- **文件**: `scripts/network/ApiTestScript.gd`
-- **功能**: 验证所有更新的API接口逻辑
-- **测试用例**: 
-  - 网络连接测试
-  - 邮箱验证码发送
-  - 邮箱冲突检测
-  - 登录功能
-  - 注册功能
-
-### 测试覆盖的场景
-- ✅ 正常成功响应
-- ✅ 409邮箱冲突
-- ✅ 206测试模式
-- ✅ 429频率限制
-- ✅ 各种错误状态码
-- ✅ Toast显示效果
-
----
-
-## 📚 使用指南
-
-### 1. **发送邮箱验证码**
-```gdscript
-# 会自动检查邮箱冲突
-var request_id = NetworkManager.send_email_verification("user@example.com", callback)
-```
-
-### 2. **处理409冲突**
-```gdscript
-func callback(success: bool, data: Dictionary, error_info: Dictionary):
-    var result = ResponseHandler.handle_send_verification_code_response(success, data, error_info)
-    if error_info.get("response_code") == 409:
-        # 邮箱已存在，引导用户登录
-        show_login_suggestion()
-```
-
-### 3. **处理测试模式**
-```gdscript
-# 测试模式下验证码会在控制台显示
-if data.get("error_code") == "TEST_MODE_ONLY":
-    var verification_code = data.data.verification_code
-    print("测试验证码: ", verification_code)
-```
-
-### 4. **处理频率限制**
-```gdscript
-# 提供重试建议
-if error_info.get("response_code") == 429:
-    show_retry_suggestion(data.get("throttle_info", {}))
-```
-
----
-
-## 🔄 向后兼容性
-
-### 保持的兼容性
-- ✅ 现有的API调用方式不变
-- ✅ 现有的回调函数签名不变
-- ✅ 现有的Toast显示接口不变
-
-### 新增的功能
-- ✅ 更丰富的错误处理
-- ✅ 更好的用户体验
-- ✅ 更详细的状态反馈
-
----
-
-## 📝 注意事项
-
-### 开发环境
-- 测试模式下验证码会在控制台显示
-- 206状态码表示测试模式，属于成功响应
-- 建议在开发时关注控制台输出
-
-### 生产环境
-- 验证码通过真实邮件发送
-- 需要正确配置邮件服务
-- 频率限制会严格执行
-
-### 错误处理
-- 优先检查HTTP状态码
-- 再检查业务错误码
-- 提供用户友好的错误提示
-
----
-
-## 🚀 后续计划
-
-### 短期优化
-- [ ] 添加更多的API接口支持
-- [ ] 优化Toast显示的动画效果
-- [ ] 添加音效反馈
-
-### 长期规划
-- [ ] 支持多语言错误消息
-- [ ] 添加离线模式支持
-- [ ] 实现请求重试机制
-
----
-
-**更新完成时间**: 2025-12-25  
-**测试状态**: ✅ 已通过基础测试  
-**部署建议**: 建议在测试环境充分验证后再部署到生产环境

docs/cleanup_summary.md

@@ -1,137 +0,0 @@
-# AuthScene 文件清理总结
-
-**清理日期**: 2025-12-25  
-**清理原因**: 修复Parser Error和优化代码结构
-
----
-
-## 🔧 修复的问题
-
-### 1. **Parser Error修复**
-- **问题**: `scripts/scenes/AuthScene.gd` 第1196行有语法错误 "母和数字"
-- **解决**: 完全重写了AuthScene.gd文件，移除了所有语法错误
-- **结果**: 文件现在可以正常解析，无语法错误
-
-### 2. **代码结构优化**
-- **重构验证逻辑**: 使用StringUtils工具类统一处理验证
-- **简化代码**: 移除重复的验证代码
-- **提高可维护性**: 更清晰的方法组织和注释
-
----
-
-## 🗑️ 删除的文件
-
-### 已删除
-1. **`scripts/network/NetworkTest.gd`**
-   - **原因**: 功能重复，已有更完善的ApiTestScript.gd
-   - **影响**: 无，功能已被ApiTestScript.gd替代
-
-### 保留的文件
-1. **`tests/auth/auth_ui_test.gd`** - 保留，用于UI测试
-2. **`tests/auth/enhanced_toast_test.gd`** - 保留，用于Toast系统测试
-3. **`core/utils/StringUtils.gd`** - 保留，提供通用验证工具
-
----
-
-## ✅ 优化后的AuthScene.gd结构
-
-### 文件组织
-```
-AuthScene.gd (约600行，结构清晰)
-├── 节点引用和变量定义
-├── 初始化和信号连接
-├── 按钮事件处理
-├── 网络响应处理
-├── 验证码冷却管理
-├── Toast消息系统
-├── UI工具方法
-├── 表单验证方法
-├── 表单验证事件
-└── 资源清理
-```
-
-### 主要改进
-1. **使用StringUtils**: 统一的验证逻辑
-2. **清晰的方法分组**: 按功能组织代码
-3. **完整的错误处理**: 支持最新API v1.1.1
-4. **优化的Toast系统**: 更好的视觉效果和动画
-
----
-
-## 🧪 测试验证
-
-### 语法检查
-```bash
-# 所有文件通过语法检查
-✅ scripts/scenes/AuthScene.gd - No diagnostics found
-✅ core/managers/NetworkManager.gd - No diagnostics found  
-✅ core/managers/ResponseHandler.gd - No diagnostics found
-```
-
-### 功能测试
-- ✅ Toast显示系统正常
-- ✅ 表单验证逻辑正确
-- ✅ 网络请求处理完整
-- ✅ 验证码冷却机制有效
-
----
-
-## 📊 代码质量提升
-
-### 前后对比
-| 指标 | 清理前 | 清理后 | 改进 |
-|------|--------|--------|------|
-| 语法错误 | 1个 | 0个 | ✅ 修复 |
-| 代码行数 | ~1400行 | ~600行 | ✅ 精简57% |
-| 重复代码 | 多处 | 无 | ✅ 消除 |
-| 可读性 | 中等 | 高 | ✅ 提升 |
-| 维护性 | 中等 | 高 | ✅ 提升 |
-
-### 代码质量指标
-- **圈复杂度**: 降低
-- **代码重复率**: 显著减少
-- **方法长度**: 更合理
-- **注释覆盖**: 完整
-
----
-
-## 🔄 兼容性保证
-
-### API兼容性
-- ✅ 保持所有公共方法签名不变
-- ✅ 保持所有信号定义不变
-- ✅ 保持节点引用路径不变
-
-### 功能兼容性
-- ✅ 登录功能完整
-- ✅ 注册功能完整
-- ✅ 验证码功能完整
-- ✅ Toast显示功能增强
-
----
-
-## 📝 后续建议
-
-### 短期
-1. **测试验证**: 在实际环境中测试所有功能
-2. **性能监控**: 观察Toast动画性能
-3. **用户反馈**: 收集UI体验反馈
-
-### 长期
-1. **单元测试**: 为验证逻辑添加更多单元测试
-2. **集成测试**: 完善端到端测试覆盖
-3. **代码审查**: 定期进行代码质量审查
-
----
-
-## 🎯 总结
-
-通过这次清理，我们成功：
-
-1. **修复了语法错误** - AuthScene.gd现在可以正常解析
-2. **优化了代码结构** - 更清晰、更易维护
-3. **提升了代码质量** - 减少重复，提高可读性
-4. **保持了功能完整** - 所有原有功能都得到保留和增强
-5. **删除了冗余文件** - 清理了不必要的测试文件
-
-AuthScene现在是一个干净、高效、易维护的认证界面组件，完全支持最新的API v1.1.1规范。

docs/final_update_summary.md

@@ -1,251 +0,0 @@
-# 最终更新总结
-
-**完成日期**: 2025-12-25  
-**更新内容**: AuthScene文件修复 + Python API测试工具
-
----
-
-## 🎯 完成的工作
-
-### 1. ✅ AuthScene.gd 文件修复
-
-#### 问题解决
-- **修复Parser Error**: 删除了第1196行的语法错误"母和数字"
-- **重构代码结构**: 完全重写了AuthScene.gd，代码更清晰、更易维护
-- **优化验证逻辑**: 使用StringUtils工具类统一处理表单验证
-
-#### 文件状态
-- **语法检查**: ✅ No diagnostics found
-- **代码行数**: 约600行（原来~1400行，精简57%）
-- **功能完整性**: ✅ 保持所有原有功能
-- **API兼容性**: ✅ 完全支持API v1.1.1
-
-### 2. ✅ Python API测试工具
-
-#### 创建的测试脚本
-1. **`quick_test.py`** - 快速测试脚本（推荐日常使用）
-2. **`api_client_test.py`** - 完整测试套件（全面功能验证）
-3. **`requirements.txt`** - Python依赖配置
-4. **`run_tests.bat`** - Windows批处理脚本
-5. **`run_tests.sh`** - Linux/Mac Shell脚本
-
-#### 测试覆盖范围
-- ✅ 应用状态检查
-- ✅ 用户认证流程（登录/注册）
-- ✅ 邮箱验证流程
-- ✅ 验证码功能（发送/验证）
-- ✅ 密码重置流程
-- ✅ 错误场景测试
-- ✅ 频率限制测试
-- ✅ API v1.1.1新特性测试
-
-### 3. ✅ 文档更新
-
-#### 新增文档
-- **`docs/testing_guide.md`** - 完整的API测试指南
-- **`docs/final_update_summary.md`** - 本总结文档
-- **`tests/api/README.md`** - 更新了测试说明
-
-#### 更新文档
-- **`docs/api_update_log.md`** - API更新日志
-- **`docs/cleanup_summary.md`** - 代码清理总结
-
----
-
-## 🔧 技术改进
-
-### AuthScene.gd 优化
-```gdscript
-# 优化前的问题
-- 语法错误导致无法解析
-- 代码重复，维护困难
-- 验证逻辑分散
-
-# 优化后的改进
-- 无语法错误，结构清晰
-- 使用StringUtils统一验证
-- 方法分组，易于维护
-```
-
-### API测试工具特性
-```python
-# 完整的API客户端
-class APIClient:
-    - 统一的请求处理
-    - 详细的错误处理
-    - 支持所有API端点
-    - 自动状态码判断
-
-# 智能测试结果
-class TestResult:
-    - 成功/失败判断
-    - 执行时间统计
-    - 详细错误信息
-    - 特殊状态码处理
-```
-
----
-
-## 📊 测试验证
-
-### 语法检查结果
-```bash
-✅ scripts/scenes/AuthScene.gd - No diagnostics found
-✅ core/managers/NetworkManager.gd - No diagnostics found  
-✅ core/managers/ResponseHandler.gd - No diagnostics found
-```
-
-### Python测试工具验证
-```bash
-# 快速测试
-python tests/api/quick_test.py
-# 预期结果: 6个基础API测试通过
-
-# 完整测试
-python tests/api/api_client_test.py  
-# 预期结果: 完整业务流程测试通过
-```
-
----
-
-## 🎯 使用指南
-
-### 开发者日常使用
-
-#### 1. 快速API测试
-```bash
-cd tests/api
-python quick_test.py
-```
-
-#### 2. 完整功能验证
-```bash
-cd tests/api
-python api_client_test.py
-```
-
-#### 3. Windows用户
-```bash
-cd tests/api
-run_tests.bat
-```
-
-#### 4. Linux/Mac用户
-```bash
-cd tests/api
-./run_tests.sh
-```
-
-### Godot开发者使用
-
-#### 1. 运行AuthScene
-- 场景文件正常加载
-- Toast系统正常工作
-- 网络请求正常处理
-
-#### 2. API测试脚本
-```gdscript
-# 在Godot中运行
-var api_test = preload("res://scripts/network/ApiTestScript.gd").new()
-add_child(api_test)
-```
-
----
-
-## 🔍 质量保证
-
-### 代码质量指标
-| 指标 | 修复前 | 修复后 | 改进 |
-|------|--------|--------|------|
-| 语法错误 | 1个 | 0个 | ✅ 完全修复 |
-| 代码行数 | ~1400行 | ~600行 | ✅ 精简57% |
-| 重复代码 | 多处 | 无 | ✅ 完全消除 |
-| 可维护性 | 中等 | 高 | ✅ 显著提升 |
-
-### 功能完整性
-- ✅ 登录功能完整保留
-- ✅ 注册功能完整保留  
-- ✅ 验证码功能完整保留
-- ✅ Toast显示功能增强
-- ✅ 错误处理功能增强
-
-### API兼容性
-- ✅ 支持409冲突检测
-- ✅ 支持206测试模式
-- ✅ 支持429频率限制
-- ✅ 支持所有新增错误码
-- ✅ 向后兼容旧版本
-
----
-
-## 📈 项目收益
-
-### 开发效率提升
-1. **无需Godot引擎**: Python测试脚本可独立运行
-2. **快速验证**: 30秒内完成基础API测试
-3. **自动化支持**: 可集成到CI/CD流程
-4. **跨平台支持**: Windows/Linux/Mac都可使用
-
-### 代码质量提升
-1. **消除语法错误**: AuthScene.gd现在完全可用
-2. **减少代码重复**: 使用工具类统一处理
-3. **提高可维护性**: 清晰的代码结构和注释
-4. **增强错误处理**: 支持最新API规范
-
-### 测试覆盖提升
-1. **完整业务流程**: 覆盖所有用户操作场景
-2. **错误场景测试**: 验证各种异常情况
-3. **性能测试**: 包含频率限制测试
-4. **兼容性测试**: 支持不同环境测试
-
----
-
-## 🚀 后续建议
-
-### 短期优化
-1. **集成CI/CD**: 将Python测试脚本集成到自动化流程
-2. **监控告警**: 设置API测试失败的通知机制
-3. **性能基准**: 建立API响应时间基准线
-
-### 长期规划
-1. **测试扩展**: 添加更多边界条件测试
-2. **压力测试**: 开发高并发场景测试
-3. **安全测试**: 添加安全漏洞检测测试
-
----
-
-## 📚 相关资源
-
-### 文档链接
-- [API文档](api-documentation.md) - 完整API接口说明
-- [测试指南](testing_guide.md) - 详细测试使用指南
-- [API更新日志](api_update_log.md) - 最新变更记录
-
-### 代码文件
-- `scripts/scenes/AuthScene.gd` - 修复后的认证场景
-- `tests/api/quick_test.py` - 快速API测试脚本
-- `tests/api/api_client_test.py` - 完整API测试套件
-
-### 工具脚本
-- `tests/api/run_tests.bat` - Windows测试启动器
-- `tests/api/run_tests.sh` - Linux/Mac测试启动器
-
----
-
-## 🎉 总结
-
-通过这次更新，我们成功：
-
-1. **修复了关键问题** - AuthScene.gd的Parser Error已完全解决
-2. **提升了代码质量** - 代码更清晰、更易维护、更高效
-3. **增强了测试能力** - 提供了完整的Python API测试工具
-4. **改善了开发体验** - 无需Godot引擎即可测试API接口
-5. **保证了向后兼容** - 所有原有功能都得到保留和增强
-
-现在开发者可以：
-- ✅ 正常使用AuthScene.gd进行认证界面开发
-- ✅ 使用Python脚本快速验证API接口
-- ✅ 在任何环境下进行API测试
-- ✅ 享受更好的错误处理和用户体验
-
-**项目现在处于完全可用状态，支持最新的API v1.1.1规范！** 🚀

docs/project_structure.md

@@ -1,505 +0,0 @@
-# Godot 项目结构说明
-
-本文档详细说明了 whaleTown 项目的文件结构设计，采用"场景+通用工具+其他"的架构模式，确保每个场景清晰独立且高度解耦。
-
-## 设计理念
-
-### 核心原则
-- **场景独立性**：每个场景都是独立的功能模块，可以单独开发和测试
-- **高度解耦**：场景之间通过事件系统和管理器进行通信，避免直接依赖
-- **组件复用**：可复用的组件放在通用模块中，提高开发效率
-- **资源管理**：统一的资源管理和命名规范，便于维护
-
-## 项目架构概览
-
-```
-whaleTown/
-├── 🎬 scenes/           # 场景层：独立的游戏场景
-├── 🔧 core/             # 核心层：通用工具和系统
-├── 🎨 assets/           # 资源层：静态资源文件
-├── 📊 data/             # 数据层：配置和游戏数据
-├── 📝 scripts/          # 脚本层：业务逻辑代码
-├── 🧩 module/           # 模块层：可复用组件
-├── 🧪 tests/            # 测试层：单元测试和集成测试
-└── 📚 docs/             # 文档层：项目文档
-```
-
-## 1. 场景层 (scenes/)
-
-场景层包含所有独立的游戏场景，每个场景都是完整的功能模块。
-
-### 1.1 场景分类
-
-#### 主要场景 (Main Scenes)
-```
-scenes/
-├── main_scene.tscn          # 主场景：游戏入口
-├── auth_scene.tscn          # 认证场景：登录注册
-├── menu_scene.tscn          # 菜单场景：主菜单界面
-├── game_scene.tscn          # 游戏场景：主要游戏玩法
-├── battle_scene.tscn        # 战斗场景：战斗系统
-├── inventory_scene.tscn     # 背包场景：物品管理
-├── shop_scene.tscn          # 商店场景：购买系统
-└── settings_scene.tscn      # 设置场景：游戏设置
-```
-
-#### 预制体场景 (Prefabs)
-```
-scenes/prefabs/
-├── ui/
-│   ├── dialog_prefab.tscn       # 对话框预制体
-│   ├── button_prefab.tscn       # 按钮预制体
-│   ├── health_bar_prefab.tscn   # 血条预制体
-│   └── notification_prefab.tscn # 通知预制体
-├── characters/
-│   ├── player_prefab.tscn       # 玩家角色预制体
-│   ├── npc_prefab.tscn          # NPC预制体
-│   └── enemy_prefab.tscn        # 敌人预制体
-├── items/
-│   ├── weapon_prefab.tscn       # 武器预制体
-│   ├── consumable_prefab.tscn   # 消耗品预制体
-│   └── collectible_prefab.tscn  # 收集品预制体
-└── effects/
-    ├── explosion_prefab.tscn    # 爆炸特效预制体
-    ├── particle_prefab.tscn     # 粒子特效预制体
-    └── damage_text_prefab.tscn  # 伤害数字预制体
-```
-
-### 1.2 场景设计原则
-
-- **单一职责**：每个场景只负责一个主要功能
-- **独立运行**：场景可以独立启动和测试
-- **标准接口**：场景间通过标准化接口通信
-- **资源隔离**：场景相关资源放在对应子目录
-## 2. 核心层 (core/)
-
-核心层提供通用的工具类、管理器和系统组件，为整个项目提供基础服务。
-
-### 2.1 核心系统结构
-
-```
-core/
-├── managers/                    # 管理器系统
-│   ├── GameManager.gd          # 游戏管理器：全局游戏状态
-│   ├── SceneManager.gd         # 场景管理器：场景切换
-│   ├── AudioManager.gd         # 音频管理器：音效音乐
-│   ├── InputManager.gd         # 输入管理器：输入处理
-│   ├── SaveManager.gd          # 存档管理器：数据存储
-│   ├── UIManager.gd            # UI管理器：界面管理
-│   └── NetworkManager.gd       # 网络管理器：网络通信
-├── systems/                     # 系统组件
-│   ├── EventSystem.gd          # 事件系统：全局事件
-│   ├── StateMachine.gd         # 状态机系统
-│   ├── ObjectPool.gd           # 对象池系统
-│   ├── ResourceLoader.gd       # 资源加载系统
-│   └── LocalizationSystem.gd   # 本地化系统
-├── utils/                       # 工具类
-│   ├── MathUtils.gd            # 数学工具
-│   ├── StringUtils.gd          # 字符串工具
-│   ├── FileUtils.gd            # 文件工具
-│   ├── TimeUtils.gd            # 时间工具
-│   └── DebugUtils.gd           # 调试工具
-├── components/                  # 通用组件
-│   ├── HealthComponent.gd      # 生命值组件
-│   ├── MovementComponent.gd    # 移动组件
-│   ├── AnimationComponent.gd   # 动画组件
-│   └── CollisionComponent.gd   # 碰撞组件
-└── interfaces/                  # 接口定义
-    ├── IInteractable.gd        # 可交互接口
-    ├── IDamageable.gd          # 可受伤接口
-    ├── ICollectable.gd         # 可收集接口
-    └── ISaveable.gd            # 可存储接口
-```
-
-### 2.2 核心系统职责
-
-#### 管理器 (Managers)
-- **单例模式**：全局唯一实例
-- **生命周期管理**：负责系统初始化和清理
-- **状态维护**：维护全局状态信息
-- **服务提供**：为其他模块提供服务
-
-#### 系统组件 (Systems)
-- **功能封装**：封装特定功能逻辑
-- **可插拔设计**：可以独立启用或禁用
-- **事件驱动**：通过事件系统通信
-- **性能优化**：提供高效的实现方案
-## 3. 模块层 (module/)
-
-模块层包含可复用的功能模块，这些模块可以在不同场景中重复使用。
-
-### 3.1 模块分类
-
-```
-module/
-├── UI/                          # UI模块
-│   ├── components/              # UI组件
-│   │   ├── Button/             # 按钮组件
-│   │   │   ├── CustomButton.gd
-│   │   │   └── custom_button.tscn
-│   │   ├── Dialog/             # 对话框组件
-│   │   │   ├── DialogBox.gd
-│   │   │   └── dialog_box.tscn
-│   │   ├── ProgressBar/        # 进度条组件
-│   │   │   ├── CustomProgressBar.gd
-│   │   │   └── custom_progress_bar.tscn
-│   │   └── InputField/         # 输入框组件
-│   │       ├── CustomInputField.gd
-│   │       └── custom_input_field.tscn
-│   ├── layouts/                # 布局组件
-│   │   ├── GridLayout.gd
-│   │   ├── FlexLayout.gd
-│   │   └── ResponsiveLayout.gd
-│   └── animations/             # UI动画
-│       ├── FadeTransition.gd
-│       ├── SlideTransition.gd
-│       └── ScaleTransition.gd
-├── Character/                   # 角色模块
-│   ├── Player/                 # 玩家角色
-│   │   ├── PlayerController.gd
-│   │   ├── PlayerStats.gd
-│   │   └── PlayerAnimator.gd
-│   ├── NPC/                    # NPC角色
-│   │   ├── NPCController.gd
-│   │   ├── NPCDialogue.gd
-│   │   └── NPCBehavior.gd
-│   └── Enemy/                  # 敌人角色
-│       ├── EnemyAI.gd
-│       ├── EnemyStats.gd
-│       └── EnemyBehavior.gd
-├── Inventory/                   # 背包模块
-│   ├── InventorySystem.gd
-│   ├── Item.gd
-│   ├── ItemSlot.gd
-│   └── ItemDatabase.gd
-├── Combat/                      # 战斗模块
-│   ├── CombatSystem.gd
-│   ├── Weapon.gd
-│   ├── Skill.gd
-│   └── DamageCalculator.gd
-└── Dialogue/                    # 对话模块
-    ├── DialogueSystem.gd
-    ├── DialogueNode.gd
-    ├── DialogueParser.gd
-    └── DialogueUI.gd
-```
-
-### 3.2 模块设计原则
-
-- **高内聚**：模块内部功能紧密相关
-- **低耦合**：模块间依赖最小化
-- **可配置**：通过配置文件自定义行为
-- **可扩展**：支持功能扩展和定制
-## 4. 资源层 (assets/)
-
-资源层统一管理所有静态资源文件，采用分类存储和标准化命名。
-
-### 4.1 资源目录结构
-
-```
-assets/
-├── sprites/                     # 精灵图资源
-│   ├── characters/             # 角色精灵
-│   │   ├── player/
-│   │   │   ├── sprite_player_idle.png
-│   │   │   ├── sprite_player_walk.png
-│   │   │   └── sprite_player_attack.png
-│   │   ├── enemies/
-│   │   │   ├── sprite_enemy_goblin_idle.png
-│   │   │   └── sprite_enemy_orc_walk.png
-│   │   └── npcs/
-│   │       ├── sprite_npc_merchant.png
-│   │       └── sprite_npc_guard.png
-│   ├── ui/                     # UI精灵
-│   │   ├── buttons/
-│   │   │   ├── ui_button_normal.png
-│   │   │   ├── ui_button_hover.png
-│   │   │   └── ui_button_pressed.png
-│   │   ├── icons/
-│   │   │   ├── icon_sword.png
-│   │   │   ├── icon_shield.png
-│   │   │   └── icon_potion.png
-│   │   └── panels/
-│   │       ├── ui_panel_main.png
-│   │       └── ui_panel_dialog.png
-│   ├── environment/            # 环境精灵
-│   │   ├── backgrounds/
-│   │   │   ├── bg_forest.png
-│   │   │   └── bg_dungeon.png
-│   │   ├── tiles/
-│   │   │   ├── tile_grass_01.png
-│   │   │   └── tile_stone_01.png
-│   │   └── objects/
-│   │       ├── obj_tree.png
-│   │       └── obj_rock.png
-│   └── effects/                # 特效精灵
-│       ├── fx_explosion.png
-│       ├── fx_magic_circle.png
-│       └── fx_damage_numbers.png
-├── audio/                       # 音频资源
-│   ├── music/                  # 背景音乐
-│   │   ├── music_main_menu.ogg
-│   │   ├── music_battle.ogg
-│   │   └── music_peaceful.ogg
-│   ├── sounds/                 # 音效
-│   │   ├── ui/
-│   │   │   ├── sound_button_click.wav
-│   │   │   └── sound_menu_open.wav
-│   │   ├── combat/
-│   │   │   ├── sound_sword_hit.wav
-│   │   │   └── sound_explosion.wav
-│   │   └── ambient/
-│   │       ├── sound_footsteps.wav
-│   │       └── sound_wind.wav
-│   └── voice/                  # 语音
-│       ├── voice_npc_greeting.wav
-│       └── voice_player_hurt.wav
-├── fonts/                       # 字体资源
-│   ├── font_main.ttf           # 主要字体
-│   ├── font_title.ttf          # 标题字体
-│   └── font_ui.ttf             # UI字体
-├── materials/                   # 材质资源
-│   ├── material_metal.tres
-│   ├── material_wood.tres
-│   └── material_water.tres
-└── shaders/                     # 着色器资源
-    ├── shader_water.gdshader
-    ├── shader_fire.gdshader
-    └── shader_outline.gdshader
-```
-
-### 4.2 资源命名规范
-
-#### 图片资源命名
-- **精灵图**：`sprite_[类别]_[名称]_[状态].png`
-  - 示例：`sprite_player_idle.png`、`sprite_enemy_goblin_walk.png`
-- **UI图片**：`ui_[类型]_[名称]_[状态].png`
-  - 示例：`ui_button_normal.png`、`ui_panel_main.png`
-- **图标**：`icon_[名称].png`
-  - 示例：`icon_sword.png`、`icon_health.png`
-- **背景**：`bg_[场景名称].png`
-  - 示例：`bg_forest.png`、`bg_dungeon.png`
-- **瓦片**：`tile_[材质]_[编号].png`
-  - 示例：`tile_grass_01.png`、`tile_stone_02.png`
-
-#### 音频资源命名
-- **音乐**：`music_[场景/情境].ogg`
-  - 示例：`music_battle.ogg`、`music_peaceful.ogg`
-- **音效**：`sound_[动作/事件].wav`
-  - 示例：`sound_jump.wav`、`sound_explosion.wav`
-- **语音**：`voice_[角色]_[内容].wav`
-  - 示例：`voice_npc_greeting.wav`、`voice_player_hurt.wav`
-
-#### 其他资源命名
-- **字体**：`font_[用途].ttf`
-  - 示例：`font_main.ttf`、`font_title.ttf`
-- **材质**：`material_[材质名].tres`
-  - 示例：`material_metal.tres`、`material_wood.tres`
-- **着色器**：`shader_[效果名].gdshader`
-  - 示例：`shader_water.gdshader`、`shader_fire.gdshader`
-## 5. 脚本层 (scripts/)
-
-脚本层包含所有业务逻辑代码，按功能模块组织。
-
-### 5.1 脚本目录结构
-
-```
-scripts/
-├── scenes/                      # 场景脚本
-│   ├── MainScene.gd            # 主场景脚本
-│   ├── AuthScene.gd            # 认证场景脚本
-│   ├── GameScene.gd            # 游戏场景脚本
-│   └── BattleScene.gd          # 战斗场景脚本
-├── ui/                         # UI脚本
-│   ├── MainMenu.gd             # 主菜单脚本
-│   ├── SettingsPanel.gd        # 设置面板脚本
-│   ├── InventoryUI.gd          # 背包界面脚本
-│   └── DialogueUI.gd           # 对话界面脚本
-├── characters/                  # 角色脚本
-│   ├── PlayerController.gd     # 玩家控制器
-│   ├── EnemyAI.gd             # 敌人AI
-│   └── NPCBehavior.gd         # NPC行为
-├── gameplay/                    # 游戏玩法脚本
-│   ├── CombatSystem.gd        # 战斗系统
-│   ├── QuestSystem.gd         # 任务系统
-│   ├── InventorySystem.gd     # 背包系统
-│   └── DialogueSystem.gd      # 对话系统
-├── network/                     # 网络脚本
-│   ├── NetworkClient.gd       # 网络客户端
-│   ├── NetworkServer.gd       # 网络服务器
-│   └── NetworkProtocol.gd     # 网络协议
-└── data/                       # 数据脚本
-    ├── GameData.gd            # 游戏数据
-    ├── PlayerData.gd          # 玩家数据
-    ├── ItemData.gd            # 物品数据
-    └── ConfigData.gd          # 配置数据
-```
-
-## 6. 数据层 (data/)
-
-数据层存储游戏配置、关卡数据和其他静态数据文件。
-
-### 6.1 数据目录结构
-
-```
-data/
-├── configs/                     # 配置文件
-│   ├── game_config.json        # 游戏配置
-│   ├── audio_config.json       # 音频配置
-│   ├── input_config.json       # 输入配置
-│   └── graphics_config.json    # 图形配置
-├── levels/                      # 关卡数据
-│   ├── level_01.json           # 第一关数据
-│   ├── level_02.json           # 第二关数据
-│   └── level_boss.json         # Boss关数据
-├── items/                       # 物品数据
-│   ├── weapons.json            # 武器数据
-│   ├── armor.json              # 装备数据
-│   └── consumables.json        # 消耗品数据
-├── characters/                  # 角色数据
-│   ├── player_stats.json       # 玩家属性
-│   ├── enemy_stats.json        # 敌人属性
-│   └── npc_data.json          # NPC数据
-├── dialogues/                   # 对话数据
-│   ├── main_story.json         # 主线对话
-│   ├── side_quests.json        # 支线对话
-│   └── npc_dialogues.json      # NPC对话
-└── localization/                # 本地化数据
-    ├── en.json                 # 英文文本
-    ├── zh_CN.json              # 简体中文文本
-    └── zh_TW.json              # 繁体中文文本
-```
-
-## 7. 测试层 (tests/)
-
-测试层包含单元测试、集成测试和功能测试。
-
-### 7.1 测试目录结构
-
-```
-tests/
-├── unit/                        # 单元测试
-│   ├── test_player_controller.gd
-│   ├── test_inventory_system.gd
-│   └── test_combat_system.gd
-├── integration/                 # 集成测试
-│   ├── test_scene_transitions.gd
-│   ├── test_save_load.gd
-│   └── test_network_sync.gd
-├── ui/                         # UI测试
-│   ├── test_main_menu.gd
-│   ├── test_inventory_ui.gd
-│   └── test_dialogue_ui.gd
-└── performance/                 # 性能测试
-    ├── test_memory_usage.gd
-    ├── test_frame_rate.gd
-    └── test_loading_times.gd
-```
-## 8. 场景间通信机制
-
-### 8.1 事件系统
-
-使用全局事件系统实现场景间的松耦合通信：
-
-```gdscript
-# 事件定义示例
-signal player_health_changed(new_health: int)
-signal scene_transition_requested(scene_name: String)
-signal item_collected(item_id: String)
-signal quest_completed(quest_id: String)
-
-# 事件发送
-EventSystem.emit_signal("player_health_changed", 80)
-
-# 事件监听
-EventSystem.connect("player_health_changed", _on_player_health_changed)
-```
-
-### 8.2 管理器模式
-
-通过单例管理器实现全局状态管理：
-
-```gdscript
-# 场景切换
-SceneManager.change_scene("battle_scene")
-
-# 音频播放
-AudioManager.play_sound("sound_button_click")
-
-# 数据保存
-SaveManager.save_game_data(player_data)
-```
-
-## 9. 开发工作流
-
-### 9.1 新场景开发流程
-
-1. **创建场景文件**：在 `scenes/` 目录创建 `.tscn` 文件
-2. **编写场景脚本**：在 `scripts/scenes/` 创建对应脚本
-3. **添加UI组件**：使用 `module/UI/` 中的可复用组件
-4. **配置场景数据**：在 `data/` 目录添加相关配置
-5. **编写测试用例**：在 `tests/` 目录添加测试
-6. **更新文档**：更新相关文档说明
-
-### 9.2 新功能模块开发流程
-
-1. **设计模块接口**：定义模块的公共接口
-2. **实现核心逻辑**：在 `module/` 目录实现功能
-3. **添加管理器支持**：在 `core/managers/` 添加管理器
-4. **创建测试场景**：创建独立的测试场景
-5. **集成到主项目**：将模块集成到现有场景
-6. **性能优化**：进行性能测试和优化
-
-## 10. 最佳实践
-
-### 10.1 代码组织
-
-- **单一职责**：每个类只负责一个功能
-- **依赖注入**：通过构造函数或属性注入依赖
-- **接口隔离**：使用接口定义模块间的契约
-- **配置外置**：将配置信息放在数据文件中
-
-### 10.2 性能优化
-
-- **对象池**：复用频繁创建的对象
-- **延迟加载**：按需加载资源和场景
-- **批量处理**：合并相似的操作
-- **内存管理**：及时释放不需要的资源
-
-### 10.3 调试和测试
-
-- **单元测试**：为核心逻辑编写单元测试
-- **集成测试**：测试模块间的交互
-- **性能监控**：监控内存和CPU使用情况
-- **日志记录**：记录关键操作和错误信息
-
-## 11. 扩展指南
-
-### 11.1 添加新场景
-
-1. 在 `scenes/` 目录创建场景文件
-2. 在 `scripts/scenes/` 创建场景脚本
-3. 在 `SceneManager` 中注册新场景
-4. 添加场景切换逻辑
-
-### 11.2 添加新模块
-
-1. 在 `module/` 目录创建模块文件夹
-2. 实现模块的核心功能
-3. 创建模块管理器（如需要）
-4. 编写模块文档和示例
-
-### 11.3 添加新资源类型
-
-1. 在 `assets/` 目录创建对应分类
-2. 更新命名规范文档
-3. 在资源加载器中添加支持
-4. 更新导入设置
-
----
-
-## 总结
-
-这个项目结构设计遵循了模块化、可扩展、易维护的原则。通过清晰的分层架构和标准化的命名规范，确保了项目的可读性和可维护性。每个开发者都应该遵循这个结构进行开发，以保持项目的一致性和质量。
-
-如有任何疑问或建议，请参考相关文档或联系项目维护者。

docs/setup.md

@@ -1,28 +0,0 @@
-# 项目设置指南
-
-## AutoLoad 配置
-
-在 Godot 编辑器中设置 NetworkManager 为全局单例：
-
-1. 打开 `Project` → `Project Settings`
-2. 切换到 `AutoLoad` 标签
-3. 添加新的 AutoLoad：
-   - **Path**: `res://core/managers/NetworkManager.gd`
-   - **Name**: `NetworkManager`
-   - **Singleton**: ✅ 勾选
-
-## 验证设置
-
-在任何脚本中可以直接使用：
-
-```gdscript
-func _ready():
-    var request_id = NetworkManager.login("username", "password", callback)
-    print("请求ID: ", request_id)
-```
-
-## 注意事项
-
-- 确保 NetworkManager.gd 和 ResponseHandler.gd 文件存在
-- 重启 Godot 编辑器以确保 AutoLoad 生效
-- 检查控制台是否有错误信息

docs/web_deployment_changelog.md

@@ -1,200 +0,0 @@
-# Web部署更新日志
-
-## v1.0.0 (2025-12-25)
-
-### 🎉 初始版本
-- 创建完整的Web导出解决方案
-- 支持Windows、Linux、macOS平台
-- 自动化构建和部署脚本
-
-### 📁 文件结构
-```
-scripts/
-├── build_web.bat      # Windows导出脚本
-├── build_web.sh       # Linux/macOS导出脚本
-├── serve_web.bat      # Windows本地服务器
-└── serve_web.sh       # Linux/macOS本地服务器
-
-docs/
-├── web_deployment_guide.md      # 完整部署指南
-└── web_deployment_changelog.md  # 更新日志
-```
-
-### ✨ 主要特性
-
-#### 自动化导出
-- 智能检测Godot安装路径
-- 验证项目文件完整性
-- 自动备份旧版本
-- 生成部署配置文件
-- 文件大小统计和优化建议
-
-#### 本地测试服务器
-- 自动端口检测和冲突处理
-- 支持局域网访问
-- 实时文件监控
-- 自动打开浏览器
-- 详细的调试信息
-
-#### 服务器配置
-- Apache .htaccess自动生成
-- Nginx配置示例
-- MIME类型配置
-- CORS头设置
-- 文件压缩优化
-- 缓存策略配置
-
-#### 部署优化
-- 资源文件压缩
-- 渐进式Web应用支持
-- 性能监控
-- 错误诊断工具
-
-### 🔧 技术规格
-
-#### 支持的平台
-- **开发环境**: Windows 10+, macOS 10.15+, Ubuntu 18.04+
-- **目标浏览器**: Chrome 80+, Firefox 75+, Safari 13+, Edge 80+
-- **Godot版本**: 4.5+
-
-#### 系统要求
-- **Godot Engine**: 4.5或更高版本
-- **Python**: 3.6+（用于本地测试）
-- **磁盘空间**: 至少100MB可用空间
-- **内存**: 建议4GB以上
-
-#### 网络要求
-- **带宽**: 建议10Mbps以上（用于资源下载）
-- **端口**: 8000（默认），8080（备用）
-- **协议**: HTTP/HTTPS
-
-### 📋 配置选项
-
-#### 导出设置
-```
-导出预设: Web
-渲染方法: gl_compatibility
-纹理压缩: 启用VRAM压缩
-文件格式: WASM + PCK
-```
-
-#### 服务器设置
-```
-默认端口: 8000
-备用端口: 8080
-文档根目录: build/web/
-索引文件: index.html
-```
-
-### 🚀 性能优化
-
-#### 文件大小优化
-- WASM文件压缩率: ~30%
-- 纹理压缩: ETC2/ASTC格式
-- 音频压缩: OGG Vorbis
-- 脚本压缩: 移除调试信息
-
-#### 加载速度优化
-- 启用Gzip压缩
-- 设置缓存策略
-- 使用CDN加速
-- 实现预加载机制
-
-### 🛡️ 安全特性
-
-#### 跨域安全
-- CORS头配置
-- CSP策略设置
-- XSS防护
-- 点击劫持防护
-
-#### 文件安全
-- MIME类型验证
-- 文件大小限制
-- 路径遍历防护
-- 敏感文件隐藏
-
-### 📊 监控和诊断
-
-#### 构建监控
-- 文件完整性检查
-- 大小统计分析
-- 构建时间记录
-- 错误日志收集
-
-#### 运行时监控
-- 性能指标收集
-- 错误报告系统
-- 用户行为分析
-- 网络请求监控
-
-### 🔄 兼容性
-
-#### 浏览器兼容性
-| 浏览器 | 最低版本 | 推荐版本 | 支持特性 |
-|--------|----------|----------|----------|
-| Chrome | 80 | 最新 | 完整支持 |
-| Firefox | 75 | 最新 | 完整支持 |
-| Safari | 13 | 最新 | 基本支持 |
-| Edge | 80 | 最新 | 完整支持 |
-
-#### 移动端兼容性
-- iOS Safari 13+
-- Android Chrome 80+
-- 响应式设计支持
-- 触摸操作优化
-
-### 📝 已知问题
-
-#### 当前限制
-1. **文件系统访问**: Web版本无法直接访问本地文件系统
-2. **性能差异**: 相比原生版本可能有10-30%的性能损失
-3. **内存限制**: 受浏览器内存限制影响
-4. **网络依赖**: 需要稳定的网络连接
-
-#### 解决方案
-1. 使用IndexedDB存储本地数据
-2. 优化资源和代码以提升性能
-3. 实现内存管理和垃圾回收
-4. 添加离线缓存支持
-
-### 🔮 未来计划
-
-#### v1.1.0 (计划中)
-- [ ] PWA（渐进式Web应用）完整支持
-- [ ] 离线模式实现
-- [ ] 自动更新机制
-- [ ] 性能分析工具
-
-#### v1.2.0 (计划中)
-- [ ] WebRTC多人游戏支持
-- [ ] WebGL 2.0优化
-- [ ] 移动端手势优化
-- [ ] 云存档同步
-
-#### v2.0.0 (远期计划)
-- [ ] WebAssembly SIMD支持
-- [ ] Web Workers多线程
-- [ ] WebXR虚拟现实支持
-- [ ] 边缘计算集成
-
-### 📞 技术支持
-
-#### 问题报告
-如遇到问题，请提供以下信息：
-1. 操作系统和版本
-2. 浏览器类型和版本
-3. Godot版本
-4. 错误日志和截图
-5. 复现步骤
-
-#### 联系方式
-- 项目文档: `docs/web_deployment_guide.md`
-- 构建日志: `build/web/server.log`
-- 部署信息: `build/web/deploy_info.json`
-
----
-
-**维护者**: 鲸鱼镇开发团队  
-**最后更新**: 2025-12-25  
-**文档版本**: 1.0.0

module/Character/.gitkeep

@@ -1 +0,0 @@
-# 保持目录结构 - 角色模块目录

module/Combat/.gitkeep

@@ -1 +0,0 @@
-# 保持目录结构 - 战斗模块目录

module/Dialogue/.gitkeep

@@ -1 +0,0 @@
-# 保持目录结构 - 对话模块目录

module/Inventory/.gitkeep

@@ -1 +0,0 @@
-# 保持目录结构 - 背包模块目录

module/UI/animations/.gitkeep

@@ -1 +0,0 @@
-# 保持目录结构 - UI动画目录

module/UI/components/.gitkeep

@@ -1 +0,0 @@
-# 保持目录结构 - UI组件目录

module/UI/layouts/.gitkeep

@@ -1 +0,0 @@
-# 保持目录结构 - UI布局目录

project.godot

@@ -11,17 +11,17 @@ config_version=5
 [application]
 
 config/name="whaleTown"
-run/main_scene="res://scenes/main_scene.tscn"
+run/main_scene="res://scenes/MainScene.tscn"
 config/features=PackedStringArray("4.5", "Forward Plus")
 config/icon="res://icon.svg"
 
 [autoload]
 
-GameManager="*res://core/managers/GameManager.gd"
-SceneManager="*res://core/managers/SceneManager.gd"
-EventSystem="*res://core/systems/EventSystem.gd"
-NetworkManager="*res://core/managers/NetworkManager.gd"
-ResponseHandler="*res://core/managers/ResponseHandler.gd"
+GameManager="*res://_Core/managers/GameManager.gd"
+SceneManager="*res://_Core/managers/SceneManager.gd"
+EventSystem="*res://_Core/systems/EventSystem.gd"
+NetworkManager="*res://_Core/managers/NetworkManager.gd"
+ResponseHandler="*res://_Core/managers/ResponseHandler.gd"
 
 [debug]
 
@@ -39,6 +39,43 @@ window/stretch/aspect="expand"
 
 theme/custom="uid://cp7t8tu7rmyad"
 
+[input]
+
+move_left={
+"deadzone": 0.5,
+"events": [Object(InputEventKey,"resource_local_to_scene":false,"resource_name":"","device":-1,"window_id":0,"alt_pressed":false,"shift_pressed":false,"ctrl_pressed":false,"meta_pressed":false,"pressed":false,"keycode":0,"physical_keycode":65,"key_label":0,"unicode":97,"location":0,"echo":false,"script":null)
+, Object(InputEventKey,"resource_local_to_scene":false,"resource_name":"","device":-1,"window_id":0,"alt_pressed":false,"shift_pressed":false,"ctrl_pressed":false,"meta_pressed":false,"pressed":false,"keycode":0,"physical_keycode":4194319,"key_label":0,"unicode":0,"location":0,"echo":false,"script":null)
+]
+}
+move_right={
+"deadzone": 0.5,
+"events": [Object(InputEventKey,"resource_local_to_scene":false,"resource_name":"","device":-1,"window_id":0,"alt_pressed":false,"shift_pressed":false,"ctrl_pressed":false,"meta_pressed":false,"pressed":false,"keycode":0,"physical_keycode":68,"key_label":0,"unicode":100,"location":0,"echo":false,"script":null)
+, Object(InputEventKey,"resource_local_to_scene":false,"resource_name":"","device":-1,"window_id":0,"alt_pressed":false,"shift_pressed":false,"ctrl_pressed":false,"meta_pressed":false,"pressed":false,"keycode":0,"physical_keycode":4194321,"key_label":0,"unicode":0,"location":0,"echo":false,"script":null)
+]
+}
+move_up={
+"deadzone": 0.5,
+"events": [Object(InputEventKey,"resource_local_to_scene":false,"resource_name":"","device":-1,"window_id":0,"alt_pressed":false,"shift_pressed":false,"ctrl_pressed":false,"meta_pressed":false,"pressed":false,"keycode":0,"physical_keycode":87,"key_label":0,"unicode":119,"location":0,"echo":false,"script":null)
+, Object(InputEventKey,"resource_local_to_scene":false,"resource_name":"","device":-1,"window_id":0,"alt_pressed":false,"shift_pressed":false,"ctrl_pressed":false,"meta_pressed":false,"pressed":false,"keycode":0,"physical_keycode":4194320,"key_label":0,"unicode":0,"location":0,"echo":false,"script":null)
+]
+}
+move_down={
+"deadzone": 0.5,
+"events": [Object(InputEventKey,"resource_local_to_scene":false,"resource_name":"","device":-1,"window_id":0,"alt_pressed":false,"shift_pressed":false,"ctrl_pressed":false,"meta_pressed":false,"pressed":false,"keycode":0,"physical_keycode":83,"key_label":0,"unicode":115,"location":0,"echo":false,"script":null)
+, Object(InputEventKey,"resource_local_to_scene":false,"resource_name":"","device":-1,"window_id":0,"alt_pressed":false,"shift_pressed":false,"ctrl_pressed":false,"meta_pressed":false,"pressed":false,"keycode":0,"physical_keycode":4194322,"key_label":0,"unicode":0,"location":0,"echo":false,"script":null)
+]
+}
+jump={
+"deadzone": 0.5,
+"events": [Object(InputEventKey,"resource_local_to_scene":false,"resource_name":"","device":-1,"window_id":0,"alt_pressed":false,"shift_pressed":false,"ctrl_pressed":false,"meta_pressed":false,"pressed":false,"keycode":0,"physical_keycode":32,"key_label":0,"unicode":32,"location":0,"echo":false,"script":null)
+]
+}
+interact={
+"deadzone": 0.5,
+"events": [Object(InputEventKey,"resource_local_to_scene":false,"resource_name":"","device":-1,"window_id":0,"alt_pressed":false,"shift_pressed":false,"ctrl_pressed":false,"meta_pressed":false,"pressed":false,"keycode":0,"physical_keycode":69,"key_label":0,"unicode":101,"location":0,"echo":false,"script":null)
+]
+}
+
 [internationalization]
 
 locale/test="zh_CN"
@@ -49,3 +86,5 @@ renderer/rendering_method="gl_compatibility"
 renderer/rendering_method.mobile="gl_compatibility"
 textures/vram_compression/import_etc2_astc=true
 fonts/dynamic_fonts/use_oversampling=true
+debug/disable_vsync=false
+debug/settings/stdout/print_fps=false

scenes/MainScene.gd

@@ -1,5 +1,16 @@
 extends Control
 
+# ============================================================================
+# MainScene.gd - 主场景控制器
+# ============================================================================
+# 这是游戏的主入口场景，负责管理所有图像显示和界面切换
+# 功能包括：
+# - 登录/注册界面管理
+# - 主游戏界面显示
+# - 用户状态管理
+# - 游戏功能模块入口
+# ============================================================================
+
 # 场景节点引用
 @onready var auth_scene: Control = $AuthScene
 @onready var main_game_ui: Control = $MainGameUI
@@ -113,4 +124,4 @@ func _input(event):
 				get_tree().quit()
 			GameState.MAIN_GAME:
 				# 在游戏中按ESC可能显示菜单或返回登录
-				show_auth_scene()
+				show_auth_scene()

scenes/MainScene.gd.uid

@@ -0,0 +1 @@
+uid://ghehm4srs0ho

scenes/MainScene.tscn

@@ -1,28 +1,14 @@
-[gd_scene load_steps=4 format=3 uid="uid://4ptgx76y83mx"]
+[gd_scene load_steps=3 format=3 uid="uid://cjabtnqbdd2ey"]
 
-[ext_resource type="Texture2D" uid="uid://bx17oy8lvaca4" path="res://assets/ui/auth/bg_auth_scene.png" id="1_background"]
-[ext_resource type="PackedScene" uid="uid://by7m8snb4xllf" path="res://scenes/auth_scene.tscn" id="2_main"]
-[ext_resource type="Script" uid="uid://cejrxy23ldhug" path="res://scripts/scenes/MainScene.gd" id="3_script"]
+[ext_resource type="Script" path="res://scenes/MainScene.gd" id="1_script"]
+[ext_resource type="PackedScene" uid="uid://by7m8snb4xllf" path="res://scenes/ui/AuthScene.tscn" id="2_main"]
 
 [node name="Main" type="Control"]
 layout_mode = 3
 anchors_preset = 15
 anchor_right = 1.0
 anchor_bottom = 1.0
-grow_horizontal = 2
-grow_vertical = 2
-script = ExtResource("3_script")
-
-[node name="BackgroundImage" type="TextureRect" parent="."]
-layout_mode = 1
-anchors_preset = 15
-anchor_right = 1.0
-anchor_bottom = 1.0
-grow_horizontal = 2
-grow_vertical = 2
-texture = ExtResource("1_background")
-expand_mode = 1
-stretch_mode = 6
+script = ExtResource("1_script")
 
 [node name="AuthScene" parent="." instance=ExtResource("2_main")]
 layout_mode = 1
@@ -33,24 +19,12 @@ layout_mode = 1
 anchors_preset = 15
 anchor_right = 1.0
 anchor_bottom = 1.0
-grow_horizontal = 2
-grow_vertical = 2
-
-[node name="UIOverlay" type="ColorRect" parent="MainGameUI"]
-layout_mode = 1
-anchors_preset = 15
-anchor_right = 1.0
-anchor_bottom = 1.0
-grow_horizontal = 2
-grow_vertical = 2
-color = Color(0, 0, 0, 0.3)
 
 [node name="TopBar" type="Panel" parent="MainGameUI"]
 layout_mode = 1
 anchors_preset = 10
 anchor_right = 1.0
 offset_bottom = 60.0
-grow_horizontal = 2
 
 [node name="HBoxContainer" type="HBoxContainer" parent="MainGameUI/TopBar"]
 layout_mode = 1
@@ -61,26 +35,16 @@ offset_left = 20.0
 offset_top = 10.0
 offset_right = -20.0
 offset_bottom = -10.0
-grow_horizontal = 2
-grow_vertical = 2
-
-[node name="WelcomeLabel" type="Label" parent="MainGameUI/TopBar/HBoxContainer"]
-layout_mode = 2
-size_flags_horizontal = 3
-theme_override_colors/font_color = Color(1, 1, 1, 1)
-text = "🐋 欢迎来到鲸鱼镇！"
-vertical_alignment = 1
 
 [node name="UserLabel" type="Label" parent="MainGameUI/TopBar/HBoxContainer"]
 layout_mode = 2
-theme_override_colors/font_color = Color(1, 1, 1, 1)
-text = "当前用户: [用户名]"
-horizontal_alignment = 2
+size_flags_horizontal = 3
+text = "当前用户: "
 vertical_alignment = 1
 
 [node name="LogoutButton" type="Button" parent="MainGameUI/TopBar/HBoxContainer"]
 layout_mode = 2
-text = "退出"
+text = "登出"
 
 [node name="MainContent" type="Control" parent="MainGameUI"]
 layout_mode = 1
@@ -88,80 +52,29 @@ anchors_preset = 15
 anchor_right = 1.0
 anchor_bottom = 1.0
 offset_top = 60.0
-grow_horizontal = 2
-grow_vertical = 2
 
 [node name="CenterContainer" type="CenterContainer" parent="MainGameUI/MainContent"]
 layout_mode = 1
 anchors_preset = 15
 anchor_right = 1.0
 anchor_bottom = 1.0
-grow_horizontal = 2
-grow_vertical = 2
 
 [node name="VBoxContainer" type="VBoxContainer" parent="MainGameUI/MainContent/CenterContainer"]
-custom_minimum_size = Vector2(600, 400)
-layout_mode = 2
-
-[node name="GameTitle" type="Label" parent="MainGameUI/MainContent/CenterContainer/VBoxContainer"]
-layout_mode = 2
-theme_override_colors/font_color = Color(1, 1, 1, 1)
-theme_override_font_sizes/font_size = 24
-text = "🏘️ 鲸鱼镇主界面"
-horizontal_alignment = 1
-
-[node name="HSeparator" type="HSeparator" parent="MainGameUI/MainContent/CenterContainer/VBoxContainer"]
-layout_mode = 2
-
-[node name="GameMenuGrid" type="GridContainer" parent="MainGameUI/MainContent/CenterContainer/VBoxContainer"]
-layout_mode = 2
-size_flags_vertical = 3
-columns = 2
-
-[node name="ExploreButton" type="Button" parent="MainGameUI/MainContent/CenterContainer/VBoxContainer/GameMenuGrid"]
-custom_minimum_size = Vector2(280, 80)
-layout_mode = 2
-text = "🗺️ 探索小镇"
-
-[node name="InventoryButton" type="Button" parent="MainGameUI/MainContent/CenterContainer/VBoxContainer/GameMenuGrid"]
-custom_minimum_size = Vector2(280, 80)
-layout_mode = 2
-text = "🎒 背包物品"
-
-[node name="ShopButton" type="Button" parent="MainGameUI/MainContent/CenterContainer/VBoxContainer/GameMenuGrid"]
-custom_minimum_size = Vector2(280, 80)
-layout_mode = 2
-text = "🏪 商店购物"
-
-[node name="FriendsButton" type="Button" parent="MainGameUI/MainContent/CenterContainer/VBoxContainer/GameMenuGrid"]
-custom_minimum_size = Vector2(280, 80)
-layout_mode = 2
-text = "👥 好友列表"
-
-[node name="HSeparator2" type="HSeparator" parent="MainGameUI/MainContent/CenterContainer/VBoxContainer"]
 layout_mode = 2
 
 [node name="StatusPanel" type="Panel" parent="MainGameUI/MainContent/CenterContainer/VBoxContainer"]
-custom_minimum_size = Vector2(0, 120)
 layout_mode = 2
+custom_minimum_size = Vector2(400, 150)
 
-[node name="StatusContainer" type="VBoxContainer" parent="MainGameUI/MainContent/CenterContainer/VBoxContainer/StatusPanel"]
+[node name="StatusContainer" type="MarginContainer" parent="MainGameUI/MainContent/CenterContainer/VBoxContainer/StatusPanel"]
 layout_mode = 1
 anchors_preset = 15
 anchor_right = 1.0
 anchor_bottom = 1.0
 offset_left = 20.0
-offset_top = 10.0
+offset_top = 20.0
 offset_right = -20.0
-offset_bottom = -10.0
-grow_horizontal = 2
-grow_vertical = 2
-
-[node name="StatusTitle" type="Label" parent="MainGameUI/MainContent/CenterContainer/VBoxContainer/StatusPanel/StatusContainer"]
-layout_mode = 2
-theme_override_colors/font_color = Color(1, 1, 1, 1)
-text = "📊 玩家状态"
-horizontal_alignment = 1
+offset_bottom = -20.0
 
 [node name="StatusGrid" type="GridContainer" parent="MainGameUI/MainContent/CenterContainer/VBoxContainer/StatusPanel/StatusContainer"]
 layout_mode = 2
@@ -169,20 +82,40 @@ columns = 2
 
 [node name="LevelLabel" type="Label" parent="MainGameUI/MainContent/CenterContainer/VBoxContainer/StatusPanel/StatusContainer/StatusGrid"]
 layout_mode = 2
-theme_override_colors/font_color = Color(1, 1, 1, 1)
 text = "等级: 1"
 
 [node name="CoinsLabel" type="Label" parent="MainGameUI/MainContent/CenterContainer/VBoxContainer/StatusPanel/StatusContainer/StatusGrid"]
 layout_mode = 2
-theme_override_colors/font_color = Color(1, 1, 1, 1)
 text = "金币: 100"
 
 [node name="ExpLabel" type="Label" parent="MainGameUI/MainContent/CenterContainer/VBoxContainer/StatusPanel/StatusContainer/StatusGrid"]
 layout_mode = 2
-theme_override_colors/font_color = Color(1, 1, 1, 1)
 text = "经验: 0/100"
 
 [node name="EnergyLabel" type="Label" parent="MainGameUI/MainContent/CenterContainer/VBoxContainer/StatusPanel/StatusContainer/StatusGrid"]
 layout_mode = 2
-theme_override_colors/font_color = Color(1, 1, 1, 1)
 text = "体力: 100/100"
+
+[node name="GameMenuGrid" type="GridContainer" parent="MainGameUI/MainContent/CenterContainer/VBoxContainer"]
+layout_mode = 2
+columns = 2
+
+[node name="ExploreButton" type="Button" parent="MainGameUI/MainContent/CenterContainer/VBoxContainer/GameMenuGrid"]
+layout_mode = 2
+custom_minimum_size = Vector2(150, 50)
+text = "🗺️ 探索小镇"
+
+[node name="InventoryButton" type="Button" parent="MainGameUI/MainContent/CenterContainer/VBoxContainer/GameMenuGrid"]
+layout_mode = 2
+custom_minimum_size = Vector2(150, 50)
+text = "🎒 背包"
+
+[node name="ShopButton" type="Button" parent="MainGameUI/MainContent/CenterContainer/VBoxContainer/GameMenuGrid"]
+layout_mode = 2
+custom_minimum_size = Vector2(150, 50)
+text = "🏪 商店"
+
+[node name="FriendsButton" type="Button" parent="MainGameUI/MainContent/CenterContainer/VBoxContainer/GameMenuGrid"]
+layout_mode = 2
+custom_minimum_size = Vector2(150, 50)
+text = "👥 好友"

scenes/Maps/.gitkeep

@@ -0,0 +1,2 @@
+# 地图场景目录
+# 存放游戏关卡、世界地图等地图场景

scenes/characters/.gitkeep

@@ -0,0 +1,2 @@
+# 人物场景目录
+# 存放角色、NPC、敌人等人物相关场景

scenes/effects/.gitkeep

@@ -0,0 +1,2 @@
+# 特效场景目录
+# 存放粒子效果、动画等特效场景

scenes/prefabs/.gitkeep

@@ -0,0 +1,2 @@
+# 预制体组件目录
+# 存放可复用的预制体组件