# NEXUS THPT Practice + Lecture Creation Standard

Ban nay la chuan bat buoc khi tao bai THPT / Grade 10 Entrance cho NEXUS Test Importer.

## 0. UTF-8 / mojibake guard

Bao toan dau tieng Viet va Unicode dung UTF-8. Khong sua text chi vi PowerShell output nhin bi loi font/mojibake. Neu nghi encoding sai, phai verify bang Node byte check hoac browser render theo `project memory/architecture/UTF8-MOJIBAKE-PREVENTION-STANDARD.md`. HTML output phai co `<meta charset="utf-8">`.

Dung tai lieu nay trong chat moi bang cach noi:

```text
Hay doc va tuan thu NEXUS THPT Practice + Lecture Creation Standard. Tao HTML nguon dung chuan parser de import vao Test Importer, skill THPT / Grade 10 Entrance. Practice phai dung flow NEXUS: hoc sinh lam bai -> Submit -> moi hien dap an va giai thich chi tiet. Sau khi import co the Make Lecture va Assign to Classroom de giao vien giang bai, highlight, take note, save va dong bo sang Student Lecture.
```

## 1. Muc tieu

Tao mot HTML nguon sach, de parser chuyen thanh `testData v2`, sau do engine NEXUS render thanh Practice dung chuan:

`Student lam bai -> Submit -> hien score -> mo tung cau de xem dap an + giai thich chi tiet`

HTML nguon chi la vat lieu import. Khong tao mot trang tu cham doc lap.

Sau khi bai Practice da nam trong Content Library, co the dung `Make Lecture` de tao ban Interactive Lecture cho giao vien giang truc tiep. Lecture giu nguyen kien thuc, dap an, explanation va layout, nhung bo Submit flow; giao vien bam icon key de reveal, highlight, take note, keo note, bam Save de dong bo sang hoc vien.

## 2. Luat vang

1. Moi cau phai co dap an may doc duoc.
2. Moi cau phai co explanation chi tiet may doc duoc.
3. Dap an va explanation phai an truoc Submit trong Practice.
4. Khong tao nut `Check`, `Show answer`, `Reset`, `Try again`, `Print`, hoac script tu cham trong HTML nguon.
5. Khong de dap an lo ngay trong phan cau hoi hoc sinh nhin thay.
6. Khong minify HTML. HTML phai readable de GV/Codex sua duoc.
7. Khong rut gon passage, cau hoi, option, answer key, explanation neu user khong yeu cau.
8. Neu thieu dap an, hinh anh, evidence, IPA, hoac source khong ro, phai flag `[MISSING: ...]`, khong doan mo.
9. Sau import, ban dung chuan trong Content Library phai la `testData v2`, `generator: "v2"`, `htmlContent: null`.
10. Community Class Practice dung chuan la bai do NEXUS engine render va chi reveal sau Submit.

## 2.1. Explanation depth v3.0 - bat buoc

Moi `.explanation` trong HTML nguon phai du chi tiet de sau khi import:

`Practice: hoc sinh Submit -> moi xem dap an + giai thich`

va sau khi `Make Lecture`:

`Teacher bam key -> hien dap an + giai thich du de giang tren lop`.

Khong duoc viet explanation 1-2 dong cho co. Moi cau phai tach ro:

- `Answer`: dap an dung.
- `Vi sao dung`: cong thuc, collocation, ngu canh, evidence, hoac logic hoi thoai.
- `Loai tru`: voi MCQ / cloze / reading-mcq / sign, phai loai tru tung dap an sai, moi option mot dong.
- `Evidence`: voi reading/listening true-false hoac reading-mcq, phai dan dung cau trong passage/script va so sanh statement voi evidence.
- `Translation`: moi cau phai co `Dich:` tu nhien bang tieng Viet; pronunciation/stress co the de `N/A`.

Quy tac theo dang cau:

- `mcq`, `cloze`, `reading-mcq`, `sign`: giai thich vi sao option dung khop grammar/collocation/context; loai tru 3 option sai tung dong.
- `tf`, `reading-tf`, `listening-tf`: co evidence, so sanh evidence voi statement; neu False phai chi ro thong tin nao trai voi source.
- `word-form`: xac dinh tu loai can dien, giai thich vi sao chon dang cua root, va them `WORD FAMILY TABLE` toi thieu 4-5 dong gom Word / POS / IPA / Meaning (VN). Neu cung root lap lai trong cung file thi dung `WordFamily-See-QN`.
- `dict-fill`: phai co `BAM-KHUNG check` liet ke collocations/phrases trong dictionary entry, giai thich vi sao cum 2-3 tu duoc chon, va `RejectedCandidates` cho tung ung vien khong khop.
- `rewrite-A`: answer va acceptable alternates phai la phan duoi sau prompt, khong lap lai dau cau cho san. Giai thich cau truc ap dung va neu co the them 2-3 alternates hop le.
- `rewrite-B`: answer la cau hoan chinh tu dau den cuoi, moi alternate phai chua tu goi y dung dang chia.

Neu source thieu dap an/evidence/hinh anh/IPA hoac co dau hieu dap an khong sach, khong duoc doan mo. Ghi ro `[MISSING: ...]` hoac flag QA trong explanation.

## 2.2. Question-type explanation principles v3.1 - bat buoc

Nhung rule nay sinh ra tu cac loi da gap khi tao 20 de THPT. Copy Codex/Gemini phai nhung ro de AI khong dung mot mau giai thich chung cho moi dang cau.

