whale-town-front/README.md

# 🐋 whaleTown

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

## 🎮 项目信息

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

## 🚀 快速开始

### 环境要求
- [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用户
tools\build_web.bat      # 导出Web版本
tools\serve_web.bat      # 启动本地测试服务器

# Linux/macOS用户
./tools/build_web.sh     # 导出Web版本
./tools/serve_web.sh     # 启动本地测试服务器
```

详细部署指南请查看: [Web部署完整指南](docs/web_deployment_guide.md)

## 🏗️ 项目架构

### 核心设计理念
项目采用 **分层架构** 和 **组件化设计**，遵循 Godot 最佳实践：
- **清晰的分层** - 框架层、玩法层、界面层明确分离
- **场景内聚** - 脚本紧邻场景文件，符合 Godot 原生开发习惯
- **高度解耦** - 通过事件系统和管理器通信
- **组件复用** - 可复用组件统一管理
- **标准化** - 统一的命名规范和目录结构
- **测试驱动** - 完整的测试体系和文档

### 目录结构
```
whaleTown/
├── _Core/                      # [框架层] 游戏的底层框架，单例，全局管理器
│   ├── managers/               # 游戏管理器
│   │   ├── GameManager.gd      # 游戏状态管理
│   │   ├── SceneManager.gd     # 场景管理
│   │   ├── NetworkManager.gd   # 网络通信
│   │   └── ResponseHandler.gd  # API响应处理
│   ├── systems/                # 核心系统
│   │   └── EventSystem.gd      # 事件系统
│   └── singletons/             # 其他单例（待扩展）
│
├── Scenes/                     # [玩法层] 具体的游戏场景、实体、地图
│   ├── Maps/                   # 地图场景
│   │   └── main_scene.tscn     # 主游戏场景
│   ├── Entities/               # 游戏实体
│   │   ├── Player/             # 玩家实体
│   │   ├── NPC/                # NPC实体
│   │   └── Interactables/      # 交互物
│   └── Components/             # 可复用组件
│
├── UI/                         # [界面层] 所有UI相关的预制体和逻辑
│   ├── HUD/                    # 抬头显示（常驻）
│   ├── Windows/                # 模态窗口
│   │   └── LoginWindow.tscn    # 登录窗口
│   ├── Dialog/                 # 对话系统
│   └── Theme/                  # 全局样式
│       ├── MainTheme.tres      # 主主题
│       └── Fonts/              # 字体文件
│
├── Assets/                     # [资源层] 美术、音频、字体
│   ├── Sprites/                # 精灵图
│   │   ├── icon/               # 图标
│   │   ├── materials/          # 材质
│   │   ├── shaders/            # 着色器
│   │   └── sprites/            # 精灵图
│   ├── Audio/                  # 音频
│   └── Fonts/                  # 字体
│
├── Config/                     # [配置层] 游戏配置文件
│   ├── game_config.json        # 游戏配置
│   └── zh_CN.json              # 中文本地化
│
├── Utils/                      # [工具层] 通用辅助脚本
│   └── StringUtils.gd          # 字符串工具
│
├── 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提交规范
│
├── tools/                      # 开发工具和脚本
│   ├── build_web.bat           # Windows Web导出脚本
│   ├── build_web.sh            # Linux/macOS Web导出脚本
│   ├── serve_web.bat           # Windows 本地服务器
│   └── serve_web.sh            # Linux/macOS 本地服务器
│
├── REFACTORING.md              # 项目结构重构文档
└── MIGRATION_COMPLETE.md       # 迁移完成标记
```

### 架构层次说明

#### 1. 框架层 (_Core/)
- **职责**: 游戏的底层框架，与具体游戏逻辑无关
- **内容**: 单例管理器、核心系统
- **特点**: 自动加载，全局可访问
- **命名**: 使用下划线前缀 `_Core` 表示这是核心框架代码

#### 2. 玩法层 (Scenes/)
- **职责**: 游戏世界，地图和实体
- **内容**: 游戏场景、角色、NPC、交互物
- **特点**: 场景内聚，脚本紧邻场景文件
- **组织**: 按游戏世界的实体类型分类

#### 3. 界面层 (UI/)
- **职责**: 所有界面，HUD和弹窗
- **内容**: 常驻界面、模态窗口、对话系统、主题样式
- **特点**: 独立于游戏场景，便于UI开发和维护
- **组织**: 按界面类型和用途分类

#### 4. 资源层 (Assets/)
- **职责**: 纯美术资源
- **内容**: 精灵图、音频、字体等
- **特点**: 与代码分离，便于美术组独立工作
- **组织**: 按资源类型分类

#### 5. 配置层 (Config/)
- **职责**: 静态数据，策划可编辑
- **内容**: 游戏配置、本地化文件
- **特点**: 数据驱动，便于调整游戏参数
- **格式**: JSON 文件

#### 6. 工具层 (Utils/)
- **职责**: 通用辅助脚本
- **内容**: 工具函数库
- **特点**: 可被任何层调用
- **原则**: 无依赖，纯函数

### 核心系统
项目包含以下自动加载的核心系统（位于 [_Core/](./_Core/)）：

- **GameManager** - 全局游戏状态管理
- **SceneManager** - 场景切换管理
- **EventSystem** - 事件通信系统
- **NetworkManager** - 网络通信管理
- **ResponseHandler** - API响应处理

使用示例：
```gdscript
# 状态管理
GameManager.change_state(GameManager.GameState.IN_GAME)

# 场景切换（已更新路径）
SceneManager.change_scene("main")  # → res://Scenes/Maps/main_scene.tscn

# 事件通信
EventSystem.emit_event("player_health_changed", 80)
EventSystem.connect_event("player_died", _on_player_died)
```

### 设计原则

#### 1. 清晰的分层
- **_Core**: 框架代码，与具体游戏逻辑无关
- **Scenes**: 游戏世界，地图和实体
- **UI**: 所有界面，HUD和弹窗
- **Config**: 静态数据，策划可编辑

#### 2. 组件化设计
可复用组件放在 `Scenes/Components/` 下，使用组合优于继承的设计模式：
- InteractableArea.tscn - 让任何物体"可交互"
- MovementSync.gd - 网络位置同步
- NameTag3D.tscn - 头顶名字条

#### 3. 场景内聚
- 每个 .tscn 配套一个 .gd
- 脚本紧邻场景文件存放
- 符合 Godot 原生开发习惯

#### 4. 职责单一
```
UI/Windows/     - 模态窗口（登录、设置、商店）
UI/HUD/         - 常驻界面（聊天框、状态栏）
UI/Dialog/      - 对话系统
```

### 团队协作
- **美术组**: 主要在 [Assets/](./Assets/) 工作
- **策划组**: 主要在 [Config/](./Config/) 工作
- **程序组**: 主要在 [_Core/](./_Core/), [Scenes/](./Scenes/), [UI/](./UI/) 工作
- **测试组**: 主要在 [Tests/](./Tests/) 工作

## ✨ 主要功能

### 🔐 用户认证系统
- **用户注册** - 支持邮箱验证码验证
- **用户登录** - 多种登录方式（用户名/邮箱/手机号）
- **密码管理** - 密码重置和修改功能
- **GitHub OAuth** - 第三方登录集成
- **错误处理** - 完整的错误提示和频率限制
- **UI界面**: [UI/Windows/LoginWindow.tscn](UI/Windows/LoginWindow.tscn)

### 🌐 Web版本部署
- **自动化导出** - 一键导出Web版本
- **本地测试服务器** - 内置HTTP服务器用于测试
- **生产环境配置** - 完整的服务器配置指南
- **跨平台支持** - Windows、Linux、macOS全平台支持
- **性能优化** - 资源压缩和加载优化

### 🎮 游戏功能
- **主场景** - 游戏主界面和菜单系统 ([Scenes/Maps/main_scene.tscn](Scenes/Maps/main_scene.tscn))
- **认证场景** - 完整的登录注册界面
- **状态管理** - 用户状态和游戏状态管理
- **网络通信** - RESTful API集成 ([_Core/managers/NetworkManager.gd](_Core/managers/NetworkManager.gd))

### 🧪 测试体系
- **API测试** - 完整的接口测试脚本 ([Tests/api/](Tests/api/))
- **UI测试** - 认证界面的交互测试 ([Tests/auth/](Tests/auth/))
- **错误场景** - 边界条件和异常处理测试

## 🔧 开发规范

### 命名规范
- **场景文件**: `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/](./Scenes/) 对应分类下创建场景文件
2. 脚本文件紧邻场景文件存放（场景内聚原则）
3. 在 [_Core/managers/SceneManager.gd](_Core/managers/SceneManager.gd) 中注册场景路径
4. 使用 `SceneManager.change_scene()` 切换场景

