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; 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; /** 一次參選 */ 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; /** 一項資歷分數: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; /** 分數的算法與出處(全部人共用) */ 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; 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; 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; // ── 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; /** 列表的一列 */ 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; 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; /** 個人頁:分數附上算法與出處 */ 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; // ── 議員選區檔: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; 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;