- `pronunciation`: chi can IPA/sound evidence. Option phai co `<u>...</u>` dung phan duoc hoi. Explanation liet ke IPA 4 option, am cua phan gach chan, va ket luan option khac. Khong them nghia, ngu phap, collocation, hay doan "Vi sao dung/Loai tru" dai dong. `Translation: N/A`.
- `stress`: liet ke IPA/stress position cua 4 option va ket luan tu co trong am khac. Khong giai thich nghia/ngu phap. `Translation: N/A`.
- `mcq`, `cloze`, `sign`, `reading-mcq`: phai co ly do option dung va loai tru tung option sai, vi ban chat cac dang nay la chon giua cac phuong an co nghia/ngu phap/evidence.
- `reading-tf` / `tf`: phai co evidence ro, so sanh statement voi evidence, va neu FALSE thi noi chinh xac diem nao trai source.
- `cloze`, `reading`, `dict-fill` dai: bat buoc de source o level section bang `ClozePassage:`, `ReadingPassage:`, hoac `WORD ENTRY` + `DictEntry-Source:` de engine render hai cot co scroll rieng. Khong nhet passage/entry vao explanation.
- `word-form`: dap an chi la phan can dien trong blank. Phai co `Root:`, `TargetPOS:`, IPA cua root va answer trong `WORD FAMILY TABLE`, ly do POS, dich cau hoan chinh. Neu la tu thong dung, tu tao/verify IPA bang agent hoac dictionary; khong de `[MISSING: IPA]` cho qua.
- `dict-fill`: BLOCK 2 phai co `WORD ENTRY` that, `Word:` la headword thuc su khop voi `DictEntry-Source`, khong duoc de `Word: dictionary entry`. Hoc sinh duoc xem entry truoc khi lam, nhung stem khong duoc chua san answer phrase. Blank phai cover dung cum answer. Vi du `My sister is a real ____; ...` thi answer la `bargain hunter`, khong phai `My sister is`.
- `dict-fill`: explanation phai co `BAM-KHUNG check`, vi sao cum 2-3 tu trong entry khop ngu phap/ngu canh, va `RejectedCandidates` cho cac cum trong entry khong khop. Khong tao answer bank/chip lo dap an truoc Submit.
- `rewrite-A`: `Answer:` va moi `AcceptableAlternates:` chi la tail answer sau prompt; khong lap lai prompt.
- `rewrite-B`: `Answer:` va moi alternate la cau hoan chinh, co tu goi y dung dang chia.
- Fill / word-form / dict-fill / rewrite: moi bien the dung phai nam trong `AcceptableAlternates:` ro rang. Khong dung shorthand `forest(s)`, `behavio(u)r`, `difficulty (in)`, `organization/organisation`, hoac `A/B`.
- Truoc khi giao, scan self-answer items de dam bao full answer khong lo san trong `Question:` text.

## 3. Chon format

### Format D - THPT 5-block plain text (recommended in Test Importer)

Dung mac dinh cho nut `THPT / Grade 10` trong `ai-generator.html`.

Flow dung UI:

`Copy Gemini/Codex prompt -> AI tra ve 5-block plain text -> Test Importer / Plain text -> Parse THPT Plain Text -> upload cac IMAGE ALERT slots -> Save testData v2`

Bat buoc:

- Output la plain text, khong phai HTML/JSON.
- Bat dau bang `⚠️ IMAGE ALERT:`. Moi hinh can upload phai co dong rieng voi Q/range dong:
  - `* [IV. SIGNS — SIGN Q7]: SIGN — circular red-bordered no-smoking sign`
  - `* [VI. READING — DIAGRAM Q24-Q25]: DIAGRAM — labelled recycling process`
- Khong hardcode Q15/Q16. Vi tri hinh phai duoc suy tu source moi lan tao bai.
- Trong BLOCK 4, moi cau dung marker `--- QN ---` va `[TYPE: ...]`.
- Parser doc Roman heading `## I. ... (pts)`, `Instruction:`, `ClozePassage:`, `ReadingPassage:`, answer/explanation/translation.
- Cau co hinh phai co mo ta ro trong `SignDescription:` neu la sign/notice/diagram/photo/map, de UI hien nhan dung target.
- BLOCK 5 `Q1: ...` phai khop BLOCK 4.
- `AcceptableAlternates:` phai explicit, khong dung shorthand `forest(s)`, `behavio(u)r`, `A/B`.
- Copy Gemini va Copy Codex prompt phai nhung TO G10 quality gate:
  - pronunciation/stress co dung `<u>...</u>` cho underlined part, IPA day du khi co IPA, va dung mot odd-one-out;
  - pronunciation/stress explanation phai dung ban chat: pronunciation chi IPA/sound evidence, stress chi stress-position evidence, khong viet MCQ-style loai tru dai dong;
  - MCQ co 4 options khac nhau va chi 1 dap an dung;
  - word-form co Root/TargetPOS, IPA root + answer, Word Family Table, va khong de missing IPA cho tu thong dung neu co the verify;
  - dict-fill co WORD ENTRY headword that, DictEntry-Source khop entry, khong lo answer trong stem/answer bank, va RejectedCandidates ro;
  - grammar/vocabulary/dialogue/translation dung chuan Grade 10, khong dung tu khong ton tai hoac logical contradiction;
  - section Roman numeral/title/pts dung, tong diem = 10.0;
  - rewrite answers/alternates khong dung ngoac tuy chon nhu `(that)`, `(in)`, `(should)`;
  - explanation phai loai tru option sai, co evidence khi co passage, dich Viet tu nhien, va khong viet disclaimer kieu "cau nay bi loi de".

Parser chinh: `js/general-practice-text-parser.js` -> `parseThptPlainText()`.

Save result:

- `skill: "thpt"`
- `testData.meta.parser: "thpt-plain-text"`
- `testData.meta.sourceFormat: "ai-plain-text"`
- Neu co `IMAGE ALERT`, `testData.meta.visualAssets[]` tao upload slot co nhan `Q/range`, `role`, `description`, `required`.
- Active save bi chan cho den khi cac required visual slots duoc upload. He thong nen compress image, luu Media Library, gan vao dung cau hoi.

Format A ben duoi chi giu cho legacy HTML Teaching Mode / Practice Mode v1.

