OLE-QS — 線上題庫系統

把國中考古題的 PDF／掃描檔轉成結構化題庫，依課綱與教科書章節分類， 供教師檢索、自由組卷、匯出考卷。

其他專案要取用題目：看 docs/USING_THE_BANK.md。 題目快照在 data/export/，取用模組是 client/oleqs_bank.py，不需要架站或金鑰。

快速開始（選題組卷平台）

pip install -r requirements.txt
python -m playwright install chromium        # 下載 PDF 用；已有 Chromium 時改設 OLEQS_CHROMIUM=<路徑>

# 1) 載入題庫（data/bank 全部約 5,500 份卷、20 萬題，約需 1～2 小時；可重複執行）
python -m apps.api.importer data/bank/

# 2) 啟動
uvicorn apps.api.main:app --host 0.0.0.0 --port 8000
# 開啟 http://127.0.0.1:8000

或用 Docker（例如放在 Synology NAS 上）：docker compose up -d --build， data/ 整個掛進容器（oleqs.db、assets/、curriculum/）。

功能：

• 題庫選題：科目 → 子科 → 冊別 → 版本 → 章節（英語為跨版本文法主題），加題型、答案、附圖、學年度、關鍵字篩選； 點題目即勾選，可本頁全選。題籃存在瀏覽器。
• 組卷匯出：標題、副標題、試題卷／答案卷／教師解答卷、單欄／雙欄、字級、作答行數、依題型自動分大題、 逐題配分與排序；右側即時預覽，下載 PDF（headless Chromium 排版，頁尾頁碼）或直接列印。
• 我的試卷：存檔、載入再編輯、直接下載 PDF。
• 每題與卷末固定印出處（授權條件，不可關閉）；AI 作答的答案在解答卷上會標示未經人工確認。

圖檔預設放在 data/assets/，可用 OLEQS_ASSETS 指定；資料庫預設 data/oleqs.db， 可用 OLEQS_DB 指定。圖檔不進版控，需要圖的話得重跑擷取。

處理新的考卷

考卷目錄請照這個慣例擺，來源標註大半靠它（見下方「目錄慣例」）：

學年度／學期-次數／縣市／學校.pdf     例如 112/1-2/彰化/埔心.pdf

# 原生數位卷 → 結構化題目 YAML（含答案掛載與圖形切出）
python scripts/extract.py "考古題目錄" -o data/bank --assets data/assets

# 整批只有一科／一個年級，而卷面沒印時，明示告訴它（不要讓它猜）
python scripts/extract.py "考古題目錄" -o data/bank --subject 數學 --grade 7

# 讓同一所學校在題庫裡只有一個校名（跨批次累積後才需要）
python scripts/canonicalize_schools.py data/bank

