# Plan: 商機雷達＋成交 CRM

> Status: `approved`  
> Status note: 使用者 2026-07-31「請繼續拆解」（plan 通過，進 tasks）  
> Source: `docs/product/demand-radar/spec.md`（**approved** 2026-07-31 使用者「好」）  
> Requirements: `docs/product/demand-radar/requirements.md`（**approved** 2026-07-31）  
> Last updated: `2026-07-31`  
> 底座：`apps/backend` + `apps/web`（haixun-backend M0–M6、growth-loop M0–M6 均已交付）

## 1. 交付策略

1. **先讓「每天有名單」成立。** M1–M3 一路做到今日商機頁能開出「今日找到 N 筆／高中低分級」，這是整個產品的價值主張；在此之前的任何 CRM 功能都沒有意義。
2. **配額閘與每日巡同批交付。** 每日自動巡是常駐 AI 成本，M2 若沒有配額截斷就上線，成本會在驗證價值之前先失控（spec §4.9、決策 #11）。
3. **判定準確度先於功能廣度。** M2 完成後、M3 上線前必須用真實貼文樣本人工抽驗一輪；名單不可信是本 run 的單點失敗風險，寧可延後 M3 也不要先擴功能。
4. **加值 hook，不重寫主流程。** 既有海巡三模式、抓取雙路徑、Outbox、AccountHealth 送出閘、Stripe 付費流程一律沿用；新能力以新 group 與新 collection 並存，橋接只做單向「升級為商機」。
5. **前後端同里程碑可驗。** 每個 M 結束都要有前端可操作的畫面並對應 spec §9 的 ID，禁止後端全做完最後才接前端。
6. **不新增 usage meter。** 沿用四個既有 meter＋`source` 標籤，避免重算三個方案的 `soft_caps` 配比（spec §5.5）。

驗收一律對照 **spec §9**（SP／RW／SW／OP／TD／RP／CR／FU／ST／QT／PR／RG）；每則 task 的完成定義必須寫明覆蓋哪些 ID。

## 2. 里程碑

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

- **目標：** `radar`／`crm` 兩個 module 與路由骨架就位，未實作能力回**明確未就緒錯誤**（禁止 102000 空成功）。
- **完成定義：**
  - `generate/api/` 新增 radar／crm 契約檔 → `make gen-api` 產出 handler／routes（不手寫）。
  - Mongo index init 擴充：`radar_watches`、`radar_opportunities`、`radar_replies`、`radar_sweeps`、`crm_contacts`、`crm_touches`、`crm_followups`；含 spec §8 列出的複合索引與唯一鍵。
  - 前端 `src/domain/types.ts` 新增 Radar／CRM 型別，`src/data/repos.ts` 新增 `radar`、`crm` 介面，live 實作分檔 `src/data/live/radarRepos.ts`（先回未就緒錯誤）。
  - 新增 `src/styles/radar.css` 空殼並於 `main.tsx` 匯入，`npm run check:tokens` 通過。
- **建議 task 區間：** **T500–T509**
- **驗證：** 既有回歸 RG-01～RG-04 不破；新路由未完成能力 ≠ 102000 空 data；`make build` 與 `npm run build` 綠。

### M1 — 服務檔案＋雷達訂閱

- **目標：** 使用者能填服務檔案、建立與管理關鍵字訂閱，並拿到 AI 建議的關鍵字。
- **完成定義：**
  - ServiceProfile 讀寫（每會員一份），`forbidden[]`／`service_areas[]`／`remote_ok` 完整。
  - RadarWatch CRUD／pause／resume／archive；**未建服務檔案不得建 active watch**。
  - 方案 `max_active_watches` 閘（Free 1／Starter 5／Pro 20）生效並回明確錯誤含升級提示。
  - `watches/suggest` 依服務檔案產關鍵字建議，計入 `ai_copy`／`source=radar.suggest`。
  - 前端：`/app/brands` 新增「服務檔案」分頁；新增 `/app/radar/watches` 頁。
