mini-starter/docs/stories/005.003.mini-auth-module-enhancement.md

Story 005.003: Mini-Auth Module Enhancement

Status

Draft

Story

As a 微信小程序用户, I want 能够通过微信小程序登录并解密手机号, so that 我可以快速注册和绑定手机号，享受完整的服务功能

Acceptance Criteria

1. 小程序登录功能完整可用，支持微信 code 换取 openid 和 session_key
2. 手机号解密功能完整可用，支持 AES-128-CBC 解密微信加密的手机号数据
3. 解密后的手机号自动绑定到用户账户
4. 所有功能与现有认证系统无缝集成
5. 提供完整的 API 文档和错误处理
6. 所有功能通过单元测试和集成测试验证

Tasks / Subtasks

• [ ] 分析现有 auth-module 中的小程序认证功能

  • 检查 mini-auth.service.ts 的当前实现
  • 检查 mini-login.route.ts 的当前实现
  • 识别缺失的手机号解密功能

• [ ] 从 mini-auth-demo 迁移手机号解密功能

  • 迁移 decryptPhoneNumber 方法到现有 MiniAuthService
  • 添加手机号解密相关的类型定义
  • 创建手机号解密路由 (/api/auth/phone-decrypt)

• [ ] 集成手机号解密到现有认证流程

  • 确保解密后的手机号自动绑定到用户账户
  • 集成 Redis sessionKey 管理
  • 更新用户实体以支持手机号字段

• [ ] 完善测试覆盖

  • 为手机号解密功能编写单元测试
  • 编写集成测试验证完整流程
  • 确保现有功能不受影响

• [ ] 文档和错误处理

  • 更新 API 文档包含手机号解密接口
  • 完善错误处理和用户友好的错误信息
  • 验证向后兼容性

Dev Notes

现有架构分析

• 技术栈: Node.js 20.19.2 + TypeScript + Hono 4.8.5 + TypeORM + PostgreSQL
• 认证模块位置: packages/auth-module/
• 现有小程序功能:
  • packages/auth-module/src/services/mini-auth.service.ts - 小程序登录服务
  • packages/auth-module/src/routes/mini-login.route.ts - 小程序登录路由
  • packages/auth-module/src/schemas/auth.schema.ts - 包含 MiniLoginSchema

需要迁移的功能

从 mini-auth-demo/packages/server/src/modules/auth/mini-auth.service.ts:

• decryptPhoneNumber(encryptedData, iv, sessionKey) 方法
• 相关的 AES-128-CBC 解密逻辑

从 mini-auth-demo/packages/server/src/api/auth/phone-decrypt/post.ts:

• 手机号解密路由实现
• 相关的 Zod schema 定义

集成点

• 用户实体: 需要确保 UserEntity 有 phone 字段支持
• Redis 集成: 需要 sessionKey 存储和获取功能
• 认证中间件: 手机号解密需要用户认证

项目结构对齐

• 新文件位置: packages/auth-module/src/routes/phone-decrypt.route.ts
• 测试位置: packages/auth-module/tests/integration/phone-decrypt.integration.test.ts
• 类型定义: 在现有 auth.schema.ts 中添加相关类型

技术约束

• 使用 Node.js 内置 crypto 模块进行 AES-128-CBC 解密
• 遵循微信小程序手机号解密规范
• 保持与现有认证流程的一致性

Testing

测试标准:

• 测试框架: Vitest 3.2.4
• 测试位置:
  • 单元测试: packages/auth-module/tests/unit/mini-auth.service.test.ts
  • 集成测试: packages/auth-module/tests/integration/phone-decrypt.integration.test.ts
• 覆盖率要求: 核心业务逻辑 > 80%
• 测试类型: 单元测试 + 集成测试

测试策略:

• 单元测试验证解密算法的正确性
• 集成测试验证完整的 API 流程
• 测试各种错误场景（无效参数、解密失败等）
• 验证与现有认证系统的集成

Change Log

Date	Version	Description	Author
2025-11-10	1.0	初始故事创建	Bob (Scrum Master)

Dev Agent Record

This section will be populated by the development agent during implementation

Agent Model Used

To be filled by dev agent

Debug Log References

To be filled by dev agent

Completion Notes List

To be filled by dev agent

File List

To be filled by dev agent

QA Results

This section will be populated by the QA agent during review