datawhale/whale-town-end
3
4
Fork 2
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
41c33d6159d282221bdb7d4bd011052cbfd40027
whale-town-end/docs/ai-reading/step6-documentation.md
moyin 5af44f95d5 style: 完善代码规范和测试覆盖 
- 新增多个模块的单元测试文件，提升测试覆盖率
- 完善AI-Reading文档系统，包含7步代码检查流程
- 新增集成测试和属性测试框架
- 优化项目结构和配置文件
- 清理过时的规范文档，统一使用新的检查标准
2026-01-12 20:09:03 +08:00

11 KiB
Raw Blame History

步骤6：功能文档生成

⚠️ 执行前必读规范

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

该README文件包含：

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

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

🎯 检查目标

生成和维护功能模块的README文档，确保文档内容完整、准确、实用。

📚 README文档结构

必须包含的章节

每个功能模块文件夹都必须有README.md文档，包含以下结构：

# [模块名称] [中文描述]

[模块名称] 是 [一段话总结文件夹的整体功能和作用，说明其在项目中的定位和价值]。

## 对外提供的接口

### 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存储，适用于开发测试和故障降级

## 潜在风险

### 内存模式数据丢失风险
- 内存存储在应用重启后数据会丢失
- 建议仅在开发测试环境使用

🔌 对外接口文档

公共方法描述

每个公共方法必须有一句话功能说明：

## 对外提供的接口

### 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：

## 对外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事件文档：

## 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'
客户端断开连接，清理相关资源和通知其他用户。
- 输入: 无
- 输出: 通知房间其他成员

🔗 内部依赖分析

依赖列表格式

## 使用的项目内部依赖

### UserStatus (来自 business/user-mgmt/enums/user-status.enum)
用户状态枚举，定义用户的激活、禁用、待验证等状态值。

### CreateUserDto (本模块)
用户创建数据传输对象，提供完整的数据验证规则和类型定义。

### LoggerService (来自 core/utils/logger)
日志服务，用于记录用户操作和系统事件。

### CacheService (来自 core/redis)
缓存服务，用于提升用户查询性能和会话管理。

### EmailService (来自 core/utils/email)
邮件服务，用于发送用户注册验证和通知邮件。

⭐ 核心特性识别

技术特性

## 核心特性

### 双存储模式支持
- 数据库模式：使用TypeORM连接MySQL，适用于生产环境
- 内存模式：使用Map存储，适用于开发测试和故障降级
- 动态模块配置：通过UsersModule.forDatabase()和forMemory()灵活切换
- 自动检测：根据环境变量自动选择存储模式

### 实时通信能力
- WebSocket支持：基于Socket.IO的实时双向通信
- 房间管理：支持用户加入/离开游戏房间
- 位置广播：实时广播用户位置更新给房间成员
- 连接管理：自动处理连接断开和重连机制

### 数据完整性保障
- 唯一性约束检查：用户名、邮箱、手机号、GitHub ID
- 数据验证：使用class-validator进行输入验证
- 事务支持：批量操作支持回滚机制
- 双模式一致性：确保内存模式和数据库模式行为一致

### 性能优化与监控
- 查询优化：使用索引和查询缓存
- 批量操作：支持批量创建和更新
- 内存缓存：热点数据缓存机制
- 性能监控：WebSocket连接数、消息处理延迟等指标
- 属性测试：使用fast-check进行随机化测试

⚠️ 潜在风险评估

风险分类和描述

## 潜在风险

### 内存模式数据丢失风险
- 内存存储在应用重启后数据会丢失
- 不适用于生产环境的持久化需求
- 建议仅在开发测试环境使用
- 缓解措施：提供数据导出/导入功能

### WebSocket连接管理风险
- 大量并发连接可能导致内存泄漏
- 网络不稳定时连接频繁断开重连
- 房间成员过多时广播性能下降
- 缓解措施：连接数限制、心跳检测、分片广播

### 实时通信性能风险
- 高频位置更新可能导致服务器压力
- 消息广播延迟影响游戏体验
- WebSocket消息丢失或重复
- 缓解措施：消息限流、优先级队列、消息确认机制

### 双模式一致性风险
- 内存模式和数据库模式行为可能不一致
- 模式切换时数据同步问题
- 测试覆盖不完整导致隐藏差异
- 缓解措施：统一接口抽象、完整的对比测试

### 安全风险
- WebSocket连接缺少足够的认证验证
- 用户位置信息泄露风险
- 管理员权限过度集中
- 缓解措施：JWT认证、数据脱敏、权限细分

🎮 游戏服务器特殊文档要求

实时通信协议说明

### 实时通信协议
- 协议类型：WebSocket (Socket.IO)
- 认证方式：JWT Token验证
- 心跳间隔：10秒
- 超时设置：30秒无响应自动断开
- 重连策略：指数退避，最大重试5次

双模式切换指南

### 双模式切换指南
- 环境变量：`STORAGE_MODE=database|memory`
- 切换命令：`npm run switch:database` 或 `npm run switch:memory`
- 数据迁移：提供内存到数据库的数据导出/导入工具
- 性能对比：内存模式响应时间<1ms，数据库模式<10ms

属性测试策略说明

### 属性测试策略
- 测试框架：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字段
  • ✅ 仅提供检查报告：说明检查结果，确认符合规范

不能跳过重新检查环节！

Reference in New Issue View Git Blame Copy Permalink