# Requirements: 商機工作收件匣與產品需求搜尋

> Status: `approved`
> Status note: 使用者 2026-08-11「幫我拆吧」，視為批准需求並要求繼續拆解
> Slug: `opportunity-inbox`
> Last updated: `2026-08-11`
> Depends on: `demand-radar`、`brand-product-radar`

## 1. 一句話

讓經營者用一個簡單收件匣處理每天找到的商機，系統先把產品能力翻成使用者真正會說的痛點與求助語言，再用低成本前處理和分層判定找出更貼近產品的貼文，並讓每一筆點數消耗可預期、可追溯且不重複。

## 2. 誰用、在什麼情境

| 角色 | 目標 |
|------|------|
| 每天巡邏商機的經營者 | 快速看完待處理結果，完成有價值的商機，移除不相關內容 |
| 單品牌、多產品經營者 | 知道貼文對應哪個產品與哪個痛點，不因產品名稱相似而誤判 |
| 重視成本的付費會員 | 在手動探索或 AI 動作前知道可能耗點，事後能查到實際用量 |
| 自備 AI 金鑰的會員 | 沿用 BYOK 規則，不扣平台點數但保留呼叫與結果紀錄 |
| 營運人員 | 能比較結果品質、使用量與成本，避免為增加結果數量無限制燒點 |

## 3. 背景與動機（As-is → 為什麼改）

- **現況問題：** 「今日商機」與「全部商機」分散了同一件工作；卡片資訊與操作過多，第一次使用者不清楚下一步。找到的結果也可能只命中表面關鍵字，未必真的在表達產品能解決的痛點。
- **現況問題：** 使用者缺少「已完成」與可復原的「移除」流程，已看過或判定無關的內容容易繼續干擾待辦，甚至再次出現。
- **現況問題：** 現有產品詞建議雖會讀取品牌與產品資料，但尚未形成可檢查的需求地圖；候選前處理主要靠字面排除與基本分類，對同義句、口語痛點和隱含求助的辨識不足。
- **現況問題：** 搜尋、AI 判定與重新生成可能耗用點數，但商機工作流程沒有在需要決策的位置清楚說明預估、實際消耗與重試規則。
- **不改的後果：** 結果越多，人工篩選成本和 AI 成本也越高；使用者會覺得這只是 Threads 關鍵字搜尋加上一個複雜介面，無法信任排序或持續每日使用。
- **參考文件（非需求本體）：** `docs/product/demand-radar/`、`docs/product/brand-product-radar/`、`docs/product/haixun-console/spec.md`。

## 4. 目標（To-be）

### 4.1 必須達成（P0）

1. **一個商機工作收件匣**
   - 把每日結果與歷史結果收斂成同一個工作入口，以「待處理／已完成／已移除」表達工作狀態。
   - 「今天／近 7 天／全部」是時間範圍，不是三套不同流程。
   - 預設畫面只回答：對方遇到什麼問題、最適合哪個產品、證據是什麼、現在要完成或移除。
   - 回覆草稿、CRM、其他產品匹配與完整判定放在次層詳情，不阻礙快速瀏覽。

2. **完成與軟移除**
   - 使用者可把一筆商機標示為已完成，之後仍可查看並恢復為待處理。
   - 使用者可移除不想再看的商機，移除後預設不在待處理清單出現，但保留來源識別，避免同一篇公開內容被下一次巡邏重新當成新商機。
   - 移除可復原，並可記錄「不符合痛點、同業／廣告、過時、已解決、重複、其他」等原因。
   - 「已完成」只代表工作進度；「已移除＋原因」才可作為後續品質調校的負向訊號，兩者不得混用。

