thread-master/docs/product/scout-topic-quality/requirements.md

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. 成功標準

• 以至少 30 組涵蓋人物／作品、事件、產業與多詞意圖的人工標註題組驗收，前 10 筆結果平均至少 8 筆為直接相關，且不得用明顯離題結果補足目標數。（見 TestTopicQualityGate）
• 在測試資料確實存在足量合格候選的題組中，至少 90% 的海巡能取得使用者設定的合格目標數；其餘批次均能顯示實得數與可理解的不足原因。（target rate 100%）
• 單一批次從第 1 頁走到最後一頁時，score 皆維持由高到低；同分時間與 ID 穩定、不重複、不漏項。
• 列表與明細中的每筆結果，100% 顯示原貼文時間或明確的「貼文時間未知」，不再把掃入時間標成貼文時間。
• 批次清單與批次結果皆能從第 1 頁走到最後一頁，所見唯一項目數與宣告總數一致；前後翻頁不產生重複或遺漏。
• 新批次完成、刪除批次及處理結果後，頁碼與選取狀態符合本文件規則，且不出現失效空白頁。
• mock 與 live 模式通過同一組使用者層級驗收案例。

8. 約束與假設

• 技術 / 合規 / 時程約束：時間一律以 UTC 儲存，產品傳遞的時間值維持 unix nanoseconds；列表遵循 page／pageSize 與 pagination＋list 契約。
• 技術 / 合規 / 時程約束：前端 mock 與 live 共用相同 repository 介面；不得用只在單一模式成立的畫面邏輯掩蓋契約差異。
• 技術 / 合規 / 時程約束：使用者會員憑證與外部 AI／採集供應商憑證持續分離；本需求不擴張自動對外互動權限。
• 假設（未驗證當真）：外部來源可能沒有可靠的原貼文時間、可能暫時無結果，也可能回傳同一貼文的不同網址形式。
• 已決議：使用者要求所有年代候選都可入選，通過關聯性門檻後依 score 排序；時間只作同分決勝。
• 假設（未驗證當真）：既有可設定的海巡目標數繼續保留，而不是改為單一固定筆數。

9. 風險

風險	影響	緩解（需求層，非實作細節）
高關聯門檻與足量目標互相衝突	某些窄題目無法達標	關聯性優先；允許有限擴展並揭露不足原因，禁止離題補量。
外部來源缺少或誤報貼文時間	最新排序失真	明確區分已知與未知時間；未知排後且不得以掃入時間冒充。
背景新增資料造成翻頁漂移	使用者跨頁時重複或漏看	同一次瀏覽需維持穩定次序；新批次不得自動切換目前位置。
歷史批次累積導致載入變慢	首頁與翻頁體感惡化	批次與結果都只取得目前需要的頁面，同時保留可信總數。
關聯性說明看似合理但結果仍離題	使用者錯信系統判定	以人工標註題組衡量直接相關比例，說明本身不取代結果驗收。

10. 開放問題

1. 已決議：完成、略過與已發佈貼文都保留在批次總數中，另列「待處理數」。
2. 已決議：歷史批次持續保留並可分頁瀏覽，直到使用者主動刪除，不另設自動隱藏期限。

11. 批准

• 需求已批准（日期 / 誰）：2026-08-09／使用者