- **建議 task 區間：** **T510–T524**
- **驗證：** SP-01～SP-02、RW-01～RW-04。

### M2 — 每日巡管線＋五問判定（後端閉環）

- **目標：** 排程自動巡 → 抓取 → 五問判定 → 商機入庫，含配額截斷、去重與可觀測性。
- **完成定義：**
  - Job template `radar_sweep`：每日 **UTC 22:00** 為每個 active watch 建一筆；手動觸發共用同一路徑；多台 worker 沿用既有 Redis lock（value = `workerID`）。
  - 抓取**復用既有海巡雙路徑**：`dev_mode_enabled` 決定 api／crawler，不新增第三種。
  - 五問判定產 `intent_score`／`intent_band`／`reasons[]`（五條齊全否則拒絕入庫）／`region_match` 三態／`freshness_hours`；硬否決寫 `rejected` 仍入庫。
  - 配額截斷：達 `max_daily_opportunities` 依分數保留，記 `truncated_count`，**非錯誤**。
  - 去重：同 `owner_uid` 同 `external_id` 只建一筆，記錄多個觸發 term。
  - RadarSweep 紀錄命中／判定／截斷／失敗原因／耗用點數；失敗發通知，**禁止空成功**。
  - 計費標籤：`web_search`／`radar.sweep`、`ai_research`／`radar.judge`。
- **建議 task 區間：** **T525–T544**
- **驗證：** SW-01～SW-06、OP-01～OP-07、QT-01～QT-02。
- **閘門（硬性）：** 本 M 結束後、進 M3 前，須以**真實貼文樣本人工抽驗判定準確度**並記錄結果；準確度不可接受時先調權重／提示詞，不得直接進 M3。

### M3 — 今日商機頁＋回覆五版本

- **目標：** 第一個可展示的完整每日價值：打開就看到分級名單與可用的回覆。
- **完成定義：**
  - `/api/v1/radar/today` 統計＋卡片；`opportunities` 列表／詳情／accept／dismiss／override。
  - 前端 `/app/radar`：統計列、高中低分組（低意向預設收合）、卡片五欄位、五個動作、**空狀態必須給原因與下一步**。
  - 回覆五版本：首次判定只生成 `public_comment`，其餘按需；`forbidden[]` 硬性過濾，連兩次命中回明確錯誤且不輸出。
  - 送出接線：公開留言版走既有海巡外展／Outbox，**必經 AccountHealth 送出閘**；私訊版 P0 僅提供複製，UI 不得宣稱已自動送出。
  - 計費標籤 `ai_copy`／`source=radar.reply`。
  - 側欄資訊架構定案：新增「商機」分組，手機底欄 `radar` 進主要四格、`scout` 移入「更多」。
- **建議 task 區間：** **T545–T564**
- **驗證：** TD-01～TD-02、RP-01～RP-05；AccountHealth throttle 回歸。

### M4 — 聯絡人與 CRM

- **目標：** 商機能加入名單、收斂成人、推進階段、回報成交。
- **完成定義：**
  - accept → 依（平台＋作者＋owner）綁定或建立 Contact，`stage=new_found`；同一人多筆商機收斂在同一 Contact。
  - 七階段任意跳轉（含回退、跳級、終態重開），每次轉移寫 `ContactTouch`；`needs_follow_up` 為**並存 boolean**，非階段值。
  - 手動 merge／unmerge，跨 owner 拒絕；跨平台不自動合併。
  - 成交回報：階段轉 `won` → 寫既有 `growth_outcomes`（`source_type=radar_opportunity`）；可改／刪並留痕；**系統永不自動判定成交**。
  - 前端 `/app/crm` 八格視圖與篩選排序、`/app/crm/:contactId` 時間軸與成交回報。
- **建議 task 區間：** **T565–T584**
- **驗證：** CR-01～CR-09；RG-03（既有成果卡不受影響、radar 成交併入同一彙總）。

### M5 — 追蹤提醒＋轉換統計

