config：更新项目配置和文档

- 更新Godot项目配置，添加自动加载脚本 - 完善.gitignore文件，排除不必要的文件 - 更新README文档，添加项目介绍和使用说明 - 更新主场景配置，集成认证系统 - 添加开发规范文档和项目结构说明
2025-12-24 20:39:33 +08:00
parent 5b67771bbc
commit 370cffbdd8
10 changed files with 2112 additions and 91 deletions
--- a/README.md
+++ b/README.md
@@ -1,101 +1,274 @@
-# whaleTown
+# 🐋 whaleTown

-一个使用 Godot 4.5 引擎开发的游戏项目。
+一个使用 Godot 4.5 引擎开发的现代化像素游戏项目，集成了完整的用户认证系统和API接口。

-## 项目信息
+## 🎮 项目信息

- **引擎版本**: Godot 4.5
+- **引擎版本**: Godot 4.5.1
 - **渲染器**: Forward Plus
- **项目类型**: 2D 游戏
+- **项目类型**: 2D 像素游戏
+- **架构模式**: 模块化 + 事件驱动
+- **后端集成**: RESTful API + 用户认证

-## 项目结构
+## 🚀 快速开始

-```
-whaleTown/
-├── addons/          # Godot 插件目录
-├── assets/          # 游戏资源文件（图片、音频等）
-├── data/            # 游戏数据文件（配置、关卡数据等）
-├── docs/            # 项目文档
-├── scenes/          # 游戏场景文件
-│   └── main_scene.tscn  # 主场景
-├── scripts/         # GDScript 脚本文件
-├── tests/           # 测试文件
-├── icon.svg         # 项目图标
-└── project.godot    # Godot 项目配置文件
-```
-
-## 开始使用
-
-### 前置要求
-
- [Godot Engine 4.5](https://godotengine.org/download) 或更高版本
+### 环境要求
+- [Godot Engine 4.5+](https://godotengine.org/download)
+- Python 3.7+ (用于API测试)

 ### 运行项目
-
-1. 克隆或下载此项目
-2. 使用 Godot 编辑器打开项目
-3. 在编辑器中点击"运行"按钮或按 F5 键启动游戏
-
-### 开发指南
-
- **场景文件**: 所有场景文件存放在 `scenes/` 目录
- **脚本文件**: 所有 GDScript 脚本存放在 `scripts/` 目录
- **资源文件**: 图片、音频等资源存放在 `assets/` 目录
- **游戏数据**: 配置文件、关卡数据等存放在 `data/` 目录
-
-### 命名规范
-
-本项目遵循统一的命名规范以保持代码一致性：
-
-**核心规则**：
-
- **场景文件**：`下划线_scene.tscn` 或 `下划线_prefab.tscn`
-  - 示例：`main_scene.tscn`、`player_prefab.tscn`
- **脚本文件**：`PascalCase.gd`（大驼峰）
-  - 示例：`PlayerController.gd`、`UI_MainMenu.gd`
- **节点名称**：`camelCase`（小驼峰）
-  - 示例：`playerHpBar`、`startButton`
- **变量/函数**：`camelCase`（小驼峰）
-  - 示例：`var moveSpeed`、`func getPlayerPos()`
- **常量**：`UPPER_CASE`（全大写 + 下划线）
-  - 示例：`const MAX_HEALTH = 100`
- **资源文件**：`lower_case`（小写 + 下划线）
-  - 示例：`bg_main_menu.png`、`sound_jump.wav`
-
-📖 查看完整的 [命名规范文档](docs/naming_convention.md)
-
-### Git 提交规范
-
-本项目遵循统一的 Git 提交信息格式：`<类型>：<描述>`
-
-**常用提交类型**：
-
- `init`：项目初始化
- `feat`：新增功能
- `fix`：修复 Bug
- `docs`：文档更新
- `scene`：场景文件相关
- `asset`：资源文件相关
- `ui`：UI 界面相关
- `gameplay`：游戏玩法相关
- `refactor`：代码重构
- `perf`：性能优化
-
-**提交示例**：
-
 ```bash
-git commit -m "init：项目初始化，搭建Godot文件结构"
-git commit -m "feat：实现玩家角色的移动和跳跃"
-git commit -m "fix：修复敌人穿墙的碰撞问题"
-git commit -m "scene：创建战斗场景并配置相机"
+# 1. 克隆项目
+git clone <repository-url>
+cd whale-town
+
+# 2. 使用Godot编辑器打开项目
+# 3. 按F5运行或点击"运行"按钮
+
+# 4. 测试API接口（可选）
+python tests/api/simple_api_test.py
 ```

-📖 查看完整的 [Git 提交规范文档](docs/git_commit_guide.md)
+## 🏗️ 项目架构

-## 贡献
+### 核心设计理念
+- **场景独立性** - 每个场景都是独立的功能模块
+- **高度解耦** - 通过事件系统和管理器通信
+- **组件复用** - 可复用组件统一管理
+- **标准化** - 统一的命名规范和目录结构
+- **测试驱动** - 完整的测试体系和文档

-欢迎提交 Issue 和 Pull Request！
+### 目录结构
+```
+whaleTown/
+├── 🎬 scenes/           # 游戏场景
+│   ├── auth_scene.tscn     # 用户认证场景
+│   ├── main_scene.tscn     # 主游戏场景
+│   └── prefabs/            # 预制体组件
+├── 🔧 core/             # 核心系统（自动加载）
+│   ├── managers/           # 全局管理器
+│   ├── systems/            # 系统组件
+│   └── utils/              # 工具类
+├── 📝 scripts/          # 业务逻辑脚本
+│   ├── scenes/             # 场景脚本
+│   ├── network/            # 网络相关
+│   └── 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接口文档
+    ├── 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** - 第三方登录集成
+- **错误处理** - 完整的错误提示和频率限制
+
+### 🎮 游戏功能
+- **主场景** - 游戏主界面和菜单系统
+- **认证场景** - 完整的登录注册界面
+- **状态管理** - 用户状态和游戏状态管理
+- **网络通信** - 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) - 提交信息标准
+
+### 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) 文件了解详情
+
+---
+
+## 🎯 项目状态
+
+- ✅ 基础架构搭建完成
+- ✅ 用户认证系统完成
+- ✅ API接口集成完成
+- ✅ 测试体系建立完成
+- ✅ 文档体系完善
+- 🚧 游戏核心玩法开发中
+- 🚧 更多功能模块开发中
+
+**最后更新**: 2025-12-24