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

概述

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

业务背景

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

目标

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

范围

包含的功能

飞鹅打印模块 (feie-printer-module-mt)
- 飞鹅API客户端封装（小票打印）
- 打印机管理（添加、查询、删除打印机）
- 打印任务管理（提交打印任务、查询打印状态）
- 基础打印配置管理
- 防退款延迟打印调度器
打印管理UI模块 (feie-printer-management-ui-mt)
- 打印机管理界面（添加、查询、删除打印机）
- 基础打印配置管理界面
- 打印任务查询界面
订单打印集成
- 订单支付成功后等待2分钟确认无退款再自动打印小票
- 打印失败基础重试机制
- 打印状态基础同步

不包含的功能（第一阶段）

发货单打印功能
手动打印功能
批量打印功能
复杂的打印模板设计器
离线打印功能
多语言打印支持
打印机硬件采购和维护
飞鹅打印服务费用管理

用户故事

故事1：创建飞鹅打印模块

作为系统管理员 我希望 能够集成飞鹅打印API 以便实现订单支付成功后自动打印小票

验收标准：

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

故事2：创建打印管理UI模块

作为后台管理员 我希望 有一个界面来管理打印机和打印配置以便方便地配置和管理打印功能

验收标准：

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

故事3：集成订单支付成功打印功能

作为商家用户 我希望 订单支付成功后自动打印小票以便及时处理订单

验收标准：

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

技术设计

数据库设计

-- 飞鹅打印机配置表
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

GET /api/feie/printers - 查询打印机列表
POST /api/feie/printers - 添加打印机
DELETE /api/feie/printers/{printerSn} - 删除打印机
POST /api/feie/print - 提交打印任务（支持延迟打印）
GET /api/feie/tasks/{taskId} - 查询打印任务状态
GET /api/feie/tasks - 查询打印任务列表
POST /api/feie/tasks/{taskId}/cancel - 取消打印任务
POST /api/feie/tasks/{taskId}/retry - 重试打印任务
GET /api/feie/config - 查询打印配置
PUT /api/feie/config - 更新打印配置

飞鹅API接口（需要封装）

打印机管理
- Open_printerAddlist - 添加打印机
- Open_printerDelList - 删除打印机
- Open_queryPrinterStatus - 查询打印机状态
打印任务管理
- Open_printMsg - 打印小票
- Open_queryOrderState - 查询订单打印状态
- Open_queryOrderInfoByDate - 根据时间查询订单

集成点

与现有系统集成

订单模块集成：
- 订单支付成功时触发打印事件（延迟2分钟执行）
- 订单发货时触发打印事件（立即执行）
- 订单退款时触发打印取消事件
- 订单详情页添加打印按钮
- 订单列表添加批量打印功能
- 打印状态同步到订单备注
配置模块集成：
- 使用现有的配置管理机制
- 支持租户级打印配置
- 配置项包括：默认打印机、打印触发条件、防退款延迟时间、重试策略等
事件系统集成：
- 监听订单支付成功事件（触发延迟打印）
- 监听订单发货事件（触发立即打印）
- 监听订单退款事件（触发打印取消）

数据流

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

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

直接打印流程（发货时）

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

手动打印流程

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

打印取消逻辑

取消场景定义

退款取消（REFUND）
- 触发条件：订单在延迟打印期间发生退款
- 取消时机：退款事件发生时立即取消
- 业务意义：避免无效打印，节省打印资源
- 实现方式：监听退款事件，自动调用取消接口
手动取消（MANUAL）
- 触发条件：管理员手动取消打印任务
- 取消时机：任何时间点
- 业务意义：人工干预打印流程
- 实现方式：提供手动取消按钮
超时取消（TIMEOUT）
- 触发条件：打印任务长时间未完成
- 取消时机：超过配置的超时时间
- 业务意义：避免僵尸任务占用资源
- 实现方式：定时任务检查超时任务

取消规则

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

配置管理

租户级配置项

