--- url: https://docs.nemo12.com/architecture/sdd-012-real-exam-bank.md description: >- Bản nháp ngân hàng đề thi thật (SDD-012): mô hình dữ liệu đề thi vào 10, đề học kỳ, bài trong đề, lời giải và metadata. --- # SDD-012 — Real Exam Bank (Ngân hàng đề thi thật) Quản lý **đề thi thật** (đề thi cũ đã diễn ra: thi vào 10 trường chuyên/chọn, đề điều kiện lẫn đề chuyên, đề học kỳ thật…), tách mỗi đề thành **từng bài**, mỗi bài có metadata phân loại + **lời giải gợi ý**, gắn một **Assessment Experience** đo answer + confidence + justification, và link ngược về **Learning Experience** để học lại. Learner lọc bài theo nhiều chiều và **đánh dấu trạng thái luyện tập cá nhân** (đã làm N lần, bế tắc, chưa tự tin…). Ví dụ định vị: *đề thi vào Chu Văn An, môn Toán điều kiện, năm học 2023-2024* → 1 exam record → 5 exam problems, mỗi problem có lời giải, dạng bài, node links, và một Assessment Experience riêng. ## 1. Nguyên tắc & phạm vi 1. **Đề thật là tư liệu gốc, immutable.** Mỗi đề lưu kèm provenance đầy đủ (trường/hệ thi, kỳ/vòng, môn, năm học, URL nguồn — Q-069 ✅: không lưu file đề gốc, chỉ lưu link; nội dung bài do Nemo12 trích xuất + biên tập). Nội dung đề sau khi published không sửa tại chỗ — sửa qua version mới (SDD-003 §13). 2. **Bài (problem) là đơn vị luyện tập**, không phải cả đề. Learner luyện từng bài, theo nhu cầu và theo dấu cá nhân. 3. **KHÔNG mock exam trên đề thật** — không có trải nghiệm "làm cả đề theo timing, chấm tổng điểm". Chỉ đạo SRC-029; đối chiếu với REQ-EXAM-02 (mock exam trên đề generated, đã ship) → xem Q-061: REQ-EXAM-02 giữ nguyên cho đề generated; đề thật chỉ luyện theo bài. 4. **Tách khỏi Item Bank, liên kết qua relations** (quyết định Q-038, RISK-006): `exam_problems` là registry riêng; một bài có thể tham chiếu item (`item_ref`) khi được tái dùng làm practice item, nhưng nguồn sự thật về "bài trong đề thật" là registry này. 5. **Hai nghĩa "blueprint" — phân biệt bắt buộc.** *Assessment Blueprint* (SDD-004 §5–8: `Blueprint → Item Bank → Selection Engine → Assessment Instance`) là mẫu đo lường của một Assessment Experience — SDD này dùng nghĩa đó (§4). *Goal blueprint* (SDD-002 §12, SDD-011: `specialized-chuyen`, readiness theo blueprint) là đích học tập — không dùng trong SDD này ngoài phần readiness. 6. **Bản quyền & nguồn:** đề thi do Sở/trường công bố là tài liệu công khai — lưu bản gốc + ghi nguồn. **Đáp án chính thức** được trích dẫn kèm nguồn. **Lời giải gợi ý chi tiết do Nemo12 tự biên soạn** (AI draft + AI multi-evaluator đạt ngưỡng; owner spot-check — AI-first SRC-035) — không sao chép lời giải từ các site thương mại; nếu tham khảo, chỉ ghi link nguồn tham khảo. 7. **School scoping:** đề thi vào 10 chuyên thuộc **Shark**; đề học kỳ thật (nếu nhập) thuộc **Turtle** — hiển thị theo REQ-SCH-10 (mỗi school chỉ thấy nội dung của mình). ## 2. Mô hình dữ liệu — đề thật (REQ-EXAM-05) Tái dùng registry `exams` hiện có (SDD-011 §3, migration 0004) — **một registry đề duy nhất**, đề thật phân biệt bằng `source='authentic'` và bộ trường provenance mở rộng: ```text exams (mở rộng) id, subject_id, exam_type[semester|selective], grade, target_school_id? → target_schools, -- trường (Chu Văn An, Ams, KHTN…) exam_system?, -- hệ thi: so-hanoi | khtn | su-pham | truong-tu-to-chuc… province?, school_year?, -- "2023-2024" (giữ year INTEGER hiện có làm năm tuyển sinh) exam_round?[dieu_kien|chuyen], -- vòng điều kiện vs vòng chuyên term?[giua_ki_1|cuoi_ki_1|giua_ki_2|cuoi_ki_2], -- dạng đề học kỳ (SRC-045) exam_date?, -- ngày thi thực tế của đề specialist_subject?, -- đề chuyên môn nào (Toán chuyên, Tin chuyên…) duration_minutes, difficulty_tier, source[generated|authentic], -- generated = SDD-011 §3; authentic = SDD này source_ref?, -- URL nguồn tới đề (Q-069 ✅: CHỈ lưu link, KHÔNG lưu file đề) status[draft|review|published|archived] target_schools (đã có) + exam_systems nếu cần registry hệ thi riêng ``` * Đề `authentic` **không có** `exam_questions` (bảng MCQ của đề generated); nội dung của nó là các `exam_problems` (§3). * Lưu ý implement: migration 0004 có CHECK `status IN ('draft','published','archived')` và `source` default `'generated'` — SQLite không ALTER CHECK được, migration mở rộng phải **rebuild bảng `exams`** (tạo bảng mới → copy → rename) để thêm `'review'` và các cột provenance. * Lifecycle content theo SDD-003 §10 (`Draft → Review → Published`); đề chưa published không hiển thị cho learner. * Đề điều kiện dùng chung (ví dụ đề chung Sở Hà Nội cho Ams/Chu Văn An/Nguyễn Huệ) lưu **một** exam record gắn `exam_system='so-hanoi'`, `target_school_id` NULL; quan hệ "trường nào dùng đề này" qua `entity_relations related_to` — không nhân bản đề. ## 3. Bài trong đề — `exam_problems` + metadata + lời giải (REQ-EXAM-06) ```text exam_problems id, exam_id → exams, ord, label, -- "Bài III", "Câu 2a" — giữ đúng nhãn đề gốc statement_ref, -- r2://exam-bank//p/statement.md (+ assets hình) answer_summary?, -- đáp số/kết quả ngắn (chấm nhanh; NULL với Văn/essay) solution_ref, -- r2://exam-bank//p/solution.md — lời giải gợi ý official_answer_ref?, -- đáp án chính thức của Sở/trường (nếu có, kèm nguồn) points?, -- thang điểm theo đề gốc difficulty[basic|standard|advanced|olympiad], est_minutes?, -- thời gian tham khảo (không phải timing bắt buộc — §1.3) assessment_experience_id? -- link Assessment Experience (§4) status, version problem_types -- taxonomy dạng bài theo môn (Q-062) id, subject_id, name_vi, parent_id? -- "Phương trình vô tỉ" ⊂ "Đại số" problem_type_links (problem_id, problem_type_id) -- n-n ``` * **Statement + solution là hai document riêng** (mỗi bài xem đề trước, lời giải chỉ mở sau khi nộp hoặc learner chủ động — §4). Markdown VI-first, công thức toán (KaTeX), hình lưu R2 cùng thư mục. * **Lời giải gợi ý** viết theo tầng: (1) gợi ý hướng đi, (2) lời giải đầy đủ, (3) nhận xét/mở rộng (bẫy thường gặp, cách khác). Gate publish: AI multi-evaluator đạt ngưỡng (SDD-003 §8, AI-first SRC-035); owner spot-check theo tỷ lệ + item bị learner report (learner evidence là trọng tài cuối — SDD-003 §11). * **Phân loại 3 lớp** cho mỗi bài: (a) `problem_types` — dạng bài để lọc luyện thi; (b) node links `entity_relations assesses/teaches` → skill/knowledge node (SDD-003 graph) — nguồn sự thật về kiến thức, để evidence cập nhật mastery và để link LX (§6); (c) metadata phẳng (difficulty, points, est_minutes). * Khi một bài được tái dùng làm practice item trong Item Bank → tạo item + `item_ref` ngược (không copy nội dung — REQ-KNW-05). ## 4. Assessment Experience per bài — answer + confidence + justification (REQ-EXAM-07) Mỗi `exam_problem` published có một **Assessment Experience** (SDD-004, subtype Assessment) sinh từ **Assessment Blueprint** `exam-problem-v1`. Blueprint này cố định *cách đo*, mọi bài dùng chung mẫu — thêm blueprint mới (ví dụ cho Văn/essay) là thêm bản ghi blueprint, không đổi engine. Khác với pipeline đầy đủ của SDD-004 (`Blueprint → Item Bank → Selection Engine → Assessment Instance`, mỗi learner một đề khác nhau): `exam-problem-v1` là **instantiation nội-dung-cố-định** — bài đề thật nằm ngoài Item Bank (Q-038) nên hai bước Item Bank → Selection Engine không áp dụng; blueprint chỉ cố định 3 lớp đo + scoring + interpretation. ```text Blueprint exam-problem-v1 đo 3 lớp: answer -- đáp án/kết quả (+ từng ý với bài nhiều phần) confidence -- learner tự đánh giá 1–5 TRƯỚC khi xem lời giải justification -- trình bày cách làm/vì sao (text/ảnh bài làm) scoring: answer_summary khớp → auto; tự luận → self-verdict đối chiếu lời giải + AI hỗ trợ đánh giá justification theo rubric (QG-010) timing: est_minutes chỉ tham khảo — không cưỡng bức (không mock exam) interpretation: ma trận answer × confidence × justification (dưới) ``` ```mermaid flowchart LR A[Mở bài] --> B[Làm bài] B --> C[Nộp: answer + confidence 1-5 + justification] C --> D[Mở lời giải gợi ý] D --> E[Self-verdict: đúng / đúng một phần / sai] E --> F[Evidence → SDD-002 §5] F --> G[Cập nhật mastery/confidence per node + learner_problem_state §5] ``` **Lớp 3 — lý do chọn, trình bày thế nào** (SRC-070 → SRC-100): 4 mã chuẩn `derived/recalled/eliminated/guessed` giữ nguyên để so sánh giữa môn, chữ hiển thị bám môn + mạch kiến thức. Ở UI mỗi lý do là **một dòng riêng**, **thứ tự xáo theo id câu hỏi** (cố định trong một câu, khác nhau giữa các câu — learner không quen tay bấm dòng đầu), và mỗi dòng có dấu **?** mở popover **giải nghĩa + một ví dụ cụ thể theo môn**: học sinh không tự hiểu "suy luận từ điều đã hiểu" nghĩa là gì thì lớp đo này chỉ thu về nhiễu. **Làm lại câu sai** (SRC-103): sai thì phải chọn lại tới khi đúng, nhưng **chỉ lần trả lời đầu được ghi evidence** — các lần sửa chấm ở client, không gửi `/answer`. Nếu tính cả lần sửa thì mọi bài đo đều về 100% và ma trận answer × confidence × justification mất nghĩa. Chi tiết ở [SDD-010 §9](sdd-010-lab-platform/unit-path.md). **Thời điểm lộ kết quả** (SRC-110 → SRC-083): với **Learning Experience (luyện tập)**, kết quả và đáp án hiện **ngay sau khi learner khai đủ 3 lớp** (answer → confidence → justification) — feedback gần hành động thì học nhanh hơn. Với **Assessment Experience (đo mức vững)** và đề thi thật, kết quả vẫn **giấu tới cuối bài**: đây là bài đo, lộ đáp án giữa chừng làm hỏng phép đo. **Diễn giải 3 lớp** (đưa vào evidence `metadata` để Engine và cockpit dùng): | answer | confidence | justification | Diễn giải | | --- | --- | --- | --- | | đúng | cao | chặt chẽ | Vững thật — tính vào readiness | | đúng | cao | yếu/không có | Nghi học vẹt → hỏi thêm biến thể (Assessment Engine) | | đúng | thấp | bất kỳ | Đúng nhưng chưa tự tin → luyện thêm cùng dạng | | sai | cao | bất kỳ | Ảo tưởng nắm chắc — ưu tiên sửa (misconception) | | sai | thấp | bất kỳ | Biết là chưa vững → học lại qua LX (§6) | **Justification taxonomy** (SRC-072) — lớp thứ 3 hỏi *cách learner đi tới đáp án*, nên câu chữ phải nói đúng ngôn ngữ của môn (hỏi "làm từng bước ra kết quả" cho một câu đọc hiểu Ngữ văn là vô nghĩa). Tách **mã chuẩn** khỏi **chữ hiển thị**: ```text kind (bất biến, để Engine so sánh giữa mọi môn — mạnh → yếu): derived -- tự làm/suy ra được đáp án recalled -- nhớ lại kiến thức đã học eliminated -- loại trừ các đáp án khác guessed -- cảm giác/đoán label (đổi theo môn × strand — SDD-004 §2): math:HH derived = "Vẽ hình rồi suy ra" vietnamese:DH derived = "Tìm được chi tiết đó trong bài" english:GR recalled = "Nhớ quy tắc, nghĩa của từ" ``` Learner chỉ thấy `label`; Evidence lưu cả `justification_kind` (mã) lẫn text tự do. Mã này là **self-report** (.50 — SDD-002 §5): không dùng để chấm đúng/sai, nhưng dùng làm tín hiệu chất lượng retrieval — `guessed` + đáp án đúng **không** được tính là retrieval độc lập trong Retention Engine ([SDD-017 §4](sdd-017-retention.md)). Phase sau: blueprint per dạng bài khai riêng bộ label (mã giữ nguyên), thay cho bảng tra trong app. **Evidence contract** (theo SDD-002 §5, sự kiện đặt tên theo SDD-010 §5): * `problem_open` · `problem_submit(answer, confidence, justification_ref, duration)` · `problem_self_verdict(verdict)` · `problem_state_change(state)` (§5). * Reliability: kết quả chấm auto theo `answer_summary` = `learning_task` (.80); self-verdict và confidence = `self-report` (.50); đánh giá justification bằng AI = ghi kèm `{model, prompt_version, evaluation_state}` theo SDD-002 §15 và chịu QG-010. * Idempotency: `exam_problem::submit:`. * Evidence gắn theo **node links** của bài (§3) → cùng pipeline mastery/readiness như mọi evidence khác (WF-04); không có đường cập nhật model riêng. ## 5. Trạng thái luyện tập cá nhân + lọc (REQ-EXAM-08) ```text learner_problem_state (learner-owned) learner_id, problem_id, attempts_count, -- đếm tự động từ problem_submit (không tự khai) last_attempt_at, personal_state[chua_lam|dang_lam|da_lam|be_tac|chua_tu_tin|tu_tin], bookmarked BOOL, note?, -- ghi chú ngắn của learner updated_at ``` * **Learner-owned marks**: `personal_state`/`bookmarked`/`note` do learner đặt, hệ không tự sửa (trừ `chua_lam → da_lam` khi có submit đầu tiên). Marks **không ghi thẳng vào Learner Model** — khi learner đánh dấu `be_tac`/`chua_tu_tin`, hệ phát thêm evidence `self-report` (.50) để Engine biết, còn mastery chỉ đổi qua pipeline evidence (§4). * **Lọc đa chiều**, kết hợp được: môn · dạng bài (`problem_types`) · trường/hệ thi · năm học · vòng (điều kiện/chuyên) · độ khó · trạng thái cá nhân · số lần làm (`= 0`, `≥ 3`, `≥ 9`…) · bookmarked. Hai lối vào: **theo đề** (trường → năm → đề → danh sách bài) và **theo bài** (filter phẳng xuyên đề). * Ví dụ đúng yêu cầu SRC-029: "bài đã làm 3 lần", "bài chưa làm lần nào", "bài bế tắc", "bài làm 9 lần vẫn chưa tự tin" — đều là 1 filter query trên bảng này. * **Overlearning** (SDD-002 §12): làm lại không giới hạn; nhưng khi node của bài đã ổn định (mastery + confidence đạt STOP), cockpit hiển thị nhắc "kỹ năng này đã vững — nên chuyển sang X" — nhắc, không chặn. ## 6. Link về Learning Experience — học lại (REQ-EXAM-09) * Mỗi bài → skill/knowledge nodes (§3, `entity_relations assesses`) → các Learning Experience `teaches` cùng node (SDD-004). UI mỗi bài có khối **"Học lại kiến thức của bài này"** liệt kê LX theo node, ưu tiên node yếu nhất theo Learner Model. * Learner xem được **LX ứng với từng bài trong mỗi đề** ngay từ màn xem bài (kể cả chưa làm) — dùng để *tham khảo* trước khi làm hoặc *học lại* sau khi sai. * Đánh dấu `be_tac` → gợi ý mở rộng: prerequisite path của node (SDD-002 §11 prerequisite check) thay vì chỉ LX cùng node. * Không curate tay từng bài → LX; mọi liên kết đi qua node graph để không tạo nguồn sự thật thứ hai. Bài thiếu node link không được publish (QG-011). ## 7. Ingestion & seed content (REQ-EXAM-10, WF-13) ```text WF-13: Sưu tầm (PDF/ảnh/text + nguồn) → OCR/nhập → Tách bài (label theo đề gốc) → Biên tập statement (markdown + KaTeX + hình) → Gắn metadata + problem_types + node links → Soạn lời giải gợi ý (AI draft → AI multi-evaluator) → Deterministic checks (QG-011) → Publish (đề + bài + Assessment Experience) ``` * Surface biên tập: **Coral** — content plane tại coral.nemo12.com (REQ-CNT, [SDD-013](sdd-013-coral-content-plane.md)) — màn Exam Bank: nhập đề, tách bài, preview statement/solution, gắn node (dùng chung Knowledge Registry browse REQ-CNT-01). * **Seed content mục tiêu** (chỉ đạo SRC-029; thứ tự ưu tiên chốt Q-063 ✅ 2026-08-14): **1. Chuyên Sư phạm → 2. Chuyên KHTN → 3. Ams** (Ams: đề điều kiện là đề chung Sở Hà Nội) × **3 năm tuyển sinh** (2024, 2025, 2026) × **3 môn** (Toán, Ngữ văn, Tiếng Anh) × **cả điều kiện lẫn chuyên**, kèm lời giải từng bài **tự biên soạn** (Q-070 ✅). Nguồn đã khảo sát ghi tại research report (không thuộc docs canonical). * Grade scope khởi điểm: thi vào 10 (grade 9) — Shark; mở rộng đề học kỳ thật (Turtle) sau. ## 8. API & UI surfaces * **API**: mở rộng module `workers/api/src/modules/exams` (giữ 1 bounded module cho exam bank): `GET /v1/exam-bank/exams?school=&year=&round=&subject=` · `GET /v1/exam-bank/exams/{id}/problems` · `GET /v1/exam-bank/problems?filters…` · `GET /v1/exam-bank/problems/{id}` (statement; solution chỉ trả sau submit hoặc khi learner yêu cầu tường minh) · `POST /v1/exam-bank/problems/{id}/submit` · `POST /v1/exam-bank/problems/{id}/state` (personal_state/bookmark/note) · route content-plane cho ingestion (staff-gated, surface Coral — SDD-013). * **Learn UI (Shark)**: tab "Đề thi thật": danh sách đề theo trường/năm → màn đề (danh sách bài + trạng thái cá nhân từng bài) → màn bài (statement → làm → lời giải → LX liên quan) + màn "Luyện theo bài" (filter phẳng §5). * Feature↔doc parity (chỉ đạo 2026-08-13): mọi màn build phải trace về REQ-EXAM-05..10 + US-43..45. ## Trace | REQ | Section | | --- | --- | | REQ-EXAM-05 | §2 | | REQ-EXAM-06 | §3 | | REQ-EXAM-07 | §4 | | REQ-EXAM-08 | §5, §8 | | REQ-EXAM-09 | §6 | | REQ-EXAM-10 | §7 | Liên quan: SDD-011 §3–§4 (đề generated + mock exam — giữ nguyên phạm vi cũ) · SDD-004 §5–9 (Assessment subtype, Item Bank) · SDD-002 §5, §11–§12 (evidence, prerequisite, overlearning) · SDD-003 §8, §10, §13 (review, lifecycle, provenance) · Q-038, Q-061, Q-062, Q-063.