### Format A - De 40 cau / full mock / mini mock nhieu phan

Dung khi bai giong de tuyen sinh Grade 10, mock test, section-only practice, hoac de 40 cau.

Bat buoc:

- Moi section nam trong `.glass-panel`.
- Section title dung `h2`, giu diem neu co, vi du: `I. Choose the best answer. (3.5 pts)`.
- Moi cau dung `.question-block`, co `id="qN"` neu co the.
- MCQ dung `.quiz-option` hoac `.nx-option`.
- Fill / word form dung `input.inline-fill` hoac `input[data-correct]`.
- Rewrite dung `input.rewrite-input`.
- Explanation nam trong `.explanation` hoac `.nx-explanation-data`, va phai `display:none`.

Parser chinh: `js/thpt-parser.js`.

### Format A-L - THPT / mock test co Listening

Dung khi bai van la THPT-style mock test 40 cau, nhung cau 1-4 la Listening va co file audio.

Muc tieu: tach rieng parser de khong lam anh huong luong THPT da co.

Bat buoc:

- Van dung `skill: "thpt"` va format cau hoi cua Format A.
- HTML nguon phai co marker parser rieng:

```html
<meta name="nexus-parser" content="thpt-listening">
<meta name="nexus-audio-url" content="/audio/path/to/file.mp3">
<body data-nexus-parser="thpt-listening" data-audio-url="/audio/path/to/file.mp3">
```

- Parser rieng: `js/thpt-listening-parser.js`.
- Parser nay chi la wrapper quanh `js/thpt-parser.js`, sau do gan:
  - `meta.skill = "thpt"`
  - `meta.parser = "thpt-listening"`
  - `meta.module = "thpt-listening"`
  - `meta.hasListening = true`
  - `meta.audioUrl = "...mp3"`
- Cau 1-4 phai nam trong section Listening, co dap an va explanation nhu cac cau khac.
- File audio phai nam trong duong dan public/on-web stable, vi du `/audio/grade8-second-semester/grade8-mock-test-01.mp3`.
- Khi Save trong Test Importer, `audioUrl` phai duoc giu trong `testData.meta.audioUrl`.
- Engine render Practice/Lecture phai hien audio panel o dau bai neu `meta.audioUrl` ton tai.

Khong duoc:

- Khong sua logic `js/thpt-parser.js` chi de them Listening.
- Khong doi skill thanh `listening`, vi day van la mock test THPT co nhieu section.
- Khong nhung audio bang local path `G:\...`; phai copy sang public asset path truoc khi import.

### Format B - General Practice / word form / rewrite theo chuyen de

Dung khi bai khong phai de 40 cau, vi du luyen word form, rewrite, grammar MCQ theo topic.

Bat buoc:

- Wrapper section: `.section-block`.
- Header: `h2.section-title`.
- Moi cau: `.question-item`.
- Noi dung cau: `.raw-text`.
- Dap an va giai thich: `.answer-block` hidden.

Parser chinh: `js/teacher-html-parser.js`.

### Format C - Legacy community practice

Chi dung de migrate bai cu:

- `const exerciseData = [...]`
- `.question-card`
- `.q-block`

Khong dung Format C cho bai moi neu khong bat buoc.

## 4. Data contract sau import

Sau khi parse, du lieu phai ve dang:

```json
{
  "meta": {
    "title": "Practice title",
    "skill": "thpt",
    "examType": "g10",
    "duration": 60,
    "totalPoints": 10,
    "scoringMode": "equal"
  },
  "sections": [
    {
      "id": "S1",
      "label": "Section label",
      "instruction": "Instruction",
      "layout": "normal",
      "questions": []
    }
  ]
}
```

Moi question toi thieu phai co:

```json
{
  "id": "q1",
  "number": 1,
  "type": "mcq",
  "text": "Question text",
  "answer": "A",
  "explanationHtml": "<p>Detailed explanation...</p>"
}
```

## 5. Canonical HTML snippets - Format A

### 5.1 MCQ

```html
<div class="glass-panel">
  <h2>I. Choose the word, phrase, or sentence that best fits the space. (3.5 pts)</h2>

  <div class="question-block" id="q1" data-correct="B">
    <p><strong>1.</strong> She usually _____ to school by bike.</p>
    <div class="quiz-option" data-val="A">A. go</div>
    <div class="quiz-option" data-val="B" data-iscorrect="true">B. goes</div>
    <div class="quiz-option" data-val="C">C. going</div>
    <div class="quiz-option" data-val="D">D. gone</div>

    <div class="explanation" style="display:none;">
      <p><strong>Dap an: B. goes</strong></p>
      <p>Dung vi chu ngu "She" la ngoi thu ba so it, thi hien tai don nen dong tu them -s/-es: "goes".</p>
      <p><strong>Loai tru:</strong></p>
      <p>A. go - sai vi khong chia theo ngoi thu ba so it.</p>
      <p>C. going - sai vi V-ing khong dung doc lap trong thi hien tai don.</p>
      <p>D. gone - sai vi past participle can di voi have/has trong hien tai hoan thanh.</p>
      <p><em>Dich:</em> Co ay thuong di hoc bang xe dap.</p>
    </div>
  </div>
</div>
```

Yeu cau:

- Co `data-correct="B"` tren `.question-block`, hoac `data-iscorrect="true"` tren option dung.
- Option co chu cai A/B/C/D ro rang.
- Explanation hidden, khong lo truoc Submit.

### 5.2 Pronunciation

