mini-starter/docs/stories/005.012.mini-program-phone-integration.story.md

Story 5.12: 小程序手机号获取集成

Status

Draft

Story

As a 出行用户 I want 能够通过微信小程序一键获取我的手机号 so that 快速完成订单联系信息填写

Acceptance Criteria

1. 支持微信小程序 getPhoneNumber 功能调用
2. 实现手机号解密API接口，接收小程序加密数据
3. 将获取的手机号保存到用户信息中
4. 订单确认页面显示已获取的手机号状态
5. 支持手机号获取失败的重试机制
6. 确保手机号数据安全性和隐私保护
7. 手机号获取成功后自动填充到订单联系信息
8. 支持手机号验证状态显示

Tasks / Subtasks

• 实现手机号解密API接口 (AC: 2)
  • 创建手机号解密路由文件 packages/server/src/api/auth/phone-decrypt/post.ts
  • 定义请求和响应Schema
  • 实现微信SDK手机号解密逻辑
  • 添加错误处理和日志记录
• 更新用户实体支持手机号字段 (AC: 3)
  • 验证用户实体中已存在的 phone 字段
  • 创建用户更新Schema支持手机号字段
  • 实现用户手机号更新服务方法
• API接口测试 (AC: 8)
  • 编写API接口单元测试
• 小程序前端集成 (AC: 1, 4, 7)
  • 在订单确认页面添加手机号获取组件
  • 实现 getPhoneNumber 组件调用
  • 处理手机号获取成功/失败状态
  • 实现手机号自动填充到订单联系信息
• 前端页面测试 (AC: 8)
  • 编写小程序组件集成测试
  • 验证手机号验证状态显示
• 实现重试机制 (AC: 5)
  • 添加手机号获取失败的重试按钮
  • 实现重试次数限制
  • 提供用户友好的错误提示
• 安全性和隐私保护 (AC: 6)
  • 验证微信SDK签名
  • 添加访问权限控制

Dev Notes

技术栈信息

• 前端框架: Taro + React 小程序框架 [Source: architecture/tech-stack.md#L13]
• 后端框架: Hono + TypeORM [Source: architecture/tech-stack.md#L12, L16]
• 数据库: PostgreSQL 17 [Source: architecture/tech-stack.md#L15]

项目结构

• 小程序项目: mini/ 目录 [Source: architecture/source-tree.md#L11]
• API服务器: packages/server/ 目录 [Source: architecture/source-tree.md#L62]
• 路由文件位置: packages/server/src/api/auth/phone-decrypt/ [Source: architecture/source-tree.md#L72-L80]

数据模型

• 用户实体: 已存在 phone 字段 [Source: packages/server/src/modules/users/user.entity.ts#L17-L18]
• 现有用户字段: id, username, email, password, phone, avatarFileId, roles [Source: architecture/data-model-schema-changes.md#L13-L18]

API设计规范

• 非通用CRUD路由: 使用业务操作路由模式 [Source: architecture/non-generic-crud-standards.md#L206-L295]
• 路由文件组织: 单一文件聚合模式 [Source: architecture/non-generic-crud-standards.md#L426-L464]
• 错误处理: 统一错误响应格式 [Source: architecture/non-generic-crud-standards.md#L359-L380]
• 权限控制: 使用 authMiddleware [Source: architecture/non-generic-crud-standards.md#L381-L398]

Schema设计规范

• 请求Schema: 使用Zod schema定义 [Source: architecture/non-generic-crud-standards.md#L297-L318]
• 响应Schema: 标准化响应格式 [Source: architecture/non-generic-crud-standards.md#L335-L354]
• 参数验证: 使用 z.coerce 处理类型转换 [Source: architecture/non-generic-crud-standards.md#L299-L302]

安全要求

• 认证: JWT Bearer Token [Source: architecture/api-design-integration.md#L9-L11]
• 数据解密: 微信SDK提供的手机号解密机制
• 隐私保护: 使用数据库标准安全措施

测试

• 测试框架: Vitest + Testing Library [Source: architecture/coding-standards.md#L15]
• 测试位置: web/tests/integration/server/api/auth/phone-decrypt/ [Source: architecture/source-tree.md#L147]
• 测试类型: 集成测试验证API功能 [Source: architecture/non-generic-crud-standards.md#L417-L421]

Testing

测试标准

• 测试文件位置: web/tests/integration/server/api/auth/phone-decrypt/
• 测试框架: Vitest + hono/testing
• 测试模式: 集成测试验证完整的API流程
• Mock策略: 使用 vi.mocked() mock微信SDK [Source: architecture/non-generic-crud-standards.md#L559-L572]

测试要求

• 验证手机号解密成功场景
• 测试解密失败的错误处理
• 验证用户手机号更新功能
• 测试权限控制和认证验证
• 验证重试机制和错误提示

Change Log

Date	Version	Description	Author
2025-10-25	1.0	创建故事文档	Bob (Scrum Master)

Dev Agent Record

Agent Model Used

Debug Log References

Completion Notes List

File List

QA Results