datawhale/whale-town-front
3
2
Fork 2
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: 文档中文化和清理

Browse Source 
新增:
- 开发规范.md (翻译自CLAUDE.md)

 重命名为中文:
- project_structure.md  项目结构说明.md
- naming_convention.md  命名规范.md
- code_comment_guide.md  代码注释规范.md
- git_commit_guide.md  Git提交规范.md
- api-documentation.md  API接口文档.md
- network_manager_setup.md  网络管理器设置.md
- setup.md  项目设置指南.md
- testing_guide.md  测试指南.md
- web_deployment_guide.md  Web部署指南.md
- module_development.md  模块开发指南.md
- performance_optimization.md  性能优化指南.md
- scene_design.md  场景设计规范.md
- auth/form_validation.md  auth/表单验证规范.md
- auth/testing_guide.md  auth/认证测试指南.md

 删除总结性文档:
- final_update_summary.md
- web_deployment_changelog.md
- CLAUDE.md
This commit is contained in:
moyin
2025-12-31 17:45:04 +08:00
parent 190b6c9a66
commit 60edcc9868
19 changed files with 124 additions and 890 deletions
Download Patch File Download Diff File Expand all files Collapse all files

96
CLAUDE.md
View File

@@ -1,96 +0,0 @@
# 🎯 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()

344
README.md
View File

