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

65 lines
4.9 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 打印失败自动补偿(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` 记录。