election-game/backend/docs
王性驊 bfdf2e3df8 選戰卡牌第四版:本週戰場、加開行程、逆風重排、逐張地圖校準;手機版修正;刪除人物資料庫與 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-30 07:42:15 +08:00
..
03-voter-model.md 初始匯入:選舉小鎮(backend、web、art 合成一個 repo) 2026-10-28 15:58:33 +08:00
10-data-sources.md 選戰卡牌第四版:本週戰場、加開行程、逆風重排、逐張地圖校準;手機版修正;刪除人物資料庫與 AI 評分 2026-10-30 07:42:15 +08:00
14-legal-and-ethics.md 選戰卡牌第四版:本週戰場、加開行程、逆風重排、逐張地圖校準;手機版修正;刪除人物資料庫與 AI 評分 2026-10-30 07:42:15 +08:00
18-feedback-backlog.md 初始匯入:選舉小鎮(backend、web、art 合成一個 repo) 2026-10-28 15:58:33 +08:00
19-classic-battles.md 初始匯入:選舉小鎮(backend、web、art 合成一個 repo) 2026-10-28 15:58:33 +08:00
20-campaign-slogans.md 初始匯入:選舉小鎮(backend、web、art 合成一個 repo) 2026-10-28 15:58:33 +08:00
22-rogue-v2.md 選戰卡牌第四版:本週戰場、加開行程、逆風重排、逐張地圖校準;手機版修正;刪除人物資料庫與 AI 評分 2026-10-30 07:42:15 +08:00
23-career-and-meta.md 初始匯入:選舉小鎮(backend、web、art 合成一個 repo) 2026-10-28 15:58:33 +08:00
24-avatar-shop-plan.md 初始匯入:選舉小鎮(backend、web、art 合成一個 repo) 2026-10-28 15:58:33 +08:00
25-gameplay-v3.md 選戰卡牌:地方事件週、對手類型、聲望解鎖、流派傾向、新牌插圖 2026-10-29 17:32:15 +08:00
26-gameplay-v4.md 選戰卡牌第四版:本週戰場、加開行程、逆風重排、逐張地圖校準;手機版修正;刪除人物資料庫與 AI 評分 2026-10-30 07:42:15 +08:00
README.md 選戰卡牌第四版:本週戰場、加開行程、逆風重排、逐張地圖校準;手機版修正;刪除人物資料庫與 AI 評分 2026-10-30 07:42:15 +08:00
appendix-1994-original.md 初始匯入:選舉小鎮(backend、web、art 合成一個 repo) 2026-10-28 15:58:33 +08:00

README.md

選舉小鎮 — 架構總覽

以台灣選舉為舞台的網頁遊戲。主要玩法是選戰卡牌:用政府開放資料建出真實的選民結構當底盤,8 週出牌拉票,最後開票夜一區一區翻過來。 外圍有政治生涯(里長一路選到總統)、政策島、小遊戲、捏人物與服裝店、歷屆參選人資料庫。

本文件寫的是 2026-10-28 程式碼的實際狀態。舊的設計文件(十週行程版、多人連線、舊架構等)描述的東西已刪除或沒有做, 已經移除;程式註解裡提到的 docs/02、04–09、11–13、15–17、21 指的就是這些舊文件,原文在 2026-10-28 的備份裡。

全貌

政府開放資料、中選會、Wikidata
        │
        ▼
backend/data/pipeline(Python)──► backend/data/build/
                                     ├─ packs/        資料包:村里人口、選民群、歷史得票、地圖
                                     ├─ scenarios/    劇本:真實候選人與得票,加上 calibration.json
                                     ├─ people/       records.json(歷屆參選人)、genders.json、slogans.json
                                     └─ council/      議員選區
        │                                   ▲
        │                 apps/sim 校準 ─────┘(舊十週引擎讓 AI 對打,寫 calibration.json)
        ▼
backend/packages ──► backend/apps/server(Fastify,REST /api)──► web(React + Vite)
                              │                                      │
                     data/runs/<局>.json                     瀏覽器 localStorage
                     (每一局卡牌的存檔)                     (進度、生涯、外觀、設定)

兩個程式庫

程式庫 內容 規則
backend/ pnpm workspace:規則、伺服器、校準工具、Python 資料管線 所有結算都在這裡
web/ React 19 + Vite;3D 小鎮用 three.js 只依賴 @election2026/protocol,不含遊戲規則

