timmy/pokemon-radar-api
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: 合併成單一 README（寫給一年後回來看的自己）

Browse Source 
- 常用指令放最上面，.env 和 API 速查在中間，架構與故障排除在最下面
- QUICKSTART / SUMMARY 砍掉，WHY 融進架構段
- 移除「給新人入門」的 step-by-step 路徑

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Timmy
2026-04-20 09:22:56 +08:00
parent da5a36e8ad
commit c95d6074d5
3 changed files with 134 additions and 311 deletions
Download Patch File Download Diff File Expand all files Collapse all files

129
QUICKSTART.md
View File

@@ -1,129 +0,0 @@
# QUICKSTART
從零把整條 pipeline 跑起來。大約 5 分鐘。
完整規格看 `README.md`，設計背景看 `SUMMARY.md`。
## 需求
- [`uv`](https://github.com/astral-sh/uv)（Python 套件管理）
- Docker（用來跑本機 Redis）
- 能連到 Function Server `http://192.168.42.124:13000/function`（內網）
- 有效的 `state.json`（twpkinfo.com 登入快照，放 repo 根目錄）
## 1. 起本機 Redis
```bash
docker run -d --name pokemon-radar-redis \
--restart unless-stopped \
-p 6379:6379 \
redis:7-alpine
docker exec pokemon-radar-redis redis-cli PING # 應回 PONG
```
管理指令：`docker stop/start/rm pokemon-radar-redis`、`docker logs -f pokemon-radar-redis`。
## 2. 設定 `.env`
複製或編輯 `.env`，本機跑的最小設定：
```ini
FUNCTION_URL=http://192.168.42.124:13000/function
FUNCTION_TOKEN=6R0W53R135510
SCRIPT_PATH=twpk_radar.mjs
STATE_PATH=state.json
UA_FROM_STATE=true
RADAR_LAT=25.0478
RADAR_LNG=121.5170
RADAR_ZOOM=11
MIN_REMAINING=300
REDIS_HOST=127.0.0.1
REDIS_PORT=6379
REDIS_DB=0
REDIS_PASSWORD=
REDIS_TTL=300
REDIS_KEY=pokemon:radar:latest
```
連正式 Redis（`192.168.42.211`）時把 `REDIS_HOST` 和 `REDIS_PASSWORD` 改回去即可。
## 3. 拉一次資料進 Redis
```bash
uv run python radar_fetcher.py
```
成功的 log：
```
INFO ENV: RADAR_ZOOM=11, MIN_REMAINING=300, ...
INFO Loaded state: cookies=7, ls=2, ua=N
INFO Calling Function Server: http://192.168.42.124:13000/function
INFO Got 120 results (before filters)
SUCCESS Redis write OK host=127.0.0.1 key=pokemon:radar:latest ttl=300s
```
跑一次約 30-60 秒。
## 4. 檢查 Redis 內容
```bash
uv run python reader.py
```
會列出目前 TTL、總筆數，以及 `rich` 表格（名稱 / IV / CP-Lv / 技能 / 剩餘時間 / 座標）。
想看 raw JSON 用 `uv run python check_redis.py`。
## 5. 起 API
```bash
./run_pokemon_radar_api.sh
# 或：uv run uvicorn pokemon_radar_api:app --host 0.0.0.0 --port 8008 --log-config logging.ini
```
另開一個 shell 測：
```bash
curl -s http://127.0.0.1:8008/ping
# {"status":"ok","backend":"redis"}
curl -s -X POST http://127.0.0.1:8008/scan \
-H "Content-Type: application/json" \
-d '{"lat":25.0478,"lng":121.5170,"min_iv":90}'
```
看到 `"source":"redis"` 且 `count_filtered` > 0 就成功。
## 6.（選用）定期自動更新
Redis TTL 預設 300s，過期後 API 會回空陣列。要讓資料持續可用，把 fetcher 排成 cron：
```cron
*/3 * * * * cd /path/to/pokemon-radar-api && /root/.local/bin/uv run python radar_fetcher.py >> /var/log/radar_fetcher.log 2>&1
```
生產環境另有 `fetch_and_upload.sh`，走的是**舊 pipeline**（本地檔 + scp），不經 Redis，見 `SUMMARY.md`。
---
## 常見問題
**`FUNCTION_TOKEN 未設定`**
`.env` 少 `FUNCTION_TOKEN`。
**`Redis 連線失敗: Timeout connecting to server`**
Redis 連不到。確認容器在跑（`docker ps | grep redis`），或 `.env` 的 `REDIS_HOST` 是否正確。API 端此時會回 `source: "redis (unreachable)"` 不會 500。
**`Got 0 results` 或 `Filtered to 0`**
通常是 `state.json` 過期，網站把你擋下來。重新登入 twpkinfo.com 匯出新的 state。`radar_fetcher` 會印 `remaining_min / remaining_max / perfect` 做診斷；若 `raw_items` 本身就 0，就是 state 問題。
**API 回 `source: "redis (empty)"`**
Redis 裡沒資料或 key 已過期。跑 `radar_fetcher.py` 重灌。
**`MJS regex 沒套到`（例如座標沒改）**
表示 `twpk_radar.mjs` 裡的 `const TARGET = {...};` 或 `const DO_SCREENSHOT = ...;` 格式被改動。Python 端用 regex 字串替換，形狀要維持。

224
README.md
View File

@@ -1,69 +1,63 @@
# pokemon-radar-api
把 twpkinfo.com 的寶可夢雷達資料包成 Redis-backed 的 HTTP API，給前端 / n8n 呼叫。
把 twpkinfo.com 的寶可夢雷達資料，透過 Redis 快取成一支 FastAPI 給前端 / n8n 呼叫。
- 上手操作：`QUICKSTART.md`
- 設計脈絡與演進：`SUMMARY.md`
- Claude Code 指引：`CLAUDE.md`
本檔為參考手冊：組件一覽、指令、環境變數、HTTP API、Redis schema。
這份 README 是給**一年後回來看的你自己**：最常用的指令放最上面，架構與決策放最下面。`CLAUDE.md` 是給 AI 助手用的，可以忽略。
---
## 組件
## 最常用的指令
| 檔案 | 角色 |
|---|---|
| `radar_fetcher.py` | **現行 fetcher**：呼叫 Function Server 抓資料 → 篩選 → 寫入 Redis（`SETEX`，預設 TTL 300s） |
| `pokemon_radar_api.py` | **FastAPI 服務**（`:8008`）：`/ping`、`/scan`；從 Redis 讀取，依 request 參數即時二次篩選 |
| `twpk_radar.mjs` | Function Server 上跑的 Puppeteer worker，負責開瀏覽器拉 `twpkinfo.com/ipoke.aspx` 的資料 |
| `pokemon_location_fetcher.py` | **舊版 CLI**：直接呼叫 Function Server，輸出本地 `pokemon_data.{json,csv}` + `screenshot.png`。API 仍重用它的 `PokemonRadarClient.postprocess` 做二次篩選 |
| `pokemon_radar_example.py` | 舊 CLI 的 Python 範例程式（非 CLI argparse 介面） |
| `reader.py` | 從 Redis 讀取並用 `rich` 表格顯示目前快取內容 |
| `check_redis.py` | 從 Redis 讀取並 dump 原始 JSON |
| `fetch_and_upload.sh` | 生產環境 cron：以 `flock` 鎖定，呼叫**舊 CLI**產 `pokemon_data.json` 後 `scp` 到 `192.168.42.104:/opt/caddy/www/pokemon/spots.json` |
| `run_pokemon_radar_api.sh` | 啟動 FastAPI（`uvicorn`，port 8008）的 shell 腳本 |
| `state.json` | twpkinfo.com 登入後的 cookies / localStorage / UA / langs 快照，注入到 MJS 繞人機驗證 |
| `logging.ini` | uvicorn 的 logging 設定 |
全部用 `uv`（Python 3.12）。設定讀 `.env`（不在 git 裡，本機有）。
## 執行指令
```bash
# 起本機 Redis（一次性）
docker run -d --name pokemon-radar-redis --restart unless-stopped -p 6379:6379 redis:7-alpine
全部以 `uv` 跑（Python 3.12，見 `.python-version`、`pyproject.toml`）。
# 跑一次 fetcher，把資料抓進 Redis（TTL 300s）
uv run python radar_fetcher.py
| 目的 | 指令 |
|---|---|
| 啟動 API | `./run_pokemon_radar_api.sh`（= `uv run uvicorn pokemon_radar_api:app --host 0.0.0.0 --port 8008 --log-config logging.ini`） |
| 跑 fetcher（寫入 Redis） | `uv run python radar_fetcher.py` |
| 跑舊 CLI（輸出本地檔案） | `uv run python pokemon_location_fetcher.py --script twpk_radar.mjs --lat 25.0478 --lng 121.5170 --zoom 16 --state state.json --ua-from-state --min-remaining 300 --min-iv 90` |
| 查 Redis 內容（表格） | `uv run python reader.py` |
| 查 Redis 內容（raw JSON） | `uv run python check_redis.py` |
| 生產排程（含 scp 上傳） | `./fetch_and_upload.sh` |
# 看 Redis 目前有什麼（rich 表格）
uv run python reader.py
本專案沒有 test / lint / build 流程。
# 看 Redis raw JSON
uv run python check_redis.py
## 環境變數（`.env`）
# 起 API
./run_pokemon_radar_api.sh
# 內部執行：uv run uvicorn pokemon_radar_api:app --host 0.0.0.0 --port 8008 --log-config logging.ini
| 變數 | 預設 | 誰用 | 說明 |
# 測 API
curl -s http://127.0.0.1:8008/ping
curl -s -X POST http://127.0.0.1:8008/scan -H "Content-Type: application/json" \
-d '{"lat":25.0478,"lng":121.5170,"min_iv":90}'
```
**生產環境 cron**：`./fetch_and_upload.sh` — 走的是**舊 pipeline**（`pokemon_location_fetcher.py` 直接輸出本地 JSON，`scp` 到 `192.168.42.104` 的 caddy），不經 Redis，不經 API。跟 fetcher/API 這條線沒關係、請不要混淆。
沒有 test / lint / build。
---
## `.env` 速查
Secrets 放 `.env`（gitignore）。本機與生產共用同一份格式、只改 `REDIS_HOST` / `REDIS_PASSWORD`。
| 變數 | 誰讀 | 預設 | 備註 |
|---|---|---|---|
| `FUNCTION_URL` | `http://192.168.42.124:13000/function` | `radar_fetcher` | Function Server endpoint |
| `FUNCTION_TOKEN` | （必填） | `radar_fetcher` | 未設會直接 `raise` |
| `SCRIPT_PATH` | `twpk_radar.mjs` | `radar_fetcher` | JS worker 檔名 |
| `STATE_PATH` | `state.json` | `radar_fetcher` | 登入狀態快照路徑 |
| `UA_FROM_STATE` | `true` | `radar_fetcher` | 是否從 state 帶 UA / langs |
| `RADAR_LAT` / `RADAR_LNG` | `25.0478` / `121.5170` | `radar_fetcher` | 掃描中心座標 |
| `RADAR_ZOOM` | `11` | `radar_fetcher` | 地圖縮放 |
| `RADAR_SHOT` | `false` | `radar_fetcher` | 是否擷取畫面（base64） |
| `MIN_REMAINING` | `300` | `radar_fetcher` | 剩餘秒數門檻 |
| `MIN_IV` | 空 | `radar_fetcher` | IV% 下限 |
| `PERFECT_ONLY` | `false` | `radar_fetcher` | 只保留 100% IV |
| `SPECIES` | 空 | `radar_fetcher` | 逗號分隔的 dex id 或名稱關鍵字（例：`133,伊布`） |
| `HTTP_TIMEOUT` | `160` | `radar_fetcher` | 呼叫 Function Server 的 HTTP timeout（秒） |
| `REDIS_HOST` | `localhost`（fetcher）/ `192.168.42.211`（API、reader） | 全部 | 注意兩邊預設不同，統一在 `.env` 指定 |
| `REDIS_PORT` | `6379` | 全部 | |
| `REDIS_DB` | `0` | 全部 | |
| `REDIS_PASSWORD` | 空 | 全部 | 空字串視為無密碼 |
| `REDIS_TTL` | `300` | `radar_fetcher` | 寫入 TTL |
| `REDIS_KEY` | `pokemon:radar:latest` | 全部 | |
| `FUNCTION_URL` | fetcher / 舊 CLI | `http://192.168.42.124:13000/function` | Function Server endpoint |
| `FUNCTION_TOKEN` | fetcher / 舊 CLI | （必填） | 空字串 fetcher 會 `raise` |
| `SCRIPT_PATH` | fetcher | `twpk_radar.mjs` | JS worker 檔名 |
| `STATE_PATH` | fetcher | `state.json` | twpkinfo.com 登入快照，**最常壞的地方** |
| `UA_FROM_STATE` | fetcher | `true` | 是否從 state 帶 UA / langs |
| `RADAR_LAT` / `RADAR_LNG` / `RADAR_ZOOM` | fetcher | `25.0478` / `121.5170` / `11` | 掃描中心 |
| `MIN_REMAINING` | fetcher | `300` | 寫入前先做一輪粗篩，低於此值不進 Redis |
| `MIN_IV` / `PERFECT_ONLY` / `SPECIES` | fetcher | 空 / `false` / 空 | fetcher 端篩選（通常留空，由 API 端即時篩） |
| `REDIS_HOST` / `REDIS_PORT` / `REDIS_DB` / `REDIS_PASSWORD` | 全部 | 本機 `127.0.0.1` / 生產 `192.168.42.211` | 預設本機無密碼 |
| `REDIS_TTL` | fetcher | `300` | 寫入 TTL |
| `REDIS_KEY` | 全部 | `pokemon:radar:latest` | |
---
## HTTP API
@@ -73,50 +67,100 @@
```
### `POST /scan`
從 Redis 讀取目前快取，依 body 篩選後回傳。**永遠回 200**，Redis 連不上或空資料都回空陣列，不會 500。
從 Redis 讀取 → 依 body 參數即時二次篩選 → 回傳。**永遠回 200**（Redis 空或不可用都回空陣列）。
**Request body**
| 欄位 | 型別 | 說明 |
|---|---|---|
| `lat`, `lng`, `zoom`, `shot`, `state_path`, `ua_from_state`, `save_files` | — | 相容性欄位，Redis 模式下**忽略** |
| `min_remaining` | `int ≥ 0` | 剩餘秒數下限 |
| `min_iv` | `int 0-100` | IV% 下限 |
| `perfect_only` | `bool` | 只保留 100% IV |
| `species` | `str` | 逗號分隔 dex id 或名稱關鍵字 |
**Response**
**Body**
| 欄位 | 說明 |
|---|---|
| `source` | `"redis"` / `"redis (empty)"` / `"redis (unreachable)"` |
| `ttl` | Redis key 剩餘秒數 |
| `count_raw` | Redis 內筆數 |
| `count_filtered` | 經 request 參數篩選後筆數 |
| `items` | 物件陣列，見下 |
| `debug` | 含 `notes`（MJS 輸出）、`redis_ttl`、`note`（錯誤訊息） |
| `min_remaining` (int) | 剩餘秒數下限 |
| `min_iv` (int 0-100) | IV% 下限 |
| `perfect_only` (bool) | 只保留 100% IV |
| `species` (str) | 逗號分隔 dex id 或名稱關鍵字，如 `"133,伊布"` |
| `lat / lng / zoom / shot / state_path / ua_from_state / save_files` | 相容性欄位，**Redis 模式下忽略** |
**`items[]` 欄位**
`id / name / gender / remaining / expire_time / expire_at / latitude / longitude / iv_pct / iv_atk / iv_def / iv_sta / cp / level / is_perfect / fast_move / charge_move`
## Redis schema
| 項目 | 值 |
|---|---|
| Key | `pokemon:radar:latest` |
| 型別 | String（JSON） |
| TTL | `REDIS_TTL`（預設 300s） |
| Writer | `radar_fetcher.py` |
| Readers | `pokemon_radar_api.py`、`reader.py`、`check_redis.py` |
**Value 結構**
**Response**
```json
{
"source": "fetcher",
"generated_at": "2026-04-20T09:06:36+08:00",
"count_raw": 120,
"count_filtered": 79,
"items": [ /* 同上方 items[] */ ],
"debug": { "notes": ["..."], "api_source": "Fresh from Function Server" }
"source": "redis" | "redis (empty)" | "redis (unreachable)",
"ttl": 281,
"count_raw": 79,
"count_filtered": 24,
"items": [ /* id, name, gender, iv_pct, cp, level, latitude, longitude,
remaining, expire_at, fast_move, charge_move, is_perfect, ... */ ],
"debug": { "notes": [...], "redis_ttl": 281 }
}
```
### Redis schema
Key `pokemon:radar:latest`，String(JSON)，TTL 由 `REDIS_TTL` 控制。Value 結構：
```json
{ "source":"fetcher", "generated_at":"2026-04-20T09:06:36+08:00",
"count_raw":120, "count_filtered":79,
"items":[...], "debug":{ "notes":[...] } }
```
---
## 架構（一年後回來看用）
### 資料流
```
twpkinfo.com/ipoke.aspx
▲
│ Puppeteer (stealth + 等黑影消退 + 解析 DOM)
│
Function Server (http://192.168.42.124:13000/function)
▲
│ POST { code: <注入後的 twpk_radar.mjs> }
│
┌─────┴─────────────────────────┐
│ │
│ A) radar_fetcher.py │ B) pokemon_location_fetcher.py（舊 CLI）
│ → Redis (SETEX, 300s) │ → pokemon_data.{json,csv} + screenshot.png
│ │ → fetch_and_upload.sh 跑這條，scp 給 caddy
└─────┬─────────────────────────┘
▼
pokemon_radar_api.py :8008
POST /scan → 從 Redis 讀，依 request 即時二次篩選
```
### 非看不可的設計決策
- **為什麼要 Redis**：v1 是每個 `/scan` 都打 Function Server，一次 browser automation 要 30-60s，多人同時打直接壞。拆成 writer（fetcher 定期 cron）+ reader（API 讀快取）後壓力從「每 request」降到「每 TTL」。
- **為什麼兩條 pipeline 並存**：caddy 前端走靜態 JSON（舊 CLI 的產物），沒理由為它引 Redis。所以 A 走 Redis 給 API，B 走本地檔給靜態前端，**兩條都還在跑**。
- **`twpk_radar.mjs` 靠 regex 注入參數**：Function Server 的契約是「你丟 JS 過來我跑」，所以參數化只能在字串層做。三個錨點別改形狀：
- `const TARGET = { lat: ..., lng: ..., zoom: ... };`
- `const DO_SCREENSHOT = true|false;`
- `globalThis.__POKE_STATE__ = ...;`
動到形狀 regex 會靜默失敗、用錯參數跑。
- **`pokemon_radar_api.py` 重用舊 CLI 的 postprocess**：為了省一份篩選邏輯，API import `PokemonRadarClient` 但傳空 url/token，只用它的 `postprocess` 方法。這是 workaround，理想做法是把篩選抽成獨立模組，兩份 fetcher 共用。
- **fetcher 端先做一輪粗篩再寫 Redis**（`MIN_REMAINING` 等），API 端再做第二輪 per-request 篩選。Redis 裡不是「原始資料」而是「粗篩後資料」，如果要在 API 端篩出 fetcher 濾掉的東西是做不到的。
### 常見故障（依機率排序）
1. **`state.json` 過期** → Function Server 回 200 但 results 是空 / 登入頁 DOM，pipeline 不會炸只會吐 0 筆。`radar_fetcher.py` 有診斷：`raw_items` 非空但篩完為 0 時 log `remaining_min / remaining_max / perfect` 分佈。重登 twpkinfo.com 匯出新 state。
2. **Redis 連不上** → API 回 `source:"redis (unreachable)"`（不會 500）、`reader.py` 回 `Timeout connecting to server`。確認 docker container / `.env` 的 `REDIS_HOST`。
3. **`FUNCTION_TOKEN` 未設定** → fetcher `raise RuntimeError`。檢查 `.env`。
4. **`/scan` 回空但 Redis 其實有資料** → body 的篩選條件太嚴，或 fetcher 的 `MIN_REMAINING` 已把你要的過濾掉了。
---
## 組件索引
| 檔案 | 角色 |
|---|---|
| `radar_fetcher.py` | 現行 fetcher，寫入 Redis |
| `pokemon_radar_api.py` | FastAPI，讀 Redis |
| `twpk_radar.mjs` | Function Server 上跑的 Puppeteer worker |
| `pokemon_location_fetcher.py` | 舊 CLI，`fetch_and_upload.sh` 還在用 |
| `pokemon_radar_example.py` | 舊 CLI 的 Python 呼叫範例 |
| `reader.py` | Redis 內容表格檢視 |
| `check_redis.py` | Redis raw JSON dump |
| `fetch_and_upload.sh` | 生產 cron：舊 CLI → scp 到 caddy |
| `run_pokemon_radar_api.sh` | 啟動 uvicorn |
| `state.json` | twpkinfo.com 登入快照（gitignore） |
| `.env` | 所有 secret（gitignore） |
| `logging.ini` | uvicorn logging |
| `CLAUDE.md` | 給 AI 助手的指引 |

92
SUMMARY.md
View File

@@ -1,92 +0,0 @@
# SUMMARY
這份文件講**為什麼長這樣**：設計脈絡、演進、取捨、目前還沒處理乾淨的地方。要查指令看 `README.md`，要跑起來看 `QUICKSTART.md`。
## 一句話
把一個只能「給座標、即時回寶可夢清單」的網站（twpkinfo.com），變成「前端 / n8n 能隨時打 API 拿最新資料」的服務。
## 為什麼需要這個專案
twpkinfo.com 的雷達頁（`/ipoke.aspx`）有完整的物種 / IV / CP / 技能 / 座標資訊，但：
1. 沒有 API，資料只在網頁 DOM 裡
2. 有人機驗證與前端黑影遮罩，直接 `curl` 拿不到
3. 前端（地圖標點）和 n8n（通知高 IV 寶可夢）都需要結構化資料
所以這個專案做兩件事：**把網頁變成 JSON**、**把 JSON 包成 API**。
## 架構演進
這條 pipeline 不是一次設計出來的，是三個階段堆疊出來的，中間每個階段的產物都還在 repo 裡。
### 第一階段：CLI 一把梭
`pokemon_location_fetcher.py` + `twpk_radar.mjs` + `fetch_and_upload.sh`。
- `twpk_radar.mjs` 送到 Function Server（一台 `browserless` / 類似的 browser automation 服務）執行，繞 stealth、等黑影消退、解析資料回傳 JSON
- `pokemon_location_fetcher.py` 是 Python CLI，讀 MJS、用 **regex 注入座標和 state.json**、POST 到 Function Server、對回來的資料做 IV%/remaining/species 篩選，最後輸出 `pokemon_data.json` + `pokemon_data.csv` + `screenshot.png`
- `fetch_and_upload.sh` 用 `flock` 避免重入，跑完後 `scp` 把 JSON 丟到另一台 caddy 主機，由前端靜態讀取
**為什麼 regex 注入**：Function Server 的契約是「你丟一段 JS 過來，我幫你跑在無頭瀏覽器」。參數化只能在字串層做 — 所以 `twpk_radar.mjs` 裡的 `const TARGET = {...};`、`const DO_SCREENSHOT = ...;`、`globalThis.__POKE_STATE__ = ...;` 三個錨點變成 Python / JS 之間的介面。改 MJS 時若動到這些行的形狀，Python regex 會失效但不會報錯，只會靜默用錯誤參數跑。
這階段到今天仍在生產跑，因為 caddy 前端是靜態檔，沒理由為了它多引入 Redis。
### 第二階段：FastAPI v1（已不存在）
`pokemon_radar_api.py_BACKUP_20251208225502`（已清除）是第一版 API：每個 `/scan` request 都呼叫一次 Function Server。
問題：
- Function Server 單次 browser automation 要 30-60 秒，前端打一次就等一次
- 多人同時打會超過 Function Server 的 concurrency
- 資料源本身是頁面抓取，3 秒打一次跟 3 分鐘打一次拿到的結果幾乎一樣（寶可夢生成間隔長）
### 第三階段：Redis backed API（現行）
把 fetch 和 serve 拆開：
- `radar_fetcher.py` 當 writer，cron 定期跑，結果 `SETEX` 到 Redis，TTL 300s
- `pokemon_radar_api.py` 當 reader，每個 request 從 Redis 讀快取資料，依 request 參數（`min_iv` / `perfect_only` / `species`）做二次篩選後回傳
- API 的 `ScanRequest` 保留了 `lat / lng / zoom / shot` 欄位**但忽略它們**，純粹相容舊前端不必改 client
Reader 端沒有 breaking change、Writer 端可以獨立調速，Function Server 壓力從「每 request 一次」降到「每 TTL 一次」。
## 目前還沒處理乾淨的地方
### 兩條 pipeline 共存
`radar_fetcher.py`（新）和 `pokemon_location_fetcher.py`（舊）都能抓資料，**篩選邏輯各寫了一份**（`_postprocess` vs `PokemonRadarClient.postprocess`）。修改篩選規則要兩邊同步改。
合併不是單純 refactor：舊 CLI 還在 `fetch_and_upload.sh` 裡給前端生靜態檔，短期不會下掉。
### API 重用舊 client 的 postprocess
`pokemon_radar_api.py` 為了不重寫一次篩選，`import PokemonRadarClient` 然後 `_filter_helper = PokemonRadarClient(url="", token="")`，只用它的 `postprocess`。這個 workaround 讓新 API 與舊 CLI 有了非必要的耦合。長期方向應該把 `_postprocess` 抽成獨立模組，兩邊共用。
### `.env` 的環境耦合
`radar_fetcher.py` 預設 `REDIS_HOST=localhost`，`pokemon_radar_api.py` 和 `reader.py` 預設 `192.168.42.211` — 因為 fetcher 歷史上跑在 Redis 本機，API 跑在遠端。實務上**一定要透過 `.env` 顯式設定**，不要依賴程式內預設。
### `state.json` 的脆弱性
整條 pipeline 最常壞的點是 state 過期。過期時 Function Server 會正常 200，但回來的資料是空陣列或登入頁 DOM — pipeline 不會炸，只會靜默吐 0 筆。`radar_fetcher._postprocess` 有個診斷分支：當 `raw_items` 非空但篩完為 0 時會 log `remaining_min / remaining_max / perfect` 分佈，優先看這個判斷是過濾太嚴還是資料本身有問題。
## 最近處理過的問題
### `/scan` 在 Redis 不可用時會 500
`get_data_from_redis()` 原本只 `try/except json.JSONDecodeError`，沒處理 `redis.exceptions.RedisError`。結果：
- Redis key 不存在 → 照原本設計回空陣列（OK）
- Redis 連不上 → 例外沒接，FastAPI 直接 500
修法：`get_data_from_redis()` 改回傳 `(data, ttl, err)` 三元組，整段 Redis 操作包 `try/except RedisError`；`scan()` 依 `err` 切換 `source` 為 `redis (unreachable)` 並把錯誤訊息放進 `debug.note`。三種情況（連線成功、key 不存在、連不上）都回 200，前端不會炸。
### 備份檔清理
repo 曾保留多份 `*_BACKUP_<timestamp>` 檔案當作版本保險，但有 git 就沒必要。已清除。
## 執行環境現況
- **本機開發**：Docker 起 `redis:7-alpine` 在 `127.0.0.1:6379`，`.env` 指本機、無密碼。Function Server 走 VPN 或同網段連 `192.168.42.124`。
- **生產**：Redis 在 `192.168.42.211`（有密碼）、API 在某台 8008 port、`fetch_and_upload.sh` 由 cron 觸發並 scp 到 `192.168.42.104` 的 caddy。兩條 pipeline 並存。