```html
<div class="question-block" id="q2" data-qtype="pronunciation" data-correct="A">
  <p><strong>2.</strong> Which word has the underlined part pronounced differently from that of the others?</p>
  <div class="quiz-option" data-val="A" data-iscorrect="true">A. ch<u>e</u>mical</div>
  <div class="quiz-option" data-val="B">B. b<u>e</u>nefit</div>
  <div class="quiz-option" data-val="C">C. gov<u>e</u>rnment</div>
  <div class="quiz-option" data-val="D">D. m<u>e</u>chanic</div>

  <div class="explanation" style="display:none;">
    <p><strong>Dap an nguon: A. chemical</strong></p>
    <p>A. chemical /ˈkem.ɪ.kəl/ - chu "e" gach chan phat am /e/.</p>
    <p>B. benefit /ˈben.ə.fɪt/ (US) - chu "e" gach chan phat am /e/.</p>
    <p>C. government /ˈɡʌv.ɚn.mənt/ - chu "e" trong van khong nhan thuong bi giam am /ə/.</p>
    <p>D. mechanic /məˈkæn.ɪk/ - chu "e" phat am /ə/.</p>
    <p><strong>Luu y hoc thuat:</strong> neu dung IPA US, A va B cung co /e/, con C va D thien ve /ə/. Neu answer key nguon chon A, van giu A de bam nguon, nhung phai flag day la cau co dau hieu khong tao duoc mot dap an duy nhat that sach.</p>
    <p><em>Dich:</em> N/A</p>
  </div>
</div>
```

Yeu cau:

- Tu nao hoi underlined part phai co `<u>...</u>` ro rang.
- Explanation phai co IPA cua 4 options.
- Neu mot tu co UK/US IPA khac nhau, ghi ro dang dung. Neu user yeu cau US, dung US.
- Neu answer key nguon co van de, khong sua ngam; giu dap an nguon va flag "Luu y hoc thuat".

### 5.3 Stress

```html
<div class="question-block" id="q3" data-qtype="stress" data-correct="C">
  <p><strong>3.</strong> Which word has a different stress pattern?</p>
  <div class="quiz-option" data-val="A">A. beautiful</div>
  <div class="quiz-option" data-val="B">B. family</div>
  <div class="quiz-option" data-val="C" data-iscorrect="true">C. enjoyable</div>
  <div class="quiz-option" data-val="D">D. energy</div>

  <div class="explanation" style="display:none;">
    <p><strong>Dap an: C. enjoyable</strong></p>
    <p>A. beautiful /ˈbjuː.tɪ.fəl/ - 3 am tiet, nhan am 1.</p>
    <p>B. family /ˈfæm.əl.i/ - 3 am tiet, nhan am 1.</p>
    <p>C. enjoyable /ɪnˈdʒɔɪ.ə.bəl/ - 4 am tiet, nhan am 2, khac voi cac tu con lai.</p>
    <p>D. energy /ˈen.ɚ.dʒi/ - 3 am tiet, nhan am 1.</p>
    <p>A, B, D nhan am 1; C nhan am 2 nen chon C.</p>
    <p><em>Dich:</em> N/A</p>
  </div>
</div>
```

### 5.4 Sign / Notice co hinh

```html
<div class="question-block" id="q15" data-qtype="sign" data-correct="A">
  <div class="q-text">
    <strong>15.</strong> What does the sign say?
    <div class="sign-wrap">
      <img
        class="sign-img"
        src="https://gonexus.edu.vn/docs/thpt-assets/example/q15-no-hunting.jpeg"
        alt="No hunting sign"
        onerror="this.style.display='none'; this.nextElementSibling.style.display='block';">
      <div style="display:none;">Image failed to load: No hunting sign.</div>
    </div>
  </div>

  <div class="quiz-option" data-val="A" data-iscorrect="true">A. No hunting</div>
  <div class="quiz-option" data-val="B">B. No littering</div>
  <div class="quiz-option" data-val="C">C. No smoking</div>
  <div class="quiz-option" data-val="D">D. No parking</div>

  <div class="explanation" style="display:none;">
    <p><strong>Dap an: A. No hunting</strong></p>
    <p>Dung vi bien bao the hien hanh dong san ban bi cam, nen nghia la "No hunting".</p>
    <p><strong>Loai tru:</strong></p>
    <p>B. No littering - sai vi khong phai bien cam xa rac.</p>
    <p>C. No smoking - sai vi khong co bieu tuong thuoc la.</p>
    <p>D. No parking - sai vi khong phai bien cam do xe.</p>
    <p><em>Dich:</em> Bien bao noi: Cam san ban.</p>
  </div>
</div>
```

Yeu cau voi hinh:

- Phai dung URL public tuyet doi (`https://...`) hoac Firebase Storage download URL.
- Khong dung duong dan may ca nhan nhu `G:\...`, `C:\...`, `file://...`.
- Khong dung relative path mong manh neu HTML se paste vao iframe/importer.
- Luon co `alt` mo ta dung noi dung hinh.
- Luon co fallback text an de khi anh loi van biet anh goc la gi.
- Sau import, preview phai hien hinh truoc Submit, nhung dap an/explanation chi hien sau Submit.

### 5.5 Cloze / Gap filling co passage

Voi cloze, dung split layout de passage ben trai va cau hoi ben phai, moi ben co scroll rieng khi can.

```html
<div class="glass-panel">
  <h2>III. Choose the word or phrase that best fits each blank in the passage. (1.5 pts)</h2>
  <div class="split-layout">
    <div class="passage-sticky">
      <p>Children need time to play (17) _____ because play helps them learn how to communicate...</p>
    </div>
    <div class="questions-pane">
      <div class="question-block" id="q17" data-correct="C">
        <p><strong>17.</strong> (17) _____</p>
        <div class="quiz-option" data-val="A">A. one another</div>
        <div class="quiz-option" data-val="B">B. each other</div>
        <div class="quiz-option" data-val="C" data-iscorrect="true">C. together</div>
        <div class="quiz-option" data-val="D">D. other</div>
        <div class="explanation" style="display:none;">
          <p><strong>Dap an: C. together</strong></p>
          <p>Dung vi collocation "play together" co nghia la choi cung nhau va phu hop voi ngu canh tre em choi theo nhom.</p>
          <p><strong>Loai tru:</strong></p>
          <p>A. one another - sai vi can "play with one another" moi tu nhien.</p>
          <p>B. each other - sai vi cung can "play with each other"; dung "together" gon va tu nhien hon.</p>
          <p>D. other - sai ngu phap vi "other" can di voi danh tu hoac dung "others".</p>
          <p><em>Dich:</em> Tre em choi cung nhau.</p>
        </div>
      </div>
    </div>
  </div>
</div>
```

