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