#03 – Đặc tả yêu cầu phần mềm (SRS)

Giai đoạn: Đặc tả (Requirements Specification) · Tham chiếu cấu trúc ISO/IEC/IEEE 29148 · Phiên bản 0.1 – 29/10/2026

Tài liệu này mô tả hệ thống phải làm gì. Cách hiện thực ở 06, 07, 08. Tiêu chí chấp nhận chi tiết theo từng story ở 04.

#1. Giới thiệu

#1.1 Mục đích

Đặc tả yêu cầu chức năng, quy tắc nghiệp vụ và yêu cầu phi chức năng của Nền tảng số sách ôn thi hybrid TNTHPT, làm căn cứ thống nhất giữa HEID/NV06 và SK cho thiết kế, phát triển, kiểm thử và nghiệm thu.

#1.2 Thuật ngữ

#1.3 Tài liệu tham chiếu

[MT], [UF], [YC] (xem README); 01 – Tầm nhìn; 02 – Phân tích đầu vào.

#2. Mô tả tổng quan

#2.1 Ngữ cảnh hệ thống

flowchart LR
    HS(["Học sinh"]) -- "Kích hoạt, nhập ID,<br/>học, làm bài" --> SYS
    GV(["Giáo viên"]) -- "Giao bài, xem báo cáo" --> SYS
    BTV(["Biên tập viên"]) -- "Soạn nội dung, ID,<br/>ma trận kiến thức" --> SYS
    ADM(["Admin HEID"]) -- "Báo cáo, vận hành" --> SYS
    SACH[/"Sách giấy<br/>(ID, QR, mã kích hoạt)"/] -. "in từ dữ liệu xuất ra" .- SYS
    SYS["Nền tảng số<br/>sách ôn thi hybrid"]
    SYS <-- "SSO, lớp học, giao bài" --> LMS[["Hoclieu.vn<br/>tài khoản + LMS"]]
    SYS <-- "Thanh toán, IPN" --> PAY[["Cổng thanh toán"]]
    SYS <-- "Lưu trữ, phát video" --> VID[["Dịch vụ video/CDN"]]
    SYS -- "OTP, thông báo" --> MSG[["SMS / Email / Zalo ZNS"]]

#2.2 Tác nhân (Actors)

#2.3 Sơ đồ use case

flowchart LR
    HS(["Học sinh"])
    GV(["Giáo viên"])
    BTV(["BTV"])
    ADM(["Admin HEID"])
    subgraph SYS["Nền tảng số sách hybrid"]
        UC01(["UC-01 Kích hoạt sách"])
        UC02(["UC-02 Mở tài nguyên bằng ID/QR"])
        UC03(["UC-03 Học lý thuyết, ví dụ, video"])
        UC04(["UC-04 Làm bài trên máy"])
        UC05(["UC-05 Xem kết quả và lời giải"])
        UC06(["UC-06 Tự chấm bài tự luận"])
        UC07(["UC-07 Nhận đề xuất củng cố"])
        UC08(["UC-08 Xem lịch sử và tiến bộ"])
        UC09(["UC-09 Mua gói đề mở rộng"])
        UC16(["UC-16 Tra đáp án khi làm trên giấy"])
        UC17(["UC-17 Duyệt thư viện học liệu"])
        UC10(["UC-10 Giao bài cho lớp"])
        UC11(["UC-11 Xem báo cáo lớp"])
        UC12(["UC-12 Quản lý nội dung, câu hỏi, video"])
        UC13(["UC-13 Quản lý ID và mã kích hoạt"])
        UC14(["UC-14 Thiết lập ma trận kiến thức"])
        UC15(["UC-15 Xem báo cáo hành vi"])
    end
    HS --- UC01 & UC02 & UC03 & UC04 & UC05 & UC06 & UC07 & UC08 & UC09 & UC16 & UC17
    GV --- UC10 & UC11
    BTV --- UC12 & UC13 & UC14
    ADM --- UC13 & UC15

#2.4 Môi trường vận hành

