# 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 語意。