mini-starter/docs/stories/007.011.mini-payment-module-multi-tenant-replication.md

故事007.011: 小程序支付模块多租户复制

状态

Completed

故事

作为 系统管理员， 我想要 复制小程序支付模块并添加多租户支持， 以便 支付记录可以在租户隔离的环境中管理，同时保持与现有单租户系统的完全兼容性。

验收标准

1. AC 1: 成功复制 @d8d/mini-payment 为 @d8d/mini-payment-mt，包含正确的包配置
2. AC 2: 创建多租户支付实体 PaymentMt，包含租户ID字段和表名 payments_mt
3. AC 3: 更新所有支付CRUD操作，自动包含租户过滤并在创建时设置租户ID
4. AC 4: 验证支付数据隔离在不同租户间正常工作
5. AC 5: 保持与现有单租户支付管理模块功能的完全兼容性
6. AC 6: 所有现有单租户API接口保持不变且功能正常
7. AC 7: 实现完整的租户数据隔离API测试，包括跨租户支付访问安全验证
8. AC 8: 确保性能影响小于5%
9. AC 9: 所有多租户模块的回归测试通过

任务 / 子任务

• [x] 复制小程序支付模块为多租户版本 (AC: 1)

  • 复制 packages/mini-payment 为 packages/mini-payment-mt
  • 更新包配置为 @d8d/mini-payment-mt
  • 更新依赖:
  • 将 @d8d/user-module 替换为 @d8d/user-module-mt
  • 将 @d8d/auth-module 替换为 @d8d/auth-module-mt
  • 将 @d8d/file-module 替换为 @d8d/file-module-mt

• [x] 更新多租户支付实体 (AC: 2)

  • 创建 PaymentMt 实体，表名为 payments_mt
  • 为实体添加 tenantId 字段和正确的TypeORM配置
  • 保持其他字段与单租户版本一致
  • 更新关联关系指向多租户实体

• [x] 更新多租户支付服务 (AC: 3, 4)

  • 使用共享CRUD库的GenericCrudService
  • 所有查询操作自动添加租户过滤
  • 创建操作自动设置租户ID
  • 更新关联查询支持租户隔离
  • 确保支付与用户等关联实体的租户一致性

• [x] 更新多租户路由配置 (AC: 3)

  • 更新支付路由使用多租户实体和服务
  • 保持API接口与单租户版本一致
  • 启用租户选项：tenantOptions: { enabled: true, tenantIdField: 'tenantId' }

• [x] 更新Schema定义 (AC: 3)

  • 使用多租户支付Schema PaymentSchema
  • 添加租户ID字段定义

• [x] 实现租户数据隔离API测试 (AC: 7)

  • 在 packages/mini-payment-mt/tests/integration/payment-routes.integration.test.ts 中添加租户隔离测试用例
  • 添加跨租户支付访问安全验证
  • 在现有功能测试中验证租户过滤功能正确性
  • 验证关联实体（用户）的租户隔离

• [x] 验证单租户系统完整性 (AC: 5, 6)

  • 运行单租户支付管理模块回归测试
  • 验证单租户API接口不受影响
  • 确认单租户数据库表结构不变

• [x] 在创建复制的代码修改完后先运行安装

  • 在复制模块后运行 pnpm install 安装依赖
  • 验证新包已正确添加到工作区
  • 确认所有依赖解析正确

• [x] 执行性能基准测试 (AC: 8)

  • 运行多租户支付管理模块性能测试
  • 比较单租户与多租户性能差异
  • 确保性能影响小于5%

• [x] 执行回归测试验证 (AC: 9)

  • 运行所有多租户模块的回归测试
  • 验证权限模块多租户测试 (38个测试)
  • 验证文件模块多租户测试 (40个测试)
  • 验证区域模块多租户测试 (29个测试)
  • 验证用户模块多租户测试 (41个测试)
  • 验证配送地址模块多租户测试 (36个测试)
  • 验证商户模块多租户测试 (37个测试)
  • 验证供应商模块多租户测试 (所有测试)
  • 验证租户模块多租户测试 (16个测试)
  • 验证广告模块多租户测试 (22个测试)
  • 验证商品模块多租户测试 (14个测试)
  • 验证订单模块多租户测试 (6个测试)
  • 确认所有多租户测试全部通过

开发说明

先前故事洞察

基于故事007.010（订单模块多租户复制）和之前故事的经验教训：

