mini-starter/docs/stories/005.013.mini-program-auto-login.story.md

Story 5.13: 微信小程序环境自动登录获取openid

Status

Ready for Review

Story

As a 微信小程序用户 I want 在微信小程序环境中能够通过微信一键登录并获取我的openid so that 便捷使用出行服务，无需手动输入账号密码

Acceptance Criteria

• 支持微信小程序 wx.login 获取code
• 实现openid获取API接口，接收小程序code
• 自动创建或关联用户账号
• 支持用户信息自动同步
• 实现静默登录机制，用户无感知（应用启动时自动登录）
• 支持登录状态持久化
• 确保登录流程的安全性和可靠性
• 支持登录失败的重试机制

Tasks / Subtasks

• 实现小程序登录API接口 (AC: 2, 3, 4)
  • 创建小程序登录路由文件 packages/server/src/api/auth/mini-login/post.ts
  • 实现MiniAuthService服务类 packages/server/src/modules/auth/mini-auth.service.ts
  • 支持微信code换取openid和session_key
  • 自动创建或关联用户账号
  • 支持用户信息更新和头像下载
• 实现小程序前端登录组件 (AC: 1, 5, 7, 8)
  • 创建微信登录页面 mini/src/pages/login/wechat-login.tsx
  • 集成Taro.login和Taro.getUserProfile
  • 实现登录状态管理和持久化
  • 支持登录失败重试机制
  • 添加错误处理和用户友好提示
• 实现静默登录机制 (AC: 5)
  • 在应用启动时检查登录状态
  • 实现静默登录逻辑（无用户感知）
  • 处理静默登录失败场景
  • 确保静默登录不影响用户体验
• 完善登录状态管理 (AC: 6)
  • 优化token存储和刷新机制
  • 实现登录状态自动续期
  • 添加登录状态检查中间件
• 编写测试用例 (AC: 7)
  • 编写小程序登录API单元测试
  • 编写前端登录组件集成测试
  • 编写静默登录流程E2E测试

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]
• 认证: JWT Bearer Token [Source: architecture/tech-stack.md#L19]

项目结构

• 小程序项目: mini/ 目录 [Source: architecture/source-tree.md#L11]
• API服务器: packages/server/ 目录 [Source: architecture/source-tree.md#L62]
• 登录页面: mini/src/pages/login/wechat-login.tsx [Source: architecture/source-tree.md#L42-L45]
• 认证API: packages/server/src/api/auth/mini-login/post.ts [Source: architecture/source-tree.md#L72-L80]

现有实现状态

• ✅ 后端小程序登录API已实现
• ✅ 前端微信登录页面已实现
• ✅ 用户自动注册和关联逻辑已实现
• ✅ 头像下载和用户信息更新已实现
• ❌ 静默登录机制待实现
• ❌ 登录状态自动续期待完善

数据模型

• 用户实体: 已包含openid、unionid字段 [Source: packages/server/src/modules/users/user.entity.ts]
• 用户字段: id, username, openid, unionid, nickname, phone, email, avatarFileId, registrationSource

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]

安全要求

• 微信API调用: 使用官方jscode2session接口
• 数据加密: session_key存储在Redis中
• 用户隐私: 严格保护用户openid等敏感信息
• 权限控制: 使用JWT token进行认证

静默登录实现方案

技术方案:

• 在应用启动时检查本地存储的token
• 如果token存在且有效，自动登录
• 如果token过期，尝试静默刷新
• 如果静默登录失败，保持未登录状态，不影响用户体验

实现要点:

• 使用Taro.useLaunch钩子
• 集成到现有的AuthProvider中
• 添加静默登录状态管理
• 确保无用户感知的登录体验

Testing

测试要求

• API测试: 验证小程序登录API的正确性
• 前端测试: 验证微信登录组件的交互
• 集成测试: 验证完整的登录流程
• E2E测试: 验证静默登录和状态持久化

测试位置

• 后端测试: packages/server/tests/unit/modules/auth/mini-auth.service.test.ts
• 前端测试: mini/tests/pages/login/wechat-login.test.tsx
• 集成测试: mini/tests/integration/auth/mini-login.test.ts
• E2E测试: tests/e2e/mini-program-login/mini-login.spec.ts

Change Log

Date	Version	Description	Author
2025-10-25	1.0	创建故事文档	James (Developer)

Dev Agent Record

Agent Model Used

James (Developer Agent)

Debug Log References

• 修复小程序登录API返回的用户类型不匹配问题：packages/server/src/api/auth/mini-login/post.ts:98-119
• 实现静默登录机制：mini/src/utils/auth.tsx:29-77
• 使用parseWithAwait处理异步字段：packages/server/src/api/auth/mini-login/post.ts:116-117

Completion Notes List

• ✅ 小程序登录API已实现，支持微信code换取openid和session_key
• ✅ 自动创建或关联用户账号功能已实现
• ✅ 用户信息自动同步和头像下载功能已实现
• ✅ 前端微信登录页面已实现，支持完整的登录流程
• ✅ 静默登录机制已实现，应用启动时自动尝试登录
• ✅ 登录状态持久化和失败重试机制已实现
• ✅ 修复了API返回类型不匹配的问题，确保前后端数据一致性

File List

• packages/server/src/api/auth/mini-login/post.ts - 小程序登录API路由（已修复类型问题）
• packages/server/src/modules/auth/mini-auth.service.ts - 小程序认证服务
• mini/src/pages/login/wechat-login.tsx - 微信登录页面
• mini/src/utils/auth.tsx - 认证状态管理（已添加静默登录）
• mini/src/app.tsx - 应用入口（已集成静默登录）

QA Results