# Plan: 成長迴路（成果歸因 · 學習閉環 · 健康分 · 邀請獎勵 · Workspace）

> Status: `approved`  
> Status note: 使用者 2026-07-20「plan 通過」  
> Source: `docs/product/growth-loop/spec.md`（**approved** 2026-07-20 使用者「spec 通過」）  
> Requirements: `docs/product/growth-loop/requirements.md`（**approved**）  
> Last updated: `2026-07-20`  
> 底座：`apps/backend` + `apps/web`（haixun-backend M0–M6 已交付）

## 1. 交付策略

1. **先 P0 價值可見**：Outcome 歸因鏈＋今日／用量「成本＋成果」並列——沒有這塊，本 run 沒有存在理由。  
2. **同波完成學習閉環最小版**：WeeklyCheckup（不扣點）＋ Persona/Brand learning 欄位；重用既有同步貼文／海巡資料，**不**開 Insights 真管線。  
3. **P1 護欄先於擴張**：AccountHealth（存亡級）→ InviteReward（增長）→ Workspace／審核／PDF（代操）。  
4. **加值 hook、不重寫主流程**：Outbox／Scout 送出成功後掛 Outcome；既有 API 擴欄優於新平行宇宙。  
5. **前後端同 milestone 可驗**：每 M 結束 FE live 接線＋對應 spec §9 ID；禁止整包最後才接前端。  
6. **缺 Threads 訊號就降級**：M1 先探測 scope；OC-08 手動成交＋觸達必須先綠，再補自動訊號。

驗收一律對照 **spec §9**（OC / CU / AL / AH / IR / WS / RG）；task 完成定義須寫明覆蓋哪些 ID。

## 2. 里程碑

### M0 — 領域殼與契約地基

- **目標：** Outcome／Checkup／Health／Workspace 的 module 殼、`.api` 路由骨架、index init、空實作回**明確未就緒錯誤**（禁止空成功）。  
- **完成定義：**  
  - go-zero `.api` 增加 outcomes／checkups／health／workspaces（或等價分檔）→ `make gen-api`。  
  - Mongo index init 擴充新集合鍵（owner_uid、source、week_key…）。  
  - 共用 envelope／時間／uid 契約回歸仍過。  
  - FE domain types 預留 Outcome／Checkup／Health／Workspace（可先 mock 介面）。  
- **建議 task 區間：** **T300–T309**  
- **驗證：** RG-01～03 抽樣不破；新路由未完成能力 ≠ 102000 空 data。

### M1 — 成果歸因 P0（後端＋FE）

- **目標：** 海巡／Outbox 真送或標記完成 → OutcomeEvent；summary／list／手動成交；今日＋用量成果區。  
- **完成定義：**  
  - Scout outreach published／標記完成、Outbox step published → 建立 `observing` Outcome。  
  - `outcome_observe` Job：72h 窗；對話／互動／追蹤能讀則寫，不能讀則跳過。  
  - API：summary、list、get、report／update／deleteConversion。  
  - confidence：confirmed｜possible 語意正確。  
  - FE：Today 成果卡、Usage 成本｜成果並列、Scout 詳情手動成交與回溯。  
  - Threads scope 探測結果寫進 module 註記或 TESTING 附錄。  
- **建議 task 區間：** **T310–T329**  
- **驗證：** OC-01～OC-08；RG 抽樣。

### M2 — 每週健檢＋資產複利 P0

- **目標：** WeeklyCheckup 自動／手動產；不扣點；3 actions＋deeplink；Persona／Brand learning 可見。  
- **完成定義：**  
  - Job `weekly_checkup`：會員 timezone 週一（無則 UTC）；findings 強制 evidence；actions 長度=3。  
  - generateNow：7 日滾動 ≤2 次。  
  - AI 呼叫**不**寫 Usage 扣點／meter。  
  - 成功 → Notification；FE 報告頁／今日入口＋行動 deep-link。  
  - Persona／Brand get／list 含 learning_*；空態明確。  
- **建議 task 區間：** **T330–T349**  
- **驗證：** CU-01～CU-05、AL-01～AL-02；用量回歸「健檢無消耗事件」。

### M3 — 帳號健康分 P1

- **目標：** 每帳號 0–100；70／40 門檻；throttle 擋自動送、手動路徑放行。  
- **完成定義：**  
  - `account_health_recompute` 日批＋發送事件觸發。  
  - 訊號：24h 發送密度、間隔違規、7 日失敗率、token 狀態；無操作不扣。  
  - ThreadPlay submit／sendOutreach 自動送／compose→Outbox：warn 帶 `health_warning`；throttle **拒絕**。  
  - 標記完成／複製路徑在 throttle 下仍可用。  
  - FE：Crew Badge、Today 警示、送出前錯誤可讀。  
- **建議 task 區間：** **T350–T364**  
- **驗證：** AH-01～AH-05；OB／SC 自動送回歸。

### M4 — 邀請獎勵 P1

- **目標：** 直邀首次 free→starter｜pro 入點；月上限 50%；邀請頁可見。  
- **完成定義：**  
  - Plan 生效 hook → InviteReward pending→credited｜capped｜skipped。  
  - 額度 Starter +100、Pro +300；僅單層、僅首次。  
  - 點數入邀請人平台額度；報表「贈點入帳」與消耗分開。  
  - getMyNetwork 擴充 rewards_summary／list。  
  - FE Invite 頁累計與列表。  
- **建議 task 區間：** **T365–T379**  
- **驗證：** IR-01～IR-06；邀請 apply 一次綁定回歸。

### M5 — Workspace＋審核＋白牌月報 P1

