election-game/backend/docs/README.md

158 lines
11 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.

# 選舉小鎮 — 架構總覽
以台灣選舉為舞台的網頁遊戲。主要玩法是**選戰卡牌**:用政府開放資料建出真實的選民結構當底盤,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) |
| `tides.ts`、`calibration.ts` | 歷史形勢的全國風向表(`apps/sim rogue-tides`)、逐張地圖的對手強度校準(`apps/sim rogue-calibrate`) |
| `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` 列出來源、版本與擷取日期。
## 測試與檢查
```bash
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](03-voter-model.md) | 選民模型:選民群、投票公式、參數、校準 |
| [10-data-sources.md](10-data-sources.md) | 資料來源、授權、已查證的法規(部分資料源只是研究,文件開頭有說明) |
| [14-legal-and-ethics.md](14-legal-and-ethics.md) | 真實人物、政黨、選舉期間的法律與倫理界線 |
| [18-feedback-backlog.md](18-feedback-backlog.md) | 使用者回饋與改版紀錄(歷史紀錄;程式註解的「18 第 N 項」指這裡) |
| [19-classic-battles.md](19-classic-battles.md) | 歷史劇本:1996–2024 總統、2014 縣市長怎麼做出來的 |
| [20-campaign-slogans.md](20-campaign-slogans.md) | 真實候選人的競選標語與出處 |
| [22-rogue-v2.md](22-rogue-v2.md) | 選戰卡牌:玩法、機制、平衡 |
| [23-career-and-meta.md](23-career-and-meta.md) | 政治生涯、政策島、小遊戲、歷屆參選人與資歷分數 |
| [24-avatar-shop-plan.md](24-avatar-shop-plan.md) | 紙娃娃部件目錄、畫風、服裝店;附開放真錢前的法規整理 |
| [25-gameplay-v3.md](25-gameplay-v3.md) | 選戰卡牌第三版:本命區、類型技能、完成度(已做);流派、對手規則、隨機行事曆、難度(規格) |
| [26-gameplay-v4.md](26-gameplay-v4.md) | 選戰卡牌第四版:桌遊機制研究、本週戰場、加開行程、急起直追、逆風階梯重排、各項設定的平衡 |
| [appendix-1994-original.md](appendix-1994-original.md) | 1994 年原作《臺灣模擬選戰》的拆解紀錄 |