# 史诗005：集成飞鹅打印接口

## 概述
为多租户电商平台集成飞鹅打印（Feie）接口，实现订单支付成功后等待2分钟确认无退款再自动打印小票功能。这是打印功能的第一阶段，聚焦核心防退款延迟打印机制。

## 业务背景
当前系统缺乏订单打印功能，商家需要手动处理订单打印，效率低下且容易出错。飞鹅打印是国内领先的云打印服务，支持多种打印机类型和打印格式。通过集成飞鹅打印接口，可以实现订单自动打印，提升商家运营效率。同时，为避免退款导致的无效打印，需要实现支付成功后等待2分钟确认无退款再打印的机制。

## 目标
1. 集成飞鹅打印API，支持小票打印功能
2. 实现订单支付成功后等待2分钟确认无退款再自动打印小票
3. 提供基础的打印配置管理
4. 确保与现有订单系统无缝集成

## 范围
### 包含的功能
1. **飞鹅打印模块** (`feie-printer-module-mt`)
   - 飞鹅API客户端封装（小票打印）
   - 打印机管理（添加、查询、删除打印机）
   - 打印任务管理（提交打印任务、查询打印状态）
   - 基础打印配置管理
   - 防退款延迟打印调度器

2. **打印管理UI模块** (`feie-printer-management-ui-mt`)
   - 打印机管理界面（添加、查询、删除打印机）
   - 基础打印配置管理界面
   - 打印任务查询界面

3. **订单打印集成**
   - 订单支付成功后等待2分钟确认无退款再自动打印小票
   - 打印失败基础重试机制
   - 打印状态基础同步

### 不包含的功能（第一阶段）
1. 发货单打印功能
2. 手动打印功能
3. 批量打印功能
4. 复杂的打印模板设计器
5. 离线打印功能
6. 多语言打印支持
7. 打印机硬件采购和维护
8. 飞鹅打印服务费用管理

## 用户故事
### 故事1：创建飞鹅打印模块
**作为** 系统管理员
**我希望** 能够集成飞鹅打印API
**以便** 实现订单支付成功后自动打印小票

**验收标准：**
- [ ] 创建`feie_printer_mt`表，存储打印机配置信息
- [ ] 创建`feie_print_task_mt`表，记录打印任务（包含防退款延迟相关字段）
- [ ] 创建`feie_config_mt`表，存储基础打印配置
- [ ] 实现飞鹅API客户端，支持小票打印接口
- [ ] 提供打印机管理服务（添加、查询、删除打印机）
- [ ] 提供打印任务管理服务（提交任务、查询状态、取消任务）
- [ ] 实现防退款延迟打印调度器（默认2分钟延迟）
- [ ] 编写单元测试覆盖核心逻辑

### 故事2：创建打印管理UI模块
**作为** 后台管理员
**我希望** 有一个界面来管理打印机和打印配置
**以便** 方便地配置和管理打印功能

**验收标准：**
- [ ] 创建打印机管理界面，支持添加、查询、删除打印机
- [ ] 创建打印配置管理界面，支持基础配置（防退款延迟时间等）
- [ ] 创建打印任务查询界面，显示打印任务状态
- [ ] 界面风格与现有后台保持一致
- [ ] 添加权限控制，只有管理员可访问

### 故事3：集成订单支付成功打印功能
**作为** 商家用户
**我希望** 订单支付成功后自动打印小票
**以便** 及时处理订单

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

