設定後臺任務

安裝與配置

在執行任何步驟之前，請閱讀開始之前 和終端基礎知識。這些說明假設您在 VS Code 中開啟了完整的 supastack monorepo；它的根 package.json 標記儲存庫根。在 pnpm 命令中，工作區包是應用程式或共享程式碼資料夾；在產品中，工作空間是團隊的資料容器和安全邊界。 corepack pnpm --filter ... 從 monorepo 選擇一個包，同時從其根執行命令。如果您僅開啟同步的移動或桌面資料夾，則它不包含 Web 後端、Docker 設定或根指令碼：從此 monorepo 或可訪問的託管伺服器執行後端，並使用平臺資料夾自己的指令碼。環境變數是儲存在本地 .env 檔案或託管儀錶板中的命名設定；更改後重新啟動相關應用程式，並將伺服器機密保留在 NEXT_PUBLIC_ 和 EXPO_PUBLIC_ 值之外。

1.在VS Code中開啟apps/web/src/job-handlers.ts和apps/web/src/scheduler-runtime.ts。工作是後臺工作；排程程式決定何時將其排隊。

2. 對於本地tick，在apps/web/.env.local和repository-root .env中設定相同的SCHEDULER_TICK_SECRET； tick 指令碼讀取根 .env，而 Web 端點讀取其應用程式設定。

3. 使用 corepack pnpm --filter @supastack/web dev 啟動 Web，然後執行 corepack pnpm jobs:tick 從根開始。預期：終端顯示 localhost:3000 的 POST 結果。 Trigger.dev 是一個獨立的提供商，需要自己的帳戶和伺服器金鑰。

為生產任務提交設定 JOB_PROVIDER=trigger，以及僅服務端的 TRIGGER_SECRET_KEY 與 TRIGGER_PROJECT_REF。配置目標專案前，先看 apps/web/trigger.config.ts 與 apps/web/trigger 中的 ai.generate 任務。

JOB_PROVIDER=trigger
TRIGGER_PROJECT_REF=your-project-reference
# Provide TRIGGER_SECRET_KEY through the server secret store.
# Local/self-hosted scheduler tick:
# SCHEDULER_TICK_SECRET=…
# SCHEDULER_TICK_URL=http://localhost:3000

要複製的命令

按照註釋檢視命令在哪個資料夾中執行。如果標記了兩個終端，請開啟兩個終端視窗，並在使用第二個命令時保持第一個命令執行。

# Terminal 1 — start the Web app from the monorepo root:
corepack pnpm --filter @supastack/web dev

# Terminal 2 — run one scheduler tick from the monorepo root:
corepack pnpm jobs:tick

實現流程

共享的 JobRunner 契約承諾 enqueue、status 與 cancel。工作流專有語義歸 Trigger.dev 所有；不要從通用介面推斷排程、重試或永續性保證。

持久的應用任務 ID 把派發、worker 執行、用量記錄與結果串起來。已確認入隊後，供應商執行後設資料掛載失敗不得導致再次入隊，也不得讓已接受的工作失效。

驗證與排障

如果勾選返回 404，請確認兩個設定檔案中都存在該金鑰並且完全匹配，然後重新啟動 Web。如果終端顯示連線被拒絕，請先啟動Web。如果沒有作業執行，請檢查計劃是否已啟用且到期；勾選一次不會立即執行未來的計劃。

驗證已部署的任務標識與專案同配置環境一致。把入隊接受、工作流完成與郵件投遞分開。手動重試之前，先讀 docs/production-ai-runtime.md 中的恢復與安全診斷說明。