3. **先建立產品需求地圖，再產生搜尋語言**
   - 每個產品的搜尋上下文至少整理成：使用者症狀／困擾語言、發生情境、想達成的結果、正在找解法的訊號、不適合或應排除的訊號。
   - 需求地圖必須能回指品牌與產品中已有的受眾、痛點、情境和能力，不得自行捏造產品用途。
   - 搜尋詞以使用者可能說出的短句與多種表達方式為主，產品名與品牌名只能當輔助訊號，不能單獨證明商機。
   - 使用者可檢查與調整需求地圖及搜尋建議；產品資料不足時，系統應指出缺口並降低信心。

4. **分層處理，先便宜後昂貴**
   - 搜尋採「廣召回、嚴排序」：先取回較多候選，再經去重、時間、語言、同業／公告／廣告排除、問題句與求助句抽取等低成本前處理。
   - 候選至少同時具備需求訊號，以及痛點、情境或期望結果中的一項產品證據，才可進入高優先商機。
   - 通過前處理的候選先做產品語意適配排序，只有高價值或難以判斷的候選才使用較昂貴的 AI 深度判定。
   - 未達高優先門檻但仍有合理證據的結果可以保留在較低順位，讓使用者取得更多結果；不可把純名稱命中或明確雜訊灌入商機數量。

5. **可解釋的優先排序與時間排序**
   - 預設以「產品痛點適配、真實需求意圖、證據品質、貼文新鮮度」形成推薦順序，其中產品痛點適配為最高權重。
   - 使用者可改按最新、最舊、產品適配、需求意圖排序，並可選今天、近 7 天或全部時間。
   - 時間排序以來源貼文的發布時間為準；未知時間不得假裝成最新。
   - 每筆高順位商機都必須顯示可回指原文的需求證據與產品適配原因；只提到品牌或產品名稱不得進入高順位。

6. **扣點透明且不重複**
   - 瀏覽、篩選、排序、完成、移除與復原不扣點。
   - 手動觸發會耗點的搜尋、需求地圖 AI 優化、深度判定或回覆生成前，顯示本次動作的扣點類型與可得的預估；實際完成後顯示本次實際耗點。
   - 每日自動巡邏不要求逐次確認，但必須受方案配額與使用者可理解的每日成本上限保護；達上限時停止新增付費判定並說明有多少候選尚未處理，不得靜默消失。
   - 候選在前處理階段被排除，不產生 AI 深度判定點數；AI 已完成判定但結果不適合，仍屬已使用服務，可正常計點。
   - 同一候選、同一產品版本已有有效判定時，重跑、跨雷達命中或頁面重試不得重複判定、重複扣點。
   - 在付費供應商呼叫前失敗不扣點；工作中斷後續跑時，已成功完成並記錄的部分不得再扣。若供應商已完成有效工作，即使最終沒有建立商機，也應如實記錄用量。
   - 沿用既有平台代付與 BYOK 規則：BYOK 不扣平台點數，但保留呼叫次數與來源紀錄；不新增難以理解的第五種用量分類。
   - 每次巡邏可查看搜尋命中、前處理排除、AI 判定、建立／合併商機、未處理候選與實際耗點，使用者能理解點數花在哪裡。

7. **結果品質必須可驗收**
   - 建立含有效商機、口語改寫、同業銷售、公告、泛討論、重複與過時內容的代表性標註集。
   - 高順位前十筆至少八筆同時具有真實需求及產品適配證據。
   - 純產品名／品牌名命中、同業叫賣與公告不得進入高順位。
   - 完成與移除後，同一來源在各時間範圍、排序方式與下一次巡邏中的狀態一致。

### 4.2 應該有（P1）

1. 將移除原因按產品彙整，建議新增排除語言或降低某類需求語言權重；任何會改變後續巡邏的建議都須由使用者確認。
2. 將品質調校集中批次執行，先顯示預估耗點，不因每次移除操作立即呼叫 AI。
3. 顯示每產品的候選數、前處理通過率、深度判定率、高順位有效率與每筆有效商機平均耗點，供產品與價格校準。
4. 支援批次完成、批次移除與可逆的短期復原操作。

### 4.3 以後再說（P2）

