126 lines
11 KiB
Markdown
126 lines
11 KiB
Markdown
# Requirements: 話題海巡品質、分數排序與批次分頁
|
||
|
||
> Status: `approved`
|
||
> Slug: `scout-topic-quality`
|
||
> Last updated: `2026-08-10`
|
||
|
||
## 1. 一句話
|
||
|
||
讓使用者能在每次話題海巡中取得足量且緊扣意圖的 Threads 貼文，依關聯分數穩定瀏覽，並能透過分頁管理歷史批次與批次結果。
|
||
|
||
## 2. 誰用、在什麼情境
|
||
|
||
| 角色 | 目標 |
|
||
|------|------|
|
||
| 品牌經營者／社群小編 | 輸入今天想參與的話題後，快速找到值得閱讀與自然回覆的近期貼文。 |
|
||
| 同一品牌的協作者 | 回到先前海巡批次，接續處理尚未完成的貼文，不漏看、不重複處理。 |
|
||
|
||
## 3. 背景與動機（As-is → 為什麼改）
|
||
|
||
- **現況問題：**「目標筆數」以搜尋到的原始候選計算，但候選經去重與關聯性篩選後可能大量減少，畫面最後得到的合格貼文低於預期。
|
||
- **現況問題：**畫面排序會優先採用分數與處理狀態，原文時間只在後面比較，因此使用者無法確定正在按貼文時間閱讀。
|
||
- **現況問題：**目前畫面顯示掃入系統的建立時間，沒有清楚呈現原貼文發佈時間；兩者容易被誤認為同一時間。
|
||
- **現況問題：**海巡批次由已載入的全部貼文在前端組合，批次本身沒有分頁；結果分頁也不是完整批次資料的穩定分頁，資料增加後容易變慢、跳頁或出現跨頁重複。
|
||
- **現況問題：**雖然已有主題核心詞與去重規則，使用者仍無法從結果理解「為何相關」，也無法知道不足目標時是來源不足、重複過多，還是關聯性不合格。
|
||
- **不改的後果：**使用者需要手動排除離題內容、核對新舊貼文及重複項目，對海巡結果失去信任；歷史批次增加後，操作成本與載入成本持續上升。
|
||
- **參考文件（非需求本體）：**`docs/product/demand-radar/spec.md`、`docs/product/haixun-console/spec.md`、`docs/product/haixun-backend/spec.md`。
|
||
|
||
## 4. 目標（To-be）
|
||
|
||
### 4.1 必須達成（P0）
|
||
|
||
1. **關聯性是入選門檻。** 每筆顯示結果都必須保留使用者話題的核心意圖，並提供可理解的命中理由；不得為湊足數量而混入只碰巧共享泛用詞的貼文。
|
||
2. **目標數以合格結果計算。** 系統應在去重與關聯性判定後計算已取得數量；尚未達標時，在有限且可控的範圍內繼續擴大候選，直到取得目標數或確認本次可用來源已耗盡。
|
||
3. **不足時誠實說明。** 無法取得目標數時，仍顯示所有合格結果，並清楚呈現目標數、實得數及不足原因；不得回傳空成功或用低關聯結果補齊。
|
||
4. **結果嚴格按關聯分數排序。** 在選定批次內，通過關聯性門檻後，以 score 由高到低為主要且固定的排序；貼文時間只作同分決勝。
|
||
5. **未知時間有明確規則。** 相同 score 時，無原文發佈時間的貼文排在已知時間之後，並以穩定規則維持順序，避免翻頁時漂移。
|
||
6. **明確顯示貼文時間。** 結果列與目前貼文明細都顯示「貼文時間」；若同時需要呈現掃入時間，必須標為「掃入時間」，不得互相代替。未知時顯示「貼文時間未知」。
|
||
7. **批次清單可分頁。** 海巡批次以最近執行的批次優先，提供總筆數、目前頁、每頁筆數與總頁數；批次增加後仍能瀏覽完整歷史。
|
||
8. **批次結果可獨立分頁。** 每個批次的貼文結果有自己的完整總數與分頁資訊；切換批次時結果回到第 1 頁，批次頁碼與結果頁碼互不干擾。
|
||
9. **分頁內容穩定且不重複。** 在同一次瀏覽期間跨頁前後移動，不應因相同時間、網址別名或背景資料更新而看到重複項目或無故漏項；排序相同時仍須有固定次序。
|
||
10. **統計反映完整批次。** 批次的總數、待處理數與完成狀態，必須以整個批次計算，不得只計算目前結果頁。
|
||
11. **新批次不打斷正在閱讀的歷史批次。** 新海巡完成後可被發現，但不應自動改變使用者目前選擇的批次或頁碼；使用者主動進入新批次時再從其第 1 頁開始。
|
||
12. **維持產品邊界。** 話題海巡持續服務自然參與話題，不自動發送回覆，也不取代 Radar 的需求商機流程。
|
||
|
||
### 4.2 應該有（P1）
|
||
|
||
1. 提供本批次摘要，至少能看出搜尋到的候選數、重複排除數、低關聯排除數、合格數與目標數。
|
||
2. 當合格結果不足時，提供使用者主動「繼續找」的入口，但仍沿用原主題意圖與相同關聯性門檻。
|
||
3. 提供使用者主動的時間範圍篩選，且篩選後仍維持 score 排序與完整分頁資訊；預設不以日期淘汰候選。
|
||
4. 刪除批次或處理最後一筆結果後，頁碼自動落在仍有效的最近頁，不出現只有空白內容的失效頁。
|
||
|
||
### 4.3 以後再說（P2）
|
||
|
||
1. 依使用者保留、略過與回覆行為學習個人化相關性。
|
||
2. 在資料可靠時加入互動量與話題升溫趨勢，但不取代 score 排序與關聯性門檻。
|
||
3. 提供跨批次的品質趨勢、來源覆蓋率與查詢建議分析。
|
||
|
||
## 5. 範圍
|
||
|
||
### In scope
|
||
|
||
- 話題海巡的候選擴展、合格數計算、關聯性入選與不足說明。
|
||
- 原貼文時間的資料語意、排序、顯示與未知時間處理。
|
||
- 海巡批次清單分頁、單一批次結果分頁、完整批次統計及頁碼互動。
|
||
- 跨來源、網址別名及跨頁結果的穩定去重。
|
||
- mock 與 live 模式對使用者呈現相同的排序、時間與分頁行為。
|
||
|
||
### Out of scope（明確不做）
|
||
|
||
- 改造 Radar 商機判定、CRM 狀態或其列表流程。
|
||
- 為湊數降低主題關聯性門檻、無限重試或無上限抓取。
|
||
- 自動發送回覆或代表使用者進行公開互動。
|
||
- 引進全新的第三種外部採集來源。
|
||
- 本次主動清除所有既有歷史重複資料；歷史資料在讀取時仍須避免重複呈現。
|
||
- 重新設計整個 Harbor Desk 導覽與視覺系統。
|
||
|
||
## 6. 使用者故事（可驗收）
|
||
|
||
| ID | 作為… | 我想要… | 以便… | 驗收要點 |
|
||
|----|--------|---------|--------|----------|
|
||
| US-01 | 品牌經營者 | 輸入明確話題後只看到緊扣核心意圖的貼文 | 不必逐則排除同字不同題的內容 | 可說明命中核心；離題候選不得為湊數入選。 |
|
||
| US-02 | 品牌經營者 | 設定希望取得的數量 | 在來源充足時拿到足量可用貼文 | 目標以去重、關聯篩選後的合格數計算；不足時顯示實得與原因。 |
|
||
| US-03 | 社群小編 | 按關聯分數從高看到低 | 優先處理最符合意圖的討論 | 同批次跨頁 score 持續為非遞增；時間只在同分時決勝。 |
|
||
| US-04 | 社群小編 | 在列表與明細看見清楚標示的貼文時間 | 判斷貼文是否仍值得互動 | 顯示原貼文時間；未知明示未知；掃入時間若出現則分開標示。 |
|
||
| US-05 | 協作者 | 分頁瀏覽全部海巡批次 | 回到較早的工作而不一次載入所有歷史 | 批次依最近執行優先，分頁資訊完整，跨頁不重複不漏項。 |
|
||
| US-06 | 協作者 | 在選定批次內分頁處理全部結果 | 可持續處理大量貼文 | 切換批次回到結果第 1 頁；結果總數與批次統計不受目前頁限制。 |
|
||
| US-07 | 正在處理舊批次的使用者 | 新掃描完成時保留目前位置 | 不被背景更新打斷 | 新批次可見但不自動切換；目前批次與頁碼保持不變。 |
|
||
|
||
## 7. 成功標準
|
||
|
||
- [x] 以至少 30 組涵蓋人物／作品、事件、產業與多詞意圖的人工標註題組驗收，前 10 筆結果平均至少 8 筆為直接相關，且不得用明顯離題結果補足目標數。（見 `TestTopicQualityGate`）
|
||
- [x] 在測試資料確實存在足量合格候選的題組中，至少 90% 的海巡能取得使用者設定的合格目標數；其餘批次均能顯示實得數與可理解的不足原因。（target rate 100%）
|
||
- [x] 單一批次從第 1 頁走到最後一頁時，score 皆維持由高到低；同分時間與 ID 穩定、不重複、不漏項。
|
||
- [x] 列表與明細中的每筆結果，100% 顯示原貼文時間或明確的「貼文時間未知」，不再把掃入時間標成貼文時間。
|
||
- [x] 批次清單與批次結果皆能從第 1 頁走到最後一頁，所見唯一項目數與宣告總數一致；前後翻頁不產生重複或遺漏。
|
||
- [x] 新批次完成、刪除批次及處理結果後，頁碼與選取狀態符合本文件規則，且不出現失效空白頁。
|
||
- [x] mock 與 live 模式通過同一組使用者層級驗收案例。
|
||
|
||
## 8. 約束與假設
|
||
|
||
- 技術 / 合規 / 時程約束：時間一律以 UTC 儲存，產品傳遞的時間值維持 unix nanoseconds；列表遵循 `page`／`pageSize` 與 `pagination`＋`list` 契約。
|
||
- 技術 / 合規 / 時程約束：前端 mock 與 live 共用相同 repository 介面；不得用只在單一模式成立的畫面邏輯掩蓋契約差異。
|
||
- 技術 / 合規 / 時程約束：使用者會員憑證與外部 AI／採集供應商憑證持續分離；本需求不擴張自動對外互動權限。
|
||
- 假設（未驗證當真）：外部來源可能沒有可靠的原貼文時間、可能暫時無結果，也可能回傳同一貼文的不同網址形式。
|
||
- 已決議：使用者要求所有年代候選都可入選，通過關聯性門檻後依 score 排序；時間只作同分決勝。
|
||
- 假設（未驗證當真）：既有可設定的海巡目標數繼續保留，而不是改為單一固定筆數。
|
||
|
||
## 9. 風險
|
||
|
||
| 風險 | 影響 | 緩解（需求層，非實作細節） |
|
||
|------|------|---------------------------|
|
||
| 高關聯門檻與足量目標互相衝突 | 某些窄題目無法達標 | 關聯性優先；允許有限擴展並揭露不足原因，禁止離題補量。 |
|
||
| 外部來源缺少或誤報貼文時間 | 最新排序失真 | 明確區分已知與未知時間；未知排後且不得以掃入時間冒充。 |
|
||
| 背景新增資料造成翻頁漂移 | 使用者跨頁時重複或漏看 | 同一次瀏覽需維持穩定次序；新批次不得自動切換目前位置。 |
|
||
| 歷史批次累積導致載入變慢 | 首頁與翻頁體感惡化 | 批次與結果都只取得目前需要的頁面，同時保留可信總數。 |
|
||
| 關聯性說明看似合理但結果仍離題 | 使用者錯信系統判定 | 以人工標註題組衡量直接相關比例，說明本身不取代結果驗收。 |
|
||
|
||
## 10. 開放問題
|
||
|
||
1. 已決議：完成、略過與已發佈貼文都保留在批次總數中，另列「待處理數」。
|
||
2. 已決議：歷史批次持續保留並可分頁瀏覽，直到使用者主動刪除，不另設自動隱藏期限。
|
||
|
||
## 11. 批准
|
||
|
||
- [x] 需求已批准（日期 / 誰）：2026-08-09／使用者
|