# 步骤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 创建新用户记录，支持数据验证和唯一性检查。 ### findById(id: string): Promise 根据用户ID查询用户信息，用于身份验证和数据获取。 ### updateStatus(id: string, status: UserStatus): Promise 更新用户状态，支持激活、禁用、待验证等状态切换。 ### delete(id: string): Promise 删除用户记录及相关数据，执行软删除保留审计信息。 ### findByEmail(email: string): Promise 根据邮箱地址查询用户，用于登录验证和账户找回。 ``` ## 🌐 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 → 提供验证报告 → 等待用户确认 - ❌ 执行修改 → 直接结束检查（错误做法） **不能跳过重新检查环节！**