前端拿到的是伺服器算好的「玩家視角」,自己不算票。改畫面不用動後端,改規則不用動前端。

後端套件

套件 做什麼 誰用
packages/protocol 前後端契約:Zod 定義(資料包、劇本、卡牌的請求與回應、參選人資料)、頭像部件目錄、政黨清單;pnpm schema 產生 JSON Schema 給 Python 驗證 全部,包括前端
packages/rogue 選戰卡牌的規則:純函式,狀態可序列化,同一個種子同一局 server、sim
packages/engine 選民模型(docs/03),加上舊的十週選戰引擎 rogue 開局用選民模型;十週引擎只給 sim
packages/content 十週引擎的行動、事件、記者堵麥、議題;手工劇本;自創角色 server、rogue、sim
packages/scenarios 劇本目錄:手工劇本+管線產生的全台劇本,套上校準值 server、sim
packages/pack-loader 從磁碟讀取並驗證資料包、劇本、標語、性別 server、sim
apps/server Fastify API,速率限制;卡牌每一局放記憶體(最多 200 局)並寫到 data/runs/ 前端
apps/sim 校準(calibrate-local.ts)、回測、平衡報告(卡牌、生涯、政黨、大絕招、里長) 開發者

rogue 裡面

檔案 內容
setup.ts、local.ts 開局:用選民模型算各區(或各里)底盤與地區特色;local.ts 是里長、議員關
archetypes.ts 候選人特色(docs/25):本命區算法、六種類型的技能/弱點/專屬牌(類型由伺服器依中選會紀錄或出身決定)
rules.ts createRun、endWeek、choose、ultimate,以及從 cards.ts 轉出的 playCard:每個動作回傳新的狀態
state.ts RunState、TOTAL_WEEKS = 8、存檔版本 SAVE_VERSION 與 migrateRun
data.ts、cards.ts 牌的資料與效果
rival.ts 對手每週的意圖與行動;每局抽的對手規則(docs/25);落後時急起直追(docs/26)
battle.ts 本週戰場:每週要搶的一區(docs/26)
route.ts、scenes.ts、content.ts 每週結束的「下一站」(含地方派系談判、下下週的門)、辯論/民調/黑函週(週次每局隨機)、堵麥與地方抉擇
advisors.ts、feats.ts、meta.ts、ultimate.ts、mechanics.ts 幕僚、成就、生涯能力與政策、大絕招、逆風等級(ASC_RULES,docs/26)
view.ts 給前端的玩家視角(含每張手牌打在每一區的預估)
tutorial.ts、bots.ts 新手教學;模擬玩家(平衡報告用)

API

路由 用途
GET /api/health 健康檢查
GET /api/scenarios 劇本清單(候選人、能力值、查證過的標語)
GET /api/packs/:packId/topology 地圖
GET /api/rogue/catalog 目錄:牌、幕僚、事件、成就、逆風等級、生涯能力、政策島建築(圖鑑、生涯、政策島用)
POST /api/rogue/runs 開一局:劇本、候選人、種子、逆風、勢均力敵、每日一戰、自創角色、生涯帶過來的東西、里長/議員關
POST /api/rogue/tutorial 開新手教學
GET /api/rogue/runs/:id、/area 這一局的玩家視角、地圖範圍
GET /api/rogue/villages/:scenarioId 里長關選里用
POST /api/rogue/runs/:id/play、/end-week、/choose、/ultimate 出牌、結束這週、選下一站、大絕招
GET /api/people、/api/people/:id 歷屆參選人與客觀資歷分數(records.json)

前端

web/src/App.tsx 是 hash 路由;首頁和卡牌一開始就載入,其他畫面用到才下載。

資料夾(web/src/game/) 畫面
home、start 首頁、會動的 3D 選戰小鎮
rogue 卡牌大廳、一局、開票夜、結果圖卡、圖鑑與成就、政治生涯
career 任期小遊戲(質詢、審預算…)
island 政策工坊與政策島
minigames 掃街握手、造勢、看板等小遊戲
creator、shop、art 捏人物、服裝店、頭像繪製(部件目錄,docs/24)
people 歷屆參選人
board3d、stage、news、audio、ui、hud 3D 棋盤、地圖、新聞台、音樂音效、共用元件、設定
../viewer、../map 資料檢視器(開發用:資料檢視器、美術總覽、頭像對照、部件檢查只有 pnpm dev 打得開,正式版不打包)

