# 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