• Web responsive (ưu tiên mobile), hỗ trợ trình duyệt trong ứng dụng (Zalo, Facebook) khi quét QR.
• CMS và trang quản trị dùng trên máy tính.
• Hạ tầng đám mây, đặt tại Việt Nam hoặc đáp ứng quy định lưu trữ dữ liệu hiện hành.

#3. Đặc tả use case chính

#UC-01 – Kích hoạt sách

Luồng chính

1. Học sinh quét QR kích hoạt → hệ thống mở trang kích hoạt với mã được điền sẵn.
2. Nếu chưa đăng nhập, hệ thống yêu cầu đăng nhập/đăng ký và giữ lại mã.
3. Hệ thống kiểm tra mã: tồn tại, chưa dùng, chưa bị thu hồi, còn hiệu lực.
4. Hệ thống hiển thị thông tin sách (môn, tên sách, năm) để học sinh xác nhận.
5. Học sinh xác nhận → hệ thống tạo quyền sử dụng, ghi sự kiện book_activated.
6. Hệ thống hiển thị "Kích hoạt thành công" và hướng dẫn cách dùng ID trên sách.

Luồng thay thế / ngoại lệ

• 1a. Nhập mã thủ công: học sinh gõ mã vào ô "Kích hoạt sách" → tiếp bước 3.
• 3a. Mã không tồn tại → thông báo lỗi, gợi ý kiểm tra lại các ký tự dễ nhầm; tăng bộ đếm sai.
• 3b. Mã đã được chính tài khoản này dùng → thông báo "Sách đã được kích hoạt", chuyển tới sách.
• 3c. Mã đã được tài khoản khác dùng → thông báo, hướng dẫn liên hệ hỗ trợ (kèm mã tham chiếu).
• 3d. Sai quá 5 lần trong 10 phút → yêu cầu captcha / tạm khoá 15 phút (BR-02).

#UC-02 – Mở tài nguyên bằng ID / QR

Luồng chính

1. Học sinh nhập ID vào ô "Nhập ID" (có trên trang chủ và thanh đầu trang) hoặc quét QR nội dung.
2. Hệ thống chuẩn hoá ID (bỏ khoảng trắng, chuyển chữ hoa, đổi ký tự dễ nhầm theo BR-05).
3. Hệ thống tra ID trong phạm vi các sách học sinh đã kích hoạt (BR-06) → xác định tài nguyên và loại.
4. Hệ thống kiểm tra quyền sử dụng → mở trang tương ứng theo loại:
   • THEORY → trang lý thuyết; EXAMPLE → trang ví dụ;
   • EXERCISE_SET, MOCK_EXAM, PRACTICE_EXAM, PLACEMENT_TEST → trang giới thiệu bài làm (chọn Làm trên máy hoặc Tra đáp án).

Luồng thay thế / ngoại lệ

• 3a. Không tìm thấy ID → thông báo, gợi ý ID gần đúng (cùng tiền tố), hình minh hoạ vị trí ID trên sách.
• 3b. ID thuộc sách chưa kích hoạt → hiển thị thông tin sách + nút "Kích hoạt sách"; nếu ID thuộc danh sách xem thử thì cho xem.
• 3c. ID đã ngừng sử dụng (RETIRED) → chuyển hướng tới tài nguyên thay thế nếu có.
• 4a. Chưa đăng nhập → đăng nhập rồi quay lại đúng tài nguyên (giữ nguyên deep link).

#UC-04 – Làm bài trên máy

Luồng chính

1. Tại trang giới thiệu bài làm, hệ thống hiển thị: tên bài, số câu, thời gian, cấu trúc phần, số lượt đã làm.
2. Học sinh chọn chế độ hiển thị (nếu bài cho phép): Giao diện đề thi hoặc Phiếu trả lời; chọn Tính giờ hoặc Luyện tập tự do (với bài tập).
3. Học sinh bấm "Bắt đầu" → hệ thống tạo lượt làm bài, bắt đầu tính giờ phía máy chủ.
4. Học sinh trả lời; hệ thống tự lưu sau mỗi thay đổi (tối đa 5 giây trễ) và hiển thị trạng thái "Đã lưu".
5. Học sinh có thể đánh dấu câu để xem lại, chuyển câu qua bảng điều hướng.
6. Học sinh bấm "Nộp bài" → hệ thống cảnh báo số câu chưa làm → học sinh xác nhận.
7. Hệ thống chấm câu khách quan (BR-08…BR-12), lưu kết quả, chuyển tới UC-05.

