mini-starter/docs/stories/005.003.story.md

Story 005.003: 集成订单支付成功打印功能

Status

Draft

Story

As a 商家用户 I want 订单支付成功后自动打印小票 so that 及时处理订单

Acceptance Criteria

1. 订单支付成功后等待2分钟确认无退款再自动打印小票
2. 实现基础打印失败重试机制（最多重试3次）
3. 打印状态同步到订单备注
4. 支持配置防退款延迟时间（默认120秒）
5. 如果2分钟内发生退款，则自动取消打印任务

Tasks / Subtasks

• 任务1：实现订单支付成功事件监听和延迟打印触发 (AC: 1,4,5)
  • 在订单模块中监听支付成功事件
  • 调用飞鹅打印模块API触发延迟打印任务
  • 实现防退款延迟时间配置读取（默认120秒）
  • 设置打印任务为DELAYED状态，记录scheduled_at时间
• 任务2：实现防退款延迟打印调度器集成 (AC: 1,5)
  • 集成飞鹅打印模块的延迟打印调度器
  • 实现延迟时间到达后的打印执行逻辑
  • 实现延迟期间退款事件监听和任务取消
  • 实现订单状态验证（延迟时间到达后再次检查订单是否退款）
• 任务3：实现打印失败重试机制 (AC: 2)
  • 集成飞鹅打印模块的重试机制
  • 实现最大重试次数配置（默认3次）
  • 实现重试间隔配置
  • 实现重试失败后的错误处理
• 任务4：实现打印状态同步到订单备注 (AC: 3)
  • 在打印任务状态更新时同步到订单备注
  • 实现订单备注更新API调用
  • 记录打印时间、打印机信息、任务状态等
  • 支持打印失败时的错误信息记录
• 任务5：实现退款事件监听和打印任务取消 (AC: 5)
  • 监听订单退款事件
  • 查询关联的打印任务（状态为PENDING、DELAYED、PRINTING）
  • 调用飞鹅打印模块API取消打印任务
  • 更新打印任务状态为CANCELLED，记录取消原因为REFUND
• 任务6：编写集成测试和E2E测试 (AC: 1,2,3,4,5)
  • 编写订单支付成功触发延迟打印的集成测试
  • 编写防退款延迟打印取消的集成测试
  • 编写打印失败重试机制的集成测试
  • 编写打印状态同步的集成测试
  • 编写E2E测试验证完整流程

Dev Notes

相关架构信息

根据史诗005的技术设计部分：

1. 防退款延迟打印流程（支付成功后）：

   • 订单支付成功 → 触发打印事件 → 打印模块接收事件
   • 打印模块查询租户打印配置 → 获取防退款延迟时间（默认120秒/2分钟）
   • 生成打印内容（小票模板） → 创建延迟打印任务
   • 记录打印任务到数据库，状态为DELAYED，设置scheduled_at为当前时间+延迟时间
   • 启动延迟任务调度器，等待延迟时间到达
   • 延迟期间监控退款事件：
     • 如果2分钟内发生退款 → 取消打印任务（状态改为CANCELLED，原因REFUND）
     • 如果2分钟内无退款 → 继续执行打印
   • 延迟时间到达后，检查订单状态：
     • 如果订单已退款 → 取消打印任务
     • 如果订单正常 → 调用飞鹅API提交打印任务
   • 提交打印任务 → 状态改为PRINTING → 记录飞鹅任务ID
   • 定时轮询打印状态 → 更新任务状态
   • 打印成功 → 状态改为SUCCESS → 更新订单备注
   • 打印失败 → 根据重试策略重试

2. 数据库表结构：

   • feie_print_task_mt表已包含防退款延迟相关字段：
     • print_status: 打印状态（PENDING, DELAYED, PRINTING, SUCCESS, FAILED, CANCELLED）
     • scheduled_at: 计划打印时间（用于延迟打印）
     • cancelled_at: 取消时间
     • cancel_reason: 取消原因（REFUND, MANUAL, TIMEOUT）
     • retry_count: 重试次数
     • max_retries: 最大重试次数

3. 配置管理：

   • 租户级配置项在feie_config_mt表中：
     • feie.anti_refund_delay: 防退款延迟时间（秒，默认120秒/2分钟）
     • feie.retry_max_count: 最大重试次数
     • feie.retry_interval: 重试间隔（秒）
     • feie.auto_print_on_payment: 支付成功时自动打印开关

4. 模块结构：

   • 飞鹅打印模块：@d8d/feie-printer-module-mt
   • 打印管理UI模块：@d8d/feie-printer-management-ui-mt
   • 订单模块：需要集成打印功能

5. API设计：

   • 飞鹅打印模块API已实现：
     • POST /api/feie/print - 提交打印任务（支持延迟打印）
     • POST /api/feie/tasks/{taskId}/cancel - 取消打印任务
     • GET /api/feie/config - 查询打印配置

源树信息

根据史诗005的模块结构部分：

packages/
├── @d8d/feie-printer-module-mt/     # 飞鹅打印模块（故事005.001已创建）
│   ├── src/
│   │   ├── services/
│   │   │   ├── feie-api.service.ts    # 飞鹅API客户端（小票打印）
│   │   │   ├── printer.service.ts     # 打印机管理服务
│   │   │   ├── print-task.service.ts  # 打印任务服务
│   │   │   ├── delay-scheduler.service.ts  # 延迟打印调度器
│   │   │   └── index.ts
│   │   └── index.ts                   # 主入口文件
└── @d8d/feie-printer-management-ui-mt/   # 打印管理UI模块（故事005.002已创建）

集成点

根据史诗005的集成点部分：

1. 订单模块集成：

   • 订单支付成功时触发打印事件（延迟2分钟执行）
   • 订单退款时触发打印取消事件
   • 打印状态同步到订单备注

2. 事件系统集成：

   • 监听订单支付成功事件（触发延迟打印）
   • 监听订单退款事件（触发打印取消）

测试标准

根据史诗005的测试策略部分：

1. 集成测试：

   • 订单打印触发测试
   • 防退款延迟打印测试
   • 打印取消功能测试
   • 打印状态同步测试

2. E2E测试：

   • 自动打印触发测试（支付成功延迟打印）
   • 防退款取消打印测试
   • 打印记录查询测试

编码标准

• 严格遵循项目多租户包架构模式，使用-mt后缀和租户ID隔离
• 异步处理打印任务，不阻塞核心业务流程
• 完善的错误处理和重试机制
• 配置驱动，支持不同租户的不同需求
• 实时同步打印状态到订单系统

Testing

测试文件位置

• 集成测试：在相关模块的tests/目录下
• E2E测试：在项目根目录的tests/e2e/目录下

测试框架和模式

• 集成测试：使用Vitest
• E2E测试：使用Playwright
• 测试模式：遵循项目现有的测试模式

特定测试要求

1. 防退款延迟打印测试：

   • 验证支付成功后延迟2分钟打印
   • 验证延迟期间退款自动取消打印
   • 验证延迟时间到达后订单状态验证

2. 重试机制测试：

   • 验证打印失败后自动重试（最多3次）
   • 验证重试间隔配置生效
   • 验证重试失败后的错误处理

3. 状态同步测试：

   • 验证打印状态同步到订单备注
   • 验证打印失败错误信息记录
   • 验证打印时间记录

Change Log

Date	Version	Description	Author
2025-12-06	1.0	初始创建故事文档	Scrum Master

Dev Agent Record

Agent Model Used

Debug Log References

Completion Notes List

File List

QA Results