Spec: 成長迴路（成果歸因 · 學習閉環 · 健康分 · 邀請獎勵 · Workspace）
Status: approved
Status note: 使用者 2026-07-20「spec 通過」
Source: docs/product/growth-loop/requirements.md（approved 2026-07-20「需求 OK」）
Last updated: 2026-07-20
底座：docs/product/haixun-backend/spec.md（已交付能力；本 run 為加值層）
決策對齊：requirements §6 #1–#9
1. 摘要
本規格定義巡樓從「工具組合包」升級為「能證明 ROI、越用越準」時的對外行為契約。
P0： 海巡成果歸因鏈、今日／用量「成本＋成果」並列、每週帳號健檢（方案內含不扣點）、人設／品牌資產複利可見。
P1： 帳號健康分與強制降速、邀請首次付費點數回饋（單層）、同租戶多 Workspace＋草稿審核＋白牌月報 PDF。
P2（本 spec 只鎖邊界，不細寫 API）： Playbook 市集、免費破冰工具、跨帳號 benchmark、UTM 自動歸因。
不做： Insights 真管線重做、多租戶帳單、多層／現金邀請回饋、新增灰帽玩法。
2. 名詞與實體
| 名詞 |
定義 |
| OutcomeEvent |
一筆可歸因成果：觸發源（海巡外展／Outbox 步驟）＋訊號類型＋可選手動成交 |
| AttributionLink |
OutcomeEvent → 來源實體（scout_post_id 和／或 outbox_step_id）＋送出帳號 id；可回溯 |
| OutcomeSummary |
會員在時間窗（本週／本月）的彙總：觸達、對話、追蹤、成交筆數／金額 |
| WeeklyCheckup |
每會員每週一份 AI 健檢報告：證據引用＋恰好 3 個下週行動（含 deep-link） |
| AssetLearning |
人設／品牌的「學到什麼」摘要＋版本號（可見複利） |
| AccountHealth |
每個 ThreadsAccount 的 0–100 分、等級、降速狀態、建議文案 |
| InviteReward |
直邀首次付費觸發的點數入帳紀錄（單層） |
| Workspace |
同租戶內工作區；擁有 brand／persona／threads_account 歸屬與審核設定 |
| DraftReview |
草稿審核狀態：none｜pending｜approved｜rejected（僅審核開啟的 Workspace） |
| Manual path |
「複製文案 → 開 Threads → 標記完成」；健康分 <40 時敏感操作只允許此路徑 |
沿用底座（不重定義）： Member、ThreadsAccount、ScoutPost（outreach_status）、OutboxBundle/Step、Persona、Brand、Usage/Plan、Invite（parent_uid／invite_code）、Job、Notification。
3. 狀態機
3.1 OutcomeEvent（歸因）
(source published | manual_mark_done)
--> observing : 進入觀測窗（預設送出後 72h）
observing --> confirmed : 觀測到對話／互動訊號，或手動回報成交
observing --> possible : 僅追蹤數變化等弱訊號（標 confidence=possible）
observing --> expired : 窗結束且無訊號（可不展示於成果卡明細，計入觸達即可）
confirmed|possible --> amended : 會員改／刪手動成交（留 audit）
- 觸發源必須已「真送出或標記完成」：
ScoutPost.outreach_status ∈ {published, …標記完成語意} 或 Outbox step published。
- 禁止對 draft／new／skipped 建立 OutcomeEvent。
confidence：confirmed｜possible（弱歸因必須標 possible，UI 不可寫成確定成交）。
3.2 WeeklyCheckup
(none) --> generating : 排程到點或手動重產
generating --> ready : AI 成功寫入報告
generating --> failed : 可重試；仍不扣點
ready --> superseded : 同週再次成功重產（舊份保留可查，列表預設最新）
- 每會員每自然週（見 §4.2）至多 1 份「當期」；7 日內手動重產 ≤2 次。
- 永不寫入 UsageEvent 扣點／meter。
3.3 AccountHealth 等級
score >= 70 --> normal : 不干預
40 <= score < 70 --> warn : 送出前提示；建議加倍間隔
score < 40 --> throttle : 強制降速（§4.4）
- 每日至少重算一次；有發送／失敗事件可即時重算。
throttle 解除：分數回升 ≥40 後下一輪重算生效（無人工解鎖按鈕需求；admin 可不擋額度類覆蓋——本 run 不做 admin 覆蓋健康分，避免繞過護欄）。
3.4 InviteReward
(直邀 parent_uid = 邀請人) + (直邀首次 plan: free → starter|pro 且付款成功語意)
--> pending_credit
pending_credit --> credited : 點數入邀請人平台額度；未超月上限
pending_credit --> capped : 超過邀請人當月上限；本筆不發、不遞延
pending_credit --> skipped : 非首次／非直邀／延伸／已發過
- 僅單層；
延伸 永不觸發。
- 額度：Starter +100；Pro +300（requirements §6 #4）。
- 月上限：邀請人當月透過邀請獲得點數 ≤ 其當月方案額度 × 50%。
3.5 Workspace
member 預設 1 個 default workspace
--> 可 create 更多
workspace active 可 archive（軟刪；至少保留 1 個不可 archive）
- 方案／用量／邀請碼仍綁 Member，不綁 Workspace。
3.6 DraftReview（Workspace 開啟審核時）
draft --> pending : 提交審核
pending --> approved : 核准 → 才可進 Outbox／sendOutreach 自動路徑
pending --> rejected : 退回（含理由字串）
rejected --> pending : 修改後再提
approved --> (送出流程沿用 Outbox／Scout)
- Workspace
review_required=false（預設）：行為與現況相同，無 pending 閘。
review_required=true：未 approved 禁止自動送出；手動標記完成路徑是否放行 → 允許（代操可先人工貼再標記），但 UI 需標示「未審核僅手動」。
4. 使用者流程（行為）
4.1 成果歸因（P0）
- 島民完成海巡外展：sendOutreach 真送 或 標記完成（手動路徑）。
- 系統建立 OutcomeEvent（
source_type=scout_outreach，連 scout_post_id、送出 threads_account_id），狀態 observing，window_ends_at = sent_at + 72h。
- Worker／排程在窗內拉取可讀訊號（§5.4）：
- 對話：目標串上出現對己方回覆的再回／引用（能判則
confirmed）。
- 互動：己方回覆或目標貼的 likes／replies 計數上升（能讀則記；弱則
possible）。
- 追蹤：送出帳號
followers_count 在窗內淨增加 → 預設 possible（不可宣稱「此回覆帶來追蹤」為確定，除非未來有更強訊號）。
- 島民可在命中詳情或成果明細 手動回報成交（金額選填、備註選填、幣別預設 TWD）→
confirmed + kind=conversion。
- 今日頁：成果摘要卡（本週：對話數、possible／confirmed 追蹤、成交筆數／金額）。
- 用量頁：成本區（既有 platform／BYOK）與成果區並列；不可只顯示成本。
- 明細列表：每筆可點回 Scout 命中或 Outbox 步驟。
- 降級： 任一 API 訊號不可用 → 仍提供手動成交＋「已送出／標記完成」計入觸達；禁止整段歸因 API 回未實作空成功。
4.2 每週健檢（P0）
- 節奏： 以會員
timezone 的當地週一 00:00 起可自動產（無 timezone → UTC）；Job weekly_checkup。
- 輸入：該會員已同步貼文成效（既有 own posts／insights 本地資料）、近 14 日海巡送出與 Outcome 摘要、active 人設摘要。
- 輸出（
ready）：
summary 短文（TC）findings[]：每條含 claim + evidence[]（貼文 id／permalink／指標，至少 1 條 evidence，無 evidence 的 finding 不得入庫）actions[3]：固定 3 個；每項含 title、reason、deeplink（枚舉：today｜scout｜studio_compose｜studio_inspire｜crew_persona｜outbox）
- 計費： 不扣 credits、不寫 platform meter、不寫 byok 次數。AI 呼叫可用平台 key；失敗可重試。
- 手動「提前重產」：7 日滾動窗內 ≤2 次；超過回明確錯誤。
- 完成 → 站內通知；今日頁可進最新報告。
4.3 資產複利可見（P0）
- 人設詳情／列表：顯示
learning_summary（短）、learning_version（遞增整數）、learned_from_posts_count、last_learned_at。
- 品牌詳情：同上語意（來源可為海巡 homework／brief 累積）。
- 更新時機（最小）：人設分析 Job 成功、健檢
ready 時可附帶刷新 summary（不強制每次分析都變 version；有實質變更才 +1）。
- 空狀態：尚未學習時明確文案，禁止假數據。
4.4 帳號健康分（P1）
- 每個
ThreadsAccount 計算 score、level（normal｜warn｜throttle）、factors[]（可解釋扣分項）、advice。
- 訊號方向（權重數值 plan／實作可調，行為門檻鎖定）：
- 24h 發送次數過高 → 扣
- 最小間隔違規（連續 steps 間隔過短）→ 扣
- 近 7 日 Outbox 失敗率高 → 扣
- token 過期／error／不可用 → 重扣
- 多日無操作 → 不扣
- 送出前檢查（自動路徑）： ThreadPlay submit、sendOutreach 自動送、compose 進 Outbox。
warn：API 仍允許，但 response 帶 health_warning；前端必顯示。throttle：拒絕自動送出（明確錯誤碼）；僅允許手動路徑（複製＋標記完成）。
- 今日頁：顯示分數最低的帳號警示（若有 warn／throttle）。
- Crew 帳號列：分數 Badge（與既有 token 健康文案並存，不取代 token 狀態）。
4.5 邀請獎勵（P1）
- 沿用既有邀請綁定（
parent_uid 一次）。
- 當直邀會員首次完成 free→starter 或 free→pro 的方案生效（對齊既有 purchase／plan 成功語意）：
- 解析邀請人 =
parent_uid
- 計算應發點數與月上限 →
credited 或 capped／skipped
- 點數進入邀請人平台方案額度池（與 BYOK 無關）；寫
InviteReward 紀錄 + 可選 Usage 類「贈點」事件（key_mode 不適用；meter=invite_bonus 或等價，不計入付費消耗進度的「已用」誤解——報表分開「贈點入帳」）。
- 邀請頁：累計已獲點數、本月已獲／上限、最近回饋列表。
- Admin 不手改回饋紀錄（防爭議）；糾錯走既有調
parent_uid（調後不回溯已發點數）。
4.6 Workspace 與審核（P1）
- 會員可 list／create／rename／switch／archive Workspace（至少留 1 個）。
- Brand、Persona、ThreadsAccount 歸屬
workspace_id；建立時寫入當前 Workspace。
- 切換 Workspace 後，列表 API 預設只回該區資源；「全部」視圖可選（若做，須明確 query）。
- Workspace 設定
review_required：開啟後，該區 plays／compose／outreach 進自動發送前須 approved。
- 審核操作：提交者 pending；審核者（同會員多席或同 Workspace 成員——P1 最小：同一 Member 自審即可；多成員協作 P2）approved／rejected。
- 白牌月報 PDF： 選 Workspace＋月份 → 匯出含成果摘要、發送數、海巡完成數、健康分概況；無巡樓品牌強制露出（可選 footer「Powered by…」開關預設關）。
- 用量／方案／邀請：不隨 Workspace 切分。
4.7 P2 邊界（只鎖不做細節）
| 能力 |
行為邊界 |
| Playbook 市集 |
可分享 brief／人設風格／劇本模板；可匿名；引用後進自己 Workspace |
| 免費破冰 |
免登入工具；結果導註冊；不做付費牆內容 |
| Benchmark |
匿名聚合；樣本不足不顯示 |
| UTM 歸因 |
點擊進 OutcomeEvent；與手動成交並存 |
5. 介面契約
5.1 共通
- 沿用
haixun-backend：成功 code=102000；page/pageSize → pagination+list；時間 unix ns UTC；uid 數字。
- Auth：Bearer；資源擁有者 = 登入 uid；Admin 另註。
- 禁止未實作回成功空資料。
5.2 API 能力分組（路徑前綴建議 /api/v1；精確 path 由 .api 定）
| 域 |
主要行為 |
波次 |
權限 |
| Outcomes |
summary(from,to|week|month)；list（filter kind/confidence/source）；get；reportConversion；updateConversion；deleteConversion |
P0 |
member |
| Checkups |
latest；list；get；generateNow（受 7 日 2 次限） |
P0 |
member |
| Asset learning |
併入既有 Persona／Brand get／list 回應欄位（§4.3）；可選 refreshLearning |
P0 |
member |
| Account health |
listByAccounts；get(accountId)；送出類 API 附加 health_warning 或 throttle 錯誤 |
P1 |
member |
| Invite rewards |
併入 getMyNetwork 擴充：rewards_summary、rewards_list；入帳由 plan 生效內部觸發 |
P1 |
member |
| Workspaces |
CRUD／switch／archive；setReviewRequired；資源 create 帶 workspace_id |
P1 |
member |
| Draft review |
submit／approve／reject／listPending |
P1 |
member |
| Monthly report |
exportPdf(workspace_id, year_month) → 檔案 URL 或 stream |
P1 |
member |
5.3 前端頁面
| 路由 |
變更 |
/app/today |
＋成果摘要卡；＋最新健檢入口；＋健康分警示（P1） |
/app/usage |
成本｜成果雙欄（或上下並列） |
/app/scout 命中詳情 |
＋歸因狀態；＋手動回報成交 |
/app/crew 帳號 |
＋健康分 Badge（P1）；token 狀態保留 |
/app/crew 人設 |
＋learning 摘要／版本 |
/app/brands |
＋learning 摘要／版本 |
新或內嵌 /app/checkup |
健檢報告全文＋3 行動 deep-link |
/app/invite |
＋回饋累計與列表（P1） |
| Workspace 切換器（殼層） |
P1；預設 Workspace 名稱可編 |
| 月報匯出入口 |
P1 在 Workspace 設定或用量／成果區 |
5.4 Job / Worker
| Template |
觸發 |
成功 |
outcome_observe |
定時／送出後入隊 |
更新 OutcomeEvent 訊號與 confidence |
weekly_checkup |
週排程／手動 generateNow |
Checkup ready＋通知；無 Usage 扣點 |
account_health_recompute |
日排程／發送事件 |
更新 AccountHealth |
（既有）outbox_publish_step / scout_scan 等 |
不變 |
送出成功後必須 hook 建立 observing Outcome（scout／outbox 源） |
5.5 歸因訊號與 Threads API（驗證表）
| 訊號 |
理想來源 |
不可用時 |
| 對話（再回／引用） |
回覆 conversation／replies API |
僅保留手動標記「有對話」可選（P0 可不做此手動，至少保留成交手動） |
| 互動計數 |
media insights / reply fields |
跳過該訊號 |
| 追蹤淨增 |
使用者檔案 followers_count 快照 diff |
跳過 |
| 成交 |
僅手動（P0） |
— |
| UTM 點擊 |
P2 |
— |
Spec 實作前：用現有 OAuth scope 跑一次探測；把「可用／不可用」寫進實作註記，但不得阻塞手動成交＋觸達計數的交付。
5.6 錯誤語意（新增 scope 建議）
| 情境 |
行為 |
| 健檢重產超過 7 日 2 次 |
明確錯誤，非 102000 |
| 健康分 throttle 擋自動送 |
明確錯誤；message 含分數與「請用手動路徑」 |
| 審核未准就自動送 |
明確錯誤 |
| 邀請回饋 capped |
邀請人側可查 capped 紀錄；被邀請人方案仍成功 |
| PDF 匯出無資料月 |
仍可出「空月」報表或明確錯誤（二選一，實作固定一種） |
6. 與現況對照（Retain / Replace / Remove）
| 能力 |
Retain |
Replace |
Remove |
備註 |
| 海巡 outreach 狀態機／真送 |
✅ |
送出後 ＋ Outcome observing |
— |
加值 hook |
| 今日頁待回／目標 |
✅ |
＋成果卡、健檢入口、健康警示 |
— |
|
| 用量頁 platform／BYOK 分欄 |
✅ |
＋成果區並列 |
純成本唯一視角 |
|
| Insights 真管線 |
— |
— |
仍不做（haixun-backend P2） |
健檢只用既有同步資料 |
| Insights 頁 local／既有同步 |
✅ 可當健檢輸入 |
— |
不冒充本 run 完成 Insights |
|
| 人設 8D／分析 Job |
✅ |
回應 ＋ learning 欄位 |
— |
|
| 邀請關係樹／apply |
✅ |
＋首次付費回饋 |
多層／現金 |
|
| Crew token 健康文案 |
✅ |
＋操作健康分（不同維度） |
混成一個「健康」 |
兩者並陳 |
| 單租戶 Member 模型 |
✅ |
＋同租戶 Workspace |
多租戶帳單 |
|
| ThreadPlay／養帳玩法 |
✅ 既有 |
僅 throttle 護欄 |
新增更激進玩法 |
|
| 手動「標記完成」路徑 |
✅ |
throttle 時升為主路徑 |
刪除人工路徑 |
|
| 模擬／空成功 API |
— |
— |
禁止 |
AGENTS.md |
7. 非功能
- 安全／權限： Outcome／Checkup／Workspace 皆 owner_uid 隔離；PDF 僅己方 Workspace；Admin 不預設讀全站 Outcome（若做 admin 分析 → 另開需求）。
- 隱私： 健檢 evidence 不跨會員；benchmark（P2）僅匿名聚合。
- 計費： 健檢 AI 不扣點；邀請贈點不計入「已消耗」誤導；BYOK 規則不變。
- 可觀測： Outcome observe Job 進度／錯誤；健檢 failed 原因；健康分重算日誌無 token 明文。
- 效能： Outcome 列表 pageSize≤50；observe 窗 72h；健康分重算 O(帳號數) 可接受日批。
- 語系： 健檢與成果文案預設繁中台灣語感。
- 契約： go-zero
.api → generate；業務在 logic／module。
8. 資料保存（邏輯層）
| 實體 |
關鍵欄位 |
生命週期 |
| OutcomeEvent |
id, owner_uid, source_type, source_id, threads_account_id, kind, confidence, metrics, conversion?, window_*, created_at |
送出後建→觀測→終態；成交可 amend |
| OutcomeSnapshot（可選） |
account_id, followers_count, taken_at |
觀測用快照 |
| WeeklyCheckup |
id, owner_uid, week_key, status, summary, findings[], actions[3], created_at |
週產；舊份可查 |
| AssetLearning 欄位 |
掛 Persona／Brand：summary, version, from_count, last_learned_at |
隨分析／健檢更新 |
| AccountHealth |
threads_account_id, owner_uid, score, level, factors[], advice, computed_at |
日更／事件更 |
| InviteReward |
id, inviter_uid, invitee_uid, plan_id, points, status, created_at |
首次付費一次 |
| Workspace |
id, owner_uid, name, review_required, archived, is_default |
CRUD |
| 資源歸屬 |
Brand/Persona/ThreadsAccount.workspace_id |
建立時寫入 |
| DraftReview |
ref_type, ref_id, workspace_id, status, reason?, actor_uid |
審核流 |
| Report export |
暫存 URL 或短 TTL 物件 |
匯出後可過期 |
9. 驗收場景（Given / When / Then）
共通： 成功 envelope 102000；時間 ns UTC；未實作≠空成功。
9.1 P0 歸因
| ID |
Given |
When |
Then |
| OC-01 |
海巡命中已 published 或標記完成 |
系統處理 |
存在 OutcomeEvent observing／終態；可 list 回溯 source |
| OC-02 |
observing 窗內出現可讀對話訊號 |
observe Job |
confidence=confirmed 或等價 kind=reply；summary 對話數＋1 |
| OC-03 |
僅 followers 淨增 |
observe Job |
confidence=possible；UI 不顯示為確定成交 |
| OC-04 |
會員手動回報成交金額 1000 |
reportConversion |
kind=conversion confirmed；成果卡成交可見 |
| OC-05 |
改／刪成交 |
update／delete |
明細與 summary 一致；非 102000 空操作 |
| OC-06 |
今日頁 |
開啟 |
可見本週成果摘要（可為 0，但區塊存在） |
| OC-07 |
用量頁 |
開啟 |
成本區與成果區同時存在 |
| OC-08 |
API 全無社群訊號 |
僅手動成交＋觸達 |
歸因域仍可用；不得整域 501 空成功 |
9.2 P0 健檢與資產
| ID |
Given |
When |
Then |
| CU-01 |
會員有 timezone=Asia/Taipei |
當地週一後排程 |
weekly_checkup Job 產出 ready |
| CU-02 |
ready 報告 |
get |
findings 每條含 evidence；actions 長度=3 且 deeplink 合法 |
| CU-03 |
產生健檢 |
查 UsageEvent |
無因健檢產生的扣點／meter 消耗 |
| CU-04 |
7 日內已手動重產 2 次 |
generateNow 第 3 次 |
明確錯誤 |
| CU-05 |
Job 成功 |
通知 |
站內通知可點進報告 |
| AL-01 |
人設分析或健檢刷新 learning |
get persona |
learning_summary 或明確空態；有變更則 version≥1 |
| AL-02 |
新品牌無學習 |
get brand |
空態文案，非假數字 |
9.3 P1 健康分
| ID |
Given |
When |
Then |
| AH-01 |
帳號 connected |
get health |
0–100 + level |
| AH-02 |
score 40–69 |
自動送出 |
成功或進行中，但帶 health_warning |
| AH-03 |
score <40 |
ThreadPlay submit 或 sendOutreach 自動送 |
拒絕；message 指手動路徑 |
| AH-04 |
score <40 |
複製＋標記完成 |
允許 |
| AH-05 |
今日頁有 throttle 帳號 |
開啟 |
可見警示 |
9.4 P1 邀請獎勵
| ID |
Given |
When |
Then |
| IR-01 |
A 邀請 B；B 首次 free→starter 成功 |
系統 |
A 得 +100；InviteReward credited |
| IR-02 |
B 首次 free→pro |
系統 |
A +300 |
| IR-03 |
B 再續訂／再升級 |
系統 |
不再發點 |
| IR-04 |
A 本月邀請點已達方案額度 50% |
再觸發 |
capped；B 方案仍成功 |
| IR-05 |
僅延伸關係非直邀 |
付費 |
skipped |
| IR-06 |
邀請頁 |
開啟 |
可見累計與列表 |
9.5 P1 Workspace／審核／PDF
| ID |
Given |
When |
Then |
| WS-01 |
新會員 |
me／list workspaces |
≥1 default |
| WS-02 |
建 WS-B 並切換 |
建 brand |
brand.workspace_id=WS-B；WS-A 列表不可見 |
| WS-03 |
review_required=true |
未審核自動送 |
拒絕 |
| WS-04 |
pending → approved |
再自動送 |
允許（仍受健康分約束） |
| WS-05 |
exportPdf |
請求 |
得 PDF（或 URL）；含成果／發送摘要結構 |
| WS-06 |
用量／方案 |
切 WS |
不變（仍綁會員） |
9.6 回歸（底座不可破壞）
| ID |
Given |
When |
Then |
| RG-01 |
既有 Outbox 真發送 |
送出 |
仍 published 僅在平台成功後 |
| RG-02 |
BYOK 用量 |
呼叫 |
仍分欄、健檢不混入消耗 |
| RG-03 |
邀請 apply 一次綁定 |
再 apply |
仍拒絕 |
10. 開放規格問題
週一起點時區 → 已定：會員 timezone，無則 UTC（§4.2）。- Threads 各訊號實際 scope 探測結果 → 實作前填表，不阻 P0 手動＋觸達。
- Draft review P1 是否僅「同一 Member 自審」→ 已定是；多成員協作 P2。
- 健康分權重精確數字 → plan／實作可調；門檻帶 70／40 鎖定。
- PDF 引擎選型 → plan 定（行為：可下載白牌月報）。
11. 批准