# 資料說明（Data Dictionary）

## 這是什麼

從 **hkoi.org**（香港電腦奧林匹克競賽官方網站）公開公示頁面收割的成績資料集，
涵蓋 1992–2026 年、12 個賽事、4,893 條得獎／參賽記錄。

抓取時間：2026-11-22　　抓取器：`harvest.py`

## 檔案

| 檔案 | 內容 |
|---|---|
| `records.json` | 全部記錄（主資料） |
| `records.csv` | 同上，CSV 版（UTF-8 with BOM，Excel 可直接開） |
| `players.json` | 選手聚合：每人拿了幾次獎、跨哪些賽事 |
| `schools.json` | 學校聚合：獎牌數、獲獎人數 |
| `by-contest/*.csv` | 按賽事拆分的單表，方便人工核對 |
| `harvest.sqlite` | 可直接 SQL 查詢的資料庫（表 `records`） |
| `SUMMARY.md` | 自動生成的總量與分佈報告 |
| `QA.md` | 自動生成的品質檢查（重複、缺漏、同名跨校、校名異體） |
| `RANKING.md` | 無綜合評分版排名：學校國際榜／本地榜／近 5 學年／獎牌總數、選手榜，含加權分對照實驗 |
| `ranking.json` | 上表機讀版 |
| `SCORING.md` | 官方學校大獎分數驗證（79 筆）+ 逐年衰減綜合榜（λ=1.00 / 1.10 / 1.25） |
| `scoring.json` | 上表機讀版 |
| `stats.json` | 官方統計 PDF 解析結果（分數線、出席人數、滿分、中位數） |
| `stats.csv` | 同上，CSV 版 |
| `noi_hk.json` | 本站直接從 noi.cn 抓的 2025/2026 香港選手名單（含指導教師、階段） |
| `ccf_hk.json` | 香港選手的 CCF 全量成績 864 條（CSP / NOIP / NOI / NGOI，2004–2026，含分數與全國名次） |
| `ccf_hk.csv` | 同上，CSV 版 |
| `oier_capacity.json` | 各場 CCF 比賽的實際參賽人數（OIerDb `/contests` 的「參賽人數」欄），用作名次百分位的分母 |
| `oier_hk_oiers.json` | OIerDb 線上資料（`result.txt`）中有香港記錄的 436 位選手（以 `uid` 為單位），含 CCF 等級、全國排名、首拼與**全部**記錄（含內地省份） |
| `oier_contests.json` | OIerDb 各場比賽的類型、年份、參賽人數與全國獲獎人數（CCF 評級要用「一等獎人數 × 5」當分母） |
| `oier_surnames.json` | 拼音姓氏異讀表（曾 z、單 s、解 x…），用於首字母搜尋 |
| `ioi_hk.json` | IOI 官方統計站的港隊成績 120 條（1992–2026，含總分、世界名次、相對百分位、逐題得分） |
| `ioi_hk.csv` | 同上，CSV 版（逐題得分轉為 JSON 字串） |
| `grades.json` | 每位選手的**推測**中六畢業年份（`gradYear`）、推導樣本數（`n`）、一致票數（`votes`）、現時推測年級（`gradeNow`）、已畢業年數（`yearsSince`） |
| `rating.json` | 選手榜用的加權評分（時間係數 × 名次係數 × 賽事係數），含獎牌小計與學校、年份區間 |
| `hkoi.db` | **真源**：關聯式資料庫（SQLite 單檔），17 賽事 / 166 屆 / 387 校 / 2,362 位選手 / 5,158 條成績，另有 `edition_stats`、`ccf_meta`、`overrides` 與三個視圖。結構見 `schema.sql` |
| `db/*.csv` | 六張主表各一份 CSV（`contests`/`editions`/`schools`/`players`/`results`/`edition_stats`）——DB 是二進位看不出差异，CSV 才是可 review 的形式 |
| `schema.sql` | 上表的建表語句與設計說明（id 不由姓名派生、統計欄位是派生值等） |

### 關聯式資料庫（hkoi.db）

```bash
sqlite3 data/hkoi.db
```