### 5.6 Reading co passage / True-False / MCQ

Reading dai phai dung split layout: passage ben trai, cau hoi ben phai.

```html
<div class="glass-panel">
  <h2>V. Read the passage and choose the correct answer. (1.5 pts)</h2>
  <div class="split-layout">
    <div class="passage-sticky">
      <p><span class="passage-ev" data-ev="1">Safaris in the Masai Mara can be conducted in several ways: by vehicle, on foot with a guide, or from above in a hot air balloon.</span></p>
    </div>
    <div class="questions-pane">
      <div class="question-block" id="q23" data-qtype="tf" data-correct="TRUE" data-evidence="1">
        <p><strong>23.</strong> Visitors can go on safari in the Masai Mara in several ways.</p>
        <div class="quiz-option" data-val="TRUE" data-iscorrect="true">True</div>
        <div class="quiz-option" data-val="FALSE">False</div>
        <div class="explanation" style="display:none;">
          <p><strong>Dap an: TRUE</strong></p>
          <p><strong>Evidence:</strong> "Safaris in the Masai Mara can be conducted in several ways..."</p>
          <p>Cau hoi noi "in several ways"; evidence cung noi "conducted in several ways" va liet ke 3 cach cu the. Hai thong tin khop nhau nen cau nay dung.</p>
          <p><em>Dich:</em> Du khach co the di safari o Masai Mara theo mot vai cach khac nhau.</p>
        </div>
      </div>
    </div>
  </div>
</div>
```

Yeu cau:

- Passage khong duoc rut gon.
- Evidence nen boc bang `.passage-ev[data-ev="N"]`.
- Question lien quan nen co `data-evidence="N"`.
- Explanation phai so sanh evidence voi cau hoi/option.

### 5.7 Word form

```html
<div class="question-block" id="q30">
  <p>
    <strong>30.</strong>
    It was a
    <input class="inline-fill" data-correct="thrilling">
    football match. (THRILL)
  </p>

  <div class="explanation" style="display:none;">
    <p><strong>Dap an: thrilling</strong></p>
    <p>Vi tri can dien nam sau mao tu "a" va truoc danh tu "football match", nen can tinh tu bo nghia cho danh tu.</p>
    <p>ROOT "THRILL" co hai tinh tu thong dung: "thrilled" chi cam xuc cua nguoi; "thrilling" chi tinh chat cua su vat/su viec. "match" la su viec nen dung "thrilling".</p>
    <p><em>Dich:</em> Do la mot tran bong da day kich tinh.</p>
    <table class="vocab-table">
      <tr><th>Word</th><th>POS</th><th>IPA</th><th>Meaning (VN)</th></tr>
      <tr><td>thrill</td><td>V</td><td>/θrɪl/</td><td>lam cho ai do hoi hop, phan khich</td></tr>
      <tr><td>thrill</td><td>N [C]</td><td>/θrɪl/</td><td>su hoi hop, cam giac phan khich</td></tr>
      <tr><td>thrilled</td><td>ADJ (ve nguoi)</td><td>/θrɪld/</td><td>cam thay hoi hop, phan khich</td></tr>
      <tr><td>thrilling</td><td>ADJ (ve vat/su viec)</td><td>/ˈθrɪlɪŋ/</td><td>day kich tinh, gay hoi hop</td></tr>
      <tr><td>thrillingly</td><td>ADV</td><td>/ˈθrɪlɪŋli/</td><td>mot cach hoi hop</td></tr>
    </table>
  </div>
</div>
```

Phrase blank rule:

- `data-correct` must match exactly what the student types inside the blank.
- If the blank replaces the full phrase, use full phrase answers.
  Example: `felt a <input data-correct="strong connection" data-correct-alt='["close connection","direct connection"]'> with...`
- If the noun/preposition is already outside the blank, use only the missing word.
  Example: `felt a <input data-correct="strong" data-correct-alt='["close","direct"]'> connection with...`
- Do not make the UI ask for `close` while the grader expects `close connection`.

Accepted-answer rule for fill / word form / short answer:

- Always put the canonical answer in `data-correct`.
- Put every teacher-approved variant in `data-correct-alt` as JSON.
- Include British/American spelling variants when both are acceptable:
  `data-correct="organization" data-correct-alt='["organisation"]'`.
- Include singular/plural variants only when the sentence does not force one form.
- Include contraction/full-form variants only when both fit the word limit and grammar:
  `data-correct="don't remind me" data-correct-alt='["do not remind me"]'`.
- The NEXUS engine also has a tolerant matcher for BrE/AmE, contractions, outer punctuation, and phrase-head legacy data; still list variants explicitly whenever you know them so the answer key is transparent.
- Do not encode optional words with parenthetical shorthand in `data-correct`.
  Bad: `data-correct="difficulty (in) cooking a decent meal"`.
  Good: `data-correct="difficulty in cooking a decent meal" data-correct-alt='["difficulty cooking a decent meal"]'`.
- If the explanation says an element is optional, every accepted surface form must be listed as a real answer variant. Explanation-only alternates do not count for grading.

### 5.8 Dictionary Entry

Dictionary entry trong Word/PDF thuong la hinh. Khi tao HTML import, phai chuyen hinh dictionary thanh text HTML, khong de nguyen hinh lam noi dung chinh.

