來源匯入規格

日期：2026-03-20 目的：定義發票、channel_master、群眾蒐集與既有分類系統，如何匯入 item master 的證據層。 相關文件：

• C03-schema.sql
• C04-migration.md
• C07-cat.md
• C12-dbx.md

1. 核心原則

1. 所有來源先保留原始樣貌，不直接覆蓋正式商品。
2. 匯入要以 append-first 為原則，保留來源與時間。
3. channel_master 與 crowd 都先進證據層，不直接長成 BI / SI。
4. 有時間語意的來源一定要帶 observed_at 或 valid_from / valid_to。
5. 分級上優先維護 mapping_tier；item_tier 在建立 BI / SI 後預設為 銅級，再逐步升級。

2. 來源對應總表

3. 發票資料匯入

目標表

• invoice_lines
• invoice_name_clusters
• cluster_members

欄位對應

匯入規則

1. invoice_lines 保留原始字串，不在此層硬做正規化映射。
2. invoice_name_clusters 預設以商家為範圍聚類；必要時再細化到店點。
3. ML 或既有系統可補 brand_hint、category_hint。

4. channel_master 匯入

目標表

• evidence_observations

不應做的事

1. 不可把每一列 channel_master 直接當成 SI。
2. 不可因單一通路資料就自動發新 BI / SI。

建議欄位對應

item_level_hint 是 evidence-level hint，不是最終 item_level 定案；若與其他證據衝突，應保留於證據層並交由 Silver / review 決定。

匯入時應補的風險旗標

• restricted_prefix
• isbn_prefix
• placeholder_barcode
• bundle_text
• carton_text
• name_conflict

如果無法判定，不要假設乾淨，請標成待審核風險。

5. crowd 資料匯入

目標表

• review_tasks
• review_answers
• evidence_observations

匯入規則

1. crowd 原始上傳不可直接改寫 item master。
2. 每筆 crowd 證據都應帶來源人、時間與上下文。
3. crowd 自由輸入若與 trusted evidence 強衝突，先進審核或隔離。

6. 既有品牌與分類系統匯入

這套系統的角色不是 BI / SI 真值來源，而是：

• brand_hint
• category_hint
• taxonomy prior

第一階段建議先接到：

• base_items.brand
• base_items.category
• invoice_name_clusters.brand_hint
• invoice_name_clusters.category_hint

7. 去重與可重跑原則

1. 每個來源都應有穩定的 source_record_id 或 fingerprint。
2. 發票可用 merchant_code + invoice_id + raw_pn + amount 當初始去重鍵。
3. channel_master 可用 source_channel + source_record_id + observed_at::date 當近似去重鍵。
4. crowd 可用 review_task_id + answered_by + answered_at::date 做去重參考。

8. 匯入後的分級策略

8.1 mapping_tier

在清整與匯入過程中，最值得先標的是 mapping_tier：

• 新生成候選：預設 銅級
• 兩種以上證據支持，或已有一次人工確認：可升 銀級
• 多證據一致、無高風險旗標，且已人工確認或長期穩定：升 金級

8.2 item_tier

item_tier 建議不要一開始就要求很細：

• 新建 BI / SI：預設 銅級
• 主欄位補齊且有基本證據支撐：升 銀級
• 衝突消化完成，可供下游穩定使用：升 金級

9. 時間欄位使用原則

• invoice_date：實際購買時間
• observed_at：證據被收集到的時間
• valid_from / valid_to：這筆證據或關聯被視為有效的時間區間

當條碼有歷史重用時，要用有效期間切開，而不是覆蓋舊關係。

10. 最小實作順序

1. 先做發票匯入。
2. 再做 channel_master -> evidence_observations。
3. 再接品牌與分類提示。
4. 最後接 crowd 證據。

11. 一句話收尾

所有來源都先進證據層，只有通過打分與審核的結果，才往上長成 BI / SI。