## 技术设计
### 数据库设计
```sql
-- 飞鹅打印机配置表
CREATE TABLE feie_printer_mt (
  id BIGINT UNSIGNED PRIMARY KEY AUTO_INCREMENT,
  tenant_id INT UNSIGNED NOT NULL COMMENT '租户ID',
  printer_sn VARCHAR(50) NOT NULL COMMENT '打印机序列号',
  printer_key VARCHAR(100) NOT NULL COMMENT '打印机密钥',
  printer_name VARCHAR(100) COMMENT '打印机名称',
  printer_type VARCHAR(20) DEFAULT '58mm' COMMENT '打印机类型: 58mm, 80mm',
  printer_status VARCHAR(20) DEFAULT 'ACTIVE' COMMENT '打印机状态: ACTIVE, INACTIVE, ERROR',
  is_default TINYINT DEFAULT 0 COMMENT '是否默认打印机(0:否,1:是)',
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
  UNIQUE KEY uk_tenant_printer_sn (tenant_id, printer_sn),
  INDEX idx_tenant_id (tenant_id),
  INDEX idx_status (printer_status)
) COMMENT='飞鹅打印机配置表';

-- 飞鹅打印任务表（支持防退款延迟打印）
CREATE TABLE feie_print_task_mt (
  id BIGINT UNSIGNED PRIMARY KEY AUTO_INCREMENT,
  tenant_id INT UNSIGNED NOT NULL COMMENT '租户ID',
  task_id VARCHAR(100) NOT NULL COMMENT '飞鹅任务ID',
  order_id INT UNSIGNED COMMENT '关联订单ID',
  printer_sn VARCHAR(50) NOT NULL COMMENT '打印机序列号',
  content TEXT NOT NULL COMMENT '打印内容',
  print_type VARCHAR(20) NOT NULL COMMENT '打印类型: RECEIPT(小票), SHIPPING(发货单), ORDER(订单)',
  print_status VARCHAR(20) DEFAULT 'PENDING' COMMENT '打印状态: PENDING, DELAYED(延迟等待), PRINTING, SUCCESS, FAILED, CANCELLED(已取消)',
  error_message VARCHAR(500) COMMENT '错误信息',
  retry_count INT DEFAULT 0 COMMENT '重试次数',
  max_retries INT DEFAULT 3 COMMENT '最大重试次数',
  scheduled_at TIMESTAMP NULL COMMENT '计划打印时间（用于延迟打印）',
  printed_at TIMESTAMP NULL COMMENT '打印完成时间',
  cancelled_at TIMESTAMP NULL COMMENT '取消时间',
  cancel_reason VARCHAR(100) COMMENT '取消原因: REFUND(退款), MANUAL(手动取消), TIMEOUT(超时)',
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
  UNIQUE KEY uk_task_id (task_id),
  INDEX idx_tenant_order (tenant_id, order_id),
  INDEX idx_status (print_status),
  INDEX idx_scheduled (scheduled_at),
  INDEX idx_created (created_at)
) COMMENT='飞鹅打印任务表';

-- 打印配置表
CREATE TABLE feie_config_mt (
  id BIGINT UNSIGNED PRIMARY KEY AUTO_INCREMENT,
  tenant_id INT UNSIGNED NOT NULL COMMENT '租户ID',
  config_key VARCHAR(50) NOT NULL COMMENT '配置键',
  config_value TEXT COMMENT '配置值',
  config_type VARCHAR(20) DEFAULT 'STRING' COMMENT '配置类型: STRING, JSON, BOOLEAN, NUMBER',
  description VARCHAR(200) COMMENT '配置描述',
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
  UNIQUE KEY uk_tenant_key (tenant_id, config_key),
  INDEX idx_tenant_id (tenant_id)
) COMMENT='飞鹅打印配置表';
```

### 模块结构
```
packages/
├── @d8d/feie-printer-module-mt/     # 飞鹅打印模块
│   ├── src/
│   │   ├── entities/                  # 实体定义
│   │   │   ├── feie-printer.mt.entity.ts
│   │   │   ├── feie-print-task.mt.entity.ts
│   │   │   ├── feie-config.mt.entity.ts
│   │   │   └── index.ts
│   │   ├── services/                  # 服务层
│   │   │   ├── feie-api.service.ts    # 飞鹅API客户端（小票打印）
│   │   │   ├── printer.service.ts     # 打印机管理服务
│   │   │   ├── print-task.service.ts  # 打印任务服务
│   │   │   ├── delay-scheduler.service.ts  # 延迟打印调度器
│   │   │   └── index.ts
│   │   ├── schemas/                   # 数据验证
│   │   │   └── index.ts
│   │   ├── routes/                    # API路由
│   │   │   └── index.ts
│   │   ├── types/                     # 类型定义
│   │   │   └── index.ts
│   │   └── index.ts                   # 主入口文件
│   ├── tests/                         # 测试文件
│   ├── tsconfig.json                  # TypeScript配置
│   ├── vitest.config.ts               # 测试配置
│   └── package.json
└── @d8d/feie-printer-management-ui-mt/   # 打印管理UI模块
    ├── src/
    │   ├── api/                       # API客户端
    │   │   ├── index.ts
    │   │   └── feiePrinterClient.ts
    │   ├── components/                # 组件
    │   │   ├── PrinterManagement.tsx
    │   │   ├── PrintConfigManagement.tsx
    │   │   ├── PrintTaskQuery.tsx
    │   │   └── index.ts
    │   ├── hooks/                     # React hooks
    │   │   └── index.ts
    │   ├── types/                     # 类型定义
    │   │   ├── index.ts
    │   │   └── feiePrinter.ts
    │   └── index.ts                   # 主入口文件
    ├── tests/                         # 测试文件
    ├── eslint.config.js               # ESLint配置
    ├── tsconfig.json                  # TypeScript配置
    ├── vitest.config.ts               # 测试配置
    └── package.json
```

