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