thread-master/old/backend/docs/threads-automation-gap-plan.md

Threads 自動營運補功能計畫

目前狀態

P1/P2 已落地到後端 API、worker 與正式前端：

• 自動補庫存：publish_inventory_policies + refill-publish-inventory job template/worker。
• 智慧時段：GET /publish-slot-insights 從 publish health / checkpoints 聚合推薦時段。
• 草稿批量排程：Persona 與 Copy Mission 草稿可批量排到 publish_queue，草稿回寫 scheduled + publish_queue_id。
• Retry / 告警 / 漏發：publish_queue_events 記錄狀態轉移；sweeper 會標記 missed；failed/cancelled/missed 可 retry。
• 頻率護欄：publish_guard_policies 支援每日上限、最小間隔、連續失敗 pause / resume。
• P2：內容日曆 date range query、多帳號 dashboard summary、style preset 語調庫、OAuth/API diagnostics。

目標

把現有「海巡找題、AI 文案、手動排程、成效追蹤」串成自動營運閉環，讓巡樓 Console 不只是一個排程工具，而是可持續補庫存、控制風險、追蹤成效的 Threads 工作台。

P1：自動補庫存

功能

• 每個 Threads account 可設定每日/每週目標篇數。
• 可設定 weekday/time slots 與 timezone；timezone 僅用於 cron/排程解讀，儲存仍用 unix nanoseconds UTC。
• 指定內容來源：persona、copy mission、brand scan posts、manual seed。
• 當 publish_queue 未來 N 天庫存低於門檻時，自動建立 copy generation job，完成後排入 queue。

後端草案

• 新增 model：internal/model/publish_inventory/。
• 新增設定 entity：
  • account_id
  • target_daily_count
  • low_stock_threshold
  • lookahead_days
  • timezone
  • slots
  • source_refs
  • enabled
• 新增 job step：refill_publish_inventory。
• 補 API：
  • GET /api/v1/threads-accounts/:accountId/publish-inventory-policy
  • PUT /api/v1/threads-accounts/:accountId/publish-inventory-policy
  • POST /api/v1/threads-accounts/:accountId/publish-inventory/refill-jobs

P1：智慧時段

功能

• 第一版以規則為主：帳號的 weekday/time slots + 最小間隔。
• 用 publish health 的 1h/24h/7d checkpoints 回填每個 slot 的平均互動。
• 前端顯示「推薦時段」與「低成效時段」。

後端草案

• 新增 summary usecase，從 publish_analytics 聚合 account slot performance。
• 補 API：
  • GET /api/v1/threads-accounts/:accountId/publish-slot-insights
• 回傳：
  • slots[]
  • avg_likes_1h/24h/7d
  • avg_replies_1h/24h/7d
  • sample_size
  • recommendation

P1：草稿批量排程

功能

• 使用者在 copy drafts 中選多篇，一次排到未來 slots。
• 支援根據智慧時段自動分配 scheduled_at。
• draft 排入 queue 後狀態改為 scheduled，保留 queue item id。

後端草案

• 補 API：
  • POST /api/v1/personas/:personaId/copy-drafts/schedule
  • POST /api/v1/personas/:personaId/copy-missions/:missionId/copy-drafts/schedule
• request：
  • account_id
  • draft_ids
  • start_at
  • timezone
  • slots
  • mode: manual / recommended

P1：發文 retry / 告警 / 漏發偵測

功能

• failed queue item 可重試，保留失敗歷史。
• sweeper 偵測到超過 grace period 的 scheduled item 未處理，標記為 missed 或重新 enqueue。
• 連續失敗超過門檻時 pause account publish，避免 token 或 rate limit 問題擴大。

後端草案

• publish_queue_events 記錄 queue 狀態轉移與錯誤分類。
• retry 使用 guarded update，只允許 failed/cancelled 回到 scheduled。
• 補 API：
  • POST /api/v1/threads-accounts/:accountId/publish-queue/:queueId/retry
  • GET /api/v1/threads-accounts/:accountId/publish-queue/:queueId/events
  • GET /api/v1/threads-accounts/:accountId/publish-alerts

P1：頻率護欄

功能

• 每帳號每日上限。
• 最小發文間隔。
• 連續失敗自動 pause。
• 手動解除 pause。

後端草案

• 擴充 Threads account connection prefs 或新增 publish_guard_policy。
• sweeper dispatch 前檢查 policy；違反則延後排程，不直接發文。
• 補 API：
  • GET /api/v1/threads-accounts/:accountId/publish-guard-policy
  • PUT /api/v1/threads-accounts/:accountId/publish-guard-policy
  • POST /api/v1/threads-accounts/:accountId/publish-guard/resume

P2

• 內容日曆：補 queue date range query，前端做週/月視圖。
• 多帳號 dashboard：補跨帳號 summary endpoint，避免前端 N+1 requests。
• 語調庫：把 style_profile、CTA、禁用詞、品牌口吻抽成 reusable preset。
• OAuth/API 診斷：把 smoke test、token expiry、permission scope 做成標準診斷報告。

驗證策略

• 所有列表維持 page/pageSize 與 pagination/list。
• 所有時間欄位寫入 unix nanoseconds。
• queue/job 狀態轉移都使用 guarded update。
• 長任務必須 heartbeat，取消走既有 cooperative cancel 語意。