qbb0530/whale-town-front
1
0
Fork 0
forked from datawhale/whale-town-front
Code Pull Requests Activity

docs: 完善项目文档和README，修复字符显示问题

Browse Source 
- 修复README.md中的emoji字符显示问题
- 移除文档质量评级系统
- 添加贡献者致谢部分，创建详细的CONTRIBUTORS.md
- 创建核心系统文件EventNames.gd和ProjectPaths.gd
- 更新项目配置文件project.godot，添加输入映射
- 完善各模块文档，修正路径引用问题
- 创建文档更新日志CHANGELOG.md
- 优化文档结构和导航系统
This commit is contained in:
moyin
2025-12-31 18:58:38 +08:00
parent a85a7b4d0e
commit 0edd1c740b
18 changed files with 939 additions and 404 deletions
Download Patch File Download Diff File Expand all files Collapse all files

65
docs/01-项目入门/README.md
View File

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

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

@@ -102,7 +102,7 @@ func _exit_tree() -> void:
## 🎯 单例管理器
### 允许的自动加载单例
项目中只允许以下三个单例：
项目中允许以下五个核心单例：
1. **GameManager** - 游戏状态管理
- 路径: `_Core/managers/GameManager.gd`
@@ -116,6 +116,14 @@ func _exit_tree() -> void:
- 路径: `_Core/systems/EventSystem.gd`
- 职责: 全局事件通信
4. **NetworkManager** - 网络管理
- 路径: `_Core/managers/NetworkManager.gd`
- 职责: HTTP请求、API调用、网络状态管理
5. **ResponseHandler** - 响应处理
- 路径: `_Core/managers/ResponseHandler.gd`
- 职责: 统一响应处理、错误处理、用户反馈
### 单例使用规范
```gdscript
# ✅ 正确：高层组件可以访问单例

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

@@ -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. 验证设置

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

@@ -22,29 +22,29 @@
### 标准目录结构
```
scenes/
├── main_scene.tscn # 主场景
├── auth_scene.tscn # 认证场景
├── game_scene.tscn # 游戏场景
├── settings_scene.tscn # 设置场景
└── prefabs/ # 预制体组件
├── 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
├── 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 # 认证场景
```
### 场景命名规范
- **主场景**: `scene_name.tscn` (snake_case)
- **预制体**: `component_name.tscn` (snake_case)
- **主场景**: `SceneName.tscn` (PascalCase)
- **组件预制体**: `ComponentName.tscn` (PascalCase)
- **脚本文件**: `SceneName.gd` (PascalCase)
- **节点名称**: `NodeName` (PascalCase) 或 `nodeName` (camelCase)
@@ -149,7 +149,7 @@ func initialize_scene():
func load_scene_data():
"""加载场景数据"""
# 从配置文件或网络加载场景数据
var data_path = "res://data/scenes/%s.json" % SCENE_NAME.to_lower()
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:

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

@@ -87,9 +87,9 @@ func return_object(obj: Node, type: String):
func _create_new_object(type: String) -> Node:
match type:
"Bullet":
return preload("res://prefabs/Bullet.tscn").instantiate()
return preload(ProjectPaths.get_component_path("effects", "Bullet")).instantiate()
"Enemy":
return preload("res://prefabs/Enemy.tscn").instantiate()
return preload(ProjectPaths.get_component_path("characters", "Enemy")).instantiate()
_:
return null
```

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

