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

228 lines
8.9 KiB
TypeScript
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.

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>;