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