# 牛刀小試(章前測)與章末小測驗(章後測)

每章第一個單元是「牛刀小試」(不計分、看學前懂多少),最後一個單元是「章末小測驗」(與牛刀小試逐題配對)。學員做完章末小測驗後會看到前後比較。機制只依 `config.role` 與 `question.pair_key`,任何課程的測驗單元都能用;沒有 role 的舊測驗完全不受影響。

## 章節檔格式

```php
['title' => '牛刀小試:這章你懂多少', 'type' => 'quiz', 'pass_score' => 0, 'xp' => 5,
 'config' => ['role' => 'pre'],
 'questions' => [ ['type' => 'single', 'difficulty' => 2, 'pair' => 'k1', 'body' => '…', 'options' => [...], 'answer' => [0], 'explanation' => '…', 'reference' => '第1章 · 觀念教學:…'], /* 共 5 題 */ ]],
// … 觀念教學、實驗、公式與計算、課後重點整理 …
['title' => '章末小測驗:學會了嗎', 'type' => 'quiz', 'pass_score' => 60, 'xp' => 20,
 'config' => ['role' => 'post'], 'questions' => [ /* 5 題,pair 鍵與牛刀小試一一對應 */ ]],
```

- `config.role`:`'pre'` 或 `'post'`;只對固定題的 quiz 有效,自適應測驗(`config.adaptive`)不處理 role。
- `pair`:匯入時存到 `questions.pair_key`(migration `2026_11_10_100000_add_pair_key_to_questions`)。同一個觀念的前後兩題用同一個鍵;對應題「同觀念、同難度、換情境與數字」,題型可以不同。
- 牛刀小試必須是本章第一個單元,章末小測驗必須是本章最後一個單元(在課後重點整理之後)。

## 驗證規則(`php tools/validate-chapter.php <章節檔>`)

適用於任何有 role 的章節(格式檢查);**國中理化(`junior-high-science/`)每章必須有 pre 與 post**,高中物理暫不強制,但有就檢查。

1. role 只能是 pre/post,只能用在 quiz,不可與 `adaptive` 並用。
2. 有 pre 就必須有 post(反之亦然),各只能一個。
3. pre 是第一個單元、post 是最後一個單元;標題分別以「牛刀小試:」「章末小測驗:」開頭。
4. pre 的 `pass_score` 必須為 0。
5. 兩者各剛好 5 題,每題有 `pair`(非空字串);pair 鍵在各自單元內不可重複;兩邊的 pair 鍵集合必須相同。
6. 對應題的 `difficulty` 必須相同(`type` 可以不同)。
7. 物理課(高中物理、國中理化):「去掉最後的 role=post 章後測」之後,最後一個單元必須是 type=text 的「課後重點整理:」。
8. 既有規則照舊(每個測驗至少 3 種題型、reference 單元名稱要對得上本章…)。

## 學員看到什麼

- **目錄/單元頁/課程頁章節清單**:🎯 牛刀小試、✅ 章末小測驗 標籤;單元頁上方有說明句。牛刀小試不顯示「及格」字樣與紅色失敗狀態。
- **牛刀小試作答後**:「你答對 X / 5 題」+ 鼓勵 + 本章觀念地圖(各題 reference 的單元名稱)。**不顯示正確答案、解析、每題對錯**。仍記錄 QuizAttempt、一定完成單元(XP 5)、**不進錯題本**。
- **章末小測驗作答後**:正常評分(60 分及格,顯示對錯與解析),加一張「學習成效」卡片:學前% → 學後%、進步/持平/低於學前(退步時語氣是「再複習一下標示的觀念」);逐觀念表格(學前 ✓/✗、學後 ✓/✗、狀態)。狀態:
  | 學前 | 學後 | 狀態 |
  |---|---|---|
  | ✗ | ✓ | 新學會 |
  | ✓ | ✓ | 一直都會 |
  | ✓ | ✗ | 還要加強 |
  | ✗ | ✗ | 仍待加強 |

  「還要加強/仍待加強」會附上該題 reference 對應單元的複習連結。沒有牛刀小試紀錄時說明沒有前後比較,並連回牛刀小試。
- **學習中心**:「學習成效」區塊,最近 5 筆(課程、章名、學前% → 學後%、進步);沒資料時顯示引導文字。
- **後台課程學員頁**:有配對資料的課程多一欄「平均進步」。

## 成效怎麼計算

- **學前基準 = 該學員在牛刀小試「最早」的一次作答**。理由:第一次才能反映真實的學前程度;學員重做牛刀小試(看過觀念地圖後)不應洗掉基準。因此重做仍會記錄 attempt,但比較不使用它。
- **學後 = 章末小測驗「本次」作答**(學習中心與後台取最近一次)。
- 進步 = 學後分數 − 學前分數(百分制)。逐觀念以 `pair_key` 配對;學前的逐題對錯由第一次 attempt 儲存的作答用題目的 `check()` 重算。
- 後台「平均進步」= 學員各章(進步)的平均,只計算同時有 pre 第一次與 post 紀錄的章。