```sql
-- 某個人的全部成績（含分數、名次、學校）
SELECT 賽事, 屆別, 組別, 獎項, 分數, 名次, 參賽人數, 學校
FROM v_player_results WHERE 選手 = '許峻齊';

-- 某間學校的學生（按記錄數）
SELECT 選手, 記錄數, 首次, 最近 FROM v_school_players
WHERE 學校 = '拔萃男書院' ORDER BY 記錄數 DESC;

-- 某屆的全部得獎者
SELECT p.name, r.division, r.award, r.score
FROM results r JOIN players p ON p.id = r.player_id
JOIN editions e ON e.id = r.edition_id
WHERE e.contest_id = 'c-001' AND e.label = '2025/26' ORDER BY r.score DESC;

-- 同名跨校、待人工確認的選手
SELECT id, name, rating FROM players WHERE status = 'ambiguous';
```

`results` 只存事實（獎項、分數、名次、出處）；`players` 的 `rating`、`rank_hk`、
`ccf_level`、獎牌數是 build 時寫回的派生欄位，不要手改。

### 姓名與校名同時保存繁體與簡體

各來源的字形不同（hkoi.org 是繁體、noi.cn 是簡體），**顯示一律用繁體，但兩種都存**：

| 欄位 | 用途 |
|---|---|
| `players.name` / `schools.name_zh` | 繁體，畫面上顯示的就這個（照大會公布的原字，不做異體字轉換） |
| `players.name_zh_hans` / `schools.name_zh_hans` | 簡體。來源本來是簡體就保留原文（`许峻齐`），否則由繁體轉出。用於比對與搜尋 |
| `results.name_raw` / `name_hans` | 該條記錄上的原文姓名（簡體或英文）與其簡體形式 |
| `results.name_en` / `school_en` | 該條記錄上的英文姓名／校名（外部比賽頁逐行不同，不能只存在選手表） |

站內搜尋同時比對繁體、簡體與拼音首字母（`许峻齐`、`許峻齊`、`xjq` 都能找到同一人）。

⚠️ **不要對姓名做 `zhconv` 全量轉換**：那會把異體字一起改掉（恒→恆、峰→峯、
于→於、杰→傑），等於改了人家的名字。本站只在「來源沒有簡體原文」時才轉出
`name_zh_hans`，且該欄位只用於比對。

### 資料變更流程（DB 是真源）

```bash
# 1) 新增一屆／更正一條：直接寫 SQL（或 DB Browser for SQLite 開 data/hkoi.db）
sqlite3 data/hkoi.db
#   例：INSERT INTO results(...) VALUES(...);
#   例：UPDATE results SET award='金獎' WHERE id='r-xxxxxxxx';

# 2) 重建網站（派生欄位會重算）
python build.py
python check_links.py

# 3) 部署（Python tarfile 打包 → scp → 遠端替換 dist）
```

`import_json.py` 只在「從原始 JSON 重建資料庫」時用；它自己讀 JSON，不經過
build.py 的載入層，所以隨時可以從原始檔重來一次。

## 記錄欄位（records.json）

| 欄位 | 說明 | 例 |
|---|---|---|
| `id` | 由內容派生的一致識別碼 | `r-8aa7661885` |
| `source` | 來源區塊 | `hkoi` / `primary` / `sdic` / `noip` / `hkgoi` / `external` |
| `contest` | 賽事名 | `HKOI` / `IOI` / `NOI` / `SDIC` / `小學電腦奧林匹克` … |
| `year` | 屆別（保留原始寫法） | `2025/26`、`2026`、`1997` |
| `yearSort` | 可排序的年份（學年取結束年） | `2026` |
| `division` | 組別 | `高級組` / `初級組` / `進階級` / `基礎級` / `提高組` / `普及組` |
| `award` | 正規化後的獎項 | `金獎`、`一等獎`、`冠軍` |
| `awardRaw` | 原始獎項字串 | `一等獎成績`、`金獎 (電腦)` |
| `awardNote` | 從原始字串拆出的備註 | `成績`、`電腦` |
| `awardKind` | 個人 / 學校 / 特別獎 | `individual` / `school` / `special` |
| `nameZh` / `nameEn` | 選手姓名（可能只有其中一個） | `許峻齊` / `Xu Adam` |
| `schoolZh` / `schoolEn` | 學校（已做異體正規化） | `九龍華仁書院` |
| `schoolZhRaw` | 正規化前的原始校名 | `陳瑞琪(喇沙)書院` |
| `detailZh` | 學校大獎的計分明細 | `六金四銀六銅共 41 分` |
| `star` | 獲得滿分（`**` 標記，**照樣計分**） | `false` |
| `nominee` | 香港電腦教育學會提名參賽（`*` 標記，**不計入學校大獎**） | `false` |
| `eventDate` / `eventVenue` | 外部比賽的日期與地點 | `2026年8月9-16日` / `烏茲別克 塔什干` |
| `sourceUrl` | 該條記錄的官方原頁 | `https://hkoi.org/zh/results/2025-26/` |
| `pid` / `sid` | 選手／學校主鍵（僅個人記錄有） | `p-728018dc44` |