玩家進度沒有帳號,存在瀏覽器 localStorage(鍵都以 tongsuan. 開頭:卡牌進度與完成度、生涯、政策島、外觀與小鎮幣、自創角色、小遊戲紀錄、設定)。

載入:index.html 內嵌載入畫面(不等任何下載),首頁等 3D 小鎮搭好才淡出(src/splash.ts);three.js 和一局卡牌的畫面用到才下載; 3D 小鎮依實際每秒張數自動降畫質,偵測到沒有顯示卡(軟體繪圖)直接用最低畫質。正式版用 pnpm start(建置後 vite preview),比 pnpm dev 小三倍以上;API 回應由伺服器壓縮(@fastify/compress)。

素材:web/public/assets/ 是 CC0/OFL 素材(逐檔記在 LICENSES.md);web/public/cards/ 是卡牌插圖,用 art/ 裡的腳本產生;頭像部件是原創 SVG,放在 backend/packages/protocol/art/avatar/,pnpm avatar:build 轉成程式碼。

一局卡牌怎麼跑

  1. 前端 POST /api/rogue/runs。伺服器從劇本目錄找劇本,讀資料包(同一份快取),rogue/setup.ts 用選民模型算出各區底盤,createRun 產生初始狀態。
  2. 每個動作(出牌、結束這週、選下一站)都是 rules.ts 的純函式:舊狀態 → 新狀態。伺服器存起來(記憶體+data/runs/<id>.json),回傳 view.ts 算好的玩家視角。
  3. 種子決定一切:同一個種子、同樣的選擇就是同一局。每日一戰的種子由日期算出,「挑戰朋友」連結帶著種子。

資料管線

backend/data/pipeline,指令是 election-data(安裝方式見 backend/README.md):

指令 產出
pack --county <代碼> 資料包:村里人口與 30 個選民群、歷史得票、村里屬性、地圖(--before 做回測用的資料包)
local --year、races --year 縣市長、總統、區域立委劇本(候選人層級得票和中選會核對)
donations 政治獻金(劇本的錢)
records 歷屆參選人與資歷分數、議員選區
parties 歷屆政黨清單(也寫 protocol/src/parties.ts)
python -m election_data.genders 候選人性別(給頭像)

資料來源與授權見 docs/10;每個資料包的 sources.json 列出來源、版本與擷取日期。

測試與檢查

cd backend && pnpm typecheck && pnpm test     # 協定、引擎、內容、卡牌、劇本、伺服器
cd web && pnpm typecheck && pnpm test && pnpm build
cd backend/data/pipeline && .venv/bin/pytest && .venv/bin/ruff check src tests

原則

  1. 規則只在後端,前端只依賴協定。
  2. 規則是純函式、狀態可序列化,同一個種子可以重現(測試、存檔、挑戰朋友都靠這點)。
  3. 內容是資料:牌、事件、幕僚、劇本都是資料檔,新增內容不改規則。
  4. 真實資料、真實人物有界線:不用照片、不用 AI 畫真人、不捏造真人引述、AI 控制的真實人物不用奧步(docs/14)。

文件

文件 內容
03-voter-model.md 選民模型:選民群、投票公式、參數、校準
10-data-sources.md 資料來源、授權、已查證的法規(部分資料源只是研究,文件開頭有說明)
14-legal-and-ethics.md 真實人物、政黨、選舉期間的法律與倫理界線
18-feedback-backlog.md 使用者回饋與改版紀錄(歷史紀錄;程式註解的「18 第 N 項」指這裡)
19-classic-battles.md 歷史劇本:1996–2024 總統、2014 縣市長怎麼做出來的
20-campaign-slogans.md 真實候選人的競選標語與出處
22-rogue-v2.md 選戰卡牌:玩法、機制、平衡
23-career-and-meta.md 政治生涯、政策島、小遊戲、歷屆參選人與資歷分數
24-avatar-shop-plan.md 紙娃娃部件目錄、畫風、服裝店;附開放真錢前的法規整理
25-gameplay-v3.md 選戰卡牌第三版:本命區、類型技能、完成度(已做);流派、對手規則、隨機行事曆、難度(規格)
26-gameplay-v4.md 選戰卡牌第四版:桌遊機制研究、本週戰場、加開行程、急起直追、逆風階梯重排、各項設定的平衡
appendix-1994-original.md 1994 年原作《臺灣模擬選戰》的拆解紀錄