election-game/backend
王性驊 0e24ee6a16 選戰卡牌:對手規則、隨機行事曆、流派核心牌、精英站、局中小勝利
每局不一樣(docs/25 第 3、4 節)
- 對手規則 7 條(名嘴加持、地方大老、大打空戰、鐵票區、網路謠言、地毯式掃街、形象牌),開局抽 1 條,逆風 5 起 2 條
- 辯論、民調、黑函的週次每局隨機;上方週次標出大場面
- 精英站「地方派系談判」:接下挑戰,下週在指定的區淨增票數,達成拿稀有幕僚
- 下一站畫面看得到下下週的門

流派與小勝利(第 2、5 節)
- 9 張流派核心牌、5 位改規則的幕僚
- 翻區抽牌(每週最多 2 張)、民調領先多一張稀有牌、落後下週體力 +1、結果頁標出最關鍵的一區

選人與手感(第 1、7 節)
- 選人畫面顯示候選人類型、技能、弱點與這個類型的逆風紀錄(伺服器啟動時先算好,人物查詢改用姓名索引)
- 出牌不等伺服器:牌先飛出去、手牌體力先扣,伺服器回來校正
- 設定加「快速模式」:開票夜、週末結算、選情快報快一倍

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Uirha5kfuiGbEBhsk7ijDg
2026-10-28 17:45:05 +08:00
..
apps 選戰卡牌:對手規則、隨機行事曆、流派核心牌、精英站、局中小勝利 2026-10-28 17:45:05 +08:00
data/pipeline 初始匯入:選舉小鎮(backend、web、art 合成一個 repo) 2026-10-28 15:58:33 +08:00
docs 選戰卡牌:對手規則、隨機行事曆、流派核心牌、精英站、局中小勝利 2026-10-28 17:45:05 +08:00
packages 選戰卡牌:對手規則、隨機行事曆、流派核心牌、精英站、局中小勝利 2026-10-28 17:45:05 +08:00
.gitignore 初始匯入:選舉小鎮(backend、web、art 合成一個 repo) 2026-10-28 15:58:33 +08:00
README.md 初始匯入:選舉小鎮(backend、web、art 合成一個 repo) 2026-10-28 15:58:33 +08:00
package.json 初始匯入:選舉小鎮(backend、web、art 合成一個 repo) 2026-10-28 15:58:33 +08:00
pnpm-lock.yaml 首頁速度、載入畫面、本命區與候選人類型、完成度 2026-10-28 17:23:32 +08:00
pnpm-workspace.yaml 初始匯入:選舉小鎮(backend、web、art 合成一個 repo) 2026-10-28 15:58:33 +08:00
tsconfig.base.json 初始匯入:選舉小鎮(backend、web、art 合成一個 repo) 2026-10-28 15:58:33 +08:00

README.md

選舉小鎮 — 後端

遊戲規則、資料管線、人物資料庫與 AI 評分。前端在另一個程式庫(../web),只透過 packages/protocol 的協定和後端溝通。設計文件在 docs/。

目錄

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 以上

第一次設定

pnpm install
pnpm schema                      # 由 Zod 產生 JSON Schema,Python 管線驗證輸出時會用到

cd data/pipeline
python3 -m venv .venv
.venv/bin/pip install -e ".[dev]"

產生資料包

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/(有快取,之後不再下載)。

歷史回測用的資料包要排除當次與之後的選舉,避免「先看答案」:

.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 年以後的選舉,現有資料包不受影響):

.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 縣市長

劇本資料(全台的真實候選人與各里得票)

.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 對打讓全區得票接近真實結果,各區、各里當驗證):

node apps/sim/src/calibrate-local.ts --set 2024-legislator [--only 63000-01]   # → data/build/scenarios/<set>/calibration.json

玩遊戲

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 可改),伺服器重開也能繼續。

政治獻金(劇本的錢)

cd data/pipeline
.venv/bin/election-data donations --election 111年直轄市市長選舉 --area 桃園市   # → data/build/finance/

回測與平衡報告

pnpm --filter @election2026/sim backtest -- --seeds 12 --rounds 12

用 AI 對打校準全國風向與投票率倍率,再拿各區、各里結果和真實開票比較,也比對 AI 陣營募到、花掉的錢和真實政治獻金。報告輸出到 apps/sim/out/。

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,直接用 node 執行。

歷屆參選人、政黨、頭像部件

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

人物資料庫與 AI 評分

目前遊戲不讀 people.json 和評分結果;歷屆參選人頁用的是上面 records 產生的客觀資歷分數。

cd data/pipeline
.venv/bin/python -m election_data.people                      # 產生 data/build/people/people.json
.venv/bin/python -m election_data.scoring --dry-run           # 不呼叫 API:預覽證據包、估計費用
.venv/bin/python -m election_data.scoring --limit 5           # 先評 5 人試跑
.venv/bin/python -m election_data.scoring                     # 全部
  • 人物資料第一次執行約 8 分鐘(Wikidata 查詢服務有流量限制),之後讀快取約 1 秒。可以設定環境變數 ELECTION_DATA_CONTACT(專案網址),放進給 Wikidata 的 User-Agent。人工維護的資料在 data/pipeline/config/people/。
  • AI 評分使用 Claude API,憑證由 SDK 自行讀取:設定環境變數 ANTHROPIC_API_KEY,或安裝 ant 指令列工具後執行 ant auth login。
  • 評分會產生費用。請先用 --dry-run 看估計,再決定範圍。
  • 評分規則:docs/rubric-v1.md。輸出 people_scored.json、scoring_report.md(一致性、政黨偏差檢查)、review_sample.csv(人工抽查清單)。

測試

pnpm test                         # 協定、引擎、內容、伺服器測試;用到資料包的測試在資料包不存在時略過
pnpm typecheck
cd data/pipeline && .venv/bin/pytest && .venv/bin/ruff check src tests

資料授權

政府開放資料多採「政府資料開放授權條款第 1 版」,每個資料包的 sources.json 列出所有來源、版本、擷取日期與授權。