定時調度

Braidrun 的排程器支援四種觸發類型：CRON（週期運算式）、INTERVAL（固定間隔）、ONE_TIME（一次性）、DELAYED_COMPLETION（工作流鏈式觸發）。所有 schedule 由平台排程服務統一管理，服務重啟後按各自時間表繼續觸發。

概念：schedule 與 execution

一個 schedule 描述「何時觸發」；每次觸發會建立一次 execution。Schedule 自身是長期物件，execution 是一次性的執行記錄。Schedule 可以攜帶一份靜態的 inputs（鍵值對），每次觸發都作為 execution 的輸入變數。

四種排程類型

四種類型共用一套通用欄位：enabled（是否啟用）、maxRuns（最大觸發次數）、inputs（靜態輸入變數）。endTime 已過或觸發次數達到 maxRuns 時，schedule 會被自動停用，但不會被刪除。

建立 CRON schedule

curl -X POST https://braidrun.com/api/schedules \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "workflowId": "<workflow-id>",
    "name": "Daily 9 AM report",
    "scheduleType": "CRON",
    "cronExpression": "0 9 * * *",
    "timezone": "Asia/Shanghai",
    "inputs": {
      "environment": "production"
    }
  }'

cron 運算式為 5 段制：分 時 日 月 週。支援 *、列表（1,3,5）、區間（1-5）、步進（*/6）；週日可寫 0 或 7。觸發時間按 schedule 自己的 timezone 計算。

INTERVAL：固定間隔

請求主體和 CRON 一樣發到 POST /api/schedules，只是欄位不同：

{
  "workflowId": "<workflow-id>",
  "name": "每 5 分钟同步一次",
  "scheduleType": "INTERVAL",
  "interval": 300000,
  "startTime": 1785542400000,
  "endTime": 1788220800000,
  "maxRuns": 500
}

• interval — 觸發間隔，單位毫秒；小於 1 秒的值會被抬到 1 秒
• startTime / endTime — 可選，epoch 毫秒時間戳記；設了 startTime 會先等到該時刻再開始，過了 endTime 自動停用
• maxRuns — 可選，觸發滿這麼多次後自動停用

ONE_TIME：一次性

{
  "workflowId": "<workflow-id>",
  "name": "上线前补跑一次",
  "scheduleType": "ONE_TIME",
  "startTime": 1785546000000
}

startTime 為 epoch 毫秒時間戳記。到點觸發一次後 schedule 自動停用；多執行個體部署下由一次性鎖保證只觸發一次。

工作流鏈式排程（DELAYED_COMPLETION）

DELAYED_COMPLETION 把兩個工作流串成鏈：上游工作流 A 每次以 COMPLETED 狀態結束後，等 delaySeconds 秒，自動觸發本 schedule 綁定的工作流 B。典型用法：資料拉取工作流跑完 10 分鐘後自動跑報表工作流。

{
  "workflowId": "<workflow-B-id>",
  "name": "A 完成 10 分钟后跑 B",
  "scheduleType": "DELAYED_COMPLETION",
  "triggerWorkflowId": "<workflow-A-id>",
  "delaySeconds": 600,
  "maxRuns": 10
}

• 無論 A 是被手動、Webhook、定時還是鏈式觸發的，只要成功完成就會計入；失敗或被取消的執行不會觸發下游
• delaySeconds — 必填，0 到 30 天（2592000 秒）；0 表示完成後立即觸發
• maxRuns — 不填為不限次數；填 1 表示只鏈一次；填 N 表示最多鏈 N 次，達到後自動停用
• triggerWorkflowId — 不能等於 workflowId（自己觸發自己會無限迴圈），且建立者需要對上游工作流有查看權限
• 等待中的延遲觸發會持久化儲存，服務重啟或滾動發布不會遺失：到點後照常觸發

管理 schedule

# 立即执行一次（返回这次 execution）
curl -X POST https://braidrun.com/api/schedules/<schedule-id>/run \
  -H "Authorization: Bearer <token>"

# 停用（enabled=true 则启用；不带参数则在两者间切换）
curl -X POST "https://braidrun.com/api/schedules/<schedule-id>/toggle?enabled=false" \
  -H "Authorization: Bearer <token>"

# 最近 50 条触发历史
curl "https://braidrun.com/api/schedules/<schedule-id>/history?limit=50" \
  -H "Authorization: Bearer <token>"

toggle 的 enabled 可以放 query 參數或 JSON body；兩者都不傳時在啟用 / 停用之間切換。history 每條記錄含狀態、成功與否、起止時間，limit 預設 50、最大 500。

共享輸入與參數預設

除了在 schedule 上直接設定 inputs，還可以給工作流建「參數預設」：同一個 workflow 用不同預設跑不同設定。

# 创建一个参数预设
curl -X POST https://braidrun.com/api/workflows/<wf>/presets \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "生产环境",
    "description": "生产环境参数",
    "variables": {
      "environment": "production",
      "debug_mode": "false",
      "max_retries": "3"
    }
  }'

# 用预设触发执行
curl -X POST https://braidrun.com/api/workflows/<wf>/presets/<id>/execute \
  -H "Authorization: Bearer <token>"

多工作流批量併發

從工作流列表多選後點擊"併發執行"，會一次啟動一批 execution。

• 每個被選中的 workflow 都會創建自己的 execution 記錄
• 超出 maxConcurrency 的 execution 會先進入 PENDING
• 前面運行中的 execution 完成後，隊列中的下一個自動轉成 RUNNING
• 0 表示不限制，同時啟動整批

服務重啟後的行為

• 已觸發的 execution：默認標 INTERRUPTED，除非開啟了自動續跑（見重啟與自動續跑）
• 未到時間的 CRON / INTERVAL / ONE_TIME：重啟後照常觸發
• 等待中的 DELAYED_COMPLETION 延遲觸發：已持久化，重啟後繼續等到點觸發
• 宕機期間錯過的觸發點：不補跑（避免雙寫風險）

相關頁面

• Webhook 觸發
• 服務重啟自動續跑