- **目標：** 同租戶多 Workspace；資源歸屬；自審閘；PDF 月報。  
- **完成定義：**  
  - Workspace CRUD／switch／archive（至少留 1）；預設 workspace 遷移既有 brand／persona／account。  
  - 建立資源寫 `workspace_id`；列表預設當前區。  
  - `review_required`：未 approved 擋自動送；同一 Member 自審即可。  
  - exportPdf(workspace, year_month) 可下載；含成果／發送／海巡／健康摘要結構。  
  - 用量／方案／邀請不隨 WS 切分。  
  - FE：殼層切換器、審核狀態、匯出入口。  
- **建議 task 區間：** **T380–T399**  
- **驗證：** WS-01～WS-06；RG 用量不變。

### M6 — 整合、回歸、文件收斂

- **目標：** P0+P1 驗收矩陣；FE↔BE smoke；已知缺口列表（P2 不實作）。  
- **完成定義：**  
  - Integration tests 覆蓋 OC／CU／AL／AH／IR／WS 主路徑（外部 Threads／AI fake）。  
  - FE live 煙測腳本或手測清單勾選。  
  - README phase → `ready-to-implement` 僅在 tasks 批准後；本 M 結束 = 實作完成定義。  
  - 明確列出 P2 未做項與 Threads 訊號降級現況。  
- **建議 task 區間：** **T400–T409**  
- **驗證：** spec §9 全表；haixun-backend 關鍵回歸抽樣。

## 3. 依賴

```text
M0 領域殼
 └─► M1 成果歸因 P0          ──┐
      └─► M2 健檢＋資產 P0    ──┼─► M6 整合收斂
           └─► M3 健康分 P1   ──┤
                └─► M4 邀請獎勵 ┤
                     └─► M5 Workspace ─┘
```

| 關係 | 說明 |
|------|------|
| M1 → M2 | 健檢輸入含 Outcome 摘要；可弱依賴（無 Outcome 仍可產報告）但建議 M1 先綠 |
| M1 → M5 PDF | 月報成果區讀 Outcome summary |
| M3 → M5 審核送出 | 自動送同時受 health + review 雙閘（AND） |
| M4 獨立於 M3 | 可與 M3 後期平行，但 task 號段仍建議 M3 後以降低衝突 |
| 硬性順序 | **不可**先做 M5 代操而跳過 M1/M2（requirements §6 #7） |

## 4. 風險與緩解

| 風險 | 緩解 |
|------|------|
| Threads 歸因訊號全無 | M1 先交付 OC-08 手動＋觸達；observe Job 訊號表可空實作跳過 |
| 健檢品質不穩／無 evidence | 入庫校驗：無 evidence 的 finding 丟棄；不夠 1 條 finding 則 failed 可重試 |
| 健檢誤扣點 | CU-03 自動化斷言；meter 白名單不含 checkup |
| 健康分誤傷正常用戶 | 先 log factors 一週可調權重；門檻 40/70 不改；手動路徑永遠可用 |
| 邀請刷點 | 僅首次付費、月上限 50%、單層；M4 加簡單同裝置／同支付指紋可選（非必須） |
| Workspace 遷移弄壞既有資料 | M5 預設 WS + 一次性 backfill；archive 軟刪；測試用副本 |
| 範圍膨脹塞 P2 | M6 只列 P2 缺口不實作；市集／UTM／benchmark 不進 task |
| 與 haixun-backend 回歸衝突 | 每 M 跑 RG + 既有 `go test`／web build |

## 5. 刻意不做（本 plan 週期內）

- Insights **真管線**、Islander agent  
- Playbook 市集、免費破冰工具、跨帳號 benchmark、UTM 自動歸因（P2）  
- 多租戶帳單、白牌域名  
- 多層／現金邀請回饋；邀請回饋回溯  
- 新增多帳互回／養帳玩法  
- Admin 覆蓋健康分、Admin 全站 Outcome 分析  
- Workspace 多成員協作審核（P1 僅自審）  
- 真實金流改造（沿用既有 purchase 語意觸發 IR 即可）

## 6. 全域驗證指令

```bash
# 後端
cd apps/backend && go test ./... -count=1

# 前端
cd apps/web && npm run build

# 建議（若有 make 目標則用專案既有）
# make test && make web-build
```

里程碑級：

| M | 額外驗證 |
|---|----------|
| M1 | `go test` outcomes／scout hook；手測 Today＋Usage 成果區 |
| M2 | `go test` checkup **無** usage debit；手測報告 3 actions |
| M3 | throttle 帳號自動送 4xx／業務錯；手動標記成功 |
| M4 | 雙帳號 invite→upgrade 點數；第二次升級不發 |
| M5 | 兩 WS 資料隔離；PDF 可開 |
| M6 | spec §9 矩陣勾選 |

## 7. Task 號段總表（供拆 task 用）

| 區間 | Milestone | 內容 |
|------|-----------|------|
| T300–T309 | M0 | api 殼、index、FE types |
| T310–T329 | M1 | Outcome 全链路 + FE |
| T330–T349 | M2 | Checkup + Asset learning + FE |
| T350–T364 | M3 | AccountHealth + 送出閘 + FE |
| T365–T379 | M4 | InviteReward + FE |
| T380–T399 | M5 | Workspace + review + PDF + FE |
| T400–T409 | M6 | 整合測試、smoke、缺口文件 |

單一 task 目標 **~100–200 行** 生產碼變更；超大則再拆。拆 task 時每則必須：Goal、Inputs、Outputs、Out of scope、Acceptance（指令）、Depends on、對應 spec ID。

## 8. 批准

- [x] Plan 已批准（2026-07-20／使用者「plan 通過」）