Imported from dungltcn272/AICodingLearn (AGENTS.md). Install upstream with npx skills add dungltcn272/AICodingLearn. Copyright stays with the author.

AI Learning Web — Coding Practice & Judge System

1. Business Feature

Mục tiêu

Tạo một nền tảng học AI cho coder theo kiểu:

Học lý thuyết → Làm bài code → Submit → Runner chấm test case → Nhận kết quả → AI Mentor giải thích lỗi → Lên level.

Tính năng này giúp web không chỉ là “web đọc bài học”, mà thành AI Coding Academy có chấm bài tự động.

2. Các loại bài tập

2.1. Bài code cơ bản

Ví dụ:

• Viết hàm tính cosine similarity.
• Implement softmax.
• Viết BM25 scoring đơn giản.
• Viết hàm chunking văn bản.
• Parse JSON response từ API.
• Viết hàm lọc món ăn theo vị trí, giá, khẩu vị.

2.2. Bài project nhỏ

Ví dụ:

• Build mini RAG pipeline.
• Build semantic cache.
• Build classifier intent.
• Build OCR preprocessing.
• Build recommendation scoring.
• Build YOLO tracking helper.

2.3. Bài debug code

User được đưa một đoạn code sai và phải sửa.

Ví dụ:

• Code RAG bị duplicate chunks.
• Code async bị race condition.
• Code ranking bị sort sai.
• Code vector search trả sai format.

2.4. Bài system design AI

Không chấm bằng test case đơn thuần, mà chấm bằng rubric:

• Kiến trúc có đúng không?
• Có fallback không?
• Có logging/evaluation không?
• Có guardrail không?
• Có tối ưu chi phí không?

3. Trạng thái chấm bài

Khi user submit code, hệ thống trả về kết quả giống online judge.

4. Luồng sử dụng chính

flowchart TD
    A[User học bài] --> B[Nhấn Practice]
    B --> C[Đọc đề bài]
    C --> D[Code trong editor]
    D --> E[Run Sample Test]
    E --> F{Sample Passed?}
    F -- No --> G[AI Mentor gợi ý lỗi]
    F -- Yes --> H[Submit]
    H --> I[Judge chạy hidden tests]
    I --> J{Kết quả}
    J -- AC --> K[Mở khóa bài tiếp theo]
    J -- WA/CE/RE/TLE --> L[Hiển thị lỗi + gợi ý]

5. Mô tả giao diện FE

5.1. Trang Roadmap

Giao diện dạng cây level:

flowchart LR
    A[AI Foundation] --> B[ML Basics]
    B --> C[Deep Learning]
    C --> D[Computer Vision]
    C --> E[GenAI]
    E --> F[RAG]
    F --> G[Agent]
    G --> H[Production AI]

Mỗi module có:

• % hoàn thành.
• Số bài học.
• Số bài code.
• Số project.
• Badge đã đạt.
• Level bị khóa/mở.

5.2. Trang Lesson Detail

Layout nên chia 2 cột:

flowchart LR
    A[Left: Nội dung bài học] --> B[Right: AI Mentor + Note]

Bên trái:

• Lý thuyết.
• Sơ đồ minh họa.
• Code mẫu.
• Video/ảnh minh họa nếu có.
• Nút “Làm bài luyện code”.

Bên phải:

• AI Mentor hỏi đáp theo bài.
• Gợi ý tài liệu.
• Tóm tắt nhanh.
• Nút “Giải thích như người mới”.

5.3. Trang Coding Practice

Đây là màn quan trọng nhất.

Layout đề xuất

flowchart LR
    A[Panel trái: Đề bài] --> B[Panel giữa: Code Editor]
    B --> C[Panel phải: Test Result + AI Hint]

Panel trái: Đề bài

Hiển thị:

• Tên bài.
• Độ khó: Easy / Medium / Hard.
• Chủ đề: RAG, Vector Search, CV, Agent.
• Mô tả bài toán.
• Input/output.
• Ví dụ sample.
• Constraints.
• Gợi ý nếu user mở hint.
• Link bài học liên quan.

Ví dụ:

Bài: Implement Cosine Similarity

User cần viết hàm:

def cosine_similarity(a: list[float], b: list[float]) -> float:
    pass

Yêu cầu:

• Trả về giá trị cosine similarity.
• Làm tròn 4 chữ số.
• Nếu vector rỗng thì raise ValueError.

Panel giữa: Code Editor

Nên dùng:

• Monaco Editor.
• Highlight Python/JavaScript.
• Auto format.
• Tab size 4.
• Dark mode.
• Nút Run.
• Nút Submit.
• Nút Reset code.
• Nút Save draft.

Trạng thái code:

• Unsaved.
• Running.
• Submitted.
• Accepted.
• Failed.

Panel phải: Test Result

Hiển thị từng test case:

Sample Test 1: Passed
Sample Test 2: Failed
Hidden Test 1: Failed

Với lỗi:

Expected: 0.7071
Your output: 0.7000
Status: WA

Nếu CE:

SyntaxError: invalid syntax at line 4

Nếu TLE:

Time Limit Exceeded: your code ran over 2s

Nếu AC:

Accepted
Runtime: 128ms
Memory: 32MB
Passed: 15/15 test cases

6. Tính năng AI Mentor trong màn code

AI Mentor không nên đưa full đáp án ngay. Nên có 3 mức gợi ý:

Hint Level 1

Gợi ý nhẹ:

Kiểm tra lại cách bạn tính độ dài vector.

Hint Level 2

Gợi ý rõ hơn:

Công thức cosine cần dot product chia cho tích norm của hai vector.

Hint Level 3