## 賽事覆蓋

| 賽事 | 記錄 | 年份 | 來源路徑 |
|---|---|---|---|
| HKOI | 2,569 | 1997/98 – 2025/26 | `/zh/results/{year}/` |
| 小學電腦奧林匹克 | 1,042 | 2017/18 – 2025/26 | `/zh/primary-results/{year}/` |
| SDIC | 472 | 2019 – 2026 | `/zh/sdic-results/{year}/` |
| NOIP | 276 | 2016 – 2025 | `/zh/noip-results/{year}/` |
| HKGOI | 149 | 2024/25 – 2026/27 | `/zh/hkgoi-results/{year}/` |
| NOI | 148 | 1997 – 2026 | `/zh/external-competitions/` |
| IOI | 139 | 1992 – 2026 | `/zh/external-competitions/` |
| APIO | 63 | 2010 – 2026 | `/zh/external-competitions/` |
| IOM | 15 | 2017 – 2021 | `/zh/external-competitions/` |
| SEARCC | 9 | 2001 / 2004 | `/zh/external-competitions/` |
| EGOI | 8 | 2025 – 2026 | `/zh/external-competitions/` |
| AGAMES | 3 | 2004 | `/zh/external-competitions/` |

合計 **4,893** 條，其中個人得獎 4,668 條、學校獎項 129 條，其餘為外部比賽的參賽但未獲獎記錄。

## 年份與賽事階段

賽事名 = 官方標籤直接併上賽事代號與組別（`HKOI2025/26 高級組`、`CSP2026 提高`、`NOI2026`）。
組別既然寫進賽事名，表格就不再另設「組別」一欄。
用官方標籤的好處是每屆獨一無二，不會兩屆同名，也不會把未舉行的屆數算成已舉行：

| 官方標籤 | 站上寫法 | 決賽／賽事時間 | 歸入年度 |
|---|---|---|---|
| `HKOI 2025/26` | `HKOI2025/26 高級組`、`HKOI2025/26 初級組` | 2025-12-06 | 2025 |
| `HKOI 2026/27` | `HKOI2026/27 高級組` … | 2026-12-05（未舉行） | — |
| `HKGOI 2026/27` | `HKGOI2026/27` | 2026-10-27 | 2026 |
| `小學電腦奧林匹克 2025/26` | `小學電腦奧林匹克2025/26` | 2026-02 | 2026 |
| `CSP 2026`、`NOI 2026` … | `CSP2026 提高`、`NOI2026` | 標籤本身就是日曆年 | 2026 |

**只計決賽**：所有記錄與統計都以決賽為準（HKOI／HKGOI／小學決賽、CSP 第二輪、NOIP、NOI），
初賽成績與官方統計 PDF 中的初賽數字一概不收。

成績表按**實際舉行日期倒序**（`build.py` 的 `rec_date()`）：

| 來源 | 用什麼時間 |
|---|---|
| 外地比賽（IOI / NOI / APIO / IOM / EGOI / SEARCC / AGAMES） | 記錄裡的 `eventDate`（官方日期） |
| CCF 賽事（CSP / NOIP / NOI） | 慣例月份：CSP 第二輪 10 月、NOIP 11 月、NOI 7 月 |
| HKOI / HKGOI / 小學電腦奧林匹克 | 官方賽期：12 月 / 10 月 / 2 月（相對標籤起始年；小學的決賽在次年 2 月） |