- **目標：** 名單不會躺著爛掉，並回答「哪個關鍵字最會成交、哪種回覆最有效」。
- **完成定義：**
  - Job `radar_followup_scan` 日排程（維護 tick＋Redis lock）：到期 → `notified` ＋站內通知（`ref_type=contact`，落地 Contact 詳情）。
  - AI 追蹤訊息（`ai_copy`／`source=radar.followup`）；snooze／done；通知達 2 次 → `escalated` 僅建議轉 `lost`，**不自動改階段**。
  - `crm/stats`：關鍵字轉換率、回覆版本成功率、成交來源三維度；**任一維度樣本 < 5 只顯示絕對數並標「樣本不足」**。
  - 用量頁可依 `radar.` source 前綴聚出雷達耗用（供 P1 價格校準）。
- **建議 task 區間：** **T585–T599**
- **驗證：** FU-01～FU-04、ST-01～ST-03、QT-03。

### M6 — 海巡橋接、整合回歸、缺口文件

- **目標：** 既有用戶無痛接上，且確認沒有弄壞底座。
- **完成定義：**
  - `POST /api/v1/scout/posts/:id/promote`：**複製**建立新 Opportunity 並記 `source_scout_post_id`，原 ScoutPost 狀態不變；跑同一套判定；前端命中列新增動作。
  - Integration tests 覆蓋 SP／RW／SW／OP／TD／RP／CR／FU／ST／QT／PR 主路徑（Threads／AI 走 fake）。
  - 回歸：既有海巡三模式行為一致、Outbox 僅平台成功才 published、`soft_caps` 四分項加總仍等於 `monthly_credits`、全 repo 無以 `lead` 指稱銷售線索。
  - `TESTING.md` 與 `GAPS.md`：列出 P1／P2 未做項與已知限制（私訊無 API、時區未個人化、跨平台不自動合併）。
- **建議 task 區間：** **T600–T614**
- **驗證：** PR-01～PR-02、RG-01～RG-05、spec §9 全表勾選。

## 3. 依賴

```text
M0 殼與地基
 └─► M1 服務檔案＋雷達訂閱
      └─► M2 每日巡＋五問判定  ──【判定準確度閘門】
           └─► M3 今日頁＋回覆五版本
                └─► M4 聯絡人與 CRM
                     └─► M5 追蹤提醒＋轉換統計
                          └─► M6 橋接＋整合回歸
```

| 關係 | 說明 |
|------|------|
| M1 → M2 | 判定需要 ServiceProfile 作輸入；無服務檔案不得建 active watch |
| M2 → M3 | 今日頁的資料來源是 M2 產出的 Opportunity |
| M3 → M4 | 「加入名單」是 CRM 的唯一入口 |
| M4 → M5 | 追蹤提醒與統計都掛在 Contact／階段之上 |
| M2 ＋ M4 → M6 | 橋接需要判定管線與 CRM 都到位 |
| M3 → 既有 AccountHealth | 送出閘為既有能力，M3 只接線不改行為 |
| M4 → 既有 growth_outcomes | 成交寫既有成果事件，不新建帳 |
| 硬性順序 | **不可**先做 M4／M5 而跳過 M2／M3（requirements 決策 #11） |

## 4. 風險與緩解