### API设计
#### 飞鹅打印模块API
1. `GET /api/feie/printers` - 查询打印机列表
2. `POST /api/feie/printers` - 添加打印机
3. `DELETE /api/feie/printers/{printerSn}` - 删除打印机
4. `POST /api/feie/print` - 提交打印任务（支持延迟打印）
5. `GET /api/feie/tasks/{taskId}` - 查询打印任务状态
6. `GET /api/feie/tasks` - 查询打印任务列表
7. `POST /api/feie/tasks/{taskId}/cancel` - 取消打印任务
8. `POST /api/feie/tasks/{taskId}/retry` - 重试打印任务
9. `GET /api/feie/config` - 查询打印配置
10. `PUT /api/feie/config` - 更新打印配置

#### 飞鹅API接口（需要封装）
1. **打印机管理**
   - `Open_printerAddlist` - 添加打印机
   - `Open_printerDelList` - 删除打印机
   - `Open_queryPrinterStatus` - 查询打印机状态

2. **打印任务管理**
   - `Open_printMsg` - 打印小票
   - `Open_queryOrderState` - 查询订单打印状态
   - `Open_queryOrderInfoByDate` - 根据时间查询订单

## 集成点
### 与现有系统集成
1. **订单模块集成**：
   - 订单支付成功时触发打印事件（延迟2分钟执行）
   - 订单发货时触发打印事件（立即执行）
   - 订单退款时触发打印取消事件
   - 订单详情页添加打印按钮
   - 订单列表添加批量打印功能
   - 打印状态同步到订单备注

2. **配置模块集成**：
   - 使用现有的配置管理机制
   - 支持租户级打印配置
   - 配置项包括：默认打印机、打印触发条件、防退款延迟时间、重试策略等

3. **事件系统集成**：
   - 监听订单支付成功事件（触发延迟打印）
   - 监听订单发货事件（触发立即打印）
   - 监听订单退款事件（触发打印取消）

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

#### 直接打印流程（发货时）
1. 订单发货 → 触发打印事件 → 打印模块接收事件
2. 打印模块查询租户打印配置 → 获取默认打印机
3. 生成打印内容（发货单模板） → 调用飞鹅API提交打印任务
4. 记录打印任务到数据库 → 返回任务ID
5. 定时轮询打印状态 → 更新任务状态
6. 打印成功 → 更新订单备注
7. 打印失败 → 根据重试策略重试

#### 手动打印流程
1. 用户在订单详情页点击打印按钮 → 调用打印API
2. 选择打印机（或使用默认打印机） → 生成打印内容
3. 提交打印任务 → 显示打印状态
4. 用户可在打印任务列表查看打印状态

## 打印取消逻辑
### 取消场景定义
1. **退款取消（REFUND）**
   - **触发条件**：订单在延迟打印期间发生退款
   - **取消时机**：退款事件发生时立即取消
   - **业务意义**：避免无效打印，节省打印资源
   - **实现方式**：监听退款事件，自动调用取消接口

2. **手动取消（MANUAL）**
   - **触发条件**：管理员手动取消打印任务
   - **取消时机**：任何时间点
   - **业务意义**：人工干预打印流程
   - **实现方式**：提供手动取消按钮

3. **超时取消（TIMEOUT）**
   - **触发条件**：打印任务长时间未完成
   - **取消时机**：超过配置的超时时间
   - **业务意义**：避免僵尸任务占用资源
   - **实现方式**：定时任务检查超时任务

### 取消规则
1. **状态检查**：只有特定状态的任务才能取消（`PENDING`, `DELAYED`, `PRINTING`）
2. **幂等性保证**：同一任务只能取消一次，防止重复取消
3. **日志记录**：每次取消都记录详细的原因和时间
4. **通知机制**：任务取消时通知相关人员

## 配置管理
### 租户级配置项
1. `feie.enabled` - 是否启用飞鹅打印
2. `feie.default_printer_sn` - 默认打印机序列号
3. `feie.auto_print_on_payment` - 支付成功时自动打印
4. `feie.auto_print_on_shipping` - 发货时自动打印
5. `feie.anti_refund_delay` - 防退款延迟时间（秒，默认120秒/2分钟）
6. `feie.retry_max_count` - 最大重试次数
7. `feie.retry_interval` - 重试间隔（秒）
8. `feie.task_timeout` - 任务超时时间（秒）
9. `feie.receipt_template` - 小票模板
10. `feie.shipping_template` - 发货单模板

