一次性延迟任务

延迟任务适合“订单创建 30 分钟后仍未确认则提醒”“明天再次检查处理结果”等一次性工作。固定每天或每周运行的任务仍使用jobs 定时任务。

先在 xdb-paas-deploy.yaml 中声明允许执行的任务：

delayed_jobs:
  - name: order-timeout
    command: npm run jobs:order-timeout
    timeout_seconds: 300

建议使用 JavaScript/Python SDK 正式版 0.1.0 或更新版本。

Node.js

import { xdbPaaS } from "@xinduobang/xdb-paas-sdk/server";

const job = await xdbPaaS.delayedJobs.enqueue("order-timeout", {
  delaySeconds: 30 * 60,
  payload: { orderId: "order_123" },
});

const queued = await xdbPaaS.delayedJobs.list({ status: "queued" });
// 需要取消时再执行。
await xdbPaaS.delayedJobs.cancel(job.id);

也可使用绝对时间：

await xdbPaaS.delayedJobs.enqueue("order-timeout", {
  runAt: new Date(Date.now() + 60 * 60 * 1000).toISOString(),
  payload: { orderId: "order_123" },
});

Python

from xdb_paas import xdb_paas

jobs = xdb_paas.delayed_jobs.create_client()
job = jobs.enqueue(
    "order-timeout",
    delay_seconds=30 * 60,
    payload={"orderId": "order_123"},
)
queued = jobs.list(status="queued")
# 需要取消时再执行。
jobs.cancel(job["id"])

安全和执行规则

• 只能由云应用 Production 后端使用平台注入的 Runtime Token 投递；浏览器、Preview 和本地电脑不能直接投递；
• 接口只接收清单中声明过的任务名，不接收动态 shell 命令；
• 取消只对尚未开始的 queued 任务有效；
• 任务状态为 queued、running、succeeded、failed 或 cancelled；
• 平台进程异常恢复时可能再次执行已领取但未确认完成的任务，因此处理器必须幂等；
• 输出、失败原因和开始/完成记录进入应用 Runtime 日志与审计。

本地开发时直接执行任务命令，并用样例 JSON 设置 XDB_PAAS_JOB_PAYLOAD。本地电脑不会被云端调度器延迟唤醒；发布到 Production 后再验证投递闭环。