Thiết kế luồng và công nghệ cho từng module

§1Bản đồ hệ thống

Hệ thống có hai máy. Máy thứ nhất chạy một API duy nhất chứa 5 module, cùng database và kho file. Máy thứ hai chỉ làm một việc: chạy bài làm của sinh viên trong container. Mã không tin cậy không bao giờ chạm tới máy thứ nhất.

Công nghệ theo tầng

§2Quy tắc giữa các module

Modular monolith chỉ có giá trị khi ranh giới được giữ. Ba quy tắc dưới đây được kiểm tra tự động trong CI, không dựa vào lời hứa.

1. Mỗi module sở hữu dữ liệu của mình. Một DbContext và một schema riêng (identity, assess, submit, ai, scoring). Không join chéo schema.
2. Gọi đồng bộ chỉ qua project Contracts. Module A chỉ được tham chiếu Asap.Modules.B.Contracts (interface + DTO), không bao giờ tham chiếu phần bên trong của B.
3. Phản ứng với việc xảy ra ở module khác qua sự kiện. Sự kiện được ghi vào bảng outbox trong cùng transaction, rồi một background service phát đi mỗi 2 giây. Không mất sự kiện khi tiến trình chết giữa chừng.

// Cấu trúc bên trong mỗi module
Asap.Modules.Assessment/
  Api/              # endpoint Minimal API, map DTO
  Application/      # use case, validator (FluentValidation), mapper (Mapperly)
  Domain/           # entity, quy tắc nghiệp vụ, sự kiện — không phụ thuộc EF
  Infrastructure/   # AssessmentDbContext, cấu hình EF, outbox
Asap.Modules.Assessment.Contracts/   # IAssessmentReader, DTO, sự kiện công khai

Ai cung cấp gì, ai nghe gì

Hợp đồng quan trọng nhất của cả hệ thống là sự kiện EvaluationRecorded. Bốn nguồn chấm (quiz, test, rule, AI, và cả giảng viên khi ghi đè) đều phát cùng một dạng này, nhờ đó Score Engine không cần biết loại bài:

public sealed record EvaluationRecorded(
    Guid AttemptId, Guid ItemId, Guid CriterionId,
    EvaluationSource Source,    // Test | Rule | Ai | Human
    decimal Score,              // 0–100, đã quy về thang chung
    string Evidence,            // "17/20 test đạt", trích dẫn từ bài làm…
    DateTimeOffset At);

Thư viện dùng chung cho mọi module backend

§3M1 · Identity & Platform SV1

Trả lời hai câu hỏi cho mọi request: ai đang gọi và họ có được làm việc này không. Đồng thời ghi lại mọi thao tác nhạy cảm.

Luồng 1 — Đăng nhập và làm mới token

Access token không nằm trong localStorage nên script lạ không đọc được. Refresh token xoay vòng mỗi lần dùng; nếu một token đã thu hồi xuất hiện lại, đó là dấu hiệu bị đánh cắp, hệ thống thu hồi toàn bộ chuỗi và buộc đăng nhập lại.

Luồng 2 — Một request đi qua những lớp nào

Phân quyền: vai trò → quyền → policy

Không kiểm tra theo tên vai trò rải rác trong code. Mỗi hành động là một quyền; vai trò chỉ là tập quyền; endpoint yêu cầu quyền. Quyền sở hữu (sinh viên chỉ xem kết quả của mình) kiểm tra bằng IAuthorizationHandler theo tài nguyên.

Thành phần và công nghệ

API: POST /auth/login · /auth/refresh · /auth/logout · /api/users · /api/roles · GET /api/admin/audit-logs

Test bắt buộc: sai mật khẩu lần thứ 6 trong 1 phút → 429 · JWT hết hạn hoặc sai chữ ký → 401 · sinh viên gọi API giảng viên → 403 · sinh viên đọc kết quả người khác → 404 · refresh token dùng lại → cả chuỗi bị thu hồi.

§4M2 · Assessment & Quiz SV2

Nơi giảng viên cấu hình mọi thứ sẽ được chấm, và nơi chạy toàn bộ phần trắc nghiệm. Học theo mô hình ngân hàng câu hỏi của Moodle.

Luồng 1 — Vòng đời một bài đánh giá

Luồng 2 — Một lượt làm trắc nghiệm

Thành phần và công nghệ

// Chấm câu nhiều đáp án — chính sách mặc định
điểm = trọng số × max(0, số_đúng_đã_chọn / k − số_sai_đã_chọn / (n − k))
// k: số đáp án đúng · n: tổng số lựa chọn · câu một đáp án luôn là đúng hết / 0

API: /api/skills · /api/assessments (+ /publish, /dry-run, /assignments) · /api/questions (+ /import) · /api/items/{id}/quiz-config | testcases | rubric · /api/attempts/{id}/quiz/start | answers/{q} | submit | result · /api/items/{id}/item-analysis

Test bắt buộc: 7 tình huống chấm của QuizScorer · ngân hàng thiếu câu cho ma trận → không cho publish · sửa câu hỏi sau publish không đổi điểm bài cũ · DTO gửi sinh viên không bao giờ có IsCorrect · câu trả lời gửi sau hạn 30 giây bị từ chối.

§5M3 · Submission & chấm tự động SV3

Nhận bài, xếp hàng, rồi build và chạy bài trong container trên máy worker. Đây là module khó nhất, học theo cách Gradescope chấm trong Docker.

Thành phần và công nghệ

Runner image dựng sẵn: asap-runner-python:3.12 · asap-runner-dotnet:10 · base image cho starter template REST (ASP.NET Core, Node/Express) đã có sẵn thư viện phổ biến để build nhanh.

