Главная Обзор Помощь
Регистрация Вход
185-template-173
/
mini-starter
ответвлено от 155-template-138/mini-starter
2
0
Ответвить 0
Файлы
Дерево: ad6ec3cd33
Ветки Метки
mini-starter
/
docs
/
stories
/
005.004.mini-payment-package.story.md

005.004.mini-payment-package.story.md 7.1 KB
История Исходник

Story 005.004: Mini Payment Package

Status

Draft

Story

As a 小程序开发者， I want 将小程序支付模块从 mini-auth-demo 项目拆分到主项目的 packages 目录下作为独立 package， so that 项目可以按需引入微信小程序支付功能，保持模块独立性和向后兼容性

Acceptance Criteria

  1. 创建 @d8d/mini-payment package，包含完整的微信小程序支付功能
  2. 从 mini-auth-demo/packages/server/src/modules/payment 迁移支付服务代码
  3. 实现支付创建、回调处理、状态查询等核心功能
  4. 提供完整的 TypeScript 类型定义和 API 文档
  5. 集成到现有的认证和用户管理系统
  6. 保持与现有订单系统的兼容性
  7. 提供单元测试和集成测试，覆盖率满足要求
  8. 更新 server package 依赖关系，支持按需引入

Tasks / Subtasks

  • [ ] Task 1: 创建 mini-payment package 基础结构 (AC: 1, 2)

    • 创建 packages/mini-payment 目录结构
    • 配置 package.json 和依赖关系
    • 配置 TypeScript 编译配置
    • 创建基础导出文件

  • [ ] Task 2: 迁移支付服务核心代码 (AC: 2, 3)

    • 迁移 PaymentService 类和相关类型定义
    • 迁移微信支付 SDK 集成代码
    • 迁移支付状态枚举和常量
    • 更新数据库实体引用

  • [ ] Task 3: 创建支付 API 路由 (AC: 3, 4)

    • 创建支付创建路由 (/api/payment/create)
    • 创建支付回调路由 (/api/payment/callback)
    • 创建支付状态查询路由 (/api/payment/status)
    • 实现完整的 OpenAPI 文档

  • [ ] Task 4: 集成认证和用户系统 (AC: 5)

    • 集成现有认证中间件
    • 添加用户权限验证
    • 集成用户 OpenID 管理
    • 确保与现有用户实体的兼容性

  • [ ] Task 5: 迁移和实现测试套件 (AC: 7)

    • 迁移现有集成测试文件：
    • mini-auth-demo/web/tests/integration/server/api/payment/callback/post.test.ts
    • mini-auth-demo/web/tests/integration/server/payment.integration.test.ts
    • 适配迁移的测试文件到新包结构
    • 编写支付路由集成测试
    • 验证测试覆盖率满足要求

  • [ ] Task 6: 更新 server package 依赖 (AC: 8)

    • 更新 server package.json 添加 mini-payment 依赖
    • 集成支付路由到主应用
    • 验证按需引入功能
    • 更新文档说明

Dev Notes