## 防洩題

- 牛刀小試結果頁不輸出答案、解析、逐題對錯;錯題本不記錄。
- 小柚 AI 導師對 pre 單元一律回覆「這是學前測,先靠自己試試看」,不送給模型、不查教材(同章其他單元的教材本來就不含測驗答案)。

## 隱私

成績只有學員本人與其負責講師/管理員(可管理該課程者)看得到;排行榜與其他學員不會看到前後測分數。

## 已知限制

- 若學員在學完本章後才補做牛刀小試,學前基準會被「學後」污染(系統無法判斷);只能靠頁面說明與流程引導。
- 前後測的題目若在上線後被改動,舊 attempt 的重算結果以目前題目為準。

## 適用範圍:所有課程

牛刀小試、章末小測驗、期末考的機制只依 `config.role` 與 `question.pair_key`,**適用所有課程**(高中物理、國中理化、Linux 與容器系列、AI 系列……)。驗證器對 `database/seeders/courses/` 底下的 `chNN.php`(每章必須有 pre/post)與 `final.php`(每門課必須有,高中物理放在各學期資料夾)強制檢查;還只有規劃導覽(plan.php、沒有章節檔)的章節不會被檢查。驗證器只是作者工具,不影響種子匯入。

## 期末考(role=final)

每門課的最後一章「期末總複習」(`<課程資料夾>/final.php`,由課程包裝檔自動載入為最後一章)包含 ≥3 個 text(至少一個標題以「總複習:」開頭)與最後一個單元:期末考。

```php
['title' => '期末總複習考:全課程', 'type' => 'quiz', 'pass_score' => 60, 'xp' => 50, 'config' => ['role' => 'final'], 'questions' => [ /* 每題 reference「第N章 · 單元名稱」指向該題所屬章 */ ]],
```

驗證規則(`final.php`):
1. 章標題「期末總複習」;最後單元是固定題(非 adaptive)、`role=final`、標題以「期末總複習考:」開頭、`xp` 50、`pass_score` 60;本章不可有 pre/post;`role=final` 只能出現在 `final.php`。
2. 題數介於 `max(28, 3×一般章數)` 與 `5×一般章數` 之間(章數由同目錄 `chNN.php` 數量推得;章數很少、上限會小於下限時,上限放寬為下限 +4,例如 2 章為 28~32 題)。例:16 章 → 48~80 題。
3. 每章至少 3 題;每題 reference 的章次必須在 1..一般章數內,單元名稱必須存在於該章(可引用任何章)。
4. 全卷難度分布 1:2:3 約 3:5:2(各難度佔比與 30%/50%/20% 差距不超過 12 個百分點);題型至少 3 種。

學員看到什麼:
- 🏁 期末考標籤(目錄、單元頁、課程頁章節清單;最後一章「🏁 期末總複習」),單元頁說明「整門課的總驗收:共 N 題,涵蓋所有章節;作答後會公開答案並分析各章表現」。
- 作答後:總分與「通過/再接再厲」(及格 60,語氣正向);**各章答對率**(依 reference 的第N章分組,長條圖),標出最弱 2 章(答對率 <100% 者)並連到該章「課後重點整理」(沒有則連到該章第一個單元);**逐題對錯與完整解析**(期末考作答後公開答案,不同於牛刀小試);若有各章牛刀小試的第一次作答,加「整門課成長」卡(各章學前平均 → 期末,只計有紀錄的章),沒有就不顯示。
- 可重考,每次都記錄;學習中心「學習成效」顯示每門課期末考的最高分與是否通過;後台課程學員頁多一欄「期末考」(最高分,沒做顯示 —)。
- 通過期末考不另外發徽章,沿用既有結業邏輯(完成所有單元即結業)。
- 小柚:交卷前對期末考與牛刀小試同樣回覆「先靠自己試試看」;交卷後(至少一次作答)可正常講解。


## 章末小測驗是進入下一章的關卡(80 分)

- 章末小測驗(role=post)的 `pass_score` 必須是 **80**(5 題至少答對 4 題)。通過後才能開啟下一章的任何單元;第 1 章永遠開放;牛刀小試與期末考不造成鎖。
- 未通過時同章其他單元仍可自由複習;結果頁用正向提示並沿用成效卡片的「建議複習」連結,「重新作答」時題目與選項順序會打亂(配對鍵不變)。
- 安全閥:累計未通過 ≥ 6 次可「先進入下一章,稍後補考」(不給 XP,列入學習中心待補考,補考通過後清除並發 XP)。
- 詳見 `docs/unit-checks.md`(兩層關卡:單元小測全對、章末 80 分)。
