Rules & Constraints

Các yêu cầu phi chức năng, quy tắc nghiệp vụ, kịch bản thực nghiệm và phân tích rủi ro

---

Tài liệu này xác định các ràng buộc hệ thống, yêu cầu phi chức năng, cấu trúc thực thể dữ liệu, tiêu chuẩn AI, quy tắc nghiệp vụ, kịch bản demo và phân tích rủi ro cho EduOne Adaptive Learning Engine.

---

1. Non-Functional Requirements (NFR)

Click to view detailed specifications & content

NFR-001 — Performance (Hiệu năng)

• Thời gian tải trang chính của học viên và giáo viên phải dưới 3 giây trong điều kiện kết nối mạng Internet bình thường.
• Thuật toán cập nhật Learner Model và tính toán đề xuất (Recommendation Engine) phải hoàn tất trong vòng dưới 5 giây đối với Prototype.
• Tác vụ sinh học liệu bằng AI (tạo outline hoặc soạn quiz) có thể mất nhiều thời gian hơn (đến 30-60 giây) nhưng hệ thống phải hiển thị thanh trạng thái (loading/progress bar) rõ ràng để người dùng không cảm giác bị treo.

NFR-002 — Availability/Stability (Khả dụng)

• Hệ thống Prototype phục vụ Hackathon phải hoạt động ổn định, đảm bảo thực hiện được kịch bản demo end-to-end mà không bị lỗi crash hệ thống hoặc yêu cầu người dùng phải chỉnh sửa dữ liệu trực tiếp trong database.

NFR-003 — Resilience & Error Handling (Khả năng phục hồi)

• Nếu kết nối API tới nhà cung cấp AI (ví dụ: Google Gemini API) bị ngắt quãng hoặc báo lỗi, hệ thống phải giữ nguyên dữ liệu yêu cầu (prompt/input) của tác giả, hiển thị thông báo lỗi rõ ràng bằng tiếng Việt và cho phép người dùng bấm thử lại (Retry).
• Sự cố API AI không được làm ảnh hưởng đến việc hiển thị giao diện học tập của học viên; hệ thống phải tự động chuyển sang đề xuất mặc định (Fallback).

NFR-004 — Scalability (Khả năng mở rộng)

• Kiến trúc phần mềm và cơ sở dữ liệu phải được thiết kế để dễ dàng nâng cấp từ quy mô 20 học viên lên hàng nghìn học viên, từ 1 khóa học thử nghiệm lên nhiều khóa học khác nhau, từ việc chỉ thu thập kết quả quiz sang thu thập nhiều dạng bằng chứng (evidence) học tập đa dạng.
• Hệ thống dễ dàng cắm rút và thay đổi giữa các nhà cung cấp mô hình AI khác nhau thông qua một lớp trung gian (AI Gateway/Service Adapter).

NFR-005 — Security (Bảo mật)

• Xác thực người dùng bằng tài khoản và mật khẩu (hoặc tích hợp Google OAuth).
• Áp dụng phân quyền vai trò (RBAC) nghiêm ngặt để đảm bảo:
  • Học viên không thể truy cập các trang quản trị của Giáo viên, Author hay Admin.
  • Content Author không được phép tự phê duyệt (Approve) học liệu của mình.
• Bảo vệ tuyệt đối các khóa bảo mật (API keys/secrets), không được để lộ trong mã nguồn Front-end hoặc lưu trữ không mã hóa.

NFR-006 — Privacy (Quyền riêng tư)

• Chỉ thu thập các dữ liệu cá nhân tối thiểu của học viên phục vụ cho việc học tập (tránh thu thập số điện thoại, địa chỉ nếu không cần thiết).
• Trong nhật ký hệ thống (Audit logs/Debug logs), ưu tiên sử dụng mã định danh (Student ID) thay vì hiển thị trực tiếp tên thật của học sinh.
• Dữ liệu gửi lên API của bên thứ ba (AI Providers) không được chứa thông tin cá nhân nhạy cảm (PII).
• Toàn bộ dữ liệu của 20 học viên demo phải là dữ liệu giả lập hoặc đã được ẩn danh hóa hoàn toàn.

NFR-007 — Auditability (Nhật ký kiểm toán)

• Mọi hành động làm thay đổi dữ liệu cấu hình hoặc trạng thái học liệu bắt buộc phải được ghi nhật ký với đầy đủ thông tin: nhãn thời gian (timestamp), định danh người thực hiện (actor ID), và phiên bản dữ liệu trước/sau khi đổi.

NFR-008 — Usability (Tính dễ sử dụng)

• Giao diện dành cho giáo viên tình nguyện và đội ngũ nội dung (những người không chuyên về công nghệ) phải được thiết kế trực quan, dễ hiểu, các nút chức năng rõ ràng.
• Các lý giải đề xuất của AI phải sử dụng từ ngữ ngôn ngữ tự nhiên thân thiện thay vì hiển thị các mã code kỹ thuật thô.

NFR-009 — Accessibility (Khả năng tiếp cận)

