WMS_MAIN/docs/print-retry-compensation.md
liufumingren 8cf2c5befa 1
2026-05-20 16:31:29 +08:00

4.9 KiB
Raw Blame History

打印失败自动补偿(printRetryCompensation)操作说明

概述

  • 目的:定时扫描失败或超时的打印记录,按仓库分组并批量触发补打(调用内部方法 print.retryFailed)。
  • 实现位置:调度任务文件 app/schedule/print_retry_compensation.js
  • 配置位置:全局配置 config.printRetryCompensation(见 config/config.default.js)

如何开启

  1. 在目标环境的配置文件中(例如 config/config.local.js 或部署时注入的 config),设置:
// 示例(config/config.local.js)
module.exports = appInfo => {
  const config = exports = {};

  config.printRetryCompensation = {
    enable: true,        // 开启自动补偿
    intervalMs: 60 * 1000, // 最小执行间隔(ms),默认 60000
    batchSize: 50,       // 每次扫描触发的最大打印记录数,默认 50
    force: false,        // 是否以强制方式触发(当前实现不放宽状态判定)
  };

  return config;
};
  1. 启用后,Egg 的调度器会按文件中的 schedule.interval(30s)触发调度器,但实际执行受 intervalMs 控制(避免重复执行)。
  2. 部署/重启应用使配置生效。

关键参数说明

  • enable (boolean):是否启用自动补偿(默认 false)。
  • intervalMs (number, ms):两次实际执行之间的最小间隔(默认 60000)。注意调度器仍以 30s 触发,但若距离上次执行时间 < intervalMs 将跳过本轮。
  • batchSize (number):每次从数据库读出的最大记录数量(默认 50)。
  • force (boolean):是否强制补打。当前最小实现中 force 参数会被传递到 print.retryFailed,但 getRetryEligibility 中并未放宽状态检查(注释标注为“最小实现”)。如需放宽,需要修改 app/service/systemMethods/print.js 中的 getRetryEligibility 实现。

行为与兼容性(与代码的一致性要点)

  • 调度逻辑:
    • 调度入口:app/schedule/print_retry_compensation.js
    • 查询条件:满足任一 send_status 为 send_failed,或 print_status 在 ['print_failed','timeout'],且 next_retry_at <= now,并且 retry_count < max_retry_count。
    • 按 warehouse_id 分组后,逐仓调用: ctx.service.systemMethods.print.retryFailed({ print_ids, warehouse_id, force })。
  • print.retryFailed 对 warehouse_id 的兼容:
    • 支持显式传入 warehouse_id,优先使用该值。
    • 若未传入 warehouse_id,会回退使用 ctx.user.store_id(接口调用者的仓库上下文)。
    • 如果两者均无(例如外部无登录上下文且未传入 warehouse_id),方法会返回 400 错误:warehouse_id 参数缺失,且当前上下文无可用仓库信息。
  • 返回值要点:成功返回包含 success_count / failed_count / skipped_count、retried(尝试项)和 skipped(跳过项)摘要;调度器依据 flag==='success' 判定调用是否成功。

排障要点(常见问题排查)

  • 任务一直没有扫描到记录:检查数据库 PrintRecord 表中是否存在满足条件的行(send_status/print_status、next_retry_at、retry_count < max_retry_count)。
  • 调度被频繁跳过:检查 config.printRetryCompensation.intervalMs 与日志中 ctx.app._printRetryCompensationLastRunAt 的时间差;若 _printRetryCompensationRunning 标识长时间为 true,进程可能在上次运行时异常退出,建议重启应用清理状态。
  • 补打触发但实际发送失败:查看打印服务调用日志(service.systems.print.index.sendToComputer 返回值),并查看 PrintRecord 的 error_message / fail_code 字段。
  • 快递/组件离线导致发送失败:print 服务会在调用前检查组件在线性(从 Redis 的 printer:{computerId}:name:{component}:status 读取,期望值为 connected)。请检查对应 Redis key 是否存在并为 connected。
  • 打印任务编码冲突:如果出现唯一索引冲突(ER_DUP_ENTRY),日志会有 打印任务编码冲突 的警告,系统会按指数退避重试写入映射表。

回滚方式

  • 临时回滚:在运行环境配置中将 printRetryCompensation.enable 设为 false 并重启服务,调度器将不再触发实际补偿逻辑。
  • 速率/批量调整:将 batchSize 缩小或增大 intervalMs,以控制对打印服务的并发压力。

参考位置

附注

  • 本说明以当前代码实现为准(2026-05-20),如修改 getRetryEligibility 或补打流程,请同步更新本说明与 methods/changes 记录。