whale-town-end/docs/ai-reading/step6-documentation.md

# 步骤6：功能文档生成

## ⚠️ 执行前必读规范

**🔥 重要：在执行本步骤之前，AI必须先完整阅读同级目录下的 `README.md` 文件！**

该README文件包含：
- 🎯 执行前准备和用户信息收集要求
- 🔄 强制执行原则和分步执行流程  
- 🔥 修改后立即重新执行当前步骤的强制规则
- 📝 文件修改记录规范和版本号递增规则
- 🧪 测试文件调试规范和测试指令使用规范
- 🚨 全局约束和游戏服务器特殊要求

**不阅读README直接执行步骤将导致执行不规范，违反项目要求！**

---

## 🎯 检查目标
生成和维护功能模块的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 → 提供验证报告 → 等待用户确认
- ❌ 执行修改 → 直接结束检查（错误做法）

**🚨 重要强调：纯检查步骤不更新修改记录**
**如果检查发现功能文档已经符合规范，无需任何修改，则：**
- ❌ **禁止添加检查记录**：不要添加"AI代码检查步骤6：功能文档检查和优化"
- ❌ **禁止更新时间戳**：不要修改@lastModified字段
- ❌ **禁止递增版本号**：不要修改@version字段
- ✅ **仅提供检查报告**：说明检查结果，确认符合规范

**不能跳过重新检查环节！**