年度總覽按**決賽所在年份**分組。舊年份官方沒有公布確切賽期，只能沿用同一月份，可能與實際相差數週至數月。
舊網址（`/contest/hkoi/2025/`、`/year/2025-26/`）會自動轉到現行網址。

## 賽事合併：同一個比賽不計兩次

hkoi.org 有兩個賽事其實就是 CCF 全國名單裡的同一場比賽，`harvest.py` 的
`merge_sdic()`（規則表 `ALIAS_CONTEST`）會把它們併入對應的 CCF 賽事：

| hkoi.org 名單 | CCF 賽事 | 重複率 |
|---|---|---|
| SDIC 進階級 | `CSP提高`（CSP-S） | 472 / 472 |
| SDIC 基礎級 | `CSP入门`（CSP-J） | 併入上列 |
| NOIP 香港賽區（提高組） | `NOIP提高` | 91 / 92 |
| NOIP 香港賽區（普及組） | `NOIP普及` | 36 / 36 |
| NOIP 香港賽區（無組別年份） | `NOIP` | 148 / 148 |

- **SDIC ＝ CSP-J/S 香港賽區**：官方選單與頁面標題寫成「全港中學生軟件開發邀請賽
  及 CSP-J/S」。獎項一一對應：金獎 ≡ 一等獎（185 條，另有 1 條金獎對二等獎）、
  銀獎 ≡ 二等獎（174 條）、銅獎 ≡ 三等獎（89 條）。
- **NOIP 香港賽區 ＝ CCF NOIP**：逐年比對 2017–2025 全部 100% 命中、2016 為 96%。
- 合併原則：**有 CCF 記錄（含分數、全國名次、年級）的以 CCF 為準**，
  CCF 沒有的才保留 hkoi.org 那條（例如「香港電腦教育學會 35 周年杯」這種特別獎）。
- 跨來源比對時會補姓名異體字（滙／匯、顔／顏、啓／啟、爲／為），只用作比對，
  不改動顯示的姓名。

⚠️ 因此**必須先跑 `harvest_oierdb.py` 再跑 `harvest.py`**，否則沒有 `ccf_hk.json`
可以比對（此時只做賽事歸併、不去重，站上會出現重複）。

## 評分（選手榜的排序依據）

與 OIerDb 同一套三因子加權（見 OIerDb-data-generator 的 `util.py`、`scoring.json`）：

```
評分 = Σ 時間係數 × 名次係數 × 賽事係數
時間係數 = DECAY ** (比賽年份 - 2000)                 DECAY = 1.25
名次係數 = RANK_CURVE[400 * 名次 // 總人數]            401 段百分位曲線，第 1 名 = 100
賽事係數 = CONTEST_FACTOR[賽事]                       CCF 各賽事沿用 OIerDb 的 scoring.json
```

- **名次優先**：有官方名次（CCF 的 `rankAll`/`totalAll`、IOI 的世界名次）就用名次算百分位。
  分母是該場**參賽人數**——抄自 OIerDb `/contests` 的「參賽人數」欄（`make_capacity.py`，
  存成 `oier_capacity.json`）；官方沒公布參賽人數時才用 noi.cn 的獲獎人數。
  官方沒公布個人名次的賽事（HKOI、HKGOI、小學、APIO、EGOI…）用獎項近似百分位：
  金 5%、銀 15%、銅 35%、優異 60%。
- **賽事係數**：IOI 0.6、NOI 1.0、APIO 0.4、NGOI 0.2、NOIP 0.15、
  NOIP 提高 0.1、NOIP 普及 0.06、CSP 提高 0.1、CSP 入門 0.06（以上照抄 OIerDb）；
  本站自訂 NOIP 女生賽 0.1、HKOI 高級組 0.12／初級組 0.06、HKGOI 0.06、
  小學 0.03、IOM 0.2、EGOI 0.3、SEARCC 0.15、AGAMES 0.05。未知賽事 0.02。
