global-store-maps

多市場門市的問題與評價，做成可用的地圖圖層。 A small ETL pipeline that turns multi-market store data (locations + customer reviews + operational issues) into a Google My Maps friendly KML — each store a pin, coloured by its top issue category, with a bilingual popup.

Data note / 資料聲明：本 repo 附的 data/sample_stores/ 為合成示範資料 （虛構品牌 BubbleWave），不含任何真實企業的評論或門市。管線本身與資料題材 無關，可套用於任何「多來源、多市場地點資料」。

Architecture

flowchart TD
    subgraph sources["來源 (per market)"]
        TW["taiwan.md"]
        JP["japan.md"]
        MY["malaysia.md"]
        NA["north_america.md"]
    end

    OV[["geocode overrides<br/>(pid,lat,lng)"]]

    subgraph core["src/ 管線"]
        P["parse_md<br/>讀表頭欄名"]
        G{"有座標?"}
        MISS["needs-geocode 報告<br/>(不放 0,0)"]
        KML["md_to_kml<br/>依問題類別分色<br/>雙語 popup"]
        AGG["aggregate_patterns<br/>匿名彙整<br/>(去店名/去原始評論)"]
    end

    subgraph out["產出"]
        MAP["*.kml → Google My Maps"]
        REP["cross_market_patterns.md<br/>各市場模式統計"]
    end

    TW & JP & MY & NA --> P
    OV -. 人工修正 .-> P
    P --> G
    G -- 否 --> MISS
    G -- 是 --> KML --> MAP
    P --> AGG --> REP

    classDef safe fill:#e8f5e9,stroke:#2e7d32;
    class AGG,REP safe;

Loading

兩條輸出線：地圖線（門市 pin，依問題類別分色）與匿名彙整線（跨市場模式統計， 安全可公開，綠色標示）。

Sample output

台灣市場的門市圖層，pin 依首要問題類別分色（合成示範資料）：

圖例：🔴 s = 服務態度・🔵 q = 品質一致性・🟢 p = 包裝・🔷 w = 等候時間・🟣 e = 價格。 座標留空的門市（如新竹）不會出現在圖上，改列入 needs-geocode 報告。

Design ideas carried over from a larger world-scale geo dataset I built (7 continents / ~200 markets, multi-source scrape → dedup → geocode → KML):

• Dual anchor key — a spatial track (coordinates, for machines) crossed with a semantic track (multilingual names, for humans); the two never contaminate each other.
• Header-name parsing — the table is read by column name, so schemas can add/drop trailing optional fields without breaking the exporter.
• Fail-loud geocoding — a store with no coordinates is never placed at 0,0; it is skipped and listed in a needs-geocode report.
• Human override lane — pid,lat,lng CSV lets a human correct any machine geocode without editing source data.

Usage

# 1) per-market map layer (import the .kml into Google My Maps)
python3 src/md_to_kml.py data/sample_stores/taiwan.md
python3 src/md_to_kml.py data/sample_stores/japan.md
python3 src/md_to_kml.py data/sample_stores/malaysia.md
python3 src/md_to_kml.py data/sample_stores/north_america.md

# 2) cross-market pattern report — anonymised (no store names, no raw reviews)
python3 src/aggregate_patterns.py data/sample_stores/*.md \
    --out docs/cross_market_patterns.md

python3 -m pytest -q          # run the tests

Publishing review analysis safely

Raw customer reviews are third-party content and often name-identifiable, so they are never published here. src/aggregate_patterns.py is the safe presentation layer: it drops store names and verbatim review text and keeps only pattern statistics (per-market issue-category counts, average rating, low-star ratio). A repeating issue across markets then reads as a systemic cause rather than a single-store one — see docs/cross_market_patterns.md.

Layout

Path	Role
src/md_to_kml.py	store Markdown table → KML (bilingual popup, colour-by-issue)
src/geocode_overrides.py	apply human coordinate corrections (pid,lat,lng)
src/aggregate_patterns.py	anonymised cross-market pattern report (no names/raw reviews)
data/sample_stores/	synthetic per-market store tables — 台灣 / 日本 / 馬來西亞 / 北美 (demo only)
docs/cross_market_patterns.md	generated anonymised cross-market summary
openspec/specs/	data schema + KML spec
docs/engineering-notes.md	how the world-scale pipeline maps onto this store use case
tests/	pytest for the parser / exporter

Issue categories → pin colour

服務態度・品質一致性・包裝・等候時間・價格・其他 each map to a stable My Maps style id (pin shape/colour is driven by style id, not icon href).

License

MIT — see LICENSE.