14 KiB

Raw Permalink Blame History

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. 交付策略

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

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. 全域驗證指令

# 後端
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. 批准

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

14 KiB Raw Permalink Blame History Unescape Escape