Quy trình tạo ngân hàng câu hỏi

Question Bank là data asset tĩnh, có version. AI có thể hỗ trợ soạn bản nháp, nhưng runtime diagnostic chỉ đọc bản đã được con người duyệt và publish.

1. Offline authoring flow — luồng soạn ngoại tuyến

RAG grounding xảy ra ở bước soạn, không ở bước chấm.

2. Directory contract

data/question_bank/<course_id>/<version>/
├── knowledge_map.json
└── question_bank.json

QuestionBankVersion.is_published chỉ đúng khi đồng thời:

published_at != null
approved_by.trim() != ""

3. Question item schema

Trường lõi:

question_id
course_id
cluster_id
chapter_id
topic_id
clo_id
competency_id
additional_competency_ids
prompt
question_type
difficulty
expected_answer
accepted_aliases
rubric
options
misconception_if_wrong
misconception_severity
distractor_rationale
source_reference

4. Coverage Map — bản đồ độ bao phủ

Mỗi competency có:

• question_ids đo nó;
• required_evidence_count;
• is_core;
• notes review.

Một gap tồn tại khi competency cốt lõi không có đủ số câu:

Baseline required_evidence_count = 1.

5. Publish gate — cổng phát hành

Runtime loader từ chối asset khi:

• file không tồn tại;
• JSON/Pydantic schema sai;
• approved_by rỗng;
• published_at thiếu;
• Knowledge Map version không khớp bank version;
• course_id không khớp;
• coverage trỏ tới question ID không tồn tại.

6. Current asset inventory — tồn kho hiện tại

v1 publish tại 2026-08-20T00:00:00Z, v2 tại 2026-08-29T00:00:00Z (tra theo BANK_APPROVAL_DATES, không phải một PUBLISHED_AT dùng chung). v1 là bất biến (PUBLISHED_IMMUTABLE_VERSION). Tổng: 715 item mỗi version, 1430 item cả hai. v2 thêm ≥3 tiêu chí rubric cho toàn bộ 26 item high_information mỗi môn, source_reference đầy đủ, accepted_aliases cho item cloze, khoá đáp án MCQ đã permute tất định (ANSWER_KEY_PERMUTATION_SEED) và 18 errata nội dung.

7. Data quality status — tình trạng chất lượng dữ liệu

Đo trực tiếp trên asset, 715 item mỗi version:

misconception_if_wrong bằng đúng số MCQ (390) ở cả hai version: nó là trường của phương án nhiễu, không phải của bài tự luận.

Histogram số tiêu chí rubric của 130 item high_information:

v1  {1: 3, 2: 101, 3: 26}
v2  {3: 130}

Đây là lý do is_servable_item() quyết định theo từng item: 104/130 item high_information của v1 dưới MIN_RUBRIC_CRITERIA_FOR_AI_RUBRIC = 3 nên không servable, còn 26 item của v1 thì đã đạt. Trên v2 cả 130 item đều đạt.

misconception_severity, distractor_rationale và additional_competency_ids vẫn trống ở cả hai version. Điều này không làm runtime sai contract, nhưng giới hạn khả năng kiểm chứng misconception major và câu hỏi đa năng lực.

8. Versioning rule — luật phiên bản

Không sửa nội dung của v1 đã publish tại chỗ. Khi thay câu/rubric:

v1 giữ nguyên cho audit
→ tạo v2
→ validate
→ Role 1 approve
→ publish v2
→ evidence mới ghi question_bank_version = v2

Script build gán approved_by từ hằng số APPROVED_BY và published_at tra theo BANK_APPROVAL_DATES[version] — cho mọi course ID. Không thêm điều kiện riêng cho DSA: regenerate có thể vô tình hạ các môn khác thành draft. PUBLISHED_IMMUTABLE_VERSION = "v1" khiến build lại v1 phải tái tạo đúng bản đã publish.

9. Validation commands

python scripts/validate_question_bank.py data/question_bank/dsa/v2/question_bank.json
python scripts/build_question_bank.py
python scripts/ingest_curriculum.py

ingest_curriculum.py là công cụ authoring offline, không phải lệnh cần chạy cho mỗi phiên diagnostic.

10. Thuật ngữ

• Question Bank — ngân hàng câu hỏi: tập câu/rubric được quản trị như dữ liệu.
• Data asset — tài sản dữ liệu: dữ liệu có owner, version và vòng đời.
• Coverage Map — bản đồ bao phủ: mapping competency ↔ câu hỏi.
• Draft — bản nháp: chưa được dùng runtime.
• Publish — phát hành: cho phép runtime sử dụng.
• Distractor rationale — lý do phương án nhiễu: giải thích lỗi hiểu sai mà đáp án sai đại diện.
• Source reference — tham chiếu nguồn: trang/slide dùng để soạn item.