docs: 重构文档结构和组织

- 重新组织docs目录结构，按功能模块分类 - 新增deployment和development目录 - 更新API文档结构 - 添加客户端README文档 - 移除过时的文档文件
2025-12-24 18:04:14 +08:00
parent 032c97a1fc
commit 85d488a508
20 changed files with 2416 additions and 1763 deletions
--- a/docs/README.md
+++ b/docs/README.md
@@ -1,139 +1,107 @@
-# 项目文档
+# 📚 Pixel Game Server 文档中心

-本目录包含了像素游戏服务器的完整文档。
+欢迎来到 Whale Town 项目文档中心！这里包含了项目的完整文档，帮助你快速了解和使用项目。

-## 文档结构
+## 📖 **文档导航**

-### 📁 api/
-API接口相关文档，包含：
- **api-documentation.md** - 详细的API接口文档
- **openapi.yaml** - OpenAPI 3.0规范文件
- **postman-collection.json** - Postman测试集合
- **README.md** - API文档使用说明
+### 🚀 **快速开始**
+- [项目概述](../README.md) - 项目介绍和快速开始指南
+- [架构设计](ARCHITECTURE.md) - 系统架构和设计理念

-### 📁 systems/
-系统设计文档，包含：
- **logger/** - 日志系统文档
- **user-auth/** - 用户认证系统文档
+### 🔌 **API文档**
+- [API接口文档](api/api-documentation.md) - 完整的API接口说明（17个接口）
+- [API状态码](API_STATUS_CODES.md) - HTTP状态码和错误代码说明
+- [OpenAPI规范](api/openapi.yaml) - 机器可读的API规范文件
+- [API使用指南](api/README.md) - API文档使用说明

-### 📄 其他文档
- **AI辅助开发规范指南.md** - AI开发规范
- **backend_development_guide.md** - 后端开发指南
- **git_commit_guide.md** - Git提交规范
- **naming_convention.md** - 命名规范
- **nestjs_guide.md** - NestJS开发指南
- **日志系统详细说明.md** - 日志系统说明
+### 💻 **开发指南**
+- [后端开发指南](development/backend_development_guide.md) - 后端开发规范和最佳实践
+- [NestJS指南](development/nestjs_guide.md) - NestJS框架使用指南
+- [命名规范](development/naming_convention.md) - 代码命名规范
+- [Git提交规范](development/git_commit_guide.md) - Git提交消息规范
+- [AI辅助开发规范](development/AI辅助开发规范指南.md) - AI辅助开发最佳实践
+- [测试指南](development/TESTING.md) - 测试策略和规范

-## 如何使用
+### 🚀 **部署运维**
+- [部署指南](deployment/DEPLOYMENT.md) - 生产环境部署说明

-### 1. 启动服务器并查看Swagger文档
+### 📋 **项目管理**
+- [贡献指南](CONTRIBUTORS.md) - 如何参与项目贡献
+- [文档清理说明](DOCUMENT_CLEANUP.md) - 文档维护记录

-```bash
-# 启动开发服务器
-pnpm run dev
+## 🏗️ **文档结构说明**

-# 访问Swagger UI
-# 浏览器打开: http://localhost:3000/api-docs
+```
+docs/
+├── README.md                    # 📚 文档中心首页
+├── ARCHITECTURE.md              # 🏗️ 架构文档
+├── API_STATUS_CODES.md          # 📋 API状态码
+├── CONTRIBUTORS.md              # 🤝 贡献指南
+├── DOCUMENT_CLEANUP.md          # 📝 文档清理说明
+│
+├── api/                         # 🔌 API文档
+│   ├── api-documentation.md     # API接口文档
+│   ├── openapi.yaml            # OpenAPI规范
+│   ├── postman-collection.json # Postman测试集合
+│   └── README.md               # API文档说明
+│
+├── development/                 # 💻 开发指南
+│   ├── backend_development_guide.md
+│   ├── nestjs_guide.md
+│   ├── naming_convention.md
+│   ├── git_commit_guide.md
+│   ├── AI辅助开发规范指南.md
+│   └── TESTING.md
+│
+└── deployment/                  # 🚀 部署文档
+    └── DEPLOYMENT.md
 ```

-### 2. 使用Postman测试API
+## 🎯 **文档特色**

-1. 打开Postman
-2. 点击 Import 按钮
-3. 选择 `docs/postman-collection.json` 文件
-4. 导入后即可看到所有API接口
-5. 修改环境变量 `baseUrl` 为你的服务器地址（默认：http://localhost:3000）
+### ✨ **业务功能模块化**
+文档结构与代码架构保持一致，按业务功能组织：
+- **用户认证模块** - 登录、注册、密码管理
+- **用户管理模块** - 状态管理、批量操作
+- **管理员模块** - 后台管理、权限控制
+- **安全模块** - 频率限制、维护模式

-### 3. 使用OpenAPI规范
+### 📊 **完整API覆盖**
+- **17个API接口** - 涵盖所有业务功能
+- **交互式文档** - Swagger UI实时测试
+- **标准化规范** - OpenAPI 3.0标准
+- **测试集合** - Postman一键导入

-#### 在Swagger Editor中查看
-1. 访问 [Swagger Editor](https://editor.swagger.io/)
-2. 将 `docs/openapi.yaml` 的内容复制粘贴到编辑器中
-3. 即可查看可视化的API文档
+### 🔧 **开发者友好**
+- **规范指导** - 命名、提交、开发规范
+- **AI辅助** - 提升开发效率的AI使用指南
+- **测试覆盖** - 140个测试用例全覆盖
+- **部署就绪** - 生产环境部署指南

-#### 生成客户端SDK
-```bash
-# 使用swagger-codegen生成JavaScript客户端
-swagger-codegen generate -i docs/openapi.yaml -l javascript -o ./client-sdk
+## 📝 **文档维护原则**

-# 使用openapi-generator生成TypeScript客户端
-openapi-generator generate -i docs/openapi.yaml -g typescript-axios -o ./client-sdk
-```
+### ✅ **保留的文档类型**
+- **长期有用**：对整个项目生命周期都有价值的文档
+- **参考价值**：开发、部署、维护时需要查阅的文档
+- **规范指南**：团队协作和代码质量保证的规范

-## API接口概览
+### ❌ **不保留的文档类型**
+- **阶段性文档**：只在特定开发阶段有用的文档
+- **临时记录**：会议记录、临时决策等
+- **过时信息**：已经不适用的旧版本文档

-| 接口 | 方法 | 路径 | 描述 |
-|------|------|------|------|
-| 用户登录 | POST | /auth/login | 支持用户名、邮箱或手机号登录 |
-| 用户注册 | POST | /auth/register | 创建新用户账户 |
-| GitHub OAuth | POST | /auth/github | 使用GitHub账户登录或注册 |
-| 发送验证码 | POST | /auth/forgot-password | 发送密码重置验证码 |
-| 重置密码 | POST | /auth/reset-password | 使用验证码重置密码 |
-| 修改密码 | PUT | /auth/change-password | 修改用户密码 |
+### 🔄 **文档更新策略**
+- **及时更新**：功能变更时同步更新相关文档
+- **版本控制**：重要变更记录版本历史
+- **定期审查**：定期检查文档的准确性和有效性

-## 快速测试
+## 🤝 **如何贡献文档**

-### 使用cURL测试登录接口
+1. **发现问题**：发现文档错误或缺失时，请提交Issue
+2. **改进文档**：按照项目规范提交Pull Request
+3. **新增文档**：新功能开发时同步编写相关文档
+4. **审查文档**：参与文档审查，确保质量和准确性

-```bash
-# 测试用户登录
-curl -X POST http://localhost:3000/auth/login \
-  -H "Content-Type: application/json" \
-  -d '{
-    "identifier": "testuser",
-    "password": "password123"
-  }'
+---

-# 测试用户注册
-curl -X POST http://localhost:3000/auth/register \
-  -H "Content-Type: application/json" \
-  -d '{
-    "username": "newuser",
-    "password": "password123",
-    "nickname": "新用户",
-    "email": "newuser@example.com"
-  }'
-```
-
-### 使用JavaScript测试
-
-```javascript
-// 用户登录
-const response = await fetch('http://localhost:3000/auth/login', {
-  method: 'POST',
-  headers: {
-    'Content-Type': 'application/json',
-  },
-  body: JSON.stringify({
-    identifier: 'testuser',
-    password: 'password123'
-  })
-});
-
-const data = await response.json();
-console.log(data);
-```
-
-## 注意事项
-
-1. **开发环境**: 当前配置适用于开发环境，生产环境需要使用HTTPS
-2. **认证**: 实际应用中应实现JWT认证机制
-3. **限流**: 建议对认证接口实施限流策略
-4. **验证码**: 示例中返回验证码仅用于演示，生产环境不应返回
-5. **错误处理**: 建议实现统一的错误处理机制
-
-## 更新文档
-
-当API接口发生变化时，请同步更新以下文件：
-1. 更新DTO类的Swagger装饰器
-2. 更新 `api-documentation.md`
-3. 更新 `openapi.yaml`
-4. 更新 `postman-collection.json`
-5. 重新生成Swagger文档
-
-## 相关链接
-
- [NestJS Swagger文档](https://docs.nestjs.com/openapi/introduction)
- [OpenAPI规范](https://swagger.io/specification/)
- [Postman文档](https://learning.postman.com/docs/getting-started/introduction/)
- [Swagger Editor](https://editor.swagger.io/)
+📧 **联系我们**：如有文档相关问题，请通过项目Issue或邮件联系维护团队。