Item Master — Channel Master 商品主檔

現況與目標架構

目前 repo 內可直接看到的現況

crawlers/ 與 build/build_channel_master.py
output/channel_master.json、output/channel_master.csv
目前可直接執行與驗證的主流程，核心仍是 channel_master 候選池 / 證據池建置

文件定義的目標架構

invoice_name_cluster -> SI -> BI
多來源證據層、候選生成、人工審核、Gold publish、Serving gate
這些目標架構主要定義在 docs/C02-spec.md、docs/C12-dbx.md、docs/C16-architecture.md

閱讀提醒

channel_master 不是最終主檔，而是候選池與證據池。
README.md 的 build 流程主要描述現況。
docs/ 裡的 BI / SI、Bronze / Silver / Gold、Serving Gate 主要描述目標設計與落地方向。

快速入門

# 重建 channel_master（需先確認 crawlers/ 各通路 data/products.json 已就緒）
cd build/
python3 build_channel_master.py      # 產出至 ../output/

# 輸出位置（從 repo root 看）
ls ../output/channel_master.json     # 2.7GB, 2,490,077 筆
ls ../output/channel_master.csv      # 1.4GB

# 條碼驗證審計（問題條碼清單，非衝突報告）
python3 barcode_utils.py ../output/channel_master.json --export-problems ../output/barcode_problems.json

目錄結構

item-master-research/
├── README.md               # 本檔案
├── CONTEXT.md              # 問題定義、目標品類/通路、核心發現
├── DECISIONS.md            # 資料源分級（5 Tiers）、技術決策記錄
│
├── docs/                   # 設計文件（Single source of truth）
│   ├── 00-README.md        # 文件索引與建議閱讀順序
│   ├── C01-eli5.md         # 白話說明
│   ├── C02-spec.md         # 正式規格（核心）
│   ├── C03-schema.sql      # 資料表骨架
│   ├── C05-review.md       # 審核、打分與分級
│   ├── C06-id.md           # BI/SI 識別碼規則
│   ├── C07-cat.md          # 分類與品牌整合
│   ├── C09-import.md       # 來源匯入規格
│   ├── C10-cases.md        # 判例手冊
│   ├── C12-dbx.md          # Databricks 架構與 job
│   ├── C15-onepage.md      # 高層一頁版
│   ├── C16-architecture.md # 架構圖（一般人 / 老闆 / 工程 / 治理 / 環境）
│   ├── R01-barcode.md      # 條碼驗證參考
│   ├── R02-terms.md        # 名詞表
│   └── Q01/Q02             # 品質檢核
│
├── client-facing/          # 客戶版文件（不暴露 crawler / source inventory）
│   ├── README.md           # 對外文件索引
│   ├── 01-onepage.md       # 對外一頁式定位與話術
│   ├── 02-data-model.md    # 對外最小資料模型
│   └── 03-workflow-and-deliverables.md
│                           # 對外流程、交付與 KPI
│
├── build/                  # 建置腳本
│   ├── build_channel_master.py   # 主建置腳本（讀取 crawlers/ → 產生 output/）
│   └── barcode_utils.py          # 共用條碼驗證模組
│
├── output/                 # 建置產物（不進版控）
│   ├── channel_master.json       # 主輸出：2,490,077 筆
│   ├── channel_master.csv        # CSV 版
│   └── barcode_conflicts.json    # 同 barcode 多品名衝突清單（ad-hoc 分析產出，非 build 自動產物）
│
├── crawlers/               # 通路爬蟲（66 通路）
│   ├── CHANNELS.md         # 通路狀態總表（Single source of truth）
│   └── {channel}/          # 每個通路一個目錄
│       ├── crawler.py      #   爬蟲腳本
│       └── data/           #   爬取結果
│           └── products.json
│
└── archive/                # 歷史資料（不影響運作）
    ├── phase1/             # Phase 1 legacy 腳本（reference-only，不可獨立執行）
    ├── phase1-data-raw/    # Phase 1 FDA/開放資料（617MB）
    ├── phase1-raw/         # Phase 1 研究員原始輸出
    ├── analysis/           # barcode 分析報告
    ├── tools/              # POC 工具
    └── stubs/              # 未完成的爬蟲 stub

核心數據（2026-03-25）

指標	數值	佔比
紀錄總數	2,490,077	100%
有國際條碼（GTIN）	440,414	18%
471 台灣碼	93,331	4%
不重複條碼（L3）	361,222	—
471 不重複	65,026	—
跨 2+ 通路條碼	61,558	—
有圖片	2,239,234	90%
有價格	2,467,469	99%
有品牌	1,546,368	62%
通路數	66（已完成 64 / 進行中 5 / 暫停 1 / 待開發 14 / 不可行 7）
FMCG 通路合計	462,289 筆、199,472 valid GTIN (43.1%)

詳細三層統計（L1/L2/L3）、FMCG 排行、爬蟲狀態見 crawlers/CHANNELS.md。

建置流程

crawlers/{channel}/crawler.py
        ↓ 各通路獨立爬取
crawlers/{channel}/data/products.json
        ↓ build_channel_master.py 統一讀取
output/channel_master.json

build_channel_master.py 做的事

讀取每個通路的 data/products.json
欄位正規化：NFKC 全形→半形、價格區間取最低、barcode 驗證
動態 confidence 計算（base + barcode/brand/price/image bonus）
ISBN / store-internal barcode 自動標記
Best-record dedup（同 (product_name, barcode, source_channel) 取 confidence 最高）
輸出 JSON + CSV

barcode_utils.py 驗證層次

長度檢查（8/12/13/14 位）
Blacklist 過濾（全 0 placeholder）
GS1 check digit 驗算
GS1 prefix 有效性
Timestamp 偽碼偵測
ISBN / store-internal 分類標記

新增通路 SOP

在 crawlers/ 建立新目錄 {channel}/
寫 crawler.py，輸出 data/products.json
JSON 格式：[{"product_name": "", "brand": "", "barcode": "", "price": "", "image_url": "", "source_url": "", "category": "", "spec": ""}]
在 build/build_channel_master.py 加入 ingest_{channel}() 函式
執行 python3 build_channel_master.py 重建
更新 crawlers/CHANNELS.md 狀態表

依角色閱讀

第一次接觸這個專案

docs/C16-architecture.md — 先看整體架構與不同版本入口
docs/C15-onepage.md — 看價值與核心故事
docs/C01-eli5.md — 看白話概念
docs/R02-terms.md — 對齊 BI / SI、學名 / 俗名 / alias
docs/C02-spec.md — 再進正式規格

管理層 / 產品 / RD

docs/C16-architecture.md
docs/C15-onepage.md
docs/C02-spec.md
docs/C04-migration.md

工程 / 數據 / 架構

docs/C16-architecture.md
docs/C02-spec.md
docs/C03-schema.sql
docs/C05-review.md
docs/C09-import.md
docs/C12-dbx.md
docs/C06-id.md

爬蟲 / channel_master 現況

README.md
crawlers/CHANNELS.md
build/build_channel_master.py
build/barcode_utils.py
DECISIONS.md

Item Master — Channel Master 商品主檔

現況與目標架構

目前 repo 內可直接看到的現況

文件定義的目標架構

閱讀提醒

快速入門

目錄結構

核心數據（2026-03-25）

建置流程

build_channel_master.py 做的事

barcode_utils.py 驗證層次

新增通路 SOP

依角色閱讀

第一次接觸這個專案

管理層 / 產品 / RD

工程 / 數據 / 架構

爬蟲 / channel_master 現況

相關知識