1. 在足夠且已確認的正負樣本上建立個人化排序，但不得讓個人化規則不可解釋。
2. 在使用者設定的月度預算內，自動調整各產品的探索廣度與深度判定比例。
3. 擴充其他公開來源，沿用同一需求地圖、去重、狀態與扣點原則。

## 5. 範圍

### In scope

- 商機單一收件匣、三種工作狀態、時間範圍與排序。
- 單筆完成、軟移除、復原、移除原因及跨巡邏不再浮現。
- 產品需求地圖、搜尋語言建議、候選前處理、產品適配排序與 AI 深度判定分層。
- 手動與自動巡邏的扣點可見性、防重扣、上限提示與用量追溯。
- 代表性品質資料集與高順位準確度驗收。

### Out of scope（明確不做）

- 不重做 Threads 抓取底座、排程器、CRM、金流、方案、用量計量或 AI 供應商抽象。
- 不用硬刪除清除商機歷史，也不因移除自動封鎖作者或刪除來源內容。
- P0 不因每次完成或移除即時訓練模型，也不自動修改品牌或產品真相。
- 不保證找到的公開發文者一定有預算或會購買；只判斷其公開表達的需求與產品適配。
- 不以增加 AI 呼叫數換取表面上的結果數量，也不在點數不足時假裝完成全部判定。
- 不調整既有方案售價；成本與品質數據只供後續校準。

## 6. 使用者故事（可驗收）

| ID | 作為… | 我想要… | 以便… | 驗收要點 |
|----|--------|---------|--------|----------|
| OI-01 | 第一次使用者 | 一進頁面只看到待處理商機與明確動作 | 不用先理解多個頁面和複雜流程 | 可在同一入口切換待處理、已完成、已移除與時間範圍 |
| OI-02 | 經營者 | 把已處理商機標成完成 | 待辦只留下還要看的內容 | 完成後離開待處理；可查看與恢復；不扣點 |
| OI-03 | 經營者 | 移除不相關或重複貼文並留下原因 | 相同雜訊不再反覆出現 | 移除後下一次巡邏不新建同來源；可復原；不扣點 |
| OI-04 | 產品經營者 | 先看產品需求地圖再開始找 | 確認系統找的是痛點語言，不只是產品名稱 | 五類需求資訊可檢查且能回指產品資料；資料不足有提示 |
| OI-05 | 業務 | 依推薦或時間整理商機 | 先處理最適合或最新的需求 | 推薦、最新、最舊、產品適配、需求意圖排序結果一致且時間未知不冒充最新 |
| OI-06 | 付費會員 | 在手動付費動作前知道可能耗點 | 決定是否值得執行 | 動作前有扣點類型／預估，完成後有實際耗點與用量入口 |
| OI-07 | 每日巡邏使用者 | 成本到上限時知道哪些工作沒做完 | 不把零結果誤認為沒有市場 | 顯示未判定候選數、停止原因與後續選項；不靜默丟棄 |
| OI-08 | 重跑工作的使用者 | 不為同一份有效判定付兩次 | 信任系統用量 | 同候選、同產品版本重跑或跨雷達合併只計一次有效判定 |
| OI-09 | BYOK 會員 | 使用自己的金鑰執行判定 | 不占平台點數且仍看得到用量 | 平台點數為零；呼叫次數、來源與巡邏結果可查 |
| OI-10 | 營運 | 用標註資料驗證排序 | 確認價值高於關鍵字搜尋 | 前十至少八筆有效；名稱命中、同業與公告不進高順位 |

## 7. 成功標準

