election-game/backend/docs/README.md

158 lines
11 KiB
Markdown
Raw Normal View History

# 選舉小鎮 — 架構總覽
以台灣選舉為舞台的網頁遊戲。主要玩法是**選戰卡牌**:用政府開放資料建出真實的選民結構當底盤,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` | 牌的資料與效果 |
選戰卡牌第四版:本週戰場、加開行程、逆風重排、逐張地圖校準;手機版修正;刪除人物資料庫與 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
| `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` | 每週結束的「下一站」(含地方派系談判、下下週的門)、辯論/民調/黑函週(週次每局隨機)、堵麥與地方抉擇 |
選戰卡牌第四版:本週戰場、加開行程、逆風重排、逐張地圖校準;手機版修正;刪除人物資料庫與 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
| `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) | 選戰卡牌第三版:本命區、類型技能、完成度(已做);流派、對手規則、隨機行事曆、難度(規格) |
選戰卡牌第四版:本週戰場、加開行程、逆風重排、逐張地圖校準;手機版修正;刪除人物資料庫與 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
| [26-gameplay-v4.md](26-gameplay-v4.md) | 選戰卡牌第四版:桌遊機制研究、本週戰場、加開行程、急起直追、逆風階梯重排、各項設定的平衡 |
| [appendix-1994-original.md](appendix-1994-original.md) | 1994 年原作《臺灣模擬選戰》的拆解紀錄 |