# 擷取結果的結構驗證（配分總和、題號連續性、選項、共用素材…）
python scripts/validate_extraction.py data/bank/*.yaml

# PDF → 頁面影像 + 文字圖層 + 圖形（自動判斷原生數位 / 掃描 / 空白頁）
python scripts/pdf_ingest.py "考古題目錄" -o out/ingest

# 從答案卷解析「題號 → 答案」
python scripts/parse_answer_key.py "考古題目錄" -o out/answer_keys

# 用多個模型交叉作答，只有不一致的才需人工判定
python scripts/generate_answers.py out/extracted.yaml --figures out/ingest/xxx/figures

目錄慣例

112/1-2/彰化/埔心.pdf ＝ 112 學年度、第 1 學期第 2 次段考、彰化縣埔心國中。

1-2 是「學期-次數」，不是「年級-學期」 —— 一個學年只有兩個學期，卻有 1-3、2-3 這種目錄；而卷頭寫得很清楚：「111學年度第一學期第二次段考」。 年級不在路徑裡，只能從卷面取得，抓不到就整份跳過（來源標註不可缺）。

目錄

apps/api/          FastAPI 後端 + 網頁介面
  models.py        資料模型（來源標註為必填欄位）
  db.py            SQLite + FTS5 trigram（中文子字串搜尋）
  importer.py      擷取結果 → 資料庫
  mathfmt.py       Markdown + 行內 LaTeX → HTML
  export.py        試題卷 / 答案卷 / 教師解答卷
  static/          單頁介面（檢索 → 題籃 → 匯出）
scripts/           擷取管線工具
data/bank/         題庫本體（擷取結果，匯入資料庫的來源）
data/samples/      黃金測試集（人工逐題確認過的兩份，回歸測試基準）
docs/STATUS.md     開發現況與關鍵決策（接手先讀這份）
docs/              開發計畫與各次 PoC 實測報告

授權與來源標註

題目取自公開試題。依法律諮詢意見，公開試題可使用，但須保留來源標註。

出處掛在題目上，不是掛在整份卷上。 這點很關鍵 —— 題庫的用途就是把不同卷的題目 重新組合，若出處只存在文件層，重組後就對應不回去了。

實作為 QuestionSource：匯入當下把來源欄位快照到每一題（含它在原卷的題號）， 一題可以有多筆出處。顯示格式刻意極簡 —— 出處要跟著每一題走，冗長會蓋過題目本身：

[台中 大業 113]                        單一來源
[台中 大業 113] [另見 台中 向上 114]      去重合併後的多重來源
[台中 大業 113] [改編 台中 大業 113]      改編題

縣市與校名簡稱由完整校名推導（split_school），完整校名、學期、次數、年級、科目、 原卷題號都仍完整存在資料庫，需要時可查。這樣三種情況才成立：

情況	為什麼需要題目層的出處
去重合併	同一題出現在多份卷，合併後每個來源都要保留，外鍵只能留一個
改編題	改過數字或敘述後不再屬於原卷，應記為「改編自 X」
原文件被改或被刪	出處已快照，不會跟著變動或消失

其他約束：

• 快照欄位（學校、考試名稱、學年度、年級、科目）不可為空， 匯入時缺少即拒絕寫入（importer.py）。
• 題目不隨文件級聯刪除 —— 清理匯入紀錄不會毀掉已被考卷引用的題目。
• 匯出的每一題底下固定印自己的出處，不提供關閉選項； 卷末再彙整本卷用到的所有來源（export.py）。

品管策略：寧缺勿濫，不修補

題庫的經濟結構與教科書不同 —— 來源卷很多，題目是可替換的， 丟掉一題的成本遠低於人工修好它。因此擷取有疑慮的題目直接剔除，不做人工校對。

apps/api/quality.py 的閘門只問一件事：這題能不能被正常作答。不做內容好壞的判斷。

剔除條件：題幹殘缺、公式未閉合、選項數不對或內容空白、標籤重複、 圖表資產缺檔、共用素材遺失、擷取時標記辨識不清、答案有疑義或個數不符。

「沒有答案」不是剔除條件 —— 那是來源沒附答案卷，補得回來； 「答案不明確」才是，那是題目本身有疑義，補不回來。

被剔除的題目不刪除，連同原因留在資料庫：

• 剔除率是管線健康度指標。從 8% 跳到 40% 代表管線壞了，不是卷變難了。
• 剔除原因可回頭改進擷取，而不是只知道「少了很多題」。

匯入時會即時回報：

✅ 113-dayeh-g7-math-s1e1.yaml  →  收錄 27/29 題（93%）
     剔除 1 題：擷取時標記辨識不清（N 處）
     剔除 1 題：資產 FIG_PN_N 沒有圖檔或結構化內容

目前狀態

題庫已收錄 1008 題，涵蓋 8 個縣市、5 個科目，收錄率 84%。 最大缺口是答案覆蓋率只有 20%（多數來源是純題目卷，沒附答案卷）。

👉 接手開發請先讀 docs/STATUS.md —— 那份記錄了現況、關鍵決策的理由，以及下一步的優先序。 開發計畫的部分內容已被後續實測推翻，兩份 PoC 報告比計畫本身更接近現況。