- **不計分**：個人特別獎（最佳年輕選手、最佳首次參賽選手…）、隊際獎、未獲獎記錄。
- **只算一次**：同一場比賽的 hkoi.org 記錄與 CCF 記錄按「賽事＋年份＋獎項」配對後只算一次。
- **時間衰減**：`DECAY = 1.25` 讓近年的比賽更重（2026 年 ≈ 2016 年的 9 倍），
  所以這是「現役實力」榜；要改成歷史累計榜，把 `build.py` 的 `DECAY` 設為 `1.0`。
- 結果輸出在 `dist/data/rating.json`（每人 `rank`、`score`、`ccfLevel` 與獎牌小計、學校、年份區間）。
- 學校榜預設按**評分**（該校所有選手評分之和）排序，可切換成**按獎牌面數**（與官方團體獎計法一致）。
- 學校頁的「歷年獎牌」折線圖是 build 時用 `results` 逐年統計畫成的內嵌 SVG（不引入圖表庫、不需要前端求值）；
  切換「全部／各賽事」只是切換預先畫好的幾張 SVG 的顯示，故仍是純靜態。少於 2 個年度有獎牌的學校不畫圖。

## CCF 評級（1–10 級）

規則見 <https://www.noi.cn/xw/2019-08-26/715369.shtml>，與 OIerDb 的
`compute_ccf_level()` 相同（`build.py` 的 `ccf_level()`）：

```
NOI            金牌 10、銀牌 9、銅牌 8
NOIP / 提高    前 10% → 7、前 20% → 6、前 50% → 4、其餘（進第二輪）→ 3
CSP 提高       同 NOIP
NOIP 普及      前 20% → 5、前 50% → 4、其餘 → 3
CSP 入門       同 NOIP 普及
```

分母 `n` = 該場參賽人數（`oier_capacity.json`），沒有時用「全國一等獎人數 × 5」
（`oier_contests.json` 的 `awards`）。與 OIerDb 顯示值在 422 位可比選手中一致 412 位，
差異來自 OIerDb 的 uid 拆分（同名兩個 uid），不是規則不同。

## 跨省選手

`harvest_oierdb_oiers.py` 從 OIerDb 線上資料取出「有香港記錄的 uid」的**全部**記錄。
其中 7 位在香港以外也有成績（李柏涵 湖南、唐浩歌 北京、劉錦城／譚健琅／黃浩楠 廣東、
彭子軒 上海、樊泊言 海南），共 26 條，以 `otherProvince` 標記並在表格顯示「內地·省名」。
因為是 uid 級判定，不會誤併同名的內地學生。

## 年級與畢業年份（推測）

官方只在 CCF（noi.cn）名單裡公布年級（`中一`…`中六` / `初一`…`高三` / `七年級`…`九年級`），
HKOI 等本地賽事的得獎名單從來只有姓名與學校。推測方法與 OIerDb 相同：

```
每條含年級記錄  畢業年 = 該場比賽所屬學年的結束年 − 年級 + 6
每人            取所有記錄中最多的那個畢業年（眾數）
任一場比賽      推測年級 = 6 − 畢業年 + 該場比賽所屬學年的結束年
```

- **10–12 月舉行的 CSP / NOIP 屬下一個學年**（OIerDb 的 `fall_semester`）。
  這一條很關鍵：若漏掉，NOIP 會與同年 CSP 差整整一年。驗證方式——
  同一人在同年 NOIP 與 CSP 的年級必須相同，處理後 200 位有多條記錄的選手中
  198 位完全自洽。
- NGOI 由 2024 年起改到秋季，同樣算下一學年。
- 不一致時取最早的一年，並在 `grades.json` 的 `votes` / `n` 標明一致度。
- 只有 CCF 記錄的選手才有年級可用；純 HKOI 選手無法推測（官方沒公布過）。

## 已知限制（重要）

1. **姓名欄不完整**：官方表格有的只列中文名，有的只列英文名（52 條）。
   因此跨賽事的選手串連只能靠「中文名 + 校名」比對；跨來源配對時會補上異體字對照
   （滙／匯、顔／顏、啓／啟、爲／為），但只用作比對，不改動顯示。
