380 lines
23 KiB
Markdown
380 lines
23 KiB
Markdown
|
# 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（歸因）
|
|||
|
|
|
|||
|
|
```text
|
|||
|
|
(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
|
|||
|
|
|
|||
|
|
```text
|
|||
|
|
(none) --> generating : 排程到點或手動重產
|
|||
|
|
generating --> ready : AI 成功寫入報告
|
|||
|
|
generating --> failed : 可重試；仍不扣點
|
|||
|
|
ready --> superseded : 同週再次成功重產（舊份保留可查，列表預設最新）
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
- 每會員每自然週（見 §4.2）**至多 1 份「當期」**；7 日內手動重產 **≤2 次**。
|
|||
|
|
- **永不**寫入 UsageEvent 扣點／meter。
|
|||
|
|
|
|||
|
|
### 3.3 AccountHealth 等級
|
|||
|
|
|
|||
|
|
```text
|
|||
|
|
score >= 70 --> normal : 不干預
|
|||
|
|
40 <= score < 70 --> warn : 送出前提示；建議加倍間隔
|
|||
|
|
score < 40 --> throttle : 強制降速（§4.4）
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
- 每日至少重算一次；有發送／失敗事件可即時重算。
|
|||
|
|
- `throttle` 解除：分數回升 ≥40 後下一輪重算生效（無人工解鎖按鈕需求；admin 可不擋額度類覆蓋——**本 run 不做** admin 覆蓋健康分，避免繞過護欄）。
|
|||
|
|
|
|||
|
|
### 3.4 InviteReward
|
|||
|
|
|
|||
|
|
```text
|
|||
|
|
(直邀 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
|
|||
|
|
|
|||
|
|
```text
|
|||
|
|
member 預設 1 個 default workspace
|
|||
|
|
--> 可 create 更多
|
|||
|
|
workspace active 可 archive（軟刪；至少保留 1 個不可 archive）
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
- 方案／用量／邀請碼仍綁 **Member**，不綁 Workspace。
|
|||
|
|
|
|||
|
|
### 3.6 DraftReview（Workspace 開啟審核時）
|
|||
|
|
|
|||
|
|
```text
|
|||
|
|
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）
|
|||
|
|
|
|||
|
|
1. 島民完成海巡外展：**sendOutreach 真送** 或 **標記完成（手動路徑）**。
|
|||
|
|
2. 系統建立 OutcomeEvent（`source_type=scout_outreach`，連 `scout_post_id`、送出 `threads_account_id`），狀態 `observing`，`window_ends_at = sent_at + 72h`。
|
|||
|
|
3. Worker／排程在窗內拉取可讀訊號（§5.4）：
|
|||
|
|
- **對話**：目標串上出現對己方回覆的再回／引用（能判則 `confirmed`）。
|
|||
|
|
- **互動**：己方回覆或目標貼的 likes／replies 計數上升（能讀則記；弱則 `possible`）。
|
|||
|
|
- **追蹤**：送出帳號 `followers_count` 在窗內淨增加 → 預設 `possible`（不可宣稱「此回覆帶來追蹤」為確定，除非未來有更強訊號）。
|
|||
|
|
4. 島民可在命中詳情或成果明細 **手動回報成交**（金額選填、備註選填、幣別預設 TWD）→ `confirmed` + `kind=conversion`。
|
|||
|
|
5. **今日頁**：成果摘要卡（本週：對話數、possible／confirmed 追蹤、成交筆數／金額）。
|
|||
|
|
6. **用量頁**：成本區（既有 platform／BYOK）**與**成果區並列；不可只顯示成本。
|
|||
|
|
7. 明細列表：每筆可點回 Scout 命中或 Outbox 步驟。
|
|||
|
|
8. **降級：** 任一 API 訊號不可用 → 仍提供手動成交＋「已送出／標記完成」計入觸達；**禁止**整段歸因 API 回未實作空成功。
|
|||
|
|
|
|||
|
|
### 4.2 每週健檢（P0）
|
|||
|
|
|
|||
|
|
1. **節奏：** 以會員 `timezone` 的**當地週一 00:00** 起可自動產（無 timezone → UTC）；Job `weekly_checkup`。
|
|||
|
|
2. 輸入：該會員已同步貼文成效（既有 own posts／insights 本地資料）、近 14 日海巡送出與 Outcome 摘要、active 人設摘要。
|
|||
|
|
3. 輸出（`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`）
|
|||
|
|
4. **計費：** 不扣 credits、不寫 platform meter、不寫 byok 次數。AI 呼叫可用平台 key；失敗可重試。
|
|||
|
|
5. 手動「提前重產」：7 日滾動窗內 ≤2 次；超過回明確錯誤。
|
|||
|
|
6. 完成 → 站內通知；今日頁可進最新報告。
|
|||
|
|
|
|||
|
|
### 4.3 資產複利可見（P0）
|
|||
|
|
|
|||
|
|
1. 人設詳情／列表：顯示 `learning_summary`（短）、`learning_version`（遞增整數）、`learned_from_posts_count`、`last_learned_at`。
|
|||
|
|
2. 品牌詳情：同上語意（來源可為海巡 homework／brief 累積）。
|
|||
|
|
3. 更新時機（最小）：人設分析 Job 成功、健檢 `ready` 時可附帶刷新 summary（不強制每次分析都變 version；有實質變更才 +1）。
|
|||
|
|
4. 空狀態：尚未學習時明確文案，禁止假數據。
|
|||
|
|
|
|||
|
|
### 4.4 帳號健康分（P1）
|
|||
|
|
|
|||
|
|
1. 每個 `ThreadsAccount` 計算 `score`、`level`（normal｜warn｜throttle）、`factors[]`（可解釋扣分項）、`advice`。
|
|||
|
|
2. **訊號方向（權重數值 plan／實作可調，行為門檻鎖定）：**
|
|||
|
|
- 24h 發送次數過高 → 扣
|
|||
|
|
- 最小間隔違規（連續 steps 間隔過短）→ 扣
|
|||
|
|
- 近 7 日 Outbox 失敗率高 → 扣
|
|||
|
|
- token 過期／error／不可用 → 重扣
|
|||
|
|
- 多日無操作 → **不扣**
|
|||
|
|
3. **送出前檢查（自動路徑）：** ThreadPlay submit、sendOutreach 自動送、compose 進 Outbox。
|
|||
|
|
- `warn`：API 仍允許，但 response 帶 `health_warning`；前端必顯示。
|
|||
|
|
- `throttle`：**拒絕**自動送出（明確錯誤碼）；僅允許手動路徑（複製＋標記完成）。
|
|||
|
|
4. 今日頁：顯示分數最低的帳號警示（若有 warn／throttle）。
|
|||
|
|
5. Crew 帳號列：分數 Badge（與既有 token 健康文案並存，不取代 token 狀態）。
|
|||
|
|
|
|||
|
|
### 4.5 邀請獎勵（P1）
|
|||
|
|
|
|||
|
|
1. 沿用既有邀請綁定（`parent_uid` 一次）。
|
|||
|
|
2. 當直邀會員**首次**完成 free→starter 或 free→pro 的方案生效（對齊既有 purchase／plan 成功語意）：
|
|||
|
|
- 解析邀請人 = `parent_uid`
|
|||
|
|
- 計算應發點數與月上限 → `credited` 或 `capped`／`skipped`
|
|||
|
|
3. 點數進入邀請人**平台方案額度池**（與 BYOK 無關）；寫 `InviteReward` 紀錄 + 可選 Usage 類「贈點」事件（`key_mode` 不適用；`meter=invite_bonus` 或等價，**不計入**付費消耗進度的「已用」誤解——報表分開「贈點入帳」）。
|
|||
|
|
4. 邀請頁：累計已獲點數、本月已獲／上限、最近回饋列表。
|
|||
|
|
5. Admin **不**手改回饋紀錄（防爭議）；糾錯走既有調 `parent_uid`（調後**不回溯**已發點數）。
|
|||
|
|
|
|||
|
|
### 4.6 Workspace 與審核（P1）
|
|||
|
|
|
|||
|
|
1. 會員可 list／create／rename／switch／archive Workspace（至少留 1 個）。
|
|||
|
|
2. Brand、Persona、ThreadsAccount **歸屬** `workspace_id`；建立時寫入當前 Workspace。
|
|||
|
|
3. 切換 Workspace 後，列表 API 預設只回該區資源；「全部」視圖可選（若做，須明確 query）。
|
|||
|
|
4. Workspace 設定 `review_required`：開啟後，該區 plays／compose／outreach 進自動發送前須 `approved`。
|
|||
|
|
5. 審核操作：提交者 pending；審核者（同會員多席或同 Workspace 成員——**P1 最小：同一 Member 自審即可**；多成員協作 P2）approved／rejected。
|
|||
|
|
6. **白牌月報 PDF：** 選 Workspace＋月份 → 匯出含成果摘要、發送數、海巡完成數、健康分概況；無巡樓品牌強制露出（可選 footer「Powered by…」開關預設關）。
|
|||
|
|
7. 用量／方案／邀請：**不**隨 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. 開放規格問題
|
|||
|
|
|
|||
|
|
1. ~~週一起點時區~~ → **已定：會員 timezone，無則 UTC**（§4.2）。
|
|||
|
|
2. Threads 各訊號實際 scope 探測結果 → **實作前填表**，不阻 P0 手動＋觸達。
|
|||
|
|
3. Draft review P1 是否僅「同一 Member 自審」→ **已定是**；多成員協作 P2。
|
|||
|
|
4. 健康分權重精確數字 → plan／實作可調；**門檻帶 70／40 鎖定**。
|
|||
|
|
5. PDF 引擎選型 → plan 定（行為：可下載白牌月報）。
|
|||
|
|
|
|||
|
|
## 11. 批准
|
|||
|
|
|
|||
|
|
- [x] Spec 已批准（2026-07-20／使用者「spec 通過」）
|