---
description: Laravel Queue Job 与 Scheduler 规范
globs: backend/app/Jobs/**,backend/app/Console/**,backend/app/Listeners/**,backend/routes/console.php
alwaysApply: false
---
# Queue / Scheduler

详见 `docs/08-queue-scheduler.md`。

## 必须入队的任务
第三方订单 / 库存 / 物流 / Tracking 同步、批量导入导出、面单生成、大量库存计算、报表生成、AI 分析、邮件通知、Webhook 处理。
**用户 HTTP 请求不得同步等待第三方 API。**

## Job 要求
- 构造参数携带 `tenant_code`，`handle()` 开始时恢复 TenantContext。
- 幂等：重复执行不重复建单、不重复扣库存（用业务唯一键或幂等键判断）。
- 显式设置 `$tries`、`$backoff`、`$timeout`，失败记录日志（`failed()`）。
- 传递业务编码 / 主键，不序列化大对象。

## Scheduler 要求
- 任务可配置（开关、频率在配置或租户设置中）。
- 使用 `withoutOverlapping()` / `onOneServer()` 防重复执行。
- 设置超时、失败重试与日志；按租户分发 Job，保证租户隔离。