技术栈信息

  • 后端框架: Hono 4.8.5 [Source: architecture/tech-stack.md#现有技术栈维护]
  • 数据库: PostgreSQL 17 + TypeORM 0.3.25 [Source: architecture/tech-stack.md#现有技术栈维护]
  • 支付SDK: wechatpay-node-v3 [Source: mini-auth-demo/packages/server/src/modules/payment/payment.service.ts:4]
  • 认证: JWT Bearer Token [Source: architecture/api-design-integration.md#API集成策略]

项目结构

  • 包位置: packages/mini-payment/ [Source: architecture/source-tree.md#实际项目结构]
  • 代码结构: 遵循现有模块化包模式 [Source: architecture/source-tree.md#包架构层次]
  • 依赖层次: mini-payment → auth-module → user-module → shared-crud → shared-utils → shared-types [Source: docs/prd/epic-005-mini-auth-modules-integration.md#依赖层次]

支付功能详情

  • 支付方式: JSAPI 支付（微信小程序）[Source: mini-auth-demo/docs/architecture/payment-integration-design.md#支付方式选择]
  • 核心功能:
    • 创建支付订单 [Source: mini-auth-demo/packages/server/src/modules/payment/payment.service.ts:52]
    • 处理支付回调 [Source: mini-auth-demo/packages/server/src/modules/payment/payment.service.ts:134]
    • 查询支付状态 [Source: mini-auth-demo/packages/server/src/modules/payment/payment.service.ts:234]
  • 支付状态: PENDING, PROCESSING, SUCCESS, FAILED, REFUNDED, CLOSED [Source: mini-auth-demo/packages/server/src/modules/payment/payment.service.ts:3]

集成点

  • 认证集成: 使用现有 auth.middleware [Source: architecture/source-tree.md:126]
  • 用户集成: 依赖 user-module 获取用户信息 [Source: architecture/source-tree.md:98]
  • 数据库: 使用现有 TypeORM 数据源 [Source: architecture/source-tree.md:74]
  • API 设计: 遵循现有 RESTful API 模式 [Source: architecture/api-design-integration.md#API集成策略]

环境配置要求

  • 微信支付配置: WECHAT_MERCHANT_ID, WX_MINI_APP_ID, WECHAT_V3_KEY 等 [Source: mini-auth-demo/packages/server/src/modules/payment/payment.service.ts:19-23]
  • 回调URL: WECHAT_PAY_NOTIFY_URL [Source: mini-auth-demo/packages/server/src/modules/payment/payment.service.ts:23]

Testing

测试标准

  • 测试框架: Vitest 3.2.4 [Source: architecture/testing-strategy.md#工具版本]
  • 测试位置: packages/mini-payment/tests/ [Source: architecture/testing-strategy.md#包测试架构]
  • 测试类型: 单元测试 + 集成测试 [Source: architecture/testing-strategy.md#包测试架构]
  • 覆盖率要求: 单元测试 ≥ 80%，集成测试 ≥ 60% [Source: architecture/testing-strategy.md#各层覆盖率要求]

测试模式

  • 集成测试: 测试支付路由与认证集成 [Source: architecture/testing-strategy.md#集成测试]
  • 测试工具: 使用 shared-test-util 基础设施 [Source: architecture/testing-strategy.md#包测试架构]

测试套件用法（参考 auth-module 模式）

  • 测试框架: Vitest + Hono Testing Client [Source: packages/auth-module/tests/integration/phone-decrypt.integration.test.ts:1-2]
  • 数据库钩子: 使用 setupIntegrationDatabaseHooksWithEntities [Source: packages/auth-module/tests/integration/phone-decrypt.integration.test.ts:31]
  • 测试客户端: 使用 testClient 创建路由测试客户端 [Source: packages/auth-module/tests/integration/phone-decrypt.integration.test.ts:41]
  • 数据源获取: 使用 IntegrationTestDatabase.getDataSource() [Source: packages/auth-module/tests/integration/phone-decrypt.integration.test.ts:44]
  • Mock策略: 对微信支付SDK进行适当的mock，避免真实API调用

关键测试场景

  • 支付创建参数验证
  • 微信支付 SDK 集成测试
  • 支付回调签名验证
  • 支付状态流转测试
  • 错误处理和异常场景测试

现有测试文件迁移

  • 支付回调集成测试: mini-auth-demo/web/tests/integration/server/api/payment/callback/post.test.ts
  • 支付功能集成测试: mini-auth-demo/web/tests/integration/server/payment.integration.test.ts
  • 说明: 由于已有完整的集成测试覆盖，无需重复编写PaymentService单元测试

Change Log

Date Version Description Author
2025-11-11 1.2 添加测试套件详细用法说明，参考auth-module模式 Bob (Scrum Master)
2025-11-11 1.1 添加现有测试文件迁移任务，优化测试策略 Bob (Scrum Master)
2025-11-11 1.0 创建小程序支付模块故事文档 Bob (Scrum Master)

Dev Agent Record

This section is populated by the development agent during implementation

Agent Model Used

Debug Log References

Completion Notes List

File List

QA Results

Results from QA Agent QA review of the completed story implementation