- [ ] 新使用者不需離開商機入口，即可完成「查看證據 → 完成或移除 → 查看已處理結果」的完整流程。
- [ ] 完成、移除、復原、篩選與排序均不產生 AI 或搜尋點數。
- [ ] 被軟移除的同來源內容不會在後續巡邏重新成為新商機，且仍可由使用者復原。
- [ ] 每筆高順位商機至少有一段需求證據與一項產品痛點／情境／期望結果的適配證據。
- [ ] 代表性標註集中，高順位前十筆至少八筆有效，且沒有只靠品牌名或產品名進榜的結果。
- [ ] 每次巡邏皆可對帳命中、前處理排除、AI 判定、建立／合併、未處理與實際耗點。
- [ ] 同候選、同產品版本在重試、重跑或跨雷達命中時不重複扣 AI 判定點數。
- [ ] 達點數或每日成本上限時，畫面明確說明停止原因與未處理數量，不以成功空結果掩蓋。
- [ ] 使用者可按推薦、最新、最舊、產品適配與需求意圖排序，且時間排序以來源發布時間為準。

## 8. 約束與假設

- 技術 / 合規 / 時程約束：沿用既有 UTC unix nanoseconds、回應格式、列表分頁、guarded job、會員權限、AI token 隔離、平台代付／BYOK 與方案配額規則。
- 技術 / 合規 / 時程約束：交付仍依 Phase A → B 前端與 mock → C 接真 API → D 業務深化；本需求不得繞過既有 goctl 後端流程。
- 技術 / 合規 / 時程約束：產品真相仍由 Brand／Product 提供，需求地圖只做可追溯轉譯，不成為另一份自動覆寫的產品資料。
- 假設（未驗證當真）：使用者更在意高順位的準確度與處理速度，而非首頁塞入最多結果；較低信心但具基本證據的結果仍可在後段查看。
- 假設（未驗證當真）：低成本前處理能顯著減少昂貴 AI 判定量；需要以真實巡邏成本與標註集驗證。
- 假設（未驗證當真）：既有四種用量分類足以承載新流程，只需沿用來源標籤分辨商機用途。

## 9. 風險

| 風險 | 影響 | 緩解（需求層，非實作細節） |
|------|------|---------------------------|
| 廣召回帶來大量雜訊 | 清單變多但更難用 | 高順位設證據硬門檻，低信心結果後置，標註集持續驗收 |
| 前處理過嚴 | 真正需求在 AI 前被誤排除 | 區分明確雜訊與低信心候選；保留各階段數量與抽樣稽核能力 |
| 需求地圖把產品用途想太多 | 搜尋與排序偏離真實產品 | 每項內容回指品牌／產品資料，缺資料就提示，不由模型補故事 |
| 自動巡邏耗點不可控 | 使用者點數快速耗盡、產品毛利受損 | 先便宜後昂貴、每日成本上限、候選去重、結果與耗點可對帳 |
| 為避免重扣而沿用過期判定 | 產品更新後仍使用舊結論 | 防重以產品版本為邊界；產品實質變更後可重新判定並清楚告知可能耗點 |
| 移除被當成永久訓練真相 | 一次誤按導致未來漏商機 | 軟移除可復原；P0 只記原因，P1 建議需人工確認後才影響巡邏 |
| 已完成與不適合混在一起 | 排序學到錯誤訊號 | 完成只表示流程進度，移除原因才是負向品質訊號 |

## 10. 開放問題

1. **每日自動巡邏成本上限的預設值**應沿用方案固定值，還是允許會員為每個產品再設更低上限？需求預設：P0 沿用方案固定上限並清楚顯示，個別產品自訂列 P1。
2. **移除資料保留多久？** 需求預設：保留來源識別與狀態，直到使用者主動復原或依既有資料保留政策清除；不提供不可逆的單筆硬刪除。
3. **產品什麼變更算新版本、允許重新扣點判定？** 需求預設：只有會影響需求地圖的受眾、痛點、情境、能力或排除訊號變更才算；純名稱或顯示資訊修改不算。

## 11. 批准

- [x] 需求已批准（2026-08-11／使用者）
- 批准後下一步：只撰寫 `spec.md`，把狀態、排序、扣點、防重與巡邏統計定成行為契約；spec 再批准後才進 plan，plan 批准後才拆 tasks。