| 風險 | 緩解 |
|------|------|
| **判定不準，名單不可信**（單點失敗） | M2 結束設硬性閘門：真實樣本人工抽驗才可進 M3；`reasons[]` 強制五條；使用者覆寫留痕作為調校素材；band 門檻 80／50 鎖定，只調權重與提示詞 |
| Threads 需求貼文量體不足 | M2 完成即可實測每日筆數；不足時先強化 `watches/suggest`（放寬關鍵字），M3 空狀態必須給原因與建議而非空白頁；手動匯入為 P1 補位 |
| 每日巡 AI 成本失控 | 配額閘與 M2 同批交付，非後補；`radar.` source 聚合每 M 檢視一次耗用 |
| 多台 worker 重複跑每日巡 | 沿用既有 Redis lock 與 guarded job 更新，M2 以多實例情境驗證 |
| 判定 Job 中途失敗導致重複扣點 | Sweep 記錄已判定進度，重跑不重判已完成者 |
| 破壞既有海巡 | 新 group／新 collection 並存，橋接單向；每個 M 都跑 RG-01～RG-05 |
| 前端 `global.css` 已 6,171 行再膨脹 | 新頁樣式一律進 `radar.css`，`npm run check:tokens` 為必跑閘 |
| 側欄 13 項資訊過載 | M3 一併定案分組與手機底欄調整，不拖到最後 |
| 私訊版被誤解為可自動送 | M3 明確禁止 UI 宣稱自動送出；「已私訊」階段在 P0 是人工標記 |
| 範圍膨脹塞 P1／P2 | M6 只列缺口不實作；手動匯入、金額、LINE 一律不進本輪 task |

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

- **P1：** 手動匯入（貼網址／CSV）、報價與成交金額欄位、價格帶校準。
- **P2：** LINE 官方帳號、Google 商家評論、網站表單 webhook、自有留言私訊收斂、空檔媒合、可公開搜尋的論壇來源。
- 每日巡的**個人化時區**（P0 固定 UTC 22:00）。
- **跨平台自動合併聯絡人**（只做手動 merge）。
- 新增第五個 usage meter；改動既有方案價格與 `soft_caps` 配比。
- 重做付費流程、重做海巡抓取、重做貼文分類器。
- Admin 全站商機檢視與跨會員分析。
- 任何繞過 AccountHealth 送出閘的新路徑。

## 6. 全域驗證指令

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

# Mongo 索引（M0 之後）
cd apps/backend && make migrate-up && make init

# 前端
cd apps/web && npm run build && npm run check:tokens && npm run test && npm run lint
```

里程碑級：

| M | 額外驗證 |
|---|----------|
| M0 | 新路由未實作回明確錯誤（非 102000 空 data）；索引建立可重複執行 |
| M1 | 無服務檔案建 active watch 被擋；Free 建第 2 個 watch 被擋 |
| M2 | 多實例 worker 不重複巡；命中 40／上限 30 時 `truncated_count=10`；**判定抽驗報告存檔** |
| M3 | 今日頁 0 筆時顯示原因；forbidden 詞連兩次命中回錯誤且不輸出；throttle 帳號自動送被拒 |
| M4 | 同一作者兩筆商機收斂同一 Contact；`won` 後既有成果彙總含此筆 |
| M5 | 到期 3 天進通知；樣本 3 筆時只顯示絕對數 |
| M6 | promote 後原 ScoutPost 狀態不變；spec §9 全表勾選；`rg -w lead` 無新增銷售線索用法 |

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

| 區間 | Milestone | 內容 |
|------|-----------|------|
| T500–T509 | M0 | radar／crm api 殼、Mongo 索引、FE 型別與 repo 介面、`radar.css` |
| T510–T524 | M1 | ServiceProfile、RadarWatch CRUD／配額閘、關鍵字建議、FE 兩處畫面 |
| T525–T544 | M2 | `radar_sweep` Job 與排程、抓取復用、五問判定、去重、配額截斷、Sweep 觀測 |
| T545–T564 | M3 | today／opportunities API、`/app/radar` 頁、回覆五版本、送出接線、側欄 IA |
| T565–T584 | M4 | Contact／Touch 模型、階段機、merge、成交回報接 `growth_outcomes`、FE CRM 兩頁 |
| T585–T599 | M5 | `radar_followup_scan`、通知、AI 追蹤訊息、`crm/stats`、用量 source 聚合 |
| T600–T614 | M6 | scout promote 橋接、integration tests、回歸、TESTING／GAPS |

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

## 8. 批准

- [x] Plan 已批准（2026-07-31／使用者「請繼續拆解」）→ tasks 見 [`tasks/INDEX.md`](./tasks/INDEX.md)（58 則，號段 T500–T604）