agentleFS
ianlkl11234sianlkl11234s/mini-taiwan-pulse/.claude/skills/layer-onboarding/SKILL.md

layer-onboarding

Skill547 starsChanged 9 days agoMITView on GitHub

從資料落地到 Layer 上線的完整驗收 SOP + UX baseline 表。當用戶說「新資料要接圖層」「PMTiles 好了怎麼上」「這個 layer 為什麼點少了」「這個 layer 的透明度/大小/popup 該怎麼設」「新 layer 該檢查什麼」「上游資料改了下游要跟嗎」「跨 repo 交接資料」時觸發。用來守門「常漏點 / 常漏 UX 設定 / 跨 repo 契約沒對齊」三大痛點。與 `/new-layer` command(產骨架)互補 — 本 skill 專注**驗收 + UX 決策 + 跨 repo 對齊**。

The file

Files
SKILL.md

Layer Onboarding SOP

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

與一條龍流程的分工:使用者只給方向(「做 X 國第 N 波」)時,入口是 analytics 的 pulse-layer-release skill(盤點→資料→前端→登記→大檔→合併 develop→驗收包,DoD 在其 references/definition-of-done.md);本 skill 是其中的前端接線與 UX 驗收段。授權判定與新網站部署規則看該 skill 的 references/license-and-deploy.md,平行 worker 規則看 references/parallel-brief-template.md,這裡不重抄。

何時觸發

  • 「新 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>
  • 開 worktree 與 branch(不碰主 checkout):git worktree add -b feat/<slug> .worktrees/<slug> origin/develop,進去 npm ci;需要的 gitignored 大檔從主 checkout ln -f hardlink
  • 先判斷放哪個儲存(ADR-0026 §5.1,正本 GIS .gis-agent-system/decisions/0026-pulse-architecture-and-data-placement.md):資料不會變或只會整批替換(選舉、選區、普查、季/年更)→ PMTiles/GeoJSON 走 S3 deploy-assets → R2,不進 Supabase、不寫 RPC;要伺服器端依時間/範圍篩選的即時資料才進 Supabase,且新表要同時登記保留期限(≤ 180 天)與 S3 正本路徑
  • 檔案放哪:國外圖層一律 public/world/<cc>_*.pmtiles(既有家族,免改 deploy/cloudflare/site_manifest.py、nginx.conf、scripts/deploy/pull-deploy-assets.sh)。資料檔一律不進 git(不論大小,CI-4):放本機 public/ 後跑 python3 scripts/deploy/build-public-assets-lock.py add <路徑> 登記 lock,再由 scripts/deploy/upload-deploy-assets.sh 上傳 S3 deploy-assets,發版時同步到 R2;commit 進 public/ 會被 deployContract 的 ratchet 擋下
  • 授權限內部使用的資料:不放 public/;不會變或整批替換的站主資料放私有 S3 private-research/owner-data/<sha256>/<檔名>,經 pulse-host coral-private sidecar 的 owner-data 家族提供(src/lib/ownerData.ts fetchOwnerJson、白名單 server/coral-private/owner-data-assets.mjs,計畫 .gis-agent-system/projects/2026-10-zeabur-migration/owner-only-storage-plan.md);只有需伺服器端依時間查詢的即時資料才留 Supabase owner-only RPC(docs/features/owner-gated-layers/);只加 GATED_LAYERS 而檔案公開=散布

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)。

DB 效能驗收(鐵則 R1/R2,正本 docs/supabase-optimization.md §0;缺一不可上線):

  • 量 RPC 冷快取耗時:/check-rpc <name> 用最大參數(最長時間窗、整天)跑,換一個最近沒人查過的日期再跑一次,取有 shared read 的那次 Execution Time:目標 <300 ms,>1 s 不上線。數字與 shared read blocks 寫進 PR 描述。
  • 確認預算表讀者:RPC 讀的預算表(*_daily/_hourly/_agg…)在 gis-platform 建表 migration 有 -- reader: <這支 RPC>(<layer key>),而且 RPC 本體真的讀這張表、不是自己從原始表重算(反例:get_youbike_h3_snapshots 旁邊有 youbike_h3_daily 卻沒接上,12 秒)。
  • 白天的 refresh 排程呼叫 _incremental,整天全量只在夜間 yesterday(R3;gis-platform CI 會擋)。

座標系統

|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 全集自動派生)

Step 3 — UX Baseline 表(照類型套,不用猜)

點層 POI

