ANGJustinl/whale-town-end
1
0
Fork 0
forked from datawhale/whale-town-end
Code Pull Requests Activity

docs: 重构文档结构和组织

Browse Source 
- 重新组织docs目录结构，按功能模块分类
- 新增deployment和development目录
- 更新API文档结构
- 添加客户端README文档
- 移除过时的文档文件
This commit is contained in:
moyin
2025-12-24 18:04:14 +08:00
parent 032c97a1fc
commit 85d488a508
20 changed files with 2416 additions and 1763 deletions
Download Patch File Download Diff File Expand all files Collapse all files

202
docs/README.md
View File

@@ -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或邮件联系维护团队。