# 單元即時小測與兩層關卡

學員要同時過兩層關卡才能一路學下去:

1. **單元即時小測**:有 `checks` 的教學單元,結尾 2~3 題,**必須全對**才算完成、才能開下一個單元。
2. **章末小測驗 80 分**:每章最後的 `role=post` 章末小測驗(`pass_score` = 80,5 題至少答對 4 題),通過才能開**下一章**的任何單元(含最後的「期末總複習」章)。

## 資料格式

```php
['title' => '原理:歐姆定律', 'type' => 'text', 'content' => "【電壓與電流】\n…", 'config' => ['check_take' => 2],
 'checks' => [
   ['type' => 'single', 'difficulty' => 1, 'body' => '…', 'options' => ['甲', '乙', '丙'], 'answer' => [1],
    'explanation' => '為什麼…', 'hint' => '建議重讀:【電壓與電流】', 'reference' => '可選'],
   // 題庫 3~6 題
 ]]
```

- `type` 允許 text / lab / video(其他類型不支援);`checks` 不可放在 role=pre/post/final 的 quiz。
- 題型:single / multiple / boolean / fill / order,欄位同一般題;另有必填 `hint`(答錯時顯示,**不得洩漏答案**)。
- `config.check_take`:每次抽幾題,2 或 3(預設 3;題庫不足取全部)。
- 匯入(`seedCourse`)後存進 `questions`,`is_check = true`;一般測驗的 `Lesson::questions()` 不含這些題,`Lesson::checks()` 才是小測題庫。
- hint 含【小標題】且教材有同名【小標題】時,畫面會加「回到這一段」連結(教材每個小標題有 `#sec-N` 錨點)。

## 學員會看到什麼

- 單元內容下方的「即時小測」:抽 take 題(順序、選項順序每次打亂;抽題存在 session,提交只批改這組題,不接受客戶端指定)。「標記完成」按鈕被隱藏,「下一單元」在通過前停用並說明原因。
- 全對:完成單元、得 XP、顯示每題解析、下一單元可用。
- 有答錯:不完成;逐題顯示對/錯,**不顯示正確答案**,錯題顯示 hint;按「重讀後重新作答」重新抽題(盡量抽到不同題)。使用 AJAX 就地更新,無 JS 退回整頁表單。
- 錯題記入錯題本(通過該單元前,錯題本也不顯示這些題的答案與解析);每次作答記在 `quiz_attempts`。
- 小柚在通過前不提示小測答案(「先靠自己試試看,答錯會有提示;通過後我可以幫你講解」)。
- 目錄:🔒 未解鎖、✅ 完成、🧠 小測標籤、章末小測驗「需 80 分」;被鎖的下一章整章顯示 🔒。

## 鎖定規則

- 只有「有 checks 的單元」與「章末小測驗」會造成鎖;沒有 checks 的單元不阻擋。
- 鎖只往後生效,隨時可回頭看已解鎖的單元;同章其他單元在章末小測驗未過時仍可複習。
- 牛刀小試(role=pre)不受單元小測的鎖,也不造成鎖(但被「章鎖」鎖住的下一章,整章含牛刀小試都暫時不可進)。期末考不造成鎖。
- 管理員與課程負責講師預覽不受鎖。
- 直接輸入被鎖單元的網址 → 導回擋住他的單元(或章末小測驗)並提示。伺服器端 `complete` 對尚未通過的有小測單元回 422。

## 安全閥(避免答案有誤時永久卡住)

狀態記在 `unit_check_states`(不是 session):累計未通過次數 `fail_count`。

- ≥ 3 次:答錯的題目顯示解析(「看解析再重讀」)。章末小測驗結果頁本來就顯示解析。
- ≥ 6 次:出現「先繼續,稍後補考」(章末小測驗為「先進入下一章,稍後補考」)。按下後 `needs_review = true`,**不給 XP**,解除鎖,並列入學習中心「待補考單元」。
- 補考通過:清除 `needs_review`、發 XP。

## 學習中心與後台

- 學習中心「單元小測」區:通過的小測單元數、一次就全對的比例、待補考單元清單。
- 後台課程學員頁:有小測的課程多一欄「小測通過」(通過單元數與一次全對率)。

## 內容撰寫準則

- 因為要 100% 才能前進,題目必須**無歧義**,只考該單元**剛教的內容**,不考延伸或陷阱。
- fill 題的 `answer` 要收錄各種合理寫法(大小寫不分,但空格、全半形、單位寫法要列出)。
- hint 只指方向(哪個小標題、哪個概念),不要出現答案文字。
- 題庫 3~6 題,各題難度相近,任意抽 2~3 題都應能代表本單元重點。
- 章末小測驗 `pass_score` 必須是 80。

## 驗證器

`php tools/validate-chapter.php <檔案…>`:檢查 checks 題數 3~6、每題必填欄位、題型、`check_take`、hint 不洩漏答案、只能放 text/lab/video。加上 `--require-checks` 會要求標題以「原理:/觀念教學:/公式與計算:/觀念與計算:」開頭的 text 單元都必須有 checks。role=post 的 `pass_score` 必須是 80。
