獨立 Theme Registry 取代 My-TW-Coverage 題材職責評估

結論

建議建立獨立的 Theme Registry repo，逐步取代 My-TW-Coverage 的「題材定義與成員真值來源」職責；不建議直接移除整個 My-TW-Coverage。

目前 My-TW-Coverage 不只是題材頁，還是 Cortex 公司語料與供應鏈知識來源。 2026-07-26 的實際資料庫盤點顯示，它同時供應：

資料	現有筆數
公司 profile	1,733
公司關係	186,099
公司實體	11,793
Coverage embeddings	6,932
供應鏈規則	23,248
題材 membership（本次發布前）	7,063
題材 membership（2026-07-26 新快照發布後）	7,692

直接拔除 submodule 會同時切斷 RAG、公司關係圖、供應鏈規則與題材資料， 風險遠大於題材品質問題本身。正確切法是把「題材 registry」先拆出去， 保留 My-TW-Coverage 作為 coverage corpus，待其他職責也有替代來源後再評估退場。

三種方案比較

方案	優點	缺點	建議
直接移除 My-TW-Coverage，建立全新 repo 全面取代	邊界最乾淨	必須一次重建公司語料、關係圖、embedding、規則與題材；切換面過大	不採用
繼續以 Pilot_Reports wikilink 衍生題材	變更最少	敘事提及與正式 membership 混在一起；LLM 寫回後會自我強化污染	僅作短期過渡
建立獨立 Theme Registry，My-TW-Coverage 暫留 corpus	題材真值、審核、證據與版本可獨立治理；可漸進切換	過渡期有兩個 repo 與 shadow diff 成本	推薦

推薦責任邊界

Theme Registry repo

負責：

• 題材 canonical ID、顯示名稱、別名與狀態。
• 題材成員、供應鏈角色、相關性與實質性。
• 每筆 membership 的證據、時效、審核者與有效期間。
• schema validation、重複檢查、ticker 主檔檢查與發布 snapshot。
• 人工審核後的 LLM 候選發布。

不負責：

• 公司完整研究報告。
• 一般客戶／供應商關係圖。
• 公司語料 embedding。
• 個股財務與行情資料。

My-TW-Coverage

過渡期繼續負責：

• Pilot_Reports 公司研究語料。
• 公司 profile、entity 與 company relation 的 ETL 輸入。
• coverage RAG embeddings。
• 供應鏈規則候選。

不再負責：

• 由任意 wikilink 自動決定正式題材 membership。
• 接收已發布題材結果寫回公司報告。
• 保存正式題材的唯一真值。

推薦資料流

flowchart LR
    W["Web／公司公告／法說／政策資料"] --> G["Theme candidate generator"]
    G --> Q["候選區：pending"]
    Q --> R["人工／規則審核"]
    R --> V["Theme Registry canonical files"]
    V --> C["Schema、ticker、證據、重複與時效檢查"]
    C --> S["不可變 snapshot"]
    S --> D["coverage_theme_membership / relation"]
    D --> A["Themes API、recap、graph consumers"]

    P["My-TW-Coverage Pilot_Reports"] --> E["Coverage corpus ETL"]
    E --> K["profile / company graph / embeddings / rules"]
    K --> A

    K -. "只能提供候選線索，不能直接發布" .-> G

發布流程必須是單向的：

1. corpus、Web 或模型產生候選。
2. 候選進入 pending，預設不是 approved。
3. validator 與 reviewer 決定是否發布。
4. 只有 canonical registry snapshot 能寫入正式 theme tables。
5. 發布結果不再寫回 Pilot_Reports，避免下次生成重新讀到自己的輸出。

建議 Repo 結構

theme-registry/
├── schema/
│   ├── theme.schema.json
│   └── snapshot.schema.json
├── themes/
│   ├── ai-rack-liquid-cooling.yaml
│   ├── csp-custom-ai-asic.yaml
│   └── ...
├── candidates/
│   └── pending/
├── snapshots/
│   └── 2026-07-26.json
├── scripts/
│   ├── validate.py
│   ├── build_snapshot.py
│   └── diff_snapshot.py
└── tests/

