election-game/backend/README.md

134 lines
6.0 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 選舉小鎮 — 後端
遊戲規則、資料管線、歷屆參選人資料庫。前端在另一個程式庫(`../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 # 選戰卡牌的平衡(模擬玩家)
```
`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` 列出所有來源、版本、擷取日期與授權。