election-game/backend/README.md

134 lines
6.0 KiB
Markdown
Raw Permalink Normal View History

# 選舉小鎮 — 後端
選戰卡牌第四版:本週戰場、加開行程、逆風重排、逐張地圖校準;手機版修正;刪除人物資料庫與 AI 評分 玩法(docs/26): - 本週戰場:每週一個選情接近的大區,對手全力搶攻,週末淨增多的一方贏(聲勢 +1、多抽一張) - 加開行程:每週一次花資金換 1 點體力;起始資金壓到 500–1,000 萬 - 對手落後 3 個百分點以上急起直追;打對台可以搶廣告版面、讓造勢冷場;大絕招集氣加快 - 逆風 0–10 重排成一級一條規則(ASC_RULES),每一級都看得出差別 - 平衡:空戰對手、對手規則、六種類型、空戰/攻防流派、擴散不看鄰區數、區的大小係數、 對手規模依區數、只有一區的選區沒有本命區和戰場、總統大選全國動員、勢均力敵的第三位候選人 - 逐張地圖校準:apps/sim rogue-calibrate 跑過 219 張勢均力敵地圖,calibration.ts 存每張的對手係數 - 模擬工具載入劇本和伺服器一致(總統合成縣市、立委只取選區村里) 畫面: - 戰場比數、加開按鈕、急起直追提示、週末戰場輸贏;遊戲中「存檔離開」回主選單 - 手機直放、橫放的破版修正(圖鑑完成度、遊戲畫面、首頁、捏人物、服裝店、小遊戲等) 刪除(依使用者決定):人物資料庫(Wikidata、內閣、現任名單 → people.json)與 AI 評分管線、 config/people、相關測試、protocol 的 people.ts、docs/rubric-v1.md;records 用到的 names、cec_results 保留 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Uirha5kfuiGbEBhsk7ijDg
2026-10-29 23:42:15 +00:00
遊戲規則、資料管線、歷屆參選人資料庫。前端在另一個程式庫(`../web`),只透過 `packages/protocol` 的協定和後端溝通。設計文件在 [`docs/`](docs/README.md)。
## 目錄
```
packages/protocol/ 前後端契約(Zod)→ 產生 JSON Schema(schema/);頭像部件目錄
packages/rogue/ 選戰卡牌的規則(主要玩法):純函式,狀態可序列化
packages/engine/ 選民模型,加上舊的十週選戰引擎(只給 apps/sim 校準用)
packages/content/ 十週引擎的行動、事件、議題,與手工劇本(資料)
packages/scenarios/ 劇本目錄:手工劇本+管線產生的全台劇本,套上校準值
packages/pack-loader/ 從磁碟讀取並驗證資料包(伺服器與模擬工具共用)
apps/server/ 遊戲 API 伺服器(Fastify)
apps/sim/ 校準、回測與平衡報告
data/pipeline/ Python 資料管線(election_data 套件)
data/raw/ 下載的原始資料(不進版控,可重建)
data/build/ 產出的資料包、劇本、參選人資料(不進版控,可重建)
data/runs/ 選戰卡牌每一局的存檔
docs/ 文件;docs/README.md 是整體架構
```
## 需求
- Node.js 22 以上、pnpm 10
- Python 3.12 以上
## 第一次設定
```bash
pnpm install
pnpm schema # 由 Zod 產生 JSON Schema,Python 管線驗證輸出時會用到
cd data/pipeline
python3 -m venv .venv
.venv/bin/pip install -e ".[dev]"
```
## 產生資料包
```bash
cd data/pipeline
.venv/bin/election-data pack --county 68000 # 桃園市
.venv/bin/election-data pack --county 00000 # 全國
```
輸出在 `data/build/packs/<縣市代碼>/`:`manifest.json`、`villages.json`、`towns.json`、`cells.json`、`history.json`、`topology.json`、`sources.json`,以及給人看的 `report.md`(欄位完整度、補值旗標、與中選會總數的核對)。
第一次執行會下載約 150 MB 的原始資料到 `data/raw/`(有快取,之後不再下載)。
歷史回測用的資料包要排除當次與之後的選舉,避免「先看答案」:
```bash
.venv/bin/election-data pack --county 68000 --before 2022-11-26 # → packs/68000-before-2022-11-26
```
一次做多個縣市用逗號分隔,`all` 是 22 個縣市。2018、2020 年劇本的資料包要加 `--older`,政黨傾向才有 2016、2018 年的選舉可用(不加時只用 2020 年以後的選舉,現有資料包不受影響):
```bash
.venv/bin/election-data pack --county all,00000 --before 2020-01-11 --older # 2020 總統、立委
.venv/bin/election-data pack --county all --before 2018-11-24 --older # 2018 縣市長
```
## 劇本資料(全台的真實候選人與各里得票)
```bash
.venv/bin/election-data local --year 2022 # 縣市長 → data/build/scenarios/2022-local/<縣市>.json(也可以 2018)
.venv/bin/election-data races --year 2024 # 總統、區域立委 → data/build/scenarios/2024-president/、2024-legislator/(也可以 2020)
```
候選人層級的得票都和中選會有效票核對(0 差);競選經費上限依法定公式計算,2018、2022 縣市長與 2020 總統已和中選會公告核對一致。
立委選區只含選區內的里;選舉後才分出來的新里依相鄰的里歸到選區。
劇本產生後要校準(AI 對打讓全區得票接近真實結果,各區、各里當驗證):
```bash
node apps/sim/src/calibrate-local.ts --set 2024-legislator [--only 63000-01] # → data/build/scenarios/<set>/calibration.json
```
## 玩遊戲
```bash
pnpm --filter @election2026/server start # API:http://127.0.0.1:8787
cd ../web && pnpm dev # 網頁:http://localhost:5173(/api 轉給上面的伺服器)
```
伺服器啟動時不讀資料包,第一局開始時才讀(約 1 秒)。選戰卡牌每一局放在記憶體(最多 200 局),同時寫成 `data/runs/<id>.json`(環境變數 `ROGUE_SAVE_DIR` 可改),伺服器重開也能繼續。
## 政治獻金(劇本的錢)
```bash
cd data/pipeline
.venv/bin/election-data donations --election 111年直轄市市長選舉 --area 桃園市 # → data/build/finance/
```
## 回測與平衡報告
```bash
pnpm --filter @election2026/sim backtest -- --seeds 12 --rounds 12
```
用 AI 對打校準全國風向與投票率倍率,再拿各區、各里結果和真實開票比較,也比對 AI 陣營募到、花掉的錢和真實政治獻金。報告輸出到 `apps/sim/out/`。
```bash
pnpm --filter @election2026/sim balance -- --seeds 30 # 每位候選人 × 五種打法
node apps/sim/src/even.ts # 校準「勢均力敵」劇本的風向
pnpm --filter @election2026/sim rogue-balance # 選戰卡牌的平衡(模擬玩家)
```
選戰卡牌第五版:趕場、政見支票、資源瘦身、新主畫面圖示、修 Bug 資源與載入(docs/27 第 1 節):首頁下載 8.7 → 1.6 MB、載入畫面 4.4 → 1.5 秒,進一局 5.0 → 1.3 MB - 中文字型切成 unicode-range 小片,照畫面出現的頻率排(art/fonts/split-webfonts.py),拿掉 Google Fonts; canvas 上的字(3D 看板、名牌、分享圖)字型片載好再畫一次(ui/canvasFont.ts) - 3D 模型 meshopt 壓縮、只留用到的動作(art/optimize-3d.mjs、game/gltf.ts),5.5 → 1.0 MB - 卡圖 320 px 小圖+srcset(art/cards-small.sh);木紋貼圖縮小;背景音樂改 Opus 96 kbps(art/music-opus.sh) - 新增 GET /api/scenarios/list 只回大廳用到的欄位(1.52 → 0.44 MB);伺服器沒有這條路由時前端改抓舊的清單 玩法(docs/27 第 2–4 節,研究桌遊機制後挑兩個做): - 趕場(推運氣):每週可以翻牌庫頂的牌免費打,越翻越容易翻車(POST /api/rogue/runs/:id/overtime) - 政見支票(藏起來的長期目標):第 1 週開跑記者會三選一或不開,開票時兌現全市加票、跳票掉票 新主畫面圖示:重畫投票箱(art/icon/icon.svg、render-icons.sh),apple-touch 滿版不透明,加 Android maskable 修 Bug: - 舊版伺服器沒有新路由時,首頁、政治生涯的紅色「Not Found」改成照樣能用;版本對不上時寫中文說明 - 捏人物「存起來,去政治生涯」直接選好剛捏的角色、跳到選家鄉 - 政見支票:開票畫面的兌現與否和開票結果一致(照投票日的票數判定);跳過=不開;模擬玩家都不開 - 趕場翻到的免費牌只免費一次 - 劇本清單算錯一次後不會一直回錯誤 - 分享圖的標語、減少動態效果時的 3D 看板,字型晚到後重畫 - Safari 解不開 OGG 時改放 MP3 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-30 09:04:19 +00:00
`apps/sim/src/` 另外有 `career-balance.ts`、`party-balance.ts`、`ultimate-balance.ts`、`village-balance.ts`、`overtime-balance.ts`(趕場,docs/27),直接用 `node` 執行。
## 歷屆參選人、政黨、頭像部件
```bash
cd data/pipeline
.venv/bin/election-data records # 歷屆參選人與資歷分數 → data/build/people/records.json、data/build/council/<年>.json
.venv/bin/election-data parties # 歷屆政黨清單 → data/build/parties/parties.json、packages/protocol/src/parties.ts
.venv/bin/python -m election_data.genders # 候選人性別(給頭像)→ data/build/people/genders.json
cd ../..
pnpm avatar:build # 頭像部件 SVG → packages/protocol/src/avatar/*.generated.ts
```
## 測試
```bash
pnpm test # 協定、引擎、內容、伺服器測試;用到資料包的測試在資料包不存在時略過
pnpm typecheck
cd data/pipeline && .venv/bin/pytest && .venv/bin/ruff check src tests
```
## 資料授權
政府開放資料多採「政府資料開放授權條款第 1 版」,每個資料包的 `sources.json` 列出所有來源、版本、擷取日期與授權。