API: POST /api/attempts · POST /api/attempts/{id}/finish · POST /api/submissions → 202 · GET /api/submissions/{id} · POST /api/submissions/precheck (nút "Kiểm tra build", không tính điểm) · POST /internal/submissions/{id}/progress

Test bắt buộc: bộ bài nộp độc hại (vòng lặp vô hạn, fork bomb, cấp phát 10 GB, đọc /etc/passwd, gọi ra Internet, in 1 GB output) phải bị chặn và vẫn nhận điểm 0 hợp lệ · kill worker giữa chừng → job được chạy lại · lời giải mẫu đạt 20/20. GitHub Actions có sẵn Docker nên chạy được các test này trên CI.

§6M4 · AI Evaluation & Interview SV4

Hai việc: chạy phiên phỏng vấn nhiều lượt, và chấm những tiêu chí không kiểm bằng test được. Học cách hỏi của CodeSignal AI Interviewer và cách chấm theo rubric của Aced; khác biệt là mọi điểm AI đều đi qua bộ kiểm soát và có giảng viên duyệt.

Luồng 1 — Chấm một bài bằng AI có kiểm soát

Luồng 2 — Một phiên phỏng vấn

Mỗi lượt hỏi–đáp gọi AI đồng bộ trong request (timeout 30 giây, giao diện hiện "AI đang soạn câu hỏi…"). Việc chấm cả phiên chạy nền bằng Hangfire trên queue ai ở máy API; máy worker chỉ dành cho queue grading.

Thành phần và công nghệ

// Kết quả AI phải trả cho mỗi tiêu chí
{
  "criterionId": "accuracy",
  "score": 7.5,                                   // 0–10, bước 0.5
  "evidence": ["PUT thay thế toàn bộ tài nguyên…"],   // phải tìm thấy trong bài làm
  "feedback": "Đúng về PUT, chưa nêu tính idempotent."
}

API: POST /api/interviews · POST /api/interviews/{id}/answers · GET /api/reviews?status=NeedsReview · POST /api/reviews/{id}/approve | override · /api/admin/ai-providers · /api/admin/prompt-templates

Test bắt buộc: FakeChatClient trả JSON sai → gọi lại 1 lần rồi NeedsReview · hai lần lệch 2 điểm → NeedsReview · trích dẫn không có trong bài → bị loại · bài làm chứa "ignore previous instructions" → gắn cờ · provider trả 429 → retry có giãn cách.

§7M5 · Scoring & Skill Profile SV5

Nơi mọi nguồn chấm hội tụ thành một con số giải thích được. Module này không gọi ai; nó chỉ nghe sự kiện và tính lại.

Thành phần và công nghệ

API: GET /api/results/{id} · GET /api/results/{id}/trace (cây kỹ năng → item → tiêu chí → bằng chứng, phục vụ yêu cầu "truy vết trong 2 lần bấm") · PUT /api/results/{id}/criteria/{cid}/override · GET /api/skill-profiles/me · GET /api/skill-profiles/{studentId}/progress · GET /api/recommendations/me · GET /api/classes/{id}/skill-stats

Test bắt buộc: phiếu tính mẫu phải ra đúng 78.50 · điểm luôn trong 0–100 · tổng trọng số khác 100% bị từ chối · ghi đè xong tính lại đúng · nhận cùng một sự kiện hai lần không đổi kết quả · chỉ có 1 item thì hiện "chưa đủ dữ liệu".

§8Frontend

Một ứng dụng React chia thư mục theo đúng 5 module của backend. Người làm module nào sở hữu cả màn hình của module đó.

web/src/
  app/            # router, provider, layout theo vai trò, trang lỗi
  modules/
    identity/     # đăng nhập, người dùng, audit        — SV1
    assessment/   # kỹ năng, soạn đề, test case, rubric — SV2
    quiz/         # làm trắc nghiệm, tự lưu            — SV2
    submission/   # nộp code, trạng thái chấm          — SV3
    interview/    # chat phỏng vấn, màn GV duyệt        — SV4
    results/      # kết quả, truy vết, hồ sơ kỹ năng    — SV5
  shared/
    api/          # client sinh từ OpenAPI (không sửa tay)
    ui/           # component dùng chung: ScoreChip, SourceChip, ExamLayout
    hooks/        # useAuth, useSubmissionStatus, useServerDeadline

Bốn luồng phía trình duyệt cần làm cẩn thận

§9Hạ tầng, CI/CD, giám sát SV1

Triển khai trên hai máy

Pipeline

Giám sát và cấu hình

• Log: Serilog ghi vào Seq; mọi log của một lần chấm mang submissionId để tra một phát ra hết.
• Health check: /health/live và /health/ready (SQL Server, MinIO, Hangfire, Docker ở worker).
• Job: Hangfire dashboard chỉ Admin mở được; thấy job lỗi, job đang retry, DeadLetter.
• Bí mật: chuỗi kết nối qua biến môi trường và GitHub Actions secrets; khoá AI do Admin nhập, lưu mã hoá bằng ASP.NET Core Data Protection.

§10Một lượt làm bài đi qua các module

Đọc bảng này để thấy các module nối với nhau thế nào trong đúng một kịch bản demo: bạn An làm "Backend Developer – Level 1".

§11Thứ tự xây & mốc tích hợp

Tuần 1–2: chốt hợp đồng và thử bốn điểm rủi ro

Trước khi ai viết tính năng, cả nhóm chốt các project Contracts, sự kiện EvaluationRecorded, enum trạng thái bài nộp và file OpenAPI đầu tiên. Song song, mỗi rủi ro kỹ thuật được thử bằng một đoạn code nhỏ vứt đi được:

Mỗi sprint, mỗi module giao gì