```html
<div class="glass-panel">
  <h2>VI. Look at the entry of the word "struggle" in a dictionary. Complete the sentences with two or three words. (0.5 pt)</h2>

  <div class="split-layout">
    <div class="passage-sticky">
      <div class="dict-entry">
        <p><strong>struggle</strong> /ˈstrʌɡl/ <em>verb</em></p>
        <p><span class="dict-hl" id="dh35"><strong>struggle to do something</strong></span>: try very hard to do something difficult.</p>
        <p><span class="dict-hl" id="dh36"><strong>struggle for something</strong></span>: try hard to get something necessary.</p>
        <p><strong>Usage:</strong> struggle + to-infinitive; struggle + for + noun.</p>
      </div>
    </div>

    <div class="questions-pane">
      <div class="question-block" id="q35" data-qtype="dict-fill" data-dicthl-id="dh35">
        <p>
          <strong>35.</strong>
          Many animals in the wild
          <input class="inline-fill" data-correct="struggle to survive">
          due to climate change.
        </p>
        <div class="explanation" style="display:none;">
          <p><strong>Dap an: struggle to survive</strong></p>
          <p><strong>Bam-khung check:</strong> Dictionary entry cho pattern "struggle to do something" = co gang rat nhieu de lam dieu kho.</p>
          <p>Sau chu ngu so nhieu "Many animals" o hien tai don, dung dong tu nguyen mau "struggle"; sau "struggle" can to-infinitive nen dap an la "struggle to survive".</p>
          <p><strong>Rejected candidates:</strong> "struggle for" sai vi sau "for" can noun, khong phu hop voi dong tu "survive".</p>
          <p><em>Dich:</em> Nhieu loai dong vat hoang da phai vat lon de sinh ton vi bien doi khi hau.</p>
        </div>
      </div>
    </div>
  </div>
</div>
```

Yeu cau:

- Khong dat `<img>` lam noi dung chinh cua dictionary entry.
- Phai transcribe word, IPA, POS, definition, usage pattern, collocation/example can thiet.
- Cum dung de tra loi phai boc bang `.dict-hl` va co id on dinh, vi du `dh35`.
- Cau hoi lien quan phai co `data-dicthl-id="dh35"`.
- Dictionary entry dai phai dung split layout de moi ben scroll rieng.

### 5.9 Rewrite A - dau cau cho san

```html
<div class="question-block" id="q37">
  <p><strong>37.</strong> The tourist said, "I didn't throw trash on the street."</p>
  <div class="rewrite-box">
    <span>→ The tourist denied </span>
    <input
      class="rewrite-input"
      data-prompt="The tourist denied"
      data-correct="throwing trash on the street"
      data-correct-alt='["having thrown trash on the street","that he had thrown trash on the street"]'>
  </div>
  <div class="explanation" style="display:none;">
    <p><strong>Dap an: throwing trash on the street.</strong></p>
    <p>Cau goc la loi phu nhan trong reported speech. Dung cau truc "deny + V-ing" hoac "deny + that-clause".</p>
    <p>Luu y: vi de da cho san "The tourist denied", input chi chua phan duoi/tail answer, khong lap lai dau cau.</p>
    <p><em>Dich:</em> Du khach phu nhan viec vut rac tren duong.</p>
  </div>
</div>
```

Rewrite A accepted-answer rule:

- `data-prompt` is the fixed starter shown before the input.
- `data-correct` and every `data-correct-alt` must be the tail only, not the full sentence.
- Add 2-5 valid tails when the structure allows more than one answer.
- BrE/AmE spelling and harmless final punctuation differences are accepted by the engine, but still list important alternatives in `data-correct-alt`.
- Never write optional tails as `(word)` inside `data-correct`. Split them into `data-correct` + `data-correct-alt`, e.g. `data-correct="difficulty in cooking..." data-correct-alt='["difficulty cooking..."]'`.

### 5.10 Rewrite B - tu goi y trong ngoac

```html
<div class="question-block" id="q38">
  <p><strong>38.</strong> I like reading books. (enjoy)</p>
  <div class="rewrite-box">
    <input
      class="rewrite-input"
      data-prompt=""
      data-correct="I enjoy reading books."
      data-correct-alt='["I really enjoy reading books.","I enjoy reading books a lot."]'>
  </div>
  <div class="explanation" style="display:none;">
    <p><strong>Dap an: I enjoy reading books.</strong></p>
    <p>Tu goi y la "enjoy". Cau truc can dung: enjoy + V-ing. Vi day la Rewrite B, dap an phai la cau hoan chinh tu dau den dau cham.</p>
    <p><em>Dich:</em> Toi thich doc sach.</p>
  </div>
</div>
```

Rewrite B accepted-answer rule:

- `data-correct` is the full rewritten sentence.
- `data-correct-alt` contains full-sentence alternatives, not tails.
- The engine accepts missing final period if the sentence text matches, so `I enjoy reading books` and `I enjoy reading books.` can both grade correct.
- Do not rely on the engine to invent semantic paraphrases. If an alternate is valid, write it into `data-correct-alt`.
- If words like `last`, `in`, `that`, or an article are optional according to the explanation, list each valid full sentence separately in `data-correct-alt`; do not hide the optional word in parentheses.

## 6. Chuan explanation theo tung dang cau

### 6.1 MCQ / cloze / sign / reading-mcq

Explanation phai co:

- Dap an dung.
- Vi sao dung: grammar, collocation, context, logic hoi thoai, hoac evidence.
- Loai tru cac option sai, moi option 1 ly do ro.
- Translation/paraphrase neu can.

Khong dat:

```html
<div class="explanation">B</div>
```

### 6.2 Pronunciation

Explanation phai co:

- IPA cua 4 options.
- Chi ro am cua phan gach chan.
- Ket luan option nao khac.
- Neu IPA UK/US khac nhau, ghi ro dang dung. Neu cau co van de, flag ro.
- Translation: `N/A`.