feie.enabled - 是否启用飞鹅打印
feie.default_printer_sn - 默认打印机序列号
feie.auto_print_on_payment - 支付成功时自动打印
feie.auto_print_on_shipping - 发货时自动打印
feie.anti_refund_delay - 防退款延迟时间（秒，默认120秒/2分钟）
feie.retry_max_count - 最大重试次数
feie.retry_interval - 重试间隔（秒）
feie.task_timeout - 任务超时时间（秒）
feie.receipt_template - 小票模板
feie.shipping_template - 发货单模板

兼容性要求

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

风险与缓解

风险1：飞鹅API调用失败影响订单流程

缓解措施：打印功能异步处理，不影响订单核心流程
降级策略：打印失败时记录日志，不影响订单状态
监控告警：监控打印失败率，设置告警阈值

风险2：打印机状态异常导致打印失败

缓解措施：定期检查打印机状态，异常时告警
备用打印机：支持配置备用打印机
手动重试：提供手动重试功能

风险3：防退款延迟机制失效导致无效打印

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

风险4：延迟打印调度器故障

缓解措施：实现调度器健康检查
故障恢复：支持调度器重启后恢复未完成任务
监控告警：监控调度器运行状态

风险5：网络延迟影响打印响应

缓解措施：异步处理打印任务，不阻塞用户操作
超时设置：设置合理的API调用超时时间
状态轮询：通过轮询方式获取打印状态

测试策略

单元测试

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

集成测试

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

E2E测试

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

部署计划

阶段1：开发环境部署

创建数据库迁移脚本
部署飞鹅打印模块和UI模块
配置测试打印机
验证基本打印功能
验证防退款延迟打印功能

阶段2：测试环境验证

功能测试和集成测试
性能测试和压力测试
兼容性测试
安全测试

阶段3：生产环境部署

执行数据库迁移
部署新模块
配置生产打印机
灰度启用打印功能
监控系统运行状态

成功指标

功能指标：
- 打印机添加成功率达到100%
- 打印任务提交成功率达到99%
- 防退款延迟打印准确率达到98%
- 打印取消功能准确率达到100%
- 打印状态查询准确率达到100%
性能指标：
- 打印任务提交响应时间 < 500ms
- 打印机状态查询响应时间 < 200ms
- 打印任务列表查询响应时间 < 300ms
- 防退款延迟调度器误差 < 10秒
业务指标：
- 商家打印效率提升50%
- 无效打印率降低到1%以下
- 商家满意度提升

后续优化建议

支持更多打印机品牌和型号
实现打印模板可视化设计器
添加打印统计和报表功能
支持离线打印队列
实现打印任务优先级管理
添加打印成本统计功能

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

开发进度

待完成

🔄 故事1：创建飞鹅打印模块
🔄 故事2：创建打印管理UI模块
🔄 故事3：集成订单打印功能

技术实现要点

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

epic-005-feie-printer-integration.md 18 KB تاريخچه خام

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

概述

业务背景

目标

范围

包含的功能

不包含的功能（第一阶段）

用户故事

故事1：创建飞鹅打印模块

故事2：创建打印管理UI模块

故事3：集成订单支付成功打印功能

技术设计

数据库设计

模块结构

API设计

飞鹅打印模块API

飞鹅API接口（需要封装）

集成点

与现有系统集成

数据流

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

直接打印流程（发货时）

手动打印流程

打印取消逻辑

取消场景定义

取消规则

配置管理

租户级配置项

兼容性要求

风险与缓解

风险1：飞鹅API调用失败影响订单流程

风险2：打印机状态异常导致打印失败

风险3：防退款延迟机制失效导致无效打印

风险4：延迟打印调度器故障

风险5：网络延迟影响打印响应

测试策略

单元测试

集成测试

E2E测试

部署计划

阶段1：开发环境部署

阶段2：测试环境验证

阶段3：生产环境部署

成功指标

后续优化建议

开发进度

待完成

技术实现要点

epic-005-feie-printer-integration.md 18 KB

تاريخچه خام