Markdown 可作為人類閱讀輸出，但不應再是 canonical schema；因為 Markdown 很難可靠保存 confidence、materiality、evidence、有效期間與 reviewer 等欄位。

Canonical schema

Theme

欄位	說明
theme_id	永久、機器可讀 ID；顯示名稱變更時不改
display_name	前台名稱
aliases	正規化別名，不使用 名稱\|名稱 類字串
description	明確定義題材邊界
status	draft、active、archived
effective_from/to	題材有效期間
related_theme_ids	只接受 canonical ID

Membership

欄位	說明
ticker、company_name	需通過 stocks 主檔驗證
role	upstream、midstream、downstream、related
relevance_score	0–100
relevance_tier	core、related、edge
materiality	high、medium、low、unknown
commercial_stage	mass_production、shipping、sampling、planning
benefit_mechanism	公司如何受惠，不只寫關鍵字
evidence[]	URL、來源類型、發布日、摘錄摘要
review_status	pending、approved、rejected、needs_evidence
reviewed_by/at	人工審核軌跡
valid_from/to	成員有效期間

缺少必要證據的候選可以存在於 candidates/pending，但不能出現在 active snapshot。

必要品質閘門

發布 active snapshot 前必須全部通過：

1. review_status=approved；預設必須是 pending，不得預設核准。
2. ticker 存在且公司名稱與主檔一致。
3. 同一 (theme_id,ticker,valid_from) 不重複。
4. 至少一個可追溯證據；核心成員要求公司公告、法說、政府或交易對手來源。
5. 證據在設定期限內，歷史供應商不得自動當成現況核心。
6. 一般終端使用、App Store 上架、售後相容、概念可用性不能當成供應關係。
7. 題材定義和電子／光學同名詞需有不同 canonical ID。
8. snapshot diff 超過設定比例時要求第二位 reviewer。

遷移計畫

Phase 0：本次資料清理

• 以完整 845 筆稽核建立乾淨基準。
• 新增題材專用 DB sync，不再用全量 Coverage ETL 更新題材。
• 保留舊日期快照以便回復。

Phase 1：建立 registry repo 與 schema

• 將乾淨基準轉成第一個 immutable snapshot。
• 導入 validator、ticker 檢查、evidence 與 review 欄位。
• Cortex 仍讀現行 DB，不改 API contract。

Phase 2：Shadow read

• CI 同時解析 My-TW-Coverage 題材頁與 registry snapshot。
• 每次發布產生新增、移除、role、名稱與證據差異。
• 連續至少兩個發布週期達到零非預期差異。

Phase 3：Cutover

• coverage.theme_registry_path 指向新 repo。
• 題材專用同步只接受 validated snapshot。
• 停止 Pilot_Reports → theme membership 的自動發布。
• 保留上一個 registry snapshot 與 DB 舊日期快照作 rollback。

Phase 4：移除 My-TW-Coverage 的 themes 職責

• 刪除或封存 My-TW-Coverage themes/ 產物。
• 移除 publish 寫回 Pilot_Reports。
• 公司 corpus ETL 繼續運作。

Phase 5：重新評估整個 My-TW-Coverage 退場

只有以下條件全部成立，才考慮移除整個 submodule：

• 公司 profile 有新的受控來源。
• company relation/entity 有替代生成與驗證流程。
• coverage embeddings 已轉移到新的 versioned corpus。
• supply-chain rules 有獨立來源。
• 所有 RAG/API consumer 已切換並完成 shadow comparison。
• 已有可演練的 rollback snapshot。

Rollback

• Registry：把 active pointer 回切上一個 immutable snapshot。
• DB：API 依 MAX(knowledge_as_of) 取最新資料；必要時可移除失敗的新日期 snapshot，立即回到舊日期。
• API：不改現有 response shape，因此 registry cutover 不需要前端同步發布。
• My-TW-Coverage：直到 Phase 4 完成前保持可用，不做一次性不可逆刪除。

決策

採用「獨立 Theme Registry、保留 My-TW-Coverage corpus」方案。

本次 issue #1087 先完成乾淨題材基準與題材專用同步，作為未來 registry 的 第一個可遷移 snapshot；建立新 repo 與正式 cutover 應另開 issue 執行。