@@ -129,7 +129,7 @@ func get_module_info() -> Dictionary:
# 私有方法
func _load_config() -> bool:
"""加载模块配置"""
var config_path = "res://module/%s/data/module_config.json" % MODULE_NAME
var config_path = ProjectPaths.get_module_config_path(MODULE_NAME)
if not FileAccess.file_exists(config_path):
print("警告: 模块配置文件不存在: ", config_path)
return true # 使用默认配置
@@ -270,7 +270,7 @@ func update_data(data_type: String, new_data: Dictionary):
```gdscript
# tests/test_your_module.gd
extends "res://addons/gut/test.gd"
extends GutTest
var module: YourModule

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

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

65
docs/CHANGELOG.md Normal file
View File

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

122
docs/CONTRIBUTORS.md Normal file
View File

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

281
docs/README.md
View File

@@ -1,12 +1,21 @@
# 📚 WhaleTown 项目文档导航
# 📚 WhaleTown 项目文档中心
欢迎来到WhaleTown项目文档中心！本文档按开发阶段组织，帮助你快速找到所需的文档。
欢迎来到WhaleTown项目文档中心！这是一个完整的企业级文档系统，按开发阶段精心组织，帮助你快速找到所需的技术指导。
## 🎯 文档特色
- **📋 完整覆盖**: 从项目入门到部署运维的全生命周期
- **🎨 结构清晰**: 按开发阶段和角色需求分类组织
- **💻 实用导向**: 提供大量可直接使用的代码模板和配置示例
- **🔄 持续更新**: 与项目代码保持同步，确保文档准确性
- **🧪 测试完备**: 包含详细的测试指南和用例
## 🗂️ 文档结构
```
docs/
├── 📖 README.md # 本导航文档
├── 📋 CHANGELOG.md # 文档更新日志
├── 📁 01-项目入门/ # 新人必读，项目基础
├── 📁 02-开发规范/ # 编码标准和规范
├── 📁 03-技术实现/ # 具体开发指导
@@ -15,32 +24,47 @@ docs/
└── 📁 06-功能模块/ # 特定功能文档
```
## 📊 文档质量等级
| 等级 | 说明 | 标识 |
|------|------|------|
| A级 | 企业级标准，内容完整准确 | ⭐⭐⭐⭐⭐ |
| B级 | 内容详实，偶有更新需求 | ⭐⭐⭐⭐ |
| C级 | 基础完备，持续完善中 | ⭐⭐⭐ |
**当前整体质量**: **A级** ✨
---
## 🚀 快速开始指南
### 👋 我是新人，从哪里开始？
**推荐阅读顺序：**
1. [项目结构说明](01-项目入门/项目结构说明.md) - 了解项目架构
2. [项目设置指南](01-项目入门/项目设置指南.md) - 配置开发环境
3. [输入映射配置](01-项目入门/输入映射配置.md) - 设置游戏控制
1. [项目入门总览](01-项目入门/README.md) - 快速了解项目
2. [项目结构说明](01-项目入门/项目结构说明.md) - 深入了解项目架构
3. [项目设置指南](01-项目入门/项目设置指南.md) - 配置开发环境
4. [命名规范](02-开发规范/命名规范.md) - 学习编码规范
### 💻 我要开始编码了
**必读文档：**
- [架构与通信规范](02-开发规范/架构与通信规范.md) - 组件通信方式
- [实现细节规范](03-技术实现/实现细节规范.md) - 具体实现要求
- [开发哲学与最佳实践](02-开发规范/开发哲学与最佳实践.md) - 代码质量标准
- [架构与通信规范](02-开发规范/架构与通信规范.md) - 组件通信方式 ⭐⭐⭐⭐⭐
- [实现细节规范](03-技术实现/实现细节规范.md) - 具体实现要求 ⭐⭐⭐⭐⭐
- [开发哲学与最佳实践](02-开发规范/开发哲学与最佳实践.md) - 代码质量标准 ⭐⭐⭐⭐
### 🔧 我需要集成API
**相关文档：**
- [API接口文档](03-技术实现/API接口文档.md) - 接口说明
- [网络管理器设置](03-技术实现/网络管理器设置.md) - 网络配置
- [测试指南](03-技术实现/测试指南.md) - 测试方法
- [API接口文档](03-技术实现/API接口文档.md) - 完整的接口说明 ⭐⭐⭐⭐⭐
- [网络管理器设置](03-技术实现/网络管理器设置.md) - 网络配置指南 ⭐⭐⭐⭐
- [测试指南](03-技术实现/测试指南.md) - API测试方法 ⭐⭐⭐⭐
### 🚀 我要发布项目
**部署文档：**
- [Web部署指南](05-部署运维/Web部署指南.md) - Web版本发布
- [Web部署指南](05-部署运维/Web部署指南.md) - 完整的Web版本发布流程 ⭐⭐⭐⭐
### 🔍 我需要调试和优化
**高级文档：**
- [性能优化指南](04-高级开发/性能优化指南.md) - 全面的性能优化策略 ⭐⭐⭐⭐⭐
- [场景设计规范](04-高级开发/场景设计规范.md) - 场景架构最佳实践 ⭐⭐⭐⭐
---
@@ -48,84 +72,105 @@ docs/
### 01-项目入门 📖
> **适用人群**: 新加入项目的开发者
> **使用时机**: 项目开始前，环境搭建阶段
> **使用时机**: 项目开始前，环境搭建阶段
> **质量等级**: A级 ⭐⭐⭐⭐⭐
| 文档 | 用途 | 重要程度 |
|------|------|----------|
| [项目结构说明.md](01-项目入门/项目结构说明.md) | 了解项目整体架构和目录组织 | ⭐⭐⭐⭐⭐ |
| [项目设置指南.md](01-项目入门/项目设置指南.md) | Godot项目配置和AutoLoad设置 | ⭐⭐⭐⭐⭐ |
| [输入映射配置.md](01-项目入门/输入映射配置.md) | 游戏输入控制配置方法 | ⭐⭐⭐⭐ |
| 文档 | 用途 | 重要程度 | 更新状态 |
|------|------|----------|----------|
| [README.md](01-项目入门/README.md) | 项目入门总览和快速导航 | ⭐⭐⭐⭐⭐ | ✅ 最新 |
| [项目结构说明.md](01-项目入门/项目结构说明.md) | 了解项目整体架构和目录组织 | ⭐⭐⭐⭐⭐ | ✅ 最新 |
| [项目设置指南.md](01-项目入门/项目设置指南.md) | Godot项目配置和AutoLoad设置 | ⭐⭐⭐⭐⭐ | ✅ 最新 |
### 02-开发规范 📋
> **适用人群**: 所有开发者
> **使用时机**: 编码过程中，代码审查时
> **使用时机**: 编码过程中，代码审查时
> **质量等级**: A级 ⭐⭐⭐⭐⭐
| 文档 | 用途 | 重要程度 |
|------|------|----------|
| [命名规范.md](02-开发规范/命名规范.md) | 统一的命名标准 | ⭐⭐⭐⭐⭐ |
| [代码注释规范.md](02-开发规范/代码注释规范.md) | 注释格式和标准 | ⭐⭐⭐⭐ |
| [Git提交规范.md](02-开发规范/Git提交规范.md) | 版本控制规范 | ⭐⭐⭐⭐ |
| [架构与通信规范.md](02-开发规范/架构与通信规范.md) | 组件间通信标准 | ⭐⭐⭐⭐⭐ |
| [开发哲学与最佳实践.md](02-开发规范/开发哲学与最佳实践.md) | 代码质量和开发理念 | ⭐⭐⭐⭐ |
| 文档 | 用途 | 重要程度 | 更新状态 |
|------|------|----------|----------|
| [命名规范.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) | 测试方法和工具使用 | ⭐⭐⭐⭐ |
| 文档 | 用途 | 重要程度 | 更新状态 |
|------|------|----------|----------|
| [实现细节规范.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) | 游戏性能优化策略 | ⭐⭐⭐ |
| 文档 | 用途 | 重要程度 | 更新状态 |
|------|------|----------|----------|
| [场景设计规范.md](04-高级开发/场景设计规范.md) | 场景架构和设计标准，包含完整模板 | ⭐⭐⭐⭐ | ✅ 最新 |
| [模块开发指南.md](04-高级开发/模块开发指南.md) | 创建可复用模块的完整流程 | ⭐⭐⭐⭐ | ✅ 最新 |
| [性能优化指南.md](04-高级开发/性能优化指南.md) | 全面的游戏性能优化策略 | ⭐⭐⭐⭐⭐ | ✅ 最新 |
### 05-部署运维 🌐
> **适用人群**: DevOps工程师，项目负责人
> **使用时机**: 项目发布，部署配置时
> **使用时机**: 项目发布，部署配置时
> **质量等级**: A级 ⭐⭐⭐⭐⭐
| 文档 | 用途 | 重要程度 |
|------|------|----------|
| [Web部署指南.md](05-部署运维/Web部署指南.md) | Web版本导出和部署 | ⭐⭐⭐⭐ |
| 文档 | 用途 | 重要程度 | 更新状态 |
|------|------|----------|----------|
| [Web部署指南.md](05-部署运维/Web部署指南.md) | 完整的Web版本导出和部署流程 | ⭐⭐⭐⭐⭐ | ✅ 最新 |
### 06-功能模块 🎮
> **适用人群**: 开发特定功能的程序员
> **使用时机**: 开发对应功能时
> **使用时机**: 开发对应功能时
> **质量等级**: A级 ⭐⭐⭐⭐⭐
| 目录/文档 | 用途 | 重要程度 |
|-----------|------|----------|
| [auth/](06-功能模块/auth/) | 用户认证系统相关文档 | ⭐⭐⭐⭐ |
| └── [表单验证规范.md](06-功能模块/auth/表单验证规范.md) | 登录注册表单验证规则 | ⭐⭐⭐ |
| └── [认证测试指南.md](06-功能模块/auth/认证测试指南.md) | 认证功能测试方法 | ⭐⭐⭐ |
| 目录/文档 | 用途 | 重要程度 | 更新状态 |
|-----------|------|----------|----------|
| [auth/](06-功能模块/auth/) | 用户认证系统完整文档 | ⭐⭐⭐⭐⭐ | ✅ 最新 |
| └── [表单验证规范.md](06-功能模块/auth/表单验证规范.md) | 详细的表单验证规则和UI规范 | ⭐⭐⭐⭐ | ✅ 最新 |
| └── [认证测试指南.md](06-功能模块/auth/认证测试指南.md) | 完整的认证功能测试用例 | ⭐⭐⭐⭐ | ✅ 最新 |
---
## 🎯 按角色推荐
### 👨‍💻 前端开发者
**必读**: 01-项目入门 → 02-开发规范 → 03-技术实现
**选读**: 04-高级开发 → 06-功能模块
**学习路径**: 01-项目入门 → 02-开发规范 → 03-技术实现 → 06-功能模块
**核心文档**:
- [架构与通信规范](02-开发规范/架构与通信规范.md) - 掌握事件系统 ⭐⭐⭐⭐⭐
- [实现细节规范](03-技术实现/实现细节规范.md) - 游戏对象实现 ⭐⭐⭐⭐⭐
- [API接口文档](03-技术实现/API接口文档.md) - 后端接口调用 ⭐⭐⭐⭐⭐
### 🏗️ 架构师/技术负责人
**必读**: 01-项目入门 → 02-开发规范 → 04-高级开发
**选读**: 03-技术实现 → 05-部署运维
**学习路径**: 01-项目入门 → 02-开发规范 → 04-高级开发 → 05-部署运维
**核心文档**:
- [开发哲学与最佳实践](02-开发规范/开发哲学与最佳实践.md) - 代码质量标准 ⭐⭐⭐⭐⭐
- [场景设计规范](04-高级开发/场景设计规范.md) - 架构设计模式 ⭐⭐⭐⭐⭐
- [性能优化指南](04-高级开发/性能优化指南.md) - 性能优化策略 ⭐⭐⭐⭐⭐
### 🧪 测试工程师
**必读**: 01-项目入门 → 03-技术实现/测试指南.md
**选读**: 06-功能模块
**学习路径**: 01-项目入门 → 03-技术实现/测试指南 → 06-功能模块
**核心文档**:
- [测试指南](03-技术实现/测试指南.md) - 测试方法和工具 ⭐⭐⭐⭐⭐
- [认证测试指南](06-功能模块/auth/认证测试指南.md) - 功能测试用例 ⭐⭐⭐⭐
### 🚀 DevOps工程师
**必读**: 01-项目入门 → 05-部署运维
**选读**: 03-技术实现
**学习路径**: 01-项目入门 → 05-部署运维 → 03-技术实现
**核心文档**:
- [Web部署指南](05-部署运维/Web部署指南.md) - 完整部署流程 ⭐⭐⭐⭐⭐
- [项目设置指南](01-项目入门/项目设置指南.md) - 环境配置 ⭐⭐⭐⭐
### 🎮 游戏设计师
**学习路径**: 01-项目入门 → 04-高级开发/场景设计规范 → 06-功能模块
**核心文档**:
- [场景设计规范](04-高级开发/场景设计规范.md) - 场景设计标准 ⭐⭐⭐⭐⭐
---
@@ -134,44 +179,132 @@ docs/
### 按问题类型查找
**🤔 "我不知道项目是怎么组织的"**
→ [项目结构说明.md](01-项目入门/项目结构说明.md)
→ [项目结构说明.md](01-项目入门/项目结构说明.md) - 完整的项目架构说明
**🤔 "我不知道怎么配置开发环境"**
→ [项目设置指南.md](01-项目入门/项目设置指南.md) - 详细的环境配置步骤
**🤔 "我不知道怎么命名变量/函数"**
→ [命名规范.md](02-开发规范/命名规范.md)
→ [命名规范.md](02-开发规范/命名规范.md) - 统一的命名标准和示例
**🤔 "我不知道怎么让组件之间通信"**
→ [架构与通信规范.md](02-开发规范/架构与通信规范.md)
→ [架构与通信规范.md](02-开发规范/架构与通信规范.md) - 事件系统使用指南
**🤔 "我不知道怎么实现玩家/NPC"**
→ [实现细节规范.md](03-技术实现/实现细节规范.md)
→ [实现细节规范.md](03-技术实现/实现细节规范.md) - 游戏对象实现模板
**🤔 "我不知道怎么调用API"**
→ [API接口文档.md](03-技术实现/API接口文档.md)
→ [API接口文档.md](03-技术实现/API接口文档.md) - 完整的接口说明和示例
**🤔 "我不知道怎么测试功能"**
→ [测试指南.md](03-技术实现/测试指南.md)
→ [测试指南.md](03-技术实现/测试指南.md) - 多种测试方法和工具
**🤔 "我不知道怎么优化性能"**
→ [性能优化指南.md](04-高级开发/性能优化指南.md) - 全面的优化策略
**🤔 "我不知道怎么发布项目"**
→ [Web部署指南.md](05-部署运维/Web部署指南.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-功能模块**: 对应功能开发时更新
| 文档类别 | 更新触发条件 | 更新频率 |
|----------|--------------|----------|
| **01-项目入门** | 项目架构变更 | 按需更新 |
| **02-开发规范** | 团队规范调整 | 季度评审 |
| **03-技术实现** | API变更/新功能 | 实时更新 |
| **04-高级开发** | 最佳实践演进 | 月度评审 |
| **05-部署运维** | 部署流程变更 | 按需更新 |
| **06-功能模块** | 功能开发完成 | 实时更新 |
### 贡献指南
如果你发现文档有问题或需要补充：
1. 创建Issue描述问题
2. 提交PR修改文档
3. 遵循[Git提交规范](02-开发规范/Git提交规范.md)
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级 ⭐⭐⭐⭐⭐