系统定时任务 API

接收来自 pg_cron 或手动触发的定时任务请求。执行后会调用 update_cron_job_status_by_name RPC 更新任务状态，连续失败达到阈值时自动禁用任务。

基础路径

/cron

认证方式

所有端点均需通过 Cron 认证中间件验证，支持两种方式：

方式	Header	说明
pg_cron 内部调用	Authorization: Bearer <service_role_key> + X-Cron-Source: pg_cron	数据库 pg_cron 函数调用，使用 service_role_key
手动调用	Authorization: Bearer <cron_token> + X-Cron-Source: manual	管理员手动触发，使用短期 Cron Token（60 秒有效期）

未携带 X-Cron-Source 时，会依次尝试 service_role_key 验证和 Cron Token 验证（向后兼容）。

---

端点列表

POST /cron/hello

测试端点，用于验证 pg_cron 调度是否正常工作。

请求参数

无。

响应格式

{
  "success": true,
  "message": "Hello 2026-03-07T10:00:00.000Z",
  "executedAt": "2026-03-07T10:00:00.000Z"
}

错误码

HTTP 状态码	说明
401	未授权的请求

---

POST /cron/process-scheduled-subscriptions

处理预约订阅变更。遍历所有已到期的 scheduled_plan_code，执行降级或续费操作。

请求参数

无。

响应格式

成功：

{
  "success": true,
  "processed": 3,
  "executedAt": "2026-03-07T10:00:00.000Z"
}

失败：

{
  "success": false,
  "error": "错误信息",
  "executedAt": "2026-03-07T10:00:00.000Z"
}

错误码

HTTP 状态码	说明
401	未授权的请求
500	任务执行失败

---

POST /cron/grant-monthly-credits

发放月度订阅积分。遍历活跃订阅，为计费周期已结束的订阅发放新周期积分。

请求参数

无。

响应格式

成功：

{
  "success": true,
  "granted": 5,
  "executedAt": "2026-03-07T10:00:00.000Z"
}

失败：

{
  "success": false,
  "error": "错误信息",
  "executedAt": "2026-03-07T10:00:00.000Z"
}

错误码

HTTP 状态码	说明
401	未授权的请求
500	任务执行失败

---

POST /cron/cleanup-push-tokens

清理过期推送 Token。删除 90 天未更新的 push token，并同步受影响用户的 Novu credentials。

请求参数

无。

响应格式

成功：

{
  "success": true,
  "deleted": 12,
  "executedAt": "2026-03-07T10:00:00.000Z"
}

失败：

{
  "success": false,
  "error": "错误信息",
  "executedAt": "2026-03-07T10:00:00.000Z"
}

错误码

HTTP 状态码	说明
401	未授权的请求
500	任务执行失败

---

源码

• 路由文件：apps/backend/src/routes/cron.ts
• 订阅处理器：apps/backend/src/services/cron/handlers/subscription.ts
• 推送清理处理器：apps/backend/src/services/cron/handlers/push-cleanup.ts