示例：
```gdscript
# 在 SceneManager.gd 中注册
var scene_paths: Dictionary = {
    "battle": "res://Scenes/Maps/battle_scene.tscn",
    "shop": "res://UI/Windows/ShopWindow.tscn",
}

# 使用
SceneManager.change_scene("battle")
```

### 创建可复用组件
1. 在 [Scenes/Components/](./Scenes/Components/) 创建组件场景
2. 实现标准接口，保持组件独立性
3. 通过 [EventSystem](_Core/systems/EventSystem.gd) 与其他模块通信
4. 组件可以被任何场景实例化复用

### 添加UI界面
1. **模态窗口** → 放入 [UI/Windows/](./UI/Windows/)
2. **常驻界面** → 放入 [UI/HUD/](./UI/HUD/)
3. **对话系统** → 放入 [UI/Dialog/](./UI/Dialog/)
4. UI脚本紧邻场景文件，保持内聚

### 资源管理
- **精灵图** → 放入 [Assets/Sprites/](./Assets/Sprites/) 对应分类
- **音频文件** → 放入 [Assets/Audio/](./Assets/Audio/) 对应分类
- **字体文件** → 放入 [UI/Theme/Fonts/](./UI/Theme/Fonts/)
- **配置文件** → 放入 [Config/](./Config/)
- 遵循命名规范，使用英文小写+下划线

### 路径映射参考

| 功能类型 | 旧路径 | 新路径 |
|---------|--------|--------|
| 核心管理器 | `core/managers/` | [_Core/managers/](_Core/managers/) |
| 游戏场景 | `scenes/main_scene.tscn` | [Scenes/Maps/main_scene.tscn](Scenes/Maps/main_scene.tscn) |
| 登录界面 | `scenes/auth_scene.tscn` | [UI/Windows/LoginWindow.tscn](UI/Windows/LoginWindow.tscn) |
| 配置文件 | `data/configs/` | [Config/](Config/) |
| 工具类 | `core/utils/` | [Utils/](Utils/) |

详细的重构说明请查看：[REFACTORING.md](REFACTORING.md)

### 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) 文件了解详情

---

## 🎯 项目状态

- ✅ 基础架构搭建完成
- ✅ 项目结构重构完成（2025-12-31）
- ✅ 用户认证系统完成
- ✅ API接口集成完成
- ✅ 测试体系建立完成
- ✅ 文档体系完善
- 🚧 游戏核心玩法开发中
- 🚧 更多功能模块开发中

**最后更新**: 2025-12-31

**重要更新**: 项目已完成架构重构，采用新的分层结构。详见 [REFACTORING.md](REFACTORING.md)