## 兼容性要求
1. **API兼容性**：新增API端点，不影响现有API
2. **数据库兼容性**：新增表，不影响现有表结构
3. **UI兼容性**：新增页面和组件，遵循现有UI规范
4. **订单流程兼容性**：打印功能作为可选扩展，不影响核心订单流程

## 风险与缓解
### 风险1：飞鹅API调用失败影响订单流程
- **缓解措施**：打印功能异步处理，不影响订单核心流程
- **降级策略**：打印失败时记录日志，不影响订单状态
- **监控告警**：监控打印失败率，设置告警阈值

### 风险2：打印机状态异常导致打印失败
- **缓解措施**：定期检查打印机状态，异常时告警
- **备用打印机**：支持配置备用打印机
- **手动重试**：提供手动重试功能

### 风险3：防退款延迟机制失效导致无效打印
- **缓解措施**：实现可靠的退款事件监听机制
- **状态验证**：延迟时间到达后再次验证订单状态
- **手动取消**：提供手动取消无效打印任务的功能

### 风险4：延迟打印调度器故障
- **缓解措施**：实现调度器健康检查
- **故障恢复**：支持调度器重启后恢复未完成任务
- **监控告警**：监控调度器运行状态

### 风险5：网络延迟影响打印响应
- **缓解措施**：异步处理打印任务，不阻塞用户操作
- **超时设置**：设置合理的API调用超时时间
- **状态轮询**：通过轮询方式获取打印状态

## 测试策略
### 单元测试
- 飞鹅API客户端测试
- 打印机管理逻辑测试
- 打印任务管理测试
- 防退款延迟调度器测试
- 模板生成逻辑测试

### 集成测试
- 飞鹅API集成测试（使用模拟API）
- 订单打印触发测试
- 防退款延迟打印测试
- 打印取消功能测试
- 打印状态同步测试
- 配置管理测试

### E2E测试
- 打印机管理流程测试
- 手动打印功能测试
- 自动打印触发测试（支付成功延迟打印）
- 防退款取消打印测试
- 打印记录查询测试

## 部署计划
### 阶段1：开发环境部署
1. 创建数据库迁移脚本
2. 部署飞鹅打印模块和UI模块
3. 配置测试打印机
4. 验证基本打印功能
5. 验证防退款延迟打印功能

### 阶段2：测试环境验证
1. 功能测试和集成测试
2. 性能测试和压力测试
3. 兼容性测试
4. 安全测试

### 阶段3：生产环境部署
1. 执行数据库迁移
2. 部署新模块
3. 配置生产打印机
4. 灰度启用打印功能
5. 监控系统运行状态

## 成功指标
1. **功能指标**：
   - 打印机添加成功率达到100%
   - 打印任务提交成功率达到99%
   - 防退款延迟打印准确率达到98%
   - 打印取消功能准确率达到100%
   - 打印状态查询准确率达到100%

2. **性能指标**：
   - 打印任务提交响应时间 < 500ms
   - 打印机状态查询响应时间 < 200ms
   - 打印任务列表查询响应时间 < 300ms
   - 防退款延迟调度器误差 < 10秒

3. **业务指标**：
   - 商家打印效率提升50%
   - 无效打印率降低到1%以下
   - 商家满意度提升

## 后续优化建议
1. 支持更多打印机品牌和型号
2. 实现打印模板可视化设计器
3. 添加打印统计和报表功能
4. 支持离线打印队列
5. 实现打印任务优先级管理
6. 添加打印成本统计功能

---
**创建时间**：2025-12-06
**负责人**：产品经理
**状态**：待开始
**优先级**：中

## 开发进度
### 待完成
1. 🔄 **故事1：创建飞鹅打印模块**
2. 🔄 **故事2：创建打印管理UI模块**
3. 🔄 **故事3：集成订单打印功能**

### 技术实现要点
1. **多租户架构**：严格遵循项目多租户包架构模式，使用`-mt`后缀和租户ID隔离
2. **防退款延迟机制**：支付成功后等待2分钟确认无退款再打印，避免无效打印
3. **异步处理**：打印任务异步处理，不阻塞核心业务流程
4. **错误处理**：完善的错误处理和重试机制
5. **配置驱动**：灵活的配置管理，支持不同租户的不同需求
6. **模板系统**：可配置的打印模板，支持变量替换
7. **状态同步**：实时同步打印状态到订单系统
8. **调度器设计**：可靠的延迟打印调度器，支持故障恢复