2. **沒有唯一識別碼**：官方從不公示學生編號，同一人只能靠姓名＋學校推斷。
   目前採保守策略：同名不同校**不自動合併**，`QA.md` 列出 59 組待人工確認。
3. **NOIP 缺 2019**：官方站上沒有該年度頁面（已驗證 404），CCF 名單同樣沒有 2019，非抓取遺漏。
4. **HKOI 2019/20**：因疫情決賽取消，官方不設獎項，資料如實留空。
5. **校名異體**：來源有打字錯誤（如「陳瑞琪」vs「陳瑞祺」、「聖約瑟」vs「聖若瑟」），
   已在 `harvest.py` 的 `SCHOOL_ALIAS` 中修正 10 組；`schoolZhRaw` 保留原值可回溯。
6. **外部比賽的空白獎項**：官方表格中部分選手獎項欄為空（未獲獎的參賽隊員），
   本資料集如實保留 `award = ""`。
7. **IOI 官方檔案收錄不全**：hkoi.org 的港隊名單 139 人年，IOI 官方統計站
   （stats.ioinformatics.org）只查得到 120 人的成績。1992–2004 年間 hkoi.org
   每年列 4 人，官方站往往只有 1–3 人，推測 hkoi.org 連同後備／隨隊成員一併列出。
   這 19 人年保留 hkoi.org 的獎項，分數與名次留空。
8. **APIO 有分數但沒有姓名**：APIO 官方逐題分數是公開的（例如
   `github.com/apio2025/apio2025_ranking` 的 `scores`），但公布時一律用
   國家／地區代號（`HKG_1` … `HKG_30`），不含姓名，代號與姓名的對應表不對外公開。
   APIO 中國區名單又只收中國選手（已逐行核實，393/400 行無香港）。
   因此本資料集只有 hkoi.org 公布的 APIO 獎項，沒有可歸屬到個人的 APIO 分數。

## 重新收割

```powershell
cd D:\hkoj\reference\oierdb-hk
Remove-Item cache -Recurse -Force   # 要重抓時才清
python harvest.py      # 抓取 + 正規化 + 輸出（會併入 SDIC，需先有 ccf_hk.json）
python qa.py           # 品質檢查 -> data/QA.md
python export_csv.py   # 按賽事拆 CSV
python rank.py         # 無評分排名 -> data/RANKING.md + ranking.json
python score.py        # 官方分數驗證 + 綜合榜 -> data/SCORING.md + scoring.json
python harvest_stats.py # 解析官方統計 PDF -> data/stats.json + stats.csv
python harvest_noi.py    # 抓 noi.cn 2025/2026 名單 -> data/noi_hk.json
python harvest_oierdb.py # 由 OIerDb raw.txt 還原全量港生成績 -> data/ccf_hk.json
# OIerDb 線上資料（跨省記錄、CCF 等級、全國獲獎人數、首拼）：
#   curl -s -o data/oierdb/static.json https://oier.api.baoshuo.dev/static.<sha7>.json
#   curl -s -o data/oierdb/result.txt  https://oier.api.baoshuo.dev/result.<sha7>.txt
#   （sha7 取 https://oier.api.baoshuo.dev/static.info.json 與 result.info.json 的 sha512 前 7 位）
python harvest_oierdb_oiers.py # -> oier_hk_oiers / oier_contests / oier_surnames
python make_capacity.py  # 抄 OIerDb 各場參賽人數 -> data/oier_capacity.json
python harvest_ioi.py    # 抓 IOI 官方統計站 -> data/ioi_hk.json
```

`harvest.py` 收尾會把 `zh/external-competitions` 與 `en/external-competitions`
逐行對齊，用英文版補上外部比賽記錄的英文姓名與校名（367 條）——
IOI 成績要靠英文姓名比對，沒有這一步會對不上。

## 授權與合規

- 原始資料著作權屬香港電腦教育學會 / 教育局（HKOI 主辦單位），本資料集僅為**公開資訊的結構化整理**。
- 使用時請註明來源 `https://hkoi.org/`。
- 若要做成公開網站，須提供更正與下架通道（見 `DEPLOY.md` 的合规做法）。