• Thiết kế giao diện sử dụng font chữ rõ ràng, độ tương phản màu sắc đạt chuẩn để không gây mỏi mắt cho học sinh K-12.
• Không sử dụng duy nhất màu sắc để biểu thị trạng thái (ví dụ: thay vì chỉ tô đỏ câu trả lời sai, cần đính kèm biểu tượng dấu X hoặc nhãn văn bản "Chưa đúng").

NFR-010 — Localization (Ngôn ngữ)

• Giao diện và nội dung học tập dành cho học viên bắt buộc phải sử dụng 100% tiếng Việt tự nhiên.
• Giao diện quản trị dành cho giáo viên và đội ngũ nội dung ưu tiên tiếng Việt, các thuật ngữ tiếng Anh chuyên ngành có thể đi kèm trong ngoặc đơn để làm rõ nghĩa.

NFR-011 — Maintainability (Khả năng bảo trì)

• Toàn bộ prompt template, luật đánh giá chất lượng (quality criteria) và các luật đề xuất (recommendation rules) phải được lưu trữ độc lập dưới dạng file cấu hình (JSON/YAML) hoặc bảng dữ liệu để dễ dàng chỉnh sửa mà không cần phải biên dịch lại mã nguồn hệ thống.

NFR-012 — Observability (Khả năng giám sát)

• Hệ thống tích hợp các công cụ ghi nhận lỗi thời gian thực, giám sát thời gian phản hồi (latency) của API AI, theo dõi số lượng token tiêu thụ và chi phí tương ứng của từng request AI để kịp thời cảnh báo khi có chi tiêu bất thường.

NFR-013 — Cost Efficiency (Tối ưu hóa chi phí)

• Thiết kế hệ thống thông minh nhằm giảm thiểu chi phí API LLM:
  • Cache kết quả phản hồi của AI cho các yêu cầu giống hệt nhau.
  • Chỉ gọi AI cho các tác vụ sinh nội dung sáng tạo hoặc kiểm tra chất lượng phức tạp.
  • Sử dụng logic code lập trình (rule-based) để xử lý việc cập nhật trạng thái học viên và lựa chọn đề xuất trong thư viện thay vì gọi LLM.

NFR-014 — Vendor Portability (Khả năng chuyển đổi nhà cung cấp)

• Hệ thống không được phụ thuộc cứng vào bất kỳ một nhà cung cấp dịch vụ AI nào. Cấu trúc prompt và định dạng dữ liệu trả về phải được chuẩn hóa để có thể dễ dàng chuyển đổi từ Google Gemini sang OpenAI GPT hoặc Anthropic Claude khi cần thiết.

---

2. Data Requirements

Click to view detailed specifications & content

Key Domain Entities (2.1. Bản đồ thực thể chính)

Hệ thống quản lý mối quan hệ giữa các thực thể cốt lõi sau:

erDiagram
    USER ||--o| ROLE : has
    STUDENT ||--|| USER : is
    TEACHER ||--|| USER : is
    CLASS ||--o{ STUDENT : contains
    CLASS ||--o{ TEACHER : managed_by
    COURSE ||--o{ CLASS : assigned_to
    COURSE ||--o{ LESSON : contains
    LESSON ||--o{ SKILL : assesses
    SKILL ||--o{ INDICATOR : details
    INDICATOR ||--o{ CONTENT_ITEM : mapped_to
    STUDENT ||--o{ SUBMISSION : submits
    SUBMISSION ||--o{ EVIDENCE : generates
    EVIDENCE ||--|| INDICATOR : linked_to
    STUDENT ||--o{ LEARNER_STATE : holds
    LEARNER_STATE ||--|| SKILL : relates_to
    LEARNER_STATE ||--o{ RECOMMENDATION : drives
    RECOMMENDATION ||--|| CONTENT_ITEM : suggests
    RECOMMENDATION ||--o{ RECOMMENDATION_LOG : records
    TEACHER ||--o{ TEACHER_OVERRIDE : performs
    CONTENT_ITEM ||--o{ CONTENT_VERSION : has
    CONTENT_ITEM ||--o{ QUALITY_CHECK : passes
    CONTENT_ITEM ||--o{ REVIEW : undergoes

• User (Người dùng): ID, Email, Password, Trạng thái hoạt động.
• Role (Vai trò): ID, Tên vai trò (Student, Teacher, Author, Reviewer, Admin), Quyền hạn.
• Student (Học viên): ID, User_ID, Tên hiển thị, Tuổi, Lớp học hiện tại.
• Teacher (Giáo viên): ID, User_ID, Tên hiển thị, Lớp quản lý.
• Course (Khóa học): ID, Tên khóa học, Mô tả, Trạng thái (Active/Draft).
• Lesson (Bài học): ID, Course_ID, Thứ tự, Tên bài học, Mô tả.
• Skill (Kỹ năng): Code, Tên kỹ năng, Mô tả, Course_ID.
• Indicator (Chỉ chỉ báo): Code, Skill_Code, Tên chỉ báo, Mô tả, Ngưỡng mastery.
• Submission (Bài nộp): ID, Student_ID, Quiz_ID, Trạng thái (Complete/Incomplete), Điểm số, Thời gian nộp.
• Evidence (Bằng chứng): ID, Student_ID, Submission_ID, Indicator_Code, Điểm (Đúng/Sai), Thời gian làm, Trọng số tin cậy.
• Learner State (Trạng thái học viên): Student_ID, Skill_Code, Mastery_Estimate, Confidence_Score, Thời gian cập nhật cuối.
• Content Item (Học liệu): ID, Title, Objective, Skill_Code, Indicator_Code, Difficulty, Status (Draft/Published/Archived), Author_ID, Reviewer_ID.
• Content Version (Phiên bản học liệu): Item_ID, Version_No, Nội dung (JSON/Markdown), Người sửa, Timestamp.
• Recommendation (Đề xuất): ID, Student_ID, Item_ID, Target_Skill, Reason_Code, Status (Active/Overridden/Completed), Timestamp.
• Teacher Override (Giáo viên ghi đè): ID, Teacher_ID, Student_ID, Original_Rec_ID, New_Item_ID, Lý do, Hạn hiệu lực.
• Audit Event (Nhật ký hệ thống): ID, Timestamp, Actor_ID, Action_Type, Chi tiết thay đổi.

Data Principles (2.2. Nguyên tắc quản lý dữ liệu)

• Tính toàn vẹn (Integrity): Mọi thực thể chính đều phải có mã định danh duy nhất (UUID/Primary Key) và các trường ghi nhận thời gian (created_at, updated_at).
• Truy vết ngược (Traceability): Điểm năng lực (Mastery Estimate) của học viên phải luôn có thể tính toán/giải thích ngược lại dựa trên danh sách các bằng chứng gốc (Evidence IDs) đã thu thập.
• Không ghi đè lịch sử (Immutability of Evidence): Dữ liệu bằng chứng học tập (Evidence) một khi đã ghi nhận thì không được phép chỉnh sửa hoặc xóa bỏ để đảm bảo tính chính xác của lịch sử tiến trình học tập.
• Đánh dấu nguồn gốc AI (Provenance): Mọi học liệu được sinh ra hoặc chỉnh sửa bởi AI phải được gắn cờ is_ai_generated: true và lưu kèm thông tin phiên bản prompt đã sử dụng.

Data Quality Rules (2.3. Kiểm soát chất lượng dữ liệu đầu vào)

• Hệ thống tự động từ chối ghi nhận hoặc đưa ra cảnh báo lỗi đối với:
  • Bản ghi nộp bài (submission) bị trùng lặp ID hoặc sai lệch thời gian nộp (nộp trước khi bắt đầu làm).
  • Điểm số nằm ngoài khoảng quy định (ví dụ: điểm số âm hoặc vượt quá điểm tối đa).
  • Học liệu bị thiếu các metadata bắt buộc như mã kỹ năng hoặc độ tuổi áp dụng.

---

3. AI Design Requirements

Click to view detailed specifications & content

• AI-REQ-001 — AI hoạt động thực tế (Real AI execution): Hệ thống Demo/Prototype bắt buộc phải có kết nối và chạy thực tế API của mô hình ngôn ngữ lớn (như Gemini 1.5) để thực hiện các tác vụ sinh bản thảo học liệu và chạy bộ luật kiểm tra chất lượng (Quality Checks). Tuyệt đối không sử dụng dữ liệu tĩnh hoặc kịch bản giả lập (mockup) cho chức năng AI Content.
• AI-REQ-002 — Phân tách rõ ràng Logic nghiệp vụ và AI (Separation of Logic): Động cơ đề xuất (Recommendation Engine) và quy trình cập nhật Learner Model phải được xử lý bằng code logic nghiệp vụ có cấu trúc rõ ràng (Deterministic Logic). Mô hình ngôn ngữ lớn (LLM) chỉ được sử dụng ở phân hệ sinh nội dung (Content Generation) và phân tích ngôn ngữ tự nhiên (Văn phong, Độ tuổi).
• AI-REQ-003 — Định dạng đầu ra có cấu trúc (Structured Output): Tất cả các câu lệnh gửi tới AI (Prompts) yêu cầu sinh học liệu, quiz hay kết quả kiểm tra chất lượng phải cấu hình tham số trả về dạng cấu trúc JSON Schema được định nghĩa sẵn để hệ thống lập trình có thể phân tích cú pháp dễ dàng.
• AI-REQ-004 — Quản lý phiên bản Prompt (Prompt Versioning): Mỗi prompt template sử dụng trong hệ thống phải được lưu trữ độc lập, đánh mã số phiên bản (ví dụ: prompt-mcq-generation-v1.2) và ghi nhận lịch sử thay đổi để phục vụ kiểm soát chất lượng đầu ra của AI.
• AI-REQ-005 — Lựa chọn mô hình tối ưu theo tác vụ (Model Selection Optimization): Hệ thống hỗ trợ cấu hình gán tác vụ cho các mô hình AI khác nhau tùy theo độ phức tạp:
  • Dùng mô hình nhỏ, tốc độ nhanh (như Gemini Flash) cho việc kiểm tra chất lượng tự động, sinh quiz cơ bản.
  • Dùng mô hình lớn, khả năng suy luận tốt (như Gemini Pro) cho việc soạn thảo bài giảng chi tiết hoặc sinh các bài tập nâng cao phức tạp.
• AI-REQ-006 — Kiểm soát lỗi ảo tưởng (Hallucination Control): Giảm thiểu tối đa lỗi sinh thông tin sai lệch của AI bằng cách:
  • Cung cấp ngữ cảnh đầu vào có cấu trúc cao (Input Context).
  • Sử dụng Prompt Kỹ thuật (Few-shot prompting) kèm theo các ví dụ mẫu chuẩn xác.
  • Bắt buộc chạy qua bộ lọc kiểm tra chất lượng tự động (Automated Quality Checks) và quy trình phê duyệt của con người trước khi xuất bản.
• AI-REQ-007 — Cơ chế xử lý khi AI gặp sự cố (AI Fallback): Nếu AI trả về định dạng JSON không hợp lệ hoặc gặp sự cố quá tải API:
  • Hệ thống giữ nguyên trạng thái yêu cầu của người dùng, không làm mất dữ liệu đã nhập.
  • Hiển thị thông báo lỗi thân thiện và cho phép tác giả thực hiện lại tác vụ.
  • Tuyệt đối không đưa các kết quả lỗi vào thư viện học liệu.
• AI-REQ-008 — Nhật ký sử dụng AI (AI Usage Logging): Ghi nhật ký chi tiết cho mỗi lượt gọi API AI phục vụ việc tối ưu hóa chi phí: Tên tác vụ, Tên mô hình sử dụng, Số lượng Input Tokens, Số lượng Output Tokens, Độ trễ phản hồi (ms), Trạng thái (Thành công/Lỗi), và Chi phí ước tính.

---

4. Mandatory Business Rules (BR)

Click to view detailed specifications & content

• BR-001: Bất kỳ đơn vị học liệu nào chưa chuyển sang trạng thái "Published" trong thư viện thì Recommendation Engine không được phép hiển thị hoặc đề xuất cho học viên.
• BR-002: Mọi đề xuất lộ trình học tập thích ứng của hệ thống phải dựa trên ít nhất một trạng thái năng lực (Learner State) hoặc bằng chứng học tập (Evidence) hợp lệ của chính học viên đó.
• BR-003: Khi chỉ số Confidence Score của một kỹ năng nằm dưới ngưỡng cấu hình (ví dụ: < 0.4 due to insufficient data), hệ thống bắt buộc phải hiển thị ghi chú cảnh báo cho giáo viên: "Dữ liệu chưa đủ tin cậy" và không được kết luận năng lực học viên đạt mức thành thạo.
• BR-004: Quyết định ghi đè (Override) của giáo viên luôn có độ ưu tiên cao nhất. Khi giáo viên đã override một đề xuất, hệ thống phải dừng hiển thị đề xuất tự động đó cho học viên và áp dụng nội dung do giáo viên chỉ định trong suốt thời gian hiệu lực của override.
• BR-005: Khi một học liệu bị chuyển trạng thái thành "Unpublished" hoặc "Archived", hệ thống phải lập tức loại bỏ học liệu này khỏi tất cả các đề xuất lộ trình đang chạy trong hàng đợi của học viên.
• BR-006: Reviewer không được phép phê duyệt (Approve) một học liệu nếu học liệu đó còn thiếu bất kỳ trường thông tin metadata bắt buộc nào (Mã kỹ năng, Độ khó, Độ tuổi).
• BR-007: Một đơn vị học liệu chỉ được coi là chuyển sang trạng thái "Published" khi có bản ghi log phê duyệt ghi rõ ID của Reviewer và thời điểm phê duyệt.
• BR-008: Tất cả các nội dung do AI sinh ra phải được đánh dấu nhãn nguồn gốc rõ ràng trên hệ thống quản trị để Reviewer dễ dàng nhận biết và tập trung rà soát.
• BR-009: Hệ thống không được phép đưa ra kết luận học viên đã thành thạo (Mastery) một kỹ năng nếu chỉ dựa trên một bằng chứng (Evidence) duy nhất. Cần tối thiểu một số lượng bằng chứng cấu hình sẵn (ví dụ: tối thiểu 3 bằng chứng làm đúng liên tiếp).
• BR-010: Học viên tuyệt đối không được nhìn thấy các thông tin kỹ thuật nội bộ của hệ thống như: Confidence Score của thuật toán, Threshold cấu hình, hoặc các mã lỗi lập trình trên giao diện của mình.
• BR-011: Giáo viên phải được quyền xem chi tiết các câu trả lời sai cụ thể của học sinh trong bài quiz để hiểu bản chất lỗi sai, hệ thống không được che giấu dữ liệu này.
• BR-012: Trong tình huống không tìm thấy bất kỳ học liệu nào phù hợp với trình độ của học viên trong kho nội dung đã phê duyệt, hệ thống phải tự động đề xuất lộ trình học an toàn mặc định (Default Fallback) hoặc gửi thông báo yêu cầu giáo viên can thiệp trực tiếp, tuyệt đối không được để màn hình trống hoặc tự tạo nội dung chưa duyệt cho học viên.

---

5. Exception Handling (EX)

Click to view detailed specifications & content

• EX-001 — Học viên mới (Cold Start): Khi học viên mới đăng nhập và hoàn toàn chưa có bất kỳ dữ liệu lịch sử làm bài nào:
  • Hệ thống hiển thị đề xuất làm bài đánh giá năng lực đầu vào (Diagnostic Quiz).
  • Nếu không có bài đánh giá, hệ thống sẽ đề xuất bài học cơ bản đầu tiên của chương trình chuẩn.
  • Thiết lập chỉ số Confidence Score của học viên ở mức 0.0.
• EX-002 — Học viên bỏ dở bài thi giữa chừng: Học viên đóng trình duyệt hoặc mất kết nối mạng khi đang làm quiz:
  • Hệ thống ghi nhận trạng thái bài nộp là Incomplete kèm điểm số tính đến câu hỏi cuối cùng học viên đã hoàn thành.
  • Hệ thống không tính các câu hỏi chưa làm là câu trả lời sai nếu quy tắc của khóa học không yêu cầu phạt.
  • Lần đăng nhập sau, hệ thống đề xuất học viên tiếp tục hoàn thành bài thi dở dang hoặc đề xuất một bài ôn luyện ngắn hơn tùy thuộc vào cấu hình của giáo viên.
• EX-003 — Kết quả làm bài bất thường (Anomaly Detected): Học viên hoàn thành bài thi 10 câu trắc nghiệm chỉ trong vòng 5 giây và đạt điểm tối đa hoặc tối thiểu:
  • Hệ thống ghi nhận kết quả làm bài vào cơ sở dữ liệu để đối chiếu.
  • Tuy nhiên, hệ thống sẽ gắn cờ cảnh báo Anomaly cho bằng chứng này và tự động giảm trọng số tin cậy của bằng chứng khi cập nhật Learner Model.
  • Gửi cảnh báo "Làm bài bất thường" đến dashboard của giáo viên.
• EX-004 — Lỗi kết nối hệ thống đề xuất (Engine Failure): Khi máy chủ Recommendation Engine gặp sự cố không thể trả về kết quả đề xuất cá nhân hóa cho học viên:
  • Giao diện học viên tự động hiển thị bài giảng/bài tập tiếp theo theo trình tự tuyến tính mặc định của khóa học.
  • Ghi nhận log lỗi hệ thống để đội kỹ thuật xử lý.
  • Tuyệt đối không hiển thị thông báo lỗi kỹ thuật gây hoang mang cho học sinh.
• EX-005 — AI sinh học liệu bị lỗi hoặc trả về rỗng: Trong quá trình Content Author sử dụng AI để soạn bài giảng mà API AI bị ngắt kết nối hoặc trả về nội dung rỗng/lỗi cú pháp JSON:
  • Hệ thống thông báo lỗi bằng tiếng Việt: "AI hiện đang bận hoặc gặp lỗi định dạng, vui lòng nhấn thử lại".
  • Giữ nguyên các thông tin yêu cầu đầu vào của tác giả trên form soạn thảo để họ không phải nhập lại từ đầu.
• EX-006 — Phát hiện học liệu đã xuất bản bị sai sót kiến thức: Sau khi học liệu đã được xuất bản và phân phối cho học viên, Reviewer hoặc Giáo viên phát hiện lỗi sai kiến thức nghiêm trọng:
  • Người dùng có quyền lập tức nhấn nút "Unpublish".
  • Hệ thống lập tức thu hồi học liệu khỏi kho đề xuất.
  • Hệ thống quét và liệt kê danh sách các học viên đã học/làm bài tập này để giáo viên có phương án hỗ trợ bù đắp kiến thức.
  • Lưu audit log ghi rõ lý do thu hồi.
• EX-007 — Không có giáo viên trực tuyến (No Teacher Online): Trong trường hợp hệ thống phát sinh đề xuất cần giáo viên duyệt hoặc ghi đè nhưng giáo viên không online:
  • Học viên vẫn được tiếp tục học tập bình thường theo các đề xuất tự động của AI đã được phê duyệt trước từ thư viện để đảm bảo việc học không bị gián đoạn.
• EX-008 — Học liệu bị gán sai mục tiêu kỹ năng (Mapping Error): Khi phát hiện một quiz/bài tập bị liên kết sai kỹ năng (ví dụ bài Toán nhưng lại gán mã kỹ năng Tin học):
  • Admin hoặc Curriculum Lead thực hiện chỉnh sửa lại metadata của học liệu.
  • Hệ thống cung cấp tùy chọn tự động tính toán lại điểm năng lực (Recalculate Learner State) của các học viên đã làm bài này bằng cách chuyển bằng chứng (evidence) sang kỹ năng đúng và cập nhật lại Learner Model.

---

6. Hackathon Demo Scenarios (DEMO)

Click to view detailed specifications & content

Để chứng minh năng lực thực tế của hệ thống trong buổi thuyết trình Hackathon, sản phẩm phải thực hiện trơn tru các kịch bản demo sau:

• DEMO-01 — Khởi tạo dữ liệu mẫu đa dạng: Hệ thống cài đặt sẵn dữ liệu của 20 học viên với các trạng thái học tập phong phú: học viên mới (chưa có dữ liệu), học viên mất gốc (hổng kiến thức nền), học viên học không ổn định, học viên xuất sắc tiến bộ nhanh, và học viên có bài nộp bị dính cờ bất thường/chưa hoàn thành.
• DEMO-02 — Cập nhật Learner Model trực quan: Thực hiện demo một học viên tiến hành làm một bài quiz ngắn, sau khi nộp bài, màn hình giáo viên lập tức cập nhật sự thay đổi của điểm năng lực (Mastery Estimate) và Độ tin cậy (Confidence Score) trên biểu đồ tương ứng.
• DEMO-03 — Đề xuất thích ứng khác biệt: Hiển thị màn hình của 3 học sinh khác nhau trong cùng một lớp học tại cùng một thời điểm để chứng minh 3 đề xuất hoàn toàn khác nhau dựa trên trình độ: ôn tập kiến thức cũ, luyện tập kỹ năng hiện tại, hoặc thử thách nâng cao.
• DEMO-04 — Minh bạch hóa quyết định của AI: Mở màn hình chi tiết Recommendation Log của học sinh để chỉ ra cho Ban giám khảo thấy rõ: hệ thống đã dùng những bằng chứng làm bài nào, khoảng trống nào được phát hiện, lý do đề xuất học liệu này và các phương án thay thế khác bị loại bỏ vì sao.
• DEMO-05 — Giao diện giáo viên can thiệp: Thực hiện kịch bản giáo viên không đồng ý với đề xuất của AI đối với một học viên, tiến hành ghi đè (override) bằng một bài tập khác từ thư viện, nhập lý do ghi đè và xác nhận. Màn hình học sinh lập tức cập nhật bài tập mới do giáo viên chỉ định.
• DEMO-06 — Phát hiện thiếu hụt học liệu: Demo tình huống hệ thống phân tích và cảnh báo thiếu học liệu phù hợp cho một nhóm năng lực cụ thể (Content Gap) và tự động tạo ra một yêu cầu soạn thảo học liệu (Content Request) tương ứng.
• DEMO-07 — AI soạn thảo học liệu bằng tiếng Việt: Content Author nhập yêu cầu vào form, nhấn nút gọi AI và hiển thị quá trình AI tạo ra trọn bộ bài giảng và 5 câu quiz MCQ bằng tiếng Việt tự nhiên kèm đáp án và lời giải thích có cấu trúc.
• DEMO-08 — Kiểm tra chất lượng tự động: Chỉ ra màn hình cảnh báo chất lượng tự động (Quality Checks Warning) khi AI sinh lỗi (ví dụ: sinh thiếu giải thích hoặc câu hỏi không có đáp án đúng), hiển thị scorecard đánh giá chất lượng.
• DEMO-09 — Quy trình duyệt bài: Thực hiện thao tác Reviewer mở giao diện duyệt bài giảng vừa sinh, thực hiện chỉnh sửa nhanh một lỗi câu từ và bấm nút "Approve".
• DEMO-10 — Xuất bản học liệu: Cho thấy học liệu chuyển trạng thái sang "Published" và được cập nhật ngay lập tức vào cơ sở dữ liệu thư viện.
• DEMO-11 — Vòng lặp khép kín: Quay lại màn hình đề xuất học sinh, chứng minh học liệu vừa xuất bản ở bước trước đã tự động xuất hiện trong danh sách đề xuất cá nhân hóa của học sinh phù hợp.
• DEMO-12 — Đo lường năng suất tạo nội dung: Hiển thị biểu đồ/bảng so sánh thời gian thực tế để tạo ra bài học vừa rồi so với baseline thủ công 40-50 giờ, chứng minh thời gian tiết kiệm được và chi phí token AI đã sử dụng.
• DEMO-13 — Thuyết minh về kiến thức AI tiết kiệm: Trình bày được sơ đồ kiến trúc hệ thống, chứng minh cách thức phân tách logic nghiệp vụ và AI để tiết kiệm tối đa chi phí gọi API LLM, đảm bảo tính kinh tế của giải pháp phi lợi nhuận.

---

7. Acceptance & Success Criteria

Click to view detailed specifications & content

Hackathon Acceptance Criteria (7.1. Tiêu chí nghiệm thu Prototype)

Prototype được coi là đạt yêu cầu tối thiểu khi đáp ứng 10 điều kiện sau:

1. Có địa chỉ chạy thử trực tiếp (Live URL) hoặc video demo đầy đủ các chức năng chính.
2. Có mã nguồn được tải lên kho lưu trữ GitHub công khai (Public GitHub Repository).
3. Đã nạp sẵn dữ liệu giả lập hợp lệ của 20 học viên mẫu.
4. Demo được ít nhất 3 đề xuất học tập thích ứng khác nhau dựa trên Learner Model.
5. Hiển thị được nhật ký đề xuất (Recommendation Log) giải thích rõ ràng lý do đề xuất.
6. Xử lý thành công ít nhất một tình huống dữ liệu lỗi hoặc dữ liệu bất thường của học sinh.
7. Giáo viên thực hiện được thao tác ghi đè (override) đề xuất và ghi lý do can thiệp.
8. Tác vụ AI Content Authoring hoạt động thực tế, sinh ra bản nháp học liệu tiếng Việt tự nhiên.
9. Đảm bảo học liệu chưa duyệt tuyệt đối không được phân phối cho học viên.
10. Reviewer thực hiện được việc chỉnh sửa và phê duyệt bài để đưa vào thư viện học liệu.

Pilot Success Criteria (7.2. Tiêu chí thành công của Pilot thực tế)

Sau thời gian thử nghiệm thực tế 4-6 tuần, dự án được coi là thành công khi đạt được các chỉ số mục tiêu cốt lõi sau:

Nhóm chỉ số	Chỉ số đo lường (KPI)	Mục tiêu kỳ vọng (Target)
Cá nhân hóa	Tỷ lệ đề xuất học liệu có giải thích rõ ràng	100%
Cá nhân hóa	Tỷ lệ giáo viên chấp nhận đề xuất (Acceptance Rate)	> 80%
Cá nhân hóa	Tỷ lệ giáo viên ghi đè (Override Rate)	< 20%
Cá nhân hóa	Thời gian phản hồi tạo đề xuất (Latency)	< 3 giây
Hiệu quả Học tập	Tỷ lệ hoàn thành bài học (Completion Rate)	Tăng 20% so với baseline
Hiệu quả Học tập	Điểm số trung bình cải thiện sau luyện tập bổ trợ	Tăng ít nhất 15%
Sản xuất Nội dung	Tổng thời gian hoàn thành học liệu (Time to Published)	Giảm từ 40-50 giờ xuống < 5 giờ
Sản xuất Nội dung	Tỷ lệ nội dung AI sinh được giữ lại sau kiểm duyệt	> 70%
Kiểm soát Chất lượng	Tỷ lệ lỗi kiến thức lọt lưới đến tay học sinh	0%
Chi phí Vận hành	Chi phí API AI trung bình trên mỗi học liệu được duyệt	< 0.5 USD
Trải nghiệm Giáo viên	Thời gian giáo viên phải dành để điều chỉnh thủ công	Giảm 60%

Lưu ý: Các mục tiêu số cụ thể sẽ được tinh chỉnh lại sau khi đo lường xong số liệu baseline thực tế trong tuần đầu tiên của Pilot.

---

8. Risk Management & Mitigations

Click to view detailed specifications & content

Mã rủi ro	Mô tả rủi ro	Khả năng xảy ra	Mức độ ảnh hưởng	Biện pháp giảm thiểu (Mitigation Actions)
RSK-001	Học viên làm bài quá ít, dẫn đến thiếu hụt dữ liệu đầu vào cho Learner Model.	Cao	Trung bình	* Thiết lập độ tin cậy (Confidence Score) thấp. * Tự động đề xuất bài đánh giá chẩn đoán đầu vào. * Yêu cầu giáo viên nhập nhận xét thủ công để tăng chất lượng ước lượng ban đầu.
RSK-002	AI soạn thảo nội dung bị lỗi ảo tưởng (hallucination) dẫn đến sai lệch kiến thức hoặc đáp án.	Trung bình	Nghiêm trọng	* Bắt buộc chạy bộ lọc QA tự động. * Thiết kế checklist phê duyệt bắt buộc đối với Reviewer. * Hỗ trợ chức năng sửa đổi trực tiếp (Direct Edit) và thu hồi học liệu nhanh (Unpublish).
RSK-003	Recommendation Engine đề xuất hoạt động học tập không phù hợp (quá khó/dễ) cho học sinh.	Trung bình	Cao	* Tuyệt đối chỉ dùng nội dung đã duyệt. * Trao quyền ghi đè tối cao cho giáo viên. * Xây dựng cơ chế ghi log chi tiết lý do đề xuất để nhanh chóng điều chỉnh luật.
RSK-004	Chi phí sử dụng API AI tăng vượt ngân sách của tổ chức phi lợi nhuận.	Trung bình	Trung bình	* Tách biệt logic nghiệp vụ đề xuất (chạy bằng code) và logic AI. * Triển khai cơ chế lưu đệm (caching). * Sử dụng mô hình nhỏ cho các tác vụ đơn giản.
RSK-005	Giáo viên tình nguyện hoài nghi và không tin tưởng vào các đề xuất của AI.	Cao	Cao	* Thiết kế hệ thống giải thích rõ ràng (Explainable AI). * Cung cấp liên kết xem trực tiếp các bằng chứng gốc (evidence). * Đào tạo giáo viên hiểu AI chỉ đóng vai trò trợ lý, giáo viên là người quyết định cuối cùng.
RSK-006	Phạm vi dự án quá rộng (Scope creep) dẫn đến không thể hoàn thành Prototype kịp thời hạn Hackathon.	Cao	Cao	* Giới hạn nghiêm ngặt quy mô: 1 khóa, 1 lớp, 20 học viên. * Chỉ triển khai 3-5 chỉ báo năng lực và 10-15 học liệu mẫu. * Tập trung tối đa vào luồng nghiệp vụ cốt lõi, hoãn các tính năng nâng cao.
RSK-007	Dữ liệu demo quá sạch, không phản ánh đúng thực tế dữ liệu học sinh làm bài lỗi hoặc mạng lag.	Trung bình	Trung bình	* Chủ động nạp các bản ghi dữ liệu bị thiếu trường thông tin, bài nộp dở dang (incomplete) và bài làm có tốc độ bất thường vào bộ dữ liệu test của 20 học viên.
RSK-008	Giải pháp bị biến tướng thành một chatbot hỏi đáp đơn giản, thiếu các cấu trúc quản lý khóa học và học liệu thực tế.	Thấp	Nghiêm trọng	* Xây dựng cơ sở dữ liệu quan hệ chặt chẽ từ cấu trúc khóa học, bản đồ kỹ năng đến hồ sơ năng lực học viên và quy trình phê duyệt học liệu.

---

9. Requirement Traceability Matrix

Click to view detailed specifications & content

Yêu cầu Nghiệp vụ (Objective)	Mã yêu cầu chức năng (Functional Req ID)	Mã yêu cầu phi chức năng / AI / Ràng buộc
OBJ-01 — Cá nhân hóa học tập	UR-LM-002, UR-LM-005, UR-REC-001, UR-REC-002, UR-STU-001	NFR-001, BR-002, EX-001
OBJ-02 — Giảm tải công việc giáo viên	UR-TCH-001, UR-TCH-002, UR-TCH-003, UR-REC-007	NFR-008, BR-004, EX-007
OBJ-03 — Tăng tốc sản xuất học liệu	UR-CNT-001, UR-CNT-002, UR-CNT-003, UR-CNT-004, UR-CNT-005	AI-REQ-001, AI-REQ-005, NFR-003
OBJ-04 — Đảm bảo kiểm soát chất lượng	UR-QA-001 đến UR-QA-005, UR-REV-001, UR-REV-003, UR-REV-005	BR-001, BR-006, BR-007, RSK-002
OBJ-05 — Giải thích được quyết định	UR-REC-004, UR-EXP-001, UR-EXP-002, UR-EXP-003	BR-003, BR-010, AI-REQ-002, RSK-005
OBJ-06 — Khả năng mở rộng & Chi phí	UR-COURSE-003, UR-COURSE-004, UR-LIB-001, UR-RPT-002	NFR-004, NFR-013, AI-REQ-003, RSK-004

---

10. Clarifications & Open Questions

Click to view detailed specifications & content

Để phục vụ cho giai đoạn thiết kế chi tiết hệ thống và triển khai Pilot, đội dự án cần làm rõ 10 câu hỏi nghiệp vụ sau với ban điều hành EduOne:

1. Khóa học cụ thể nào sẽ được chọn để số hóa và thử nghiệm trong giai đoạn Pilot? (Ví dụ: Lập trình Scratch cơ bản hay Python)?
2. Khung năng lực hiện tại của EduOne đã có sẵn danh mục các kỹ năng (skills) và chỉ chỉ báo (indicators) chưa, hay đội ngũ chuyên môn phải xây dựng mới hoàn toàn?
3. Hình thức bài nộp (submissions) hiện tại của học viên trên EduOne chủ yếu là gì? Hệ thống có cần hỗ trợ thu thập mã nguồn code (source code) hay chỉ cần thu thập kết quả quiz trắc nghiệm?
4. Quy trình tính toán thời gian chuẩn bị học liệu (baseline 40-50 giờ) hiện nay bao gồm những bước cụ thể nào? (Soạn bài giảng, thiết kế slide, làm quiz, quay video...)?
5. Tiêu chuẩn chất lượng nội dung (Quality Standards) hiện hành của EduOne đối với học liệu K-12 được tài liệu hóa ở đâu?
6. Môi trường hạ tầng công nghệ hiện tại của EduOne đang chạy trên nền tảng nào? (LMS Moodle, EdX, Canvas hay một hệ thống tự phát triển)? Có yêu cầu xuất bản học liệu theo chuẩn SCORM hoặc xAPI không?
7. Hạn mức ngân sách tối đa cho chi phí API AI trên mỗi học viên hàng tháng trong giai đoạn Pilot là bao nhiêu?
8. Các chính sách về bảo mật dữ liệu và quyền riêng tư của EduOne có cấm gửi dữ liệu học tập ẩn danh của học sinh lên các dịch vụ đám mây công cộng (như Google Cloud hoặc OpenAI) không?
9. Cơ chế phân vai trong thực tế của EduOne: Một giáo viên tình nguyện giảng dạy lớp học có được phép kiêm nhiệm vai trò Reviewer để phê duyệt nhanh học liệu do chính lớp học đó đề xuất hay không?
10. Chỉ số thành công quan trọng nhất (North Star Metric) của EduOne trong dự án này là gì: giảm tỷ lệ dropout học sinh, giảm tải công việc của giáo viên tình nguyện, hay tăng tốc độ mở rộng số lượng khóa học?