Gần như hướng dẫn sửa:

Bạn đang thiếu bước xử lý trường hợp vector toàn số 0.

Sau khi AC, AI Mentor có thể giải thích:

• Vì sao code đúng.
• Có cách tối ưu hơn không.
• Complexity O(n).
• Liên hệ với embedding/vector search trong RAG.

7. Backend cần có

7.1. Các service chính

flowchart TD
    FE[Frontend] --> API[FastAPI Backend]
    API --> Auth[Auth Service]
    API --> Lesson[Lesson Service]
    API --> Problem[Problem Service]
    API --> Submission[Submission Service]
    Submission --> Queue[Redis Queue]
    Queue --> Judge[Code Runner Sandbox]
    Judge --> Result[Judge Result]
    API --> DB[(PostgreSQL)]
    API --> Vector[(Qdrant/pgvector)]
    API --> LLM[AI Mentor]

7.2. Backend module

Auth Service

Quản lý:

• Đăng ký.
• Đăng nhập.
• User profile.
• Role: student, admin, instructor.
• Progress học tập.

Lesson Service

Quản lý:

• Course.
• Module.
• Lesson.
• Markdown content.
• Code sample.
• Quiz.
• Practice liên kết với bài học.

Problem Service

Quản lý đề bài:

• Title.
• Slug.
• Difficulty.
• Tags.
• Statement.
• Starter code.
• Solution reference.
• Public test cases.
• Hidden test cases.
• Time limit.
• Memory limit.
• Allowed languages.

Submission Service

Quản lý bài nộp:

• User ID.
• Problem ID.
• Language.
• Source code.
• Status.
• Runtime.
• Memory.
• Test case result.
• Error message.
• Created time.

Judge Runner Service

Đây là phần quan trọng nhất.

Nhiệm vụ:

• Nhận code từ queue.
• Chạy trong sandbox.
• Compile nếu cần.
• Chạy public test.
• Chạy hidden test.
• So sánh output.
• Trả status AC/WA/CE/RE/TLE/MLE.

Nên chạy bằng Docker sandbox, mỗi submission tạo container riêng hoặc process bị giới hạn tài nguyên.

8. Database schema gợi ý

erDiagram
    USERS ||--o{ USER_PROGRESS : has
    USERS ||--o{ SUBMISSIONS : makes
    COURSES ||--o{ MODULES : contains
    MODULES ||--o{ LESSONS : contains
    LESSONS ||--o{ PROBLEMS : links
    PROBLEMS ||--o{ TEST_CASES : has
    PROBLEMS ||--o{ SUBMISSIONS : receives

    USERS {
        uuid id
        string email
        string name
        string role
        int xp
        int level
    }

    COURSES {
        uuid id
        string title
        string slug
        string description
    }

    MODULES {
        uuid id
        uuid course_id
        string title
        int order_index
    }

    LESSONS {
        uuid id
        uuid module_id
        string title
        text content_md
        int order_index
    }

    PROBLEMS {
        uuid id
        uuid lesson_id
        string title
        string difficulty
        text statement_md
        text starter_code
        int time_limit_ms
        int memory_limit_mb
    }

    TEST_CASES {
        uuid id
        uuid problem_id
        text input
        text expected_output
        boolean is_hidden
    }

    SUBMISSIONS {
        uuid id
        uuid user_id
        uuid problem_id
        text source_code
        string language
        string status
        int runtime_ms
        int memory_mb
    }

9. Admin Dashboard

Admin cần có giao diện để tạo nội dung.

9.1. Quản lý course

• Tạo course.
• Tạo module.
• Kéo thả thứ tự lesson.
• Gắn problem vào lesson.

9.2. Quản lý problem

Form tạo bài gồm:

• Tên bài.
• Difficulty.
• Tags.
• Statement markdown.
• Starter code.
• Reference solution.
• Public test cases.
• Hidden test cases.
• Time limit.
• Memory limit.
• Language support.

9.3. Quản lý submission

Admin xem được:

• User nào nộp.
• Code user.
• Status.
• Lỗi thường gặp.
• Tỉ lệ AC.
• Test case nào fail nhiều nhất.

10. Gamification

Để user có động lực học:

• XP sau mỗi bài học.
• Badge sau mỗi module.
• Streak học mỗi ngày.
• Ranking theo tuần.
• Unlock level.
• Certificate sau project lớn.
• Portfolio page tự động sinh từ project đã hoàn thành.

Ví dụ badge:

• RAG Beginner.
• Vector Search Builder.
• Agent Tool Caller.
• Computer Vision Rookie.
• Production AI Engineer.

11. MVP nên làm trước

Phase 1

• Auth.
• Roadmap.
• Lesson markdown.
• Problem detail.
• Python code editor.
• Run sample test.
• Submit.
• Judge bằng Docker.
• AC/WA/CE/RE/TLE.
• User progress.

Phase 2

• AI Mentor hint.
• Hidden test cases.
• Admin tạo bài.
• Leaderboard.
• Badge.

Phase 3

• Project-based grading.
• Multi-language runner.
• RAG hỏi đáp tài liệu.
• Chấm system design bằng rubric.
• Portfolio tự động.

12. Một câu mô tả sản phẩm chuẩn business

AI Learning Web là nền tảng học AI dành cho coder, kết hợp roadmap cá nhân hóa, bài học tương tác, coding practice, online judge, AI mentor và project lab, giúp người học không chỉ hiểu GenAI/Agent/Computer Vision mà còn tự build, test, deploy và tạo portfolio AI Engineer thực tế.

12. Roadmap bài tập cần có trong website

**ROADMAP_AI_EXERCISE.md