Luồng thay thế / ngoại lệ

• 2a. Placement test: luôn ở chế độ Một câu/màn hình, không quay lại câu trước (Q19), ghi thời gian từng câu.
• 4a. Mất kết nối → câu trả lời lưu tạm trên thiết bị, đồng bộ khi có mạng; cảnh báo "Đang ngoại tuyến".
• 4b. Đóng trình duyệt giữa chừng → khi mở lại bài, hệ thống đề nghị "Tiếp tục lượt đang làm".
• 4c. Hết giờ → hệ thống tự nộp phần đã làm (BR-14).
• 4d. Bài có câu tự luận → ô soạn văn bản có đếm từ; tuỳ chọn tải ảnh bài viết tay (P1).

#UC-05 – Xem kết quả và lời giải

Luồng chính: Sau khi nộp → hiển thị điểm (thang 10 với đề; số câu đúng/tổng với bài tập), điểm theo phần, thời gian làm bài → danh sách câu với trạng thái đúng/sai/bỏ trống → mở từng câu xem đáp án đúng, đáp án đã chọn, lời giải text, video (nếu có) → khối "Đề xuất củng cố" (UC-07) → nút "Làm lại", "Quay lại học tiếp trên sách". Ngoại lệ: Bài tự luận → hiển thị bài làm cạnh hướng dẫn giải và rubric, mời tự chấm (UC-06).

#UC-06 – Tự chấm bài tự luận

Học sinh mở từng câu tự luận → xem hướng dẫn chấm theo tiêu chí → chọn mức đạt cho từng tiêu chí → hệ thống cộng điểm, gắn nhãn "Tự đánh giá" → lưu và dùng cho đề xuất kỹ năng (BR-13). Học sinh có thể bỏ qua tự chấm.

#UC-07 – Nhận đề xuất củng cố

Hệ thống tính tỷ lệ sai theo chuyên đề/kỹ năng/dạng bài của lượt vừa nộp (BR-16, BR-17) → hiển thị tối đa 5 mục, mỗi mục có liên kết: Lý thuyết · Ví dụ · Bài tập thực hành cùng chuyên đề, kèm ID trên sách để học sinh mở sách giấy → ghi sự kiện recommendation_shown, recommendation_clicked.

#UC-16 – Tra đáp án khi làm trên giấy

Tại trang giới thiệu bài làm, học sinh chọn "Tôi đã làm trên giấy – xem đáp án" → hệ thống hiển thị bảng đáp án và lời giải từng câu. Tuỳ chọn: học sinh nhập nhanh đáp án đã làm trên giấy vào Phiếu trả lời để được chấm và nhận đề xuất (khuyến khích bằng thông điệp "Nhập đáp án để biết chuyên đề cần ôn").

#Các use case còn lại (tóm tắt)

#4. Yêu cầu chức năng (Functional Requirements)

Ký hiệu nguồn: YCxx = user story gốc; MT = mô tả tổng quát; UF = user flow; Nx = yêu cầu ngầm định (02 §4.2).

#EP01 – Tài khoản & kích hoạt sách

#EP02 – Liên kết giấy – số (ID / QR)

#EP03 – Học liệu số & thư viện

#EP04 – Làm bài trực tuyến

#EP05 – Kết quả, đáp án & lời giải

#EP06 – Đề xuất kiến thức cần củng cố

#EP07 – Lịch sử & tiến bộ

#EP08 – Gói đề mở rộng & thanh toán

#EP09 – Giáo viên & LMS Hoclieu

#EP10 – CMS quản trị nội dung

#EP11 – Phân tích hành vi & báo cáo quản trị

#5. Quy tắc nghiệp vụ (Business Rules)

Chi tiết thuật toán chấm và đề xuất: 09.

#6. Yêu cầu phi chức năng (NFR)

#7. Yêu cầu giao tiếp ngoài