docs：添加AI代码检查执行指南文档
- 添加完整的7步代码检查流程指导 - 包含命名规范、注释标准、代码质量等检查标准 - 提供游戏服务器特殊要求和最佳实践 - 支持NestJS双模式架构和WebSocket实时通信检查 涉及文件： - docs/ai-reading/README.md - 总体执行指南 - docs/ai-reading/step1-naming-convention.md - 命名规范检查 - docs/ai-reading/step2-comment-standard.md - 注释规范检查 - docs/ai-reading/step3-code-quality.md - 代码质量检查 - docs/ai-reading/step4-architecture-layer.md - 架构分层检查 - docs/ai-reading/step5-test-coverage.md - 测试覆盖检查 - docs/ai-reading/step6-documentation.md - 功能文档生成 - docs/ai-reading/step7-code-commit.md - 代码提交规范
This commit is contained in:
moyin
327
docs/ai-reading/step6-documentation.md
Normal file
327
docs/ai-reading/step6-documentation.md
Normal file
@@ -0,0 +1,327 @@
|
||||
# 步骤6：功能文档生成
|
||||
|
||||
## 🎯 检查目标
|
||||
生成和维护功能模块的README文档，确保文档内容完整、准确、实用。
|
||||
|
||||
## 📚 README文档结构
|
||||
|
||||
### 必须包含的章节
|
||||
每个功能模块文件夹都必须有README.md文档，包含以下结构：
|
||||
|
||||
```markdown
|
||||
# [模块名称] [中文描述]
|
||||
|
||||
[模块名称] 是 [一段话总结文件夹的整体功能和作用，说明其在项目中的定位和价值]。
|
||||
|
||||
## 对外提供的接口
|
||||
|
||||
### create()
|
||||
创建新用户记录，支持数据验证和唯一性检查。
|
||||
|
||||
### findByEmail()
|
||||
根据邮箱地址查询用户，用于登录验证和账户找回。
|
||||
|
||||
## 对外API接口（如适用）
|
||||
|
||||
### POST /api/auth/login
|
||||
用户登录接口，支持用户名/邮箱/手机号多种方式登录。
|
||||
|
||||
### GET /api/users/:id
|
||||
根据用户ID获取用户详细信息。
|
||||
|
||||
## WebSocket事件接口（如适用）
|
||||
|
||||
### 'connection'
|
||||
客户端建立WebSocket连接，需要提供JWT认证token。
|
||||
|
||||
### 'position_update'
|
||||
接收客户端位置更新，广播给房间内其他用户。
|
||||
|
||||
## 使用的项目内部依赖
|
||||
|
||||
### UserStatus (来自 business/user-mgmt/enums/user-status.enum)
|
||||
用户状态枚举，定义用户的激活、禁用、待验证等状态值。
|
||||
|
||||
## 核心特性
|
||||
|
||||
### 双存储模式支持
|
||||
- 数据库模式：使用TypeORM连接MySQL，适用于生产环境
|
||||
- 内存模式：使用Map存储，适用于开发测试和故障降级
|
||||
|
||||
## 潜在风险
|
||||
|
||||
### 内存模式数据丢失风险
|
||||
- 内存存储在应用重启后数据会丢失
|
||||
- 建议仅在开发测试环境使用
|
||||
```
|
||||
|
||||
## 🔌 对外接口文档
|
||||
|
||||
### 公共方法描述
|
||||
每个公共方法必须有一句话功能说明：
|
||||
|
||||
```markdown
|
||||
## 对外提供的接口
|
||||
|
||||
### create(userData: CreateUserDto): Promise<User>
|
||||
创建新用户记录，支持数据验证和唯一性检查。
|
||||
|
||||
### findById(id: string): Promise<User>
|
||||
根据用户ID查询用户信息，用于身份验证和数据获取。
|
||||
|
||||
### updateStatus(id: string, status: UserStatus): Promise<User>
|
||||
更新用户状态，支持激活、禁用、待验证等状态切换。
|
||||
|
||||
### delete(id: string): Promise<void>
|
||||
删除用户记录及相关数据，执行软删除保留审计信息。
|
||||
|
||||
### findByEmail(email: string): Promise<User>
|
||||
根据邮箱地址查询用户，用于登录验证和账户找回。
|
||||
```
|
||||
|
||||
## 🌐 API接口文档（Business模块）
|
||||
|
||||
### HTTP API接口
|
||||
如果business模块开放了可访问的API，必须列出所有API：
|
||||
|
||||
```markdown
|
||||
## 对外API接口
|
||||
|
||||
### POST /api/auth/login
|
||||
用户登录接口，支持用户名/邮箱/手机号多种方式登录。
|
||||
|
||||
### GET /api/users/:id
|
||||
根据用户ID获取用户详细信息。
|
||||
|
||||
### PUT /api/users/:id/status
|
||||
更新指定用户的状态（激活/禁用/待验证）。
|
||||
|
||||
### DELETE /api/users/:id
|
||||
删除指定用户账户及相关数据。
|
||||
|
||||
### GET /api/users/search
|
||||
根据条件搜索用户，支持邮箱、用户名、状态等筛选。
|
||||
|
||||
### POST /api/users/batch
|
||||
批量创建用户，支持Excel导入和数据验证。
|
||||
```
|
||||
|
||||
## 🔌 WebSocket接口文档（Gateway模块）
|
||||
|
||||
### WebSocket事件接口
|
||||
Gateway模块需要详细的WebSocket事件文档：
|
||||
|
||||
```markdown
|
||||
## WebSocket事件接口
|
||||
|
||||
### 'connection'
|
||||
客户端建立WebSocket连接，需要提供JWT认证token。
|
||||
- 输入: `{ token: string }`
|
||||
- 输出: 连接成功确认
|
||||
|
||||
### 'position_update'
|
||||
接收客户端位置更新，广播给房间内其他用户。
|
||||
- 输入: `{ x: number, y: number, timestamp: number }`
|
||||
- 输出: 广播给房间成员
|
||||
|
||||
### 'join_room'
|
||||
用户加入游戏房间，建立实时通信连接。
|
||||
- 输入: `{ roomId: string }`
|
||||
- 输出: `{ success: boolean, members: string[] }`
|
||||
|
||||
### 'chat_message'
|
||||
处理聊天消息，支持Zulip集成和消息过滤。
|
||||
- 输入: `{ message: string, roomId: string }`
|
||||
- 输出: 广播给房间成员或转发到Zulip
|
||||
|
||||
### 'disconnect'
|
||||
客户端断开连接，清理相关资源和通知其他用户。
|
||||
- 输入: 无
|
||||
- 输出: 通知房间其他成员
|
||||
```
|
||||
|
||||
## 🔗 内部依赖分析
|
||||
|
||||
### 依赖列表格式
|
||||
```markdown
|
||||
## 使用的项目内部依赖
|
||||
|
||||
### UserStatus (来自 business/user-mgmt/enums/user-status.enum)
|
||||
用户状态枚举，定义用户的激活、禁用、待验证等状态值。
|
||||
|
||||
### CreateUserDto (本模块)
|
||||
用户创建数据传输对象，提供完整的数据验证规则和类型定义。
|
||||
|
||||
### LoggerService (来自 core/utils/logger)
|
||||
日志服务，用于记录用户操作和系统事件。
|
||||
|
||||
### CacheService (来自 core/redis)
|
||||
缓存服务，用于提升用户查询性能和会话管理。
|
||||
|
||||
### EmailService (来自 core/utils/email)
|
||||
邮件服务，用于发送用户注册验证和通知邮件。
|
||||
```
|
||||
|
||||
## ⭐ 核心特性识别
|
||||
|
||||
### 技术特性
|
||||
```markdown
|
||||
## 核心特性
|
||||
|
||||
### 双存储模式支持
|
||||
- 数据库模式：使用TypeORM连接MySQL，适用于生产环境
|
||||
- 内存模式：使用Map存储，适用于开发测试和故障降级
|
||||
- 动态模块配置：通过UsersModule.forDatabase()和forMemory()灵活切换
|
||||
- 自动检测：根据环境变量自动选择存储模式
|
||||
|
||||
### 实时通信能力
|
||||
- WebSocket支持：基于Socket.IO的实时双向通信
|
||||
- 房间管理：支持用户加入/离开游戏房间
|
||||
- 位置广播：实时广播用户位置更新给房间成员
|
||||
- 连接管理：自动处理连接断开和重连机制
|
||||
|
||||
### 数据完整性保障
|
||||
- 唯一性约束检查：用户名、邮箱、手机号、GitHub ID
|
||||
- 数据验证：使用class-validator进行输入验证
|
||||
- 事务支持：批量操作支持回滚机制
|
||||
- 双模式一致性：确保内存模式和数据库模式行为一致
|
||||
|
||||
### 性能优化与监控
|
||||
- 查询优化：使用索引和查询缓存
|
||||
- 批量操作：支持批量创建和更新
|
||||
- 内存缓存：热点数据缓存机制
|
||||
- 性能监控：WebSocket连接数、消息处理延迟等指标
|
||||
- 属性测试：使用fast-check进行随机化测试
|
||||
```
|
||||
|
||||
## ⚠️ 潜在风险评估
|
||||
|
||||
### 风险分类和描述
|
||||
```markdown
|
||||
## 潜在风险
|
||||
|
||||
### 内存模式数据丢失风险
|
||||
- 内存存储在应用重启后数据会丢失
|
||||
- 不适用于生产环境的持久化需求
|
||||
- 建议仅在开发测试环境使用
|
||||
- 缓解措施：提供数据导出/导入功能
|
||||
|
||||
### WebSocket连接管理风险
|
||||
- 大量并发连接可能导致内存泄漏
|
||||
- 网络不稳定时连接频繁断开重连
|
||||
- 房间成员过多时广播性能下降
|
||||
- 缓解措施：连接数限制、心跳检测、分片广播
|
||||
|
||||
### 实时通信性能风险
|
||||
- 高频位置更新可能导致服务器压力
|
||||
- 消息广播延迟影响游戏体验
|
||||
- WebSocket消息丢失或重复
|
||||
- 缓解措施：消息限流、优先级队列、消息确认机制
|
||||
|
||||
### 双模式一致性风险
|
||||
- 内存模式和数据库模式行为可能不一致
|
||||
- 模式切换时数据同步问题
|
||||
- 测试覆盖不完整导致隐藏差异
|
||||
- 缓解措施：统一接口抽象、完整的对比测试
|
||||
|
||||
### 安全风险
|
||||
- WebSocket连接缺少足够的认证验证
|
||||
- 用户位置信息泄露风险
|
||||
- 管理员权限过度集中
|
||||
- 缓解措施：JWT认证、数据脱敏、权限细分
|
||||
```
|
||||
|
||||
## 🎮 游戏服务器特殊文档要求
|
||||
|
||||
### 实时通信协议说明
|
||||
```markdown
|
||||
### 实时通信协议
|
||||
- 协议类型：WebSocket (Socket.IO)
|
||||
- 认证方式：JWT Token验证
|
||||
- 心跳间隔：10秒
|
||||
- 超时设置：30秒无响应自动断开
|
||||
- 重连策略：指数退避，最大重试5次
|
||||
```
|
||||
|
||||
### 双模式切换指南
|
||||
```markdown
|
||||
### 双模式切换指南
|
||||
- 环境变量：`STORAGE_MODE=database|memory`
|
||||
- 切换命令：`npm run switch:database` 或 `npm run switch:memory`
|
||||
- 数据迁移：提供内存到数据库的数据导出/导入工具
|
||||
- 性能对比：内存模式响应时间<1ms，数据库模式<10ms
|
||||
```
|
||||
|
||||
### 属性测试策略说明
|
||||
```markdown
|
||||
### 属性测试策略
|
||||
- 测试框架：fast-check
|
||||
- 测试范围：管理员操作、用户状态变更、权限验证
|
||||
- 随机化参数：用户ID(1-1000000)、状态枚举、权限级别
|
||||
- 执行次数：每个属性测试运行1000次随机用例
|
||||
- 失败处理：自动收集失败用例，生成最小化复现案例
|
||||
```
|
||||
|
||||
## 📝 文档质量标准
|
||||
|
||||
### 内容质量要求
|
||||
- **准确性**：所有信息必须与代码实现一致
|
||||
- **完整性**：覆盖所有公共接口和重要功能
|
||||
- **简洁性**：每个说明控制在一句话内，突出核心要点
|
||||
- **实用性**：提供对开发者有价值的信息和建议
|
||||
|
||||
### 语言表达规范
|
||||
- 使用中文进行描述，专业术语可保留英文
|
||||
- 语言简洁明了，避免冗长的句子
|
||||
- 统一术语使用，保持前后一致
|
||||
- 避免主观评价，客观描述功能和特性
|
||||
|
||||
## 🔍 检查执行步骤
|
||||
|
||||
1. **检查README文件存在性**
|
||||
- 确保每个功能模块文件夹都有README.md
|
||||
- 检查文档结构是否完整
|
||||
|
||||
2. **验证对外接口文档**
|
||||
- 列出所有公共方法
|
||||
- 为每个方法提供一句话功能说明
|
||||
- 确保接口描述准确
|
||||
|
||||
3. **检查API接口文档**
|
||||
- 如果是business模块且开放API，必须列出所有API
|
||||
- 每个API提供一句话功能说明
|
||||
- 包含请求方法和路径
|
||||
|
||||
4. **检查WebSocket接口文档**
|
||||
- Gateway模块必须详细说明WebSocket事件
|
||||
- 包含输入输出格式
|
||||
- 说明事件处理逻辑
|
||||
|
||||
5. **验证内部依赖分析**
|
||||
- 列出所有项目内部依赖
|
||||
- 说明每个依赖的用途
|
||||
- 确保依赖关系准确
|
||||
|
||||
6. **检查核心特性描述**
|
||||
- 识别技术特性、功能特性、质量特性
|
||||
- 突出游戏服务器特殊特性
|
||||
- 描述双模式、实时通信等特点
|
||||
|
||||
7. **评估潜在风险**
|
||||
- 识别技术风险、业务风险、运维风险、安全风险
|
||||
- 提供风险缓解措施
|
||||
- 特别关注游戏服务器特有风险
|
||||
|
||||
8. **验证文档与代码一致性**
|
||||
- 确保文档内容与实际代码实现一致
|
||||
- 检查接口签名、参数类型等准确性
|
||||
- 验证特性描述的真实性
|
||||
|
||||
## 🔥 重要提醒
|
||||
|
||||
**如果在本步骤中执行了任何修改操作（创建README文件、更新文档内容、修正接口描述等），必须立即重新执行步骤6的完整检查！**
|
||||
|
||||
- ✅ 执行修改 → 🔥 立即重新执行步骤6 → 提供验证报告 → 等待用户确认
|
||||
- ❌ 执行修改 → 直接结束检查（错误做法）
|
||||
|
||||
**不能跳过重新检查环节！**
|
||||
Reference in New Issue
Block a user