### 6.3 Stress

Explanation phai co:

- IPA/stress pattern cua 4 options.
- So am tiet neu huu ich.
- Chi ro option khac.
- Translation: `N/A`.

### 6.4 Word form

Explanation phai co:

- Xac dinh tu loai can dien va ly do.
- Vi sao chon dang do cua root.
- Dich cau.
- Word Family Table it nhat 4-5 dong neu root moi xuat hien.
- Neu root da co table truoc do trong cung file/chat, co the ghi `WordFamily-See-Q[N]`.

### 6.5 Dict-fill

Explanation phai co:

- Bam-khung check: nhac lai collocation/pattern trong dictionary entry.
- Vi sao cum duoc chon phu hop voi ngu phap va ngu canh.
- Rejected candidates neu co cac pattern khac trong khung.
- Dap an phai bam word/pattern trong dictionary, khong tu y tao word form ngoai khung.

### 6.6 Rewrite A

Explanation phai co:

- Cau truc/cach bien doi.
- Input answer chi la tail answer, khong lap dau cau da cho.
- Acceptable alternatives neu co, va moi alt phai noi tiep dung prompt.

### 6.7 Rewrite B

Explanation phai co:

- Cau truc voi tu goi y.
- Dap an la cau hoan chinh.
- Moi alt phai co tu goi y dung dang chia.

### 6.8 Reading TF

Explanation phai co:

- Evidence cu the.
- So sanh evidence voi cau hoi.
- Neu False, chi ro thong tin nao trai evidence.
- Neu Not Given, chi ro bai khong de cap.

## 7. Flow lam viec chuan

1. Doc de/Word/PDF/anh nguon.
2. Quet image alert truoc: sign, notice, diagram, dictionary entry, table.
3. Neu cau co hinh sign/notice, trich hinh thanh asset public va dung URL public trong HTML.
4. Neu dictionary entry la hinh, transcribe thanh text HTML.
5. Chon Format A hoac Format B.
6. Tao HTML nguon parser-ready.
7. Import tai `ai-generator.html`, skill `THPT / Grade 10 Entrance`.
8. Bam `Parse & Preview`.
9. QA preview:
   - So cau dung.
   - Dap an dung.
   - Explanation du.
   - Anh hien dung.
   - Split layout doc de: passage/dictionary ben trai, cau hoi ben phai.
   - Submit xong moi reveal dap an/explanation.
10. Save vao Content Library.
11. Neu can giang bai: trong Content Library bam `Make Lecture`, assign to Classroom.
12. Trong Lecture: GV bam key de reveal, highlight, take note, keo note den vi tri mong muon, bam Save de dong bo sang Student Lecture.

## 8. QA checklist truoc khi giao

- [ ] Moi cau co so thu tu lien tuc.
- [ ] Moi cau co answer key.
- [ ] Moi cau co explanation chi tiet.
- [ ] MCQ co du option A/B/C/D neu nguon co 4 options.
- [ ] Pronunciation co gach chan va IPA.
- [ ] Stress co stress pattern.
- [ ] Word form co root word va word family table khi can.
- [ ] Rewrite A co `data-prompt` va tail answer.
- [ ] Rewrite B co dap an cau hoan chinh.
- [ ] Reading/co passage khong bi rut gon.
- [ ] Evidence duoc gan neu co reading.
- [ ] Sign/notice image dung URL public, co alt, co fallback.
- [ ] Dictionary entry khong de dang anh, da chuyen thanh text HTML.
- [ ] Khong co nut Check/Show Answer/Reset tu tao trong HTML nguon.
- [ ] Khong co dap an lo truoc Submit.
- [ ] Parse Preview ra `testData v2`.
- [ ] Community Class Practice dung Submit flow.
- [ ] Make Lecture tao duoc Interactive Lecture va note/highlight save duoc.

## 9. Anti-patterns can tranh

Khong lam:

```html
<button onclick="showAnswer()">Show Answer</button>
```

```html
<p>Dap an: B vi...</p>
```

```html
<input>
<script>
  const answer = "B";
</script>
```

```html
<div class="question">1. ...</div>
<div class="key">B</div>
```

Khong de:

```html
<img src="G:\MY KINGDOM FOR EDUCATION\...\q15.png">
```

Khong rut gon:

```text
Passage omitted for brevity.
```

## 10. Prompt copy sang chat moi

Copy nguyen khoi sau de giao viec cho Codex/AI trong chat moi:

```text
Ban dang lam viec voi NEXUS Test Importer, skill THPT / Grade 10 Entrance.

Hay tao HTML nguon parser-ready de import vao NEXUS, tuan thu NEXUS THPT Practice + Lecture Creation Standard.

Muc tieu bat buoc:
1. Practice phai dung flow NEXUS: hoc sinh lam bai -> bam Submit -> moi hien dap an + giai thich chi tiet.
2. Khong tao nut Check/Show Answer/Reset/Try again/Print hoac script tu cham trong HTML nguon.
3. Khong de dap an lo trong phan cau hoi.
4. Moi cau phai co answer key va explanation chi tiet.
5. Neu la de 40 cau/full mock, dung Format A: .glass-panel + h2 section + .question-block.
6. Neu la general practice/word form/rewrite theo chuyen de, dung Format B: .section-block + .question-item + .answer-block.
7. Pronunciation phai co gach chan bang <u>...</u>, co IPA 4 options, ghi ro UK/US neu can.
8. MCQ/cloze/sign/reading-mcq phai giai thich vi sao dung va loai tru option sai.
9. Word form phai co target POS, ly do chon word form, dich cau, va Word Family Table khi can.
10. Rewrite A co dau cau cho san: data-prompt la dau cau, data-correct chi la tail answer.
11. Rewrite B co tu goi y trong ngoac: data-correct la cau hoan chinh.
12. Reading phai giu nguyen passage, co evidence neu co the, dung split layout neu passage dai.
13. Sign/notice co hinh: dung URL public, co alt va fallback; khong dung G:\, C:\, file://, hoac relative path mong manh.
14. Dictionary entry dang hinh phai chuyen thanh text HTML, khong de anh lam noi dung chinh; dung .dict-hl id va data-dicthl-id de map cau hoi.
15. Neu thieu thong tin hoac cau nguon co van de, flag [MISSING: ...] hoac "Luu y hoc thuat", khong doan mo.

Sau khi tao HTML:
- Neu co repo/local parser, hay test bang Test Importer/parser.
- Chi coi la xong khi parser doc dung so cau, dap an/explanation du, Submit flow dung, va preview khong mat hinh.
- Neu user muon giang bai, sau khi Practice duoc save vao Content Library thi dung Make Lecture -> Assign to Classroom -> Interactive Lecture. Ban Lecture giu nguyen kien thuc, cho GV bam key reveal, highlight, take note, keo note, bam Save de dong bo sang Student Lecture.

Output mong muon:
- Chi tra ve file HTML nguon day du, readable, khong minify.
- Khong chen giai thich ngoai HTML tru khi can flag loi nguon.
```

