mini-taiwan-pulse: Command for Claude Code

/new-layer

為 Mini Taiwan Pulse 新增一個地圖圖層。

本 command 只負責產骨架。UX 決策 / 資料驗收 / 跨 repo 對齊 → 走 layer-onboarding skill（本 command 執行完會自動提示）。

⚠️ 2026-08-12（AR-22 Phase 4）改版：舊版的「7 步強制順序」裡有 5 個接觸點是 登記簿（LAYER_COLORS / LAYER_ICONS / THEMES 的 label / UPSTREAM_REGISTRY / useTransportParams 的 case），現在全部由 layerManifest.ts 與 layerParamsSpec.ts 兩筆宣告派生。新流程是 manifest 一筆 ＋ spec 一筆 ＋ 實質邏輯檔。

舊版還要求手動改 useLayerVisibility.ts 的 DEFAULT_ON —— 那張表的 key 全集已由 LAYER_COLORS 派生且現為空集合，預設關的層完全不用碰。

參數

• $1 (必填): layer key，camelCase，例如 busRoutes / floodZones
• --static / --dynamic (擇一)：
  • static = Mapbox overlayRegistry（GeoJSON / PMTiles，fill/line/circle）
  • dynamic = Custom WebGL layer 或 Three.js scene（時序動畫）
• --source=supabase|geojson|pmtiles：資料來源

Step 0 — 開跑前必做（⚠️ 不可跳）

跑本 command 前先確認：

1. Feature slug 已定（kebab-case，例如 flood-zones）
2. 開分支：git checkout -b feat/<slug>
3. 建 feature 資料夾：

   cp -r docs/features/_TEMPLATE docs/features/<slug>
   

4. 若涉新資料 / 資料契約：先開 upstream handoff

   cp taipei-gis-analytics/docs/handoff/_TEMPLATE.md \
      taipei-gis-analytics/docs/handoff/<slug>.md
   

Step 1 — 產骨架

使用 layer-creator subagent 處理樣板產生。委派時傳入：

1. Layer key（從 $1）
2. Layer 類型（static/dynamic）
3. 資料來源
4. 現有類似 layer 參考（若 static → earthquakes / disasterAlerts；若 dynamic → freewayCongestion / cwaImagery）

必產生 / 修改的檔案（新三步 ＋ 條件觸點）

① 型別入口

src/types/index.ts — LayerVisibility interface 加 $1: boolean。 若這層可點選 → 同檔 FeatureInfo["layerType"] union 也加一個 layerType。

🔒 tsc：下游多張 Record<keyof LayerVisibility, T> 會立刻 TS2739。

② manifest 一筆（取代舊版 5 個登記簿觸點）

src/data/layerManifest.ts — LAYER_MANIFEST 加一筆完整 entry：

$1: {
  key: "$1",
  section: { theme: "水資源 Water", group: "河川" },  // orphan 才寫 null
  label: "中文名 English",
  // labelMobile / expandable / gated 選填
  color: "#0284c7",
  icon: Waves,                       // lucide 元件參照，不是字串
  upstream: { status: "verified", datasets: [{ datasetId: "…", confidence: "HIGH" }] },
  dataClass: "A",                    // A 靜態 GeoJSON / B PMTiles / C Supabase / D 自行接線
  source: { kind: "geojson", sourceId: "$1-src", url: "./$1.geojson" },
  legend: null,                      // 分類 ≥ 2 色就要填圖例 id（鐵則 2）
  popup: null,                       // 可點選就填 FeatureInfo 的 layerType（鐵則 3）
  params: { count: 1, kinds: ["slider"] },   // 沒有控件寫 null（鐵則 1）
  description: "一句話說明這層在講什麼",
  topics: ["水資源", "河川"],
},