CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

專案概觀

這是一個純前端的靜態網頁，用 Leaflet 在台灣地圖上顯示寶可夢（Pokémon GO）出沒點資料。沒有建置系統、沒有套件管理、沒有測試。遠端 repo：http://192.168.42.124:31337/timmy/pokemon（Gitea，公開）。

整個專案只有三個真正的組件：

index.html：主畫面。fetch spots.json 後，為每筆資料在地圖上建立帶圖示的 marker 與 popup。
spots.json：資料來源。頂層是 { "items": [...] }，也相容頂層直接是陣列（toList() 會處理兩種）。
img/<id>.png：寶可夢圖鑑編號對應的圖示（已備齊 1–1000）。

常用指令

沒有 build / lint / test。直接開啟本機伺服器即可：

# 在專案根目錄起 server，直接訪問 http://localhost:8000/ 即可
python3 -m http.server 8000

圖示 URL 使用相對路徑 img/${item.id}.png（index.html:139），本地與生產都能運作。生產部署在 https://<host>/pokemon/ 下，Caddy 把 /opt/caddy/www/pokemon 作為該路徑的 root。

批次下載寶可夢圖示

./download_poke_imgs.sh [START] [END]           # 預設 1..1000
CONCURRENCY=16 ./download_poke_imgs.sh 1 1025   # 自訂並行數

會從 https://twpkinfo.com/images/poke1/<id>.png 下載到 img/，已存在則跳過，用 .part 暫存避免半成品。

資料結構與相容性注意事項

spots.json 的每筆 item 欄位命名可能混用兩種來源，index.html 的 buildPopup() 與 marker 建立邏輯都必須容錯：

座標欄位有三組別名：latitude/longitude、Latitude_Adjusted/Longitude_Adjusted、Latitude_Raw/Longitude_Raw。程式碼用 ?? 鏈依序 fallback（index.html:81-82、index.html:134-135）。新增欄位讀取時請沿用同一套 fallback 模式，不要只讀單一命名。
數值欄位（iv_pct、iv_atk、iv_def、iv_sta、cp、level）一律用 isNum() 驗證後才顯示，否則顯示 —。缺欄位不視為錯誤。
is_perfect 也可用 iv_pct === 100 推導（index.html:93）。
剩餘秒數用 liveRemaining() 動態算（index.html:59-64）：以 expire_time（unix 秒）扣 Date.now()/1000，避免直接用 JSON 內寫死的 remaining。popup 透過 bindPopup(() => buildPopup(item))（index.html:147）延後到開啟時才建，確保每次開都是最新值。

地圖同時支援 hover / click 固定 / 外部點擊取消，三者共用一個 module-scope 的 pinnedPopup 來協調：

hover：開 popup + marker 放大 class hovered；離開時若不是目前被固定的，就關閉。
click marker：若目前有其他 pinned popup 先關掉它、移除其放大樣式，再固定新的。
click 地圖空白處：關閉 pinned popup。

修改互動行為時要同步更新這三個 handler，否則容易出現「popup 關不掉」或「圖示放大沒復原」的狀態不一致。

載入錯誤提示

showLoadError(msg)（index.html:113-122）會在地圖右上角顯示紅框 Leaflet control。三種情境會觸發：HTTP 非 2xx、JSON 解析失敗、有效座標為零。修改 fetch 流程時請維持這層使用者可見的回饋，不要退回只剩 console.error。

部署

生產機在 192.168.42.104，Caddy 服務根目錄為 /opt/caddy/www/pokemon。一律透過 Gitea 推送，不再用 scp：

git add -u            # 或指定檔案
git commit -m "..."
git -c http.extraheader="Authorization: token <TOKEN>" push

生產機由其他流程（cron 或 webhook）從 Gitea 同步到 Caddy root。本機禁用 scp 直接覆蓋生產檔，避免跟 git 狀態分叉。

（資料檔 spots.json 由其他流程寫入生產機，不要在本地修改後推上去覆蓋；若要動它，確認流程。）

其他檔案

IV100.png：為 100% IV 完美個體預留的標示圖（目前 index.html 尚未引用）。

4.0 KiB Raw Permalink Blame History Unescape Escape