技术挑战和解决方案 [Source: docs/prd/epic-007-multi-tenant-package-replication.md#实施经验总结]

• 数据库同步冲突: 在vitest配置中使用 fileParallelism: false 避免并行测试导致的数据库表重复创建错误
• 租户ID字段管理: 确保所有测试数据包含正确的tenantId字段，避免null value in column "tenant_id" violates not-null constraint错误
• 目录结构错误: 清理多租户模块中错误包含的单租户模块目录，确保多租户和单租户模块在同一层级
• 共享CRUD库租户验证顺序: 确保租户验证先于数据权限验证，跨租户访问正确返回404状态码
• 多租户模块依赖: 系统清理所有多租户包的文件命名，统一使用 .mt.ts 后缀

最佳实践 [Source: docs/prd/epic-007-multi-tenant-package-replication.md#最佳实践]

• 文件命名规范: 严格使用 .mt.ts 后缀区分多租户文件
• 测试配置: 使用 fileParallelism: false 避免数据库冲突
• 类型处理: 在测试中使用类型断言处理必需参数验证
• 数据工厂: 确保所有测试数据包含正确的tenantId字段
• 依赖管理: 及时更新多租户模块间的依赖关系

数据模型

支付实体 [Source: packages/mini-payment/src/entities/payment.entity.ts]

• 表名: payments → payments_mt
• 主要字段: externalOrderId, userId, totalAmount, description, paymentStatus, wechatTransactionId, outTradeNo, openid
• 关联关系: user (通过userId关联)
• 需要添加: tenantId 字段和复合索引

API规范

路由结构 [Source: packages/mini-payment/src/routes/]

• 支付路由: payment-routes.ts
• 支付回调路由: payment-callback-routes.ts

API端点 [Source: packages/mini-payment/src/routes/]

• 支付创建: 创建支付订单
• 支付查询: 查询支付状态
• 支付回调: 处理微信支付回调
• 支付退款: 处理退款请求

文件位置

新文件路径 [Source: docs/architecture/source-tree.md#包架构层次]

• 包根目录: packages/mini-payment-mt/
• 实体文件: packages/mini-payment-mt/src/entities/payment.mt.entity.ts
• 服务文件: packages/mini-payment-mt/src/services/payment.mt.service.ts
• 路由文件: packages/mini-payment-mt/src/routes/*.mt.ts
• Schema文件: packages/mini-payment-mt/src/schemas/*.mt.schema.ts
• 测试文件: packages/mini-payment-mt/tests/integration/*.integration.test.ts

技术约束

多租户架构 [Source: docs/prd/epic-007-multi-tenant-package-replication.md#架构设计详情]

• 使用共享CRUD库的GenericCrudService
• 所有查询操作自动添加租户过滤
• 创建操作自动设置租户ID
• 启用租户选项: tenantOptions: { enabled: true, tenantIdField: 'tenantId' }
• 确保关联实体（用户）的租户一致性

性能要求 [Source: docs/prd/epic-007-multi-tenant-package-replication.md#成功标准]

• 性能影响小于5%
• 租户过滤使用数据库索引
• 确保查询性能优化，特别是支付记录查询

测试

测试标准 [Source: docs/architecture/testing-strategy.md#包测试架构]

• 测试位置: packages/mini-payment-mt/tests/integration/
• 测试框架: Vitest + hono/testing + shared-test-util
• 覆盖率目标: 集成测试 ≥ 60%
• 测试类型: 集成测试验证模块功能

测试要求 [Source: docs/architecture/testing-strategy.md#测试金字塔策略]

• 集成测试范围: 多个组件/服务协作
• 测试目标: 验证模块间集成和交互
• 执行频率: 每次API变更

特定测试要求

• 租户数据隔离验证
• 跨租户支付访问安全验证
• 租户过滤功能正确性
• 关联实体租户一致性验证
• 支付与用户的租户关联验证
• 性能基准测试

变更日志

日期	版本	描述	作者
2025-11-17	1.0	初始故事创建	Bob (Scrum Master)
2025-11-17	1.1	完成多租户支付模块实施	Claude Code

开发代理记录

Agent Model Used

• Claude Code (d8d-model)

Debug Log References

• 2025-11-17: 基于先前多租户模块复制经验创建小程序支付模块多租户复制故事
• 2025-11-17: 成功实施多租户支付模块，包括实体、服务、路由和测试
• 2025-11-17: 修复测试数据库设置问题，使用正确的 setupIntegrationDatabaseHooksWithEntities 模式

Completion Notes List

• ✅ 基于已完成的多租户模块复制经验创建详细的故事文档
• ✅ 吸取了订单模块、商品模块等多租户复制的技术挑战和解决方案
• ✅ 包含了完整的验收标准、任务分解和开发说明
• ✅ 确保与现有单租户系统完全兼容
• ✅ 成功复制并更新了多租户支付模块的所有组件
• ✅ 所有测试通过，包括租户数据隔离验证
• ✅ 修复了测试数据库设置问题，确保测试稳定运行

File List

• docs/stories/007.011.mini-payment-module-multi-tenant-replication.md - 故事文档
• packages/mini-payment-mt/package.json - 多租户支付模块包配置
• packages/mini-payment-mt/src/entities/payment.mt.entity.ts - 多租户支付实体
• packages/mini-payment-mt/src/services/payment.mt.service.ts - 多租户支付服务
• packages/mini-payment-mt/src/routes/payment/create.mt.ts - 多租户支付创建路由
• packages/mini-payment-mt/src/routes/payment/callback.mt.ts - 多租户支付回调路由
• packages/mini-payment-mt/src/routes/payment/status.mt.ts - 多租户支付状态查询路由
• packages/mini-payment-mt/src/schemas/payment.mt.schema.ts - 多租户支付Schema
• packages/mini-payment-mt/tests/integration/payment-routes.integration.test.ts - 多租户支付路由集成测试
• packages/mini-payment-mt/tests/integration/payment.integration.test.ts - 多租户支付集成测试
• packages/mini-payment-mt/tests/integration/payment-callback.integration.test.ts - 多租户支付回调集成测试

QA结果

此部分将在质量保证审查过程中由QA代理填充