election-game/backend/packages/protocol/src/records.ts

228 lines
8.9 KiB
TypeScript
Raw Normal View History

import { z } from "zod";
import { CountyCode, IsoDate, Share, TownCode, VillageCode } from "./common.ts";
/**
* 歷屆參選人資料庫(data/build/people/records.json,由 election-data records 產生):
* 縣市長、議員,加上總統副總統、立法委員(區域、原住民、不分區)。
* 只用中選會選舉資料庫的公開紀錄計算資歷分數;分數是遊戲數值,不代表對個人的評價。
* 檔名叫 records 是為了和 people.ts(具名人物名單 people.json)分開。
*/
/** mayor:首長(縣市長、直轄市長、臺灣省長);councilor:議員;president:總統、副總統;legislator:立法委員 */
export const ElectionOffice = z.enum(["mayor", "councilor", "president", "legislator"]);
export type ElectionOffice = z.infer<typeof ElectionOffice>;
export const RECORD_SCORE_KEYS = ["fame", "organization", "seniority", "strength", "finance"] as const;
export const RecordScoreKey = z.enum(RECORD_SCORE_KEYS);
export type RecordScoreKey = z.infer<typeof RecordScoreKey>;
/** 一次參選 */
export const ElectionRun = z.object({
year: z.number().int(),
date: IsoDate,
/** 臺灣省長、直轄市長、縣市長、臺灣省議員、直轄市議員、縣市議員、總統、副總統、立法委員、不分區立法委員 */
election: z.string().min(1),
office: ElectionOffice,
/** 平地原住民、山地原住民、原住民(1994–2006 北高);區域選舉是 null */
indigenous: z.string().nullable(),
/** 當年的縣市名稱(臺北縣、臺灣省……);總統副總統、原住民立委、不分區立委是「全國」 */
county: z.string(),
/** 對到目前的縣市代碼(臺北縣 → 65000);臺灣省、全國是 null */
countyCode: CountyCode.nullable(),
/** 第 3 選區;首長選舉或整個縣市一個選區是 null */
district: z.string().nullable(),
/** 號次;不分區立委是政黨的號次 */
number: z.number().int().nullable(),
/** 政黨(總統副總統是推薦的政黨);無黨籍是 null */
party: z.string().nullable(),
/** 得票;副總統是同一組正副總統的票;不分區立委沒有個人得票,是 null */
votes: z.number().int().nonnegative().nullable(),
share: Share.nullable(),
elected: z.boolean(),
/** 中選會候選人檔的「現任」欄;舊資料沒有填就是 null */
incumbent: z.boolean().nullable(),
/** 總統副總統選舉同一組的搭檔:總統候選人這裡是副總統,副總統候選人這裡是總統候選人 */
runningMate: z.string().min(1).optional(),
/** 不分區立委:政黨名單上的排名(第 1 名……) */
listRank: z.number().int().positive().optional(),
/** 不分區立委:所屬政黨的全國政黨票與得票率 */
partyVotes: z.number().int().nonnegative().optional(),
partyShare: Share.optional(),
});
export type ElectionRun = z.infer<typeof ElectionRun>;
/** 一項資歷分數:value 0–10(null 是無資料),basis 是代入公式的數字 */
export const RecordScore = z.object({
key: RecordScoreKey,
value: z.number().min(0).max(10).nullable(),
basis: z.string(),
});
export type RecordScore = z.infer<typeof RecordScore>;
/** 分數的算法與出處(全部人共用) */
export const RecordScoreDef = z.object({
key: RecordScoreKey,
label: z.string().min(1),
formula: z.string().min(1),
source: z.string().min(1),
});
export type RecordScoreDef = z.infer<typeof RecordScoreDef>;
export const RecordStats = z.object({
runs: z.number().int().positive(),
wins: z.number().int().nonnegative(),
firstYear: z.number().int(),
lastYear: z.number().int(),
maxVotes: z.number().int().nonnegative(),
});
/** records.json 裡的一個人 */
export const PersonRecord = z.object({
id: z.string().regex(/^r-[0-9a-f]{10}$/),
name: z.string().min(1),
gender: z.enum(["M", "F"]).nullable(),
birthYear: z.number().int().nullable(),
/** high:同名+出生年對上;low:有一筆沒有出生年、用同名+同縣市對的,或出生年差 1 年串起來的(比對信心:低) */
confidence: z.enum(["high", "low"]),
/** 比對信心低的原因(例如出生年差 1 年串起來的);沒有就是一般的「沒有出生年」 */
matchNote: z.string().optional(),
counties: z.array(CountyCode),
/** 參選過的政黨,最近的排前面;null 是無黨籍 */
parties: z.array(z.string().nullable()),
stats: RecordStats,
runs: z.array(ElectionRun).min(1),
scores: z.array(RecordScore),
});
export type PersonRecord = z.infer<typeof PersonRecord>;
export const RecordSource = z.object({
title: z.string().min(1),
url: z.string(),
retrievedAt: IsoDate.nullish(),
sha256: z.string().nullish(),
license: z.string().optional(),
note: z.string().optional(),
});
export const RecordElection = z.object({
folder: z.string(),
year: z.number().int(),
date: IsoDate,
election: z.string(),
office: ElectionOffice,
indigenous: z.string().nullable(),
candidates: z.number().int().nonnegative(),
elected: z.number().int().nonnegative(),
noVotes: z.number().int().nonnegative(),
});
/** data/build/people/records.json 整個檔案 */
export const RecordsFile = z.object({
protocolVersion: z.string(),
generatedAt: IsoDate,
note: z.string(),
sources: z.array(RecordSource),
scoreDefs: z.array(RecordScoreDef),
elections: z.array(RecordElection),
people: z.array(PersonRecord),
});
export type RecordsFile = z.infer<typeof RecordsFile>;
// ── API:GET /api/people、GET /api/people/:id ──
export const PEOPLE_PAGE_SIZE = 50;
export const PeopleListQuery = z.object({
county: CountyCode.optional(),
office: ElectionOffice.optional(),
year: z.coerce.number().int().min(1900).max(2100).optional(),
q: z.string().trim().max(40).optional(),
page: z.coerce.number().int().min(1).max(10_000).default(1),
});
export type PeopleListQuery = z.infer<typeof PeopleListQuery>;
/** 列表的一列 */
export const PersonRecordSummary = z.object({
id: z.string(),
name: z.string(),
/** 最近一次參選的政黨;無黨籍是 null */
party: z.string().nullable(),
runs: z.number().int(),
wins: z.number().int(),
firstYear: z.number().int(),
lastYear: z.number().int(),
/** 最近一次參選:「2022 臺北市第3選區 直轄市議員」「2024 全國 副總統」 */
latest: z.string(),
confidence: z.enum(["high", "low"]),
});
export type PersonRecordSummary = z.infer<typeof PersonRecordSummary>;
export const PeopleListResponse = z.object({
total: z.number().int().nonnegative(),
page: z.number().int().positive(),
pageSize: z.number().int().positive(),
people: z.array(PersonRecordSummary),
/** 資料庫有收的年份(篩選用) */
years: z.array(z.number().int()),
note: z.string(),
});
export type PeopleListResponse = z.infer<typeof PeopleListResponse>;
/** 個人頁:分數附上算法與出處 */
export const PersonRecordResponse = z.object({
person: PersonRecord.omit({ scores: true }).extend({
scores: z.array(RecordScore.extend({ label: z.string(), formula: z.string(), source: z.string() })),
}),
sources: z.array(RecordSource),
note: z.string(),
});
export type PersonRecordResponse = z.infer<typeof PersonRecordResponse>;
// ── 議員選區檔:data/build/council/<年>.json(政治生涯的議員關用) ──
export const CouncilCandidate = z.object({
number: z.number().int().nullable(),
name: z.string(),
party: z.string().nullable(),
votes: z.number().int().nullable(),
share: Share.nullable(),
elected: z.boolean(),
incumbent: z.boolean().nullable(),
/** records.json 的人物 id */
personId: z.string().nullable(),
});
export const CouncilDistrict = z.object({
/** 縣市代碼-中選會選區代碼,例如 63000-03 */
id: z.string(),
countyCode: CountyCode,
countyName: z.string(),
election: z.string(),
indigenous: z.string().nullable(),
district: z.string().nullable(),
districtCode: z.string(),
/** 應選席次(當選人數,含婦女保障名額) */
seats: z.number().int().nonnegative(),
electors: z.number().int().nullable(),
validVotes: z.number().int().nullable(),
towns: z.array(TownCode),
villages: z.array(VillageCode),
candidates: z.array(CouncilCandidate),
/** 當選門檻:得票最少的當選者 */
threshold: z.object({ name: z.string(), votes: z.number().int().nullable(), share: Share.nullable() }).nullable(),
});
export type CouncilDistrict = z.infer<typeof CouncilDistrict>;
export const CouncilFile = z.object({
protocolVersion: z.string(),
year: z.number().int(),
date: IsoDate,
source: RecordSource,
districts: z.array(CouncilDistrict),
/** 選舉當時的村里代碼對不上目前資料包的(選後合併、改名) */
unmatchedVillages: z.array(z.object({ district: z.string(), code: z.string(), reason: z.string() })),
/** 目前資料包有、但不在任何區域議員選區內的村里(選後新設) */
uncoveredVillages: z.record(z.string(), z.array(z.string())),
});
export type CouncilFile = z.infer<typeof CouncilFile>;