qbb0530/whale-town-front
1
0
Fork 0
forked from datawhale/whale-town-front
Code Pull Requests Activity
Files
749e2c257b4e60135607bbbe0db35e0ddf76f282
whale-town-front/docs/README.md
moyin 0edd1c740b docs: 完善项目文档和README，修复字符显示问题 
- 修复README.md中的emoji字符显示问题
- 移除文档质量评级系统
- 添加贡献者致谢部分，创建详细的CONTRIBUTORS.md
- 创建核心系统文件EventNames.gd和ProjectPaths.gd
- 更新项目配置文件project.godot，添加输入映射
- 完善各模块文档，修正路径引用问题
- 创建文档更新日志CHANGELOG.md
- 优化文档结构和导航系统
2025-12-31 18:58:38 +08:00

310 lines
14 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 📚 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级 ⭐⭐⭐⭐⭐
View Git Blame Copy Permalink