# 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