# 史诗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. **调度器设计**：可靠的延迟打印调度器，支持故障恢复