@@ -23,19 +23,13 @@ Whale Town 是一个功能完整的像素游戏前端客户端，采用模块化
## 🚀 快速开始
<<<<<<< HEAD
### 📋 环境要求
- **Godot Engine** >= 4.5.0 (推荐 4.5.1)
- **Godot Engine** >= 4.5.0 (推荐 4.5.1)(https://godotengine.org/download)
- **Python** >= 3.7.0 (用于API测试，可选)
- **Git** >= 2.0.0
### 🛠️ 安装与运行
=======
### 环境要求
- [Godot Engine 4.5+](https://godotengine.org/download)
- Python 3.7+ (用于API测试和Web服务器)
>>>>>>> whale-town-front/main
```bash
# 1. 克隆项目
@@ -49,333 +43,12 @@ cd whale-town
# 按F5或点击"运行"按钮启动游戏
```
<<<<<<< HEAD
🎉 **游戏启动成功！** 进入认证界面开始体验
### 🧪 快速测试
```bash
# API接口测试
=======
### 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连通性
>>>>>>> whale-town-front/main
python tests/api/simple_api_test.py
# 完整功能测试
@@ -392,7 +65,6 @@ python tests/api/api_test.py --verbose
## 🎓 新开发者指南
<<<<<<< HEAD
### 第一步：了解项目规范 📚
**⚠️ 重要：在开始开发前，请务必阅读以下文档**
@@ -703,17 +375,3 @@ Made with ❤️ by the Whale Town Team
[⭐ Star](https://gitea.xinghangee.icu/datawhale/whale-town) | [🍴 Fork](https://gitea.xinghangee.icu/datawhale/whale-town/fork) | [📖 Docs](./docs/) | [🐛 Issues](https://gitea.xinghangee.icu/datawhale/whale-town/issues)
</div>
=======
- ✅ 基础架构搭建完成
- ✅ 项目结构重构完成（2025-12-31）
- ✅ 用户认证系统完成
- ✅ API接口集成完成
- ✅ 测试体系建立完成
- ✅ 文档体系完善
- 🚧 游戏核心玩法开发中
- 🚧 更多功能模块开发中
**最后更新**: 2025-12-31
**重要更新**: 项目已完成架构重构，采用新的分层结构。详见 [REFACTORING.md](REFACTORING.md)
>>>>>>> whale-town-front/main

0
docs/api-documentation.md → docs/API接口文档.md
View File

0
docs/git_commit_guide.md → docs/Git提交规范.md
View File

0
docs/web_deployment_guide.md → docs/Web部署指南.md
View File

0
docs/auth/form_validation.md → docs/auth/表单验证规范.md
View File

0
docs/auth/testing_guide.md → docs/auth/认证测试指南.md
View File

251
docs/final_update_summary.md
View File

@@ -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规范！** 🚀

200
docs/web_deployment_changelog.md
View File

@@ -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

0
docs/code_comment_guide.md → docs/代码注释规范.md
View File

0
docs/naming_convention.md → docs/命名规范.md
View File

0
docs/scene_design.md → docs/场景设计规范.md
View File

0
docs/performance_optimization.md → docs/性能优化指南.md
View File

0
docs/module_development.md → docs/模块开发指南.md
View File

0
docs/testing_guide.md → docs/测试指南.md
View File

0
docs/network_manager_setup.md → docs/网络管理器设置.md
View File

0
docs/project_structure.md → docs/项目结构说明.md
View File

0
docs/setup.md → docs/项目设置指南.md
View File

123
开发规范.md Normal file
View File

@@ -0,0 +1,123 @@
# 🎯 WhaleTown 项目开发规范
## 1. 项目愿景与背景
- **项目名称**: "WhaleTown" - 一个2D俯视角像素风RPG游戏
- **引擎**: Godot 4.2+ (严格禁止使用Godot 3.x语法)
- **架构**: 严格分层架构：`_Core`(框架层)、`Scenes`(游戏层)、`UI`(界面层)
- **核心原则**: "信号向上，调用向下"。通过`EventSystem`实现高度解耦
## 2. 🛠 命令参考与设置
- **输入映射 (必需配置)**:
- `move_left`, `move_right`, `move_up`, `move_down` (WASD / 方向键)
- `interact` (E键 / 空格键)
- `pause` (ESC键)
- **运行游戏**: `godot --path .`
- **运行测试 (GUT)**: `godot --headless -s addons/gut/gut_cmdline.gd -gdir=res://tests/ -ginclude_subdirs`
- **初始化结构**: `mkdir -p _Core/managers _Core/systems Scenes/Maps Scenes/Entities Scenes/Components UI/Windows UI/HUD Assets/Sprites tests/unit tests/integration`
## 3. 📂 文件路径规则 (严格小写)
*注意：根目录文件夹必须小写。脚本和场景必须放在一起。*
- **核心管理器**: `_Core/managers/[Name].gd`
- **核心系统**: `_Core/systems/[Name].gd`
- **实体**: `Scenes/Entities/[EntityName]/[EntityName].tscn` (脚本`.gd`放在同一文件夹)
- **地图**: `Scenes/Maps/[map_name].tscn`
- **组件**: `Scenes/Components/[ComponentName].gd` (可复用逻辑节点)
- **UI窗口**: `UI/Windows/[WindowName].tscn`
- **测试**: `tests/[unit|integration]/test_[name].gd` (文件夹名为小写`tests`)
## 4. 📋 编码标准 (必须遵守)
- **类型安全**: 始终使用严格静态类型：`var speed: float = 100.0`, `func _ready() -> void`
- **命名约定**:
- 每个脚本顶部必须有`class_name PascalCase`
- 变量/函数：`snake_case`。常量：`SCREAMING_SNAKE_CASE`
- 私有成员：使用下划线前缀`_` (例如：`var _health: int`)
- **节点访问**: 对UI和内部场景组件使用`%UniqueName`
- **信号**: 使用"信号向上，调用向下"原则。父节点调用子节点方法；子节点发出信号
- **禁止模式**:
- ❌ 禁止使用`yield()` -> 使用`await`
- ❌ 禁止在`_process`中使用`get_node()` -> 使用`@onready`缓存
- ❌ 禁止线性过滤 -> 所有Sprite2D/TileMap资源必须使用**最近邻**过滤
## 5. 🏛 架构与通信
- **事件系统**: 使用`_Core/systems/EventSystem.gd`进行跨模块消息传递
- **事件注册**: 在`_Core/EventNames.gd`中使用`class_name EventNames`
```gdscript
class_name EventNames
const PLAYER_MOVED = "player_moved"
const INTERACT_PRESSED = "interact_pressed"
const NPC_TALKED = "npc_talked"
```
- **单例**: 只允许GameManager、SceneManager、EventSystem作为自动加载
- **解耦**: 底层实体不得直接引用GameManager。使用事件系统
## 6. 🏗 实现细节
- **玩家**: 使用CharacterBody2D。必须包含Camera2D，设置`position_smoothing_enabled = true`
- **NPC/交互物**: 使用名为InteractionArea的Area2D。通过EventSystem触发
- **TileMap图层**:
- 图层0：地面 (无碰撞)
- 图层1：障碍物 (启用物理层)
- 图层2：装饰 (启用Y排序)
- **相机**: 必须通过`TileMap.get_used_rect()`自动计算边界
## 7. 🧪 测试要求 (强制性)
- **覆盖率**: `_Core/`中的每个管理器/系统都必须有GUT测试
- **命名**: 测试文件必须以`test_`开头并继承`GutTest`
- **示例**:
```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. 🧘 开发哲学
- **流畅体验**: 每个交互(UI弹窗、NPC对话)都必须有Tween动画占位符
- **零魔法数字**: 所有速度/计时器必须使用`@export`或在`Config/`中定义
- **简洁性**: 如果一个函数做两件事，就拆分它
- **隐藏逻辑**: 隐藏的逻辑(如ResponseHandler.gd)必须和HUD一样干净
## 9. 📝 代码模板 (实体模式)
```gdscript
extends CharacterBody2D
class_name Player
# 1. 导出变量与常量
@export var move_speed: float = 200.0
# 2. 节点引用
@onready var sprite: Sprite2D = %Sprite2D
# 3. 生命周期
func _physics_process(delta: float) -> void:
_move(delta)
# 4. 私有方法
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()
```
## 10. 🎨 UI设计规范
- **响应式布局**: 使用Anchor和Margin实现自适应
- **主题统一**: 所有UI组件使用统一主题资源
- **动画效果**: 界面切换必须有过渡动画
- **无障碍支持**: 支持键盘导航
## 11. 🔧 性能优化
- **对象池**: 频繁创建销毁的对象使用对象池
- **视锥剔除**: 只渲染可见区域的对象
- **批量处理**: 合并相似的渲染调用
- **内存管理**: 及时释放不需要的资源
## 12. 📚 最佳实践
- **模块化**: 功能拆分为独立模块
- **可测试**: 设计易于测试的代码结构
- **文档化**: 为复杂逻辑添加详细注释
- **版本控制**: 遵循Git提交规范
---
**记住：代码质量是游戏成功的基础！**