## 10.1. Prompt copy rieng cho THPT + Listening

Khi de co audio Listening (thuong Q1-Q4), copy khoi sau sang chat moi thay vi prompt tong quat:

```text
Ban dang lam viec voi NEXUS Test Importer, skill THPT / Grade 10 Entrance, che do THPT + Listening.

Hay tao/sua HTML nguon parser-ready de import bang parser rieng `thpt-listening`. Van save duoi skill `thpt`, khong doi sang skill `listening`, vi day la de mock nhieu section co audio Listening.

Bat buoc:
1. HTML co marker:
   <meta name="nexus-parser" content="thpt-listening">
   <meta name="nexus-audio-url" content="/audio/path/to/file.mp3">
   <body data-nexus-parser="thpt-listening" data-audio-url="/audio/path/to/file.mp3" data-audio-source="...">
2. Audio path phai la public/on-web stable path, khong dung G:\, C:\, file://.
3. Q1-Q4 Listening nam trong section Listening rieng, moi cau co answer + explanation.
4. Full tape script phai duoc giu trong hidden `.teacher-notes`, khong rut gon thanh summary.
5. Moi cau q1 -> qN co `.question-block id="qN"` lien tuc, co dap an may doc duoc va `.explanation style="display:none;"`.
6. Practice dung flow NEXUS: hoc sinh lam bai -> bam Submit -> moi hien dap an + giai thich.
7. HTML nguon khong tao nut Check/Show Answer/Reset/Try Again/Print, khong script tu cham, khong lo dap an truoc Submit.
8. Sign/notice image dung URL public, co alt/fallback. Dictionary entry dang hinh phai chuyen thanh text HTML.
9. Reading/cloze/dictionary dai dung split layout: source ben trai, cau hoi ben phai, moi ben scroll rieng.
10. Explanation depth v3.0:
    - MCQ/cloze/sign/reading-mcq/listening-mcq: vi sao dung + loai tru tung option sai + dich.
    - Listening/reading TF: evidence + so sanh statement voi source + False thi chi ro diem sai + dich.
    - Word form: TargetPOS + ly do chon form + dich + Word Family Table 4-5 dong.
    - Dict-fill: BÁM-KHUNG check + vi sao chon cum + RejectedCandidates.
    - Rewrite A: data-prompt la dau cau, data-correct chi la tail answer, khong lap prompt.
    - Rewrite B: data-correct la cau hoan chinh.
    - BrE/AmE/contractions/singular-plural hop le phai dua vao data-correct-alt.
    - Tuyet doi khong dung ngoac de danh dau tu optional trong dap an, vi du khong viet `difficulty (in) cooking`; phai tach thanh `data-correct` va `data-correct-alt` ro rang.

QA truoc khi giao:
- q1-qN lien tuc, tong cau dung.
- 100% cau co answer + explanation.
- Full transcript co mat, khong bi summary.
- Passage khong bi cat.
- AudioUrl duoc giu trong meta sau parse.
- Parse Preview chon THPT + Listening ra `testData.meta.parser = "thpt-listening"`, `hasListening = true`.
- Sau Save co the Make Lecture -> Assign to Classroom -> Interactive Lecture, giu audio + answer + explanation + highlight/note sync.

Output mong muon: file HTML nguon day du, readable, parser-ready. Neu source thieu dap an/evidence/audio/hinh/IPA, flag `[MISSING: ...]`, khong doan mo.
```

Full prompt rieng co tai: `docs/prompts/thpt-with-listening-practice-standard.md`.

## 11. File lien quan trong repo

- `ai-generator.html` - Test Importer UI.
- `docs/prompts/thpt-practice-parser-standard.md` - tai lieu chuan nay.
- `docs/prompts/thpt-with-listening-practice-standard.md` - prompt copy rieng cho THPT + Listening.
- `js/thpt-parser.js` - parser cho Format A.
- `js/thpt-listening-parser.js` - wrapper parser rieng cho THPT + Listening.
- `js/teacher-html-parser.js` - parser cho Format B.
- `js/thpt-engine.js` - engine render Practice va toolbar annotation.
- `js/thpt-lecture-converter.js` - Make Lecture tu Practice sang Interactive Lecture.
- `content-library.html` - noi bam Make Lecture / Assign to Class.
- `general-viewer.html` - viewer giao vien / teacher preview.
- `viewer.html` - viewer hoc vien / Student Lecture.
- `docs/CONTENT-QUALITY-STANDARD.md` - chuan chat luong Practice Mode.
- `docs/CONTENT-QUALITY-STANDARD-TEACHING-MODE.md` - chuan chat luong Teaching/Lecture Mode.