資料密度radius (zoom 6)radius (zoom 12)opacity 預設cluster?
< 1k4px8px0.9否
1k ~ 10k3px6px0.85否
10k ~ 100k2px5px0.75可選(zoom < 10 開)
> 100k1.5px4px0.6必開 cluster + 低 zoom -r 抽稀

線層

類型width (zoom 6)width (zoom 14)opacity
主要路網1px3px0.9
次要路網0.5px2px0.7
軌跡 / 流向2px4px0.85

Polygon / 覆蓋

類型fill-opacityoutline width
熱區 / 密度圖0.550
行政區0.150.5px
覆蓋範圍(等時圈類)0.351px

Raster / 影像

  • 預設 opacity 0.7(可蓋底圖)
  • Slider 範圍 0.3 ~ 1.0

3D / CustomLayer

  • 先跑 three-3d-component skill 看元件庫
  • 確認 dispose / blending / 動態時間源

所有 layer 都必提供 opacity slider(見四鐵則 #1)。

Step 4 — 圖層 UX 四鐵則自檢

#鐵則檢查
1透明度 slidersrc/data/layerParamsSpec.ts 該層規格有 opacity control?(舊 useTransportParams.ts 已退役)
2分類 ≥ 2 種必寫圖例LEGEND_REGISTRY 有加?src/components/legend/<domain>Legends.tsx sub-component 有寫?
3可選取物件必接 click popupuseMapInteraction.ts + featureInfo/registry.tsx 有加?
4Select options ≥ 4 用原生 <select>ctrl.options.length > 3 自動切 dropdown?

layerConsistency test 會擋 #2,但 #1/#3/#4 靠自檢。

全國視角可見性(map-layers §3.8):新圖層照 V-1~V-7 檢查——國家全覽縮放(台 z7/日 z5/英 z5.5/韓 z6)看得到點或熱區、layer minzoom 不比圖磚晚超過 1 級、分類圖例 ≥2 類要有類別篩選、面圖層有點/面切換(區劃面除外);熱區色不用寫,預設依主題(同主題撞色時在 heatmapPaletteDefaults.ts 覆寫表錯開)。visibilityContract.test.ts(V-2/V-4 ratchet)與 layerPalette.test.ts 會擋。

Step 5 — 跨 repo 對齊

必動的四份檔:

  1. taipei-gis-analytics/docs/handoff/<slug>.md — 資料契約 SSOT(upstream)
  2. mini-taiwan-pulse/docs/features/<slug>/handoff.md — 反向引用 + 硬依賴欄位表
  3. mini-taiwan-pulse/docs/features/<slug>/changelog.md — 本次 PR 記
  4. mini-taiwan-pulse/.claude/memory/BACKLOG.md — 對應列移到「已關閉」附證據

若動到資料契約 → 開 ADR:taipei-gis-analytics/docs/adr/NNNN-<title>.md。

Step 6 — 驗收

# TypeScript 驗證(禁 --noEmit)
npx tsc -b

# 全站測試(含 layerConsistency 擋漏圖例)
npm test

# Browser:按「All Off」→ 只開新 layer → 邊界 zoom / timeline 都測
npm run dev

給使用者驗收的本機站:worktree 停在最新 origin/develop,npx vite --strictPort --host 127.0.0.1 --port <空 port>(不歸 gis-up 管,只殺自己的 PID,禁 pkill -f vite)。每層截國家全覽縮放+放大各一張;agent-browser 參數與不 curl vite 模組等坑見 analytics pulse-layer-release/references/pitfalls.md 2026-11-06 段。

常見驗收失敗:

  • TS2739 → LayerVisibility 加了 key 但 layerManifest.ts 沒補 entry
  • layerConsistency「沒有 manifest entry」→ 同上(別塞 HANDWRITTEN_LAYER_COLORS 繞過)
  • layerConsistency「宣告了『沒有 X』但沒登記進 ledger」→ manifest 寫了 null, 去該測試檔的 NO_LEGEND_LEDGER / NO_POPUP_LEDGER / NO_PARAMS_LEDGER 補一行 + 理由
  • layerManifest「legend 宣告了但 LEGEND_REGISTRY 沒覆蓋」→ LegendPanel 沒加
  • Browser 打不出 popup → useMapInteraction 的 GIS_LAYERS 沒 register

Step 6a — Agent 查詢關卡

登記是每個新圖層的必經步驟(2026-11-06 使用者拍板):manifest 每個 upstream.datasets[].datasetId 都要在 pulse-data 有 registry/<datasetId>.yaml,consumers.pulse_layers 列出這個 layer key;資料換版或新增使用圖層時改既有條目。圖層 PR 合進 develop 後,在 pulse-data 跑 python3 scripts/check_layer_coverage.py --from-checkout <mini checkout> 要 exit 0(不該登記的寫進 registry/_no_upstream.yaml 附理由)。只登記、沒有 warehouse 區塊時,Agent 還查不到;要可查再走下面的入倉流程。

入倉守門(AG-13,2026-11-09):圖層上線即入倉;做不到就標 DISPLAY_ONLY 並寫解鎖條件。 驗收清單:

  • 至少一個 upstream.datasets[].datasetId 的登記條目有 warehouse 區塊(統計層:dataset 進了 stats_observations,即 _indicator_semantics.yaml 有它)。登記仍是每個 datasetId 都要(見上段);入倉則是多資料集圖層任一 dataset 入倉即算可分析——與 scripts/research/layer-warehouse-status.mjs、pulse-data check_layer_coverage.py 現行判定一致(2026-11-10 使用者決定)
  • 做不到入倉、且確實只做展示(純視覺特效、連續 raster 等)→ 加進 pulse-data registry/_display_only.yaml,reason(為什麼不能入倉)與 unlock(滿足什麼就入倉)缺一不可;即時、授權待清、還沒排到的層不算展示專用
  • registry/_warehouse_baseline.yaml 是既有未入倉層的基準,只減不增:新層不可加進去;某層入倉後要刪該行
  • PULSE_DATA_ROOT=<pulse-data> npx vitest run src/data/__tests__/layerRegistryCoverage.test.ts 綠(AG-13 case);pulse-data python3 scripts/check_layer_coverage.py --from-checkout <mini> 的 (d)(e) 為 0

新圖層:L2 可分析=在 pulse-data registry 有 warehouse 區塊,且已組裝上線(ADR-0023;不再靠掃描 analytics 自動入倉)。入倉流程:analytics 備好 _manifest.json → publish_package.py 發包(點線面 --dataset、統計 --stats-cdn、別名 --aliases)→ pulse-data PR 合併 → assemble_store.py 組裝 → warehouse:upload(保留 3 版);驗收要在新的 stdio process 下 pulse_find_data 找得到、pulse_sql 查得到。步驟與指令見 ARCHITECTURE.md §5c、MCP warehouse/README.md「新資料入口」。分級定義見 PLAN-warehouse-20260926。上線仍留 Q0–Q6 收據:先核來源、授權、版次、筆數/缺值與 geometry,再接 DatasetDescriptor 和有界 reader,以新地點、問題變體、原表獨立 oracle 及正常 MCP 實問。需要地圖的結果再驗 ready/readback/目視。預設至少 Q0–Q3 通過才稱「Agent 可查」;僅有 PMTiles/地圖展示不得當作查詢已通。對已接受來源,驗的是系統忠實查詢原座標;來源點是否等於真實現場的限制要說明,但不反覆重審既有資料品質。來源本質不能查或授權不明時標具體 DISPLAY_ONLY/HOLD,記解鎖條件,不編造分析能力。

Step 7 — 收尾

  • 根目錄 CHANGELOG.md 條目只加在 ## [Unreleased](沒有對應小節就自己新增)
  • PR --base develop,gh pr merge --merge(禁 squash);合併後看 develop CI;不發版到 master(發版須使用者拍板)
  • 更新 docs/features/<slug>/changelog.md(PR # + merge commit hash)
  • 在 .claude/memory/BACKLOG.md 關閉對應列(移到「已關閉」附證據)
  • 更新 .claude/memory/STATUS.md 加最新段落
  • 若踩到新坑 → 寫 .claude/pitfalls/YYYY-MM-DD-<slug>.md
  • 若學到 P0 規則 → 補進 .claude/memory/PRINCIPLES.md

常漏點快速索引

看 .claude/pitfalls/2026-07-01-layer-integration-common-misses.md。

Related

  • Command:/new-layer — 產骨架
  • Skill:supabase-optimize — RPC 效能;DB 效能鐵則 R1–R4 → docs/supabase-optimization.md §0
  • Skill:three-3d-component — 3D layer
  • Skill:gis-data-onboard(在 taipei-gis-analytics)— 資料落地路由
  • Rules:CLAUDE.md §5 §5a + docs/development-rules.md

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.