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:

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)

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/<exam_id>/p<ord>/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/<exam_id>/p<ord>/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.

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)

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.

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ị:

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). 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:<problem_id>:submit:<attempt>.
• 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)

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)

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) — 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.