mini-taiwan-pulse: Skill for Claude Code

Layer Onboarding SOP

目的：把「從 taipei-gis-analytics 資料落地 → mini-taiwan-pulse 上線」變成無法漏項的流程。

何時觸發

• 「新 layer 要接」「PMTiles 好了要怎麼上」
• 「這 layer 點怎麼少了」「這 layer 為什麼有些點顯示不出來」
• 「透明度 / 半徑 / popup / 圖例 該怎麼設」
• 「上游改了欄位下游要動嗎」
• Review 一個剛完成的 layer 前

步驟總覽

Step 0  規劃 (feature 資料夾 + upstream handoff)
Step 1  資料完整性驗收 (count / attrs / 檔名契約)
Step 2  接線 (走 /new-layer 或手動：manifest 一筆 + spec 一筆 + 邏輯檔)
Step 3  UX baseline 套用 (radius / opacity / cluster / min-zoom)
Step 4  四鐵則自檢 (slider / legend / popup / dropdown)
Step 5  跨 repo 對齊 (handoff 反向引用 + commit hash)
Step 6  驗收 (tsc / test / browser All Off 單測)
Step 6a Agent 查詢關卡 (來源契約 / 有界 reader / 實問 / 可分析範圍)
Step 7  收尾 (changelog + backlog 標 ✅)

Step 0 — 規劃

• 選 slug：kebab-case，例如 air-quality-station
• 開 upstream handoff（若還沒）：taipei-gis-analytics/docs/handoff/<slug>.md
• 開 downstream feature 資料夾：cp -r docs/features/_TEMPLATE docs/features/<slug>
• 開 branch：git checkout -b feat/<slug>

Step 1 — 資料完整性驗收（⚠️ 最常漏的地方）

從 upstream 拿到產物後先驗數字對得上，不要急著接線。

PMTiles

# 檢查 tile 數 + zoom 範圍
tippecanoe-decode public/xxx.pmtiles | head -20

# 檢查 keep_attrs 是否帶到（隨機挑 tile）
tile-join --version && python3 -c "
import subprocess
# 從 PMTiles 抽 feature 屬性看 keep_attrs 齊不齊
"

常見漏項：

• keep_attrs 沒帶 → 前端 popup 空白 / 分色失效 → 回上游改 tippecanoe 參數重出
• 扁平檔名契約斷了 → nginx 找不到 → 檢查 public/ 命名（不要加子資料夾）

GeoJSON

# 點數
jq '.features | length' public/xxx.geojson
# 屬性 key 齊不齊
jq '.features[0].properties | keys' public/xxx.geojson

Supabase RPC

-- 直接跑 EXPLAIN ANALYZE
EXPLAIN (ANALYZE, BUFFERS) SELECT * FROM public.get_xxx(...);

若 > 1s 或 > 10k rows → 立刻套 pre-aggregate pattern（見 supabase-optimize skill）。

座標系統

|Response_X| > 1000 → 是 TWD97 TM2 → 要轉 WGS84。

Step 2 — 接線

優先走 /new-layer <slug> slash command（自動產骨架 + 跑 tsc / vitest）。

若手動，強制順序（CLAUDE.md §5 / development-rules §4）—— ⚠️ 2026-08-12（AR-22 Phase 4）起登記簿不再手寫：

1. src/types/index.ts → LayerVisibility 加 key（可點選再加 FeatureInfo["layerType"]）
2. src/data/layerManifest.ts → 一筆完整 entry。LAYER_COLORS / LAYER_ICONS / THEMES 的 LayerDef / LAYER_LABELS / UPSTREAM_REGISTRY 全部由它派生，不要手寫
   • ⚠️ legend / popup / params 寫 null = 豁免鐵則 2/3/1 → 必須同步 layerConsistency.test.ts 的對應 ledger 並寫理由，否則測試紅
3. src/components/sidebar/layerCatalog.ts → THEMES 對應子群加一行 fromManifest("key") （只放位置；SECTIONS / LAYER_LABELS 自動派生）
4. src/data/layerParamsSpec.ts → 一筆 key: [ opacitySlider("keyOpacity", 0.8), … ] （⚠️ 禁去 useLayerParamsRuntime.ts 加 useState / case / deps）
5. src/data/xxxLoader.ts → loader + loadingRegistry（⚠️ 禁靜默 rpc().then()）
6. src/hooks/useXxxLayer.ts → React hook（⚠️ 動態圖層禁 currentTime 進 deps）
7. src/map/overlayRegistry.ts 或 CustomLayer（sourceId 要與 manifest 的 source 逐字相同）
8. src/App.tsx → 接線
9. 預設開啟的層才需要碰 src/state/layerVisibilityStore.ts 的 DEFAULT_ON （現為空集合；key 全集自動派生）