4.9 KiB
4.9 KiB
打印失败自动补偿(printRetryCompensation)操作说明
概述
- 目的:定时扫描失败或超时的打印记录,按仓库分组并批量触发补打(调用内部方法
print.retryFailed)。 - 实现位置:调度任务文件 app/schedule/print_retry_compensation.js
- 配置位置:全局配置
config.printRetryCompensation(见config/config.default.js)
如何开启
- 在目标环境的配置文件中(例如
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;
};
- 启用后,Egg 的调度器会按文件中的
schedule.interval(30s)触发调度器,但实际执行受intervalMs控制(避免重复执行)。 - 部署/重启应用使配置生效。
关键参数说明
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,以控制对打印服务的并发压力。
参考位置
- 调度实现:app/schedule/print_retry_compensation.js
- 默认配置:config/config.default.js(
printRetryCompensation段) - 补打实现与仓库兼容性:app/service/systemMethods/print.js 中
retryFailed与getRetryEligibility方法
附注
- 本说明以当前代码实现为准(2026-05-20),如修改
getRetryEligibility或补打流程,请同步更新本说明与methods/changes记录。