Dokhacgiakhoa/K4-3A-e403-Vinonymus

Mini Hackathon

TypeScript

0

81 commits

updated Sep 17, 2026

See the code

README

Vinonymus — Adaptive Learning System: AI Mentor & AI Helpdesk

Mini Hackathon AI · Batch 04 · Lớp 3A · Phòng E403 · Cụm C2 · Track E — Làn mở (trong phạm vi AI20k) SPEC → Prototype → Demo. Đây không phải cuộc thi code — đây là cuộc thi tư duy sản phẩm AI.

verify

Trang chủ hệ thốnghttps://k4-3a-e403-vinonymus.kailabs.io.vn
Demo Lộ trình cá nhân hoá (Phần chấm thi)https://k4-3a-e403-vinonymus.kailabs.io.vn/personalized-path
Bản demo dự phòng (Vercel)https://k4-3a-e403-vinonymus.vercel.app/personalized-path
AI Spec (Tài liệu chấm chính thức)spec.md
Đặc tả yêu cầu hệ thống (SRS)docs/01-SRS.md
Kiến trúc & Luồng dữ liệudocs/02-kien-truc.md
Kiểm định Eval 50 case (100%)eval/run_results.md
Tích hợp Discord Activity (+5 XP)docs/feature-discord-api.md
Việc của nhómMilestones theo checkpoint

Adaptive Learning System cho học viên Khoá 4, gồm 2 AI:

AINgười dùng có trò chuyện không?Làm gìHiện ra ở đâuVai trò trong cuộc thi
AI MentorKhông. AI thực thi, chạy phía sauĐọc thông tin của học viên, đọc tài liệu giảng viên tải lên, phân tích CV để ra bài test năng lực, phân tích điểm test để xây lộ trình học (chi tiết bên dưới)Tính năng Lộ trình cá nhân hoá tại /personalized-pathPhần được chấm (demo scope) là tính năng này, theo spec.md
AI HelpdeskCó. Là AI duy nhất người dùng nói chuyệnTra cứu, giải đáp về tài liệu và lộ trình học, có trích dẫn nguồnChatbox (widget chat nổi)Tính năng nền, không thuộc phần chấm. Chatbox đã gọi AI thật (xem Trạng thái)

AI Mentor làm 4 việc (trạng thái thật tính đến 17/9):

#Việc của AI MentorTrạng thái
1Đọc thông tin đầu vào của học viên⚠️ Một phần: đọc nền tảng tự khai, số phút rảnh, bài lab, ghi chú. Chưa đọc từ hồ sơ đăng nhập
2Đọc tài liệu giảng viên tải lên, phân tích rồi đưa vào thư viện tài liệu❌ Chưa làm: thư viện do nhóm tự soạn tay; chưa có giao diện giảng viên
3Phân tích CV của học viên để ra bài test năng lực online❌ Chưa có AI: màn hình mẫu chạy quy tắc cố định
4Phân tích điểm test để xây lộ trình học từ thư viện⚠️ Một phần: đã chọn tài liệu từ thư viện theo nền tảng tự khai, chưa theo điểm test

Với tính năng Lộ trình cá nhân hoá (Personalized Learning Path):

  1. Học viên chọn nền tảng của mình (non-tech, tech-base hoặc đã học AI).
  2. Học viên cho biết hôm nay rảnh bao nhiêu phútbài lab tiếp theo là gì.
  3. AI Mentor chọn ra tối đa 3 việc cần làm trước. Mỗi việc có lý do, thời lượng và link tài liệu lấy từ catalog đã kiểm chứng.
  4. Học viên tick, bỏ hoặc đổi thứ tự trước khi bắt đầu học.

Mục lục

👥 Thành viên & phân công

Nhóm: Vinonymus · Lớp: 3A · Phòng: E403 · Cụm: C2 · Track: E — Làn mở (trong phạm vi AI20k)

Họ và TênMã Học ViênVai trò chínhGitHubPhần việc đảm nhiệm trong dự ánViệc được giao
Đỗ Khắc Gia Khoa (đội trưởng)02733PM@DokhacgiakhoaChốt Canvas & lát cắt, khảo sát nỗi đau, viết spec.md, điều phối checkpoint & nộp form, slide + pitch, validation (R6)Issues
Trần Nhật Minh02483BE@minh-tran-2611Backend/API cho prototype (/api/roadmap), tích hợp lời gọi AI qua LLM router, CI, quản lý biến môi trường (không commit key)Issues
Đinh Ngọc Đức02935AI@dinhngocduc1311Thiết kế prompt/pipeline AI, catalog tài liệu, xây golden set & chạy eval (eval/), phân tích lỗi và kịch bản rủi roIssues
Nguyễn Việt Thành02924FE@thanhnvhust514Giao diện & luồng người dùng, mock bấm được (CP2), quay video thao tác CP3 và video demo dự phòng CP5Issues

Bảng phân công chi tiết theo từng checkpoint (người phụ trách, người hỗ trợ, hạn): docs/hackathon/tasks.md.


🎯 Sản phẩm

Người dùng: học viên Khoá 4 tự học trước mỗi buổi lab/workshop, gồm cả người có nền tảng kỹ thuật (tech) và không có (non-tech).

Vấn đề: tài liệu nằm rải rác ở Discord, Zoom, Drive, VLearn và GitHub. Học viên không biết phần nào là trọng tâm so với quỹ thời gian mình có, nên dễ làm bài sát hạn hoặc nộp muộn.

Bằng chứng (chi tiết và cách đếm ở spec.md §1 và thư mục docs/research/):

  • 8.8% lượt chat VLearn (1.189/13.494) là xin tóm tắt hoặc xin chỉ trọng tâm thay vì tự đọc hết.
  • AI Tutor hiện tại chỉ chủ động gợi ý bước học tiếp theo ở 0.13% lượt (18/13.494).
  • Khảo sát form (n = 82 học viên): 87% không tự xác định được phần cần học bù trước buổi lab; 93% gặp tài liệu rải rác; 93% tự khai mất ít nhất 15 phút mỗi buổi chỉ để gom tài liệu.
  • Phỏng vấn (n = 2): cả 2 người đều gặp cùng kiểu khó khăn. Một người mất 20–25 phút mỗi buổi chỉ để gom link; người kia có 45 phút mà slide dài hơn 60 trang.

Phần được chấm (demo scope), tóm trong một câu: Một học viên Khoá 4 cần lên kế hoạch tự học cho bài lab tiếp theo · được AI Mentor chẩn đoán nền tảng (non-tech / tech-base / AI) và quỹ thời gian rảnh · để đề xuất tối đa 3 đầu việc trọng tâm kèm link tài liệu · giúp học viên hoàn thành bài đúng hạn.

Mức tự động hoá: conditional. AI chỉ đề xuất và giải thích; học viên tự tick, chọn hoặc sửa trước khi làm. Khi thông tin không đủ, AI hỏi lại thay vì tự đoán.

Nguyên tắc thiết kế:

Nguyên tắcThể hiện trong sản phẩm
Giải thích đượcMỗi việc có một dòng lý do và link nguồn
Người dùng quyết định cuốiChecklist tick, bỏ, đổi thứ tự được; AI không tự làm thay
Biết mình không biếtDưới 30 phút, bài lab lạ hoặc ghi chú mâu thuẫn thì hỏi lại
Không vượt phạm viChỉ hiện link có trong catalog; từ chối các yêu cầu làm hộ, xin đáp án, xin gia hạn, xin điểm

Không làm: thanh toán, chứng chỉ; nộp bài hộ hay đổi deadline; thay AI Tutor VLearn; lưu lịch sử học dài hạn.

🧭 Luồng người dùng

Học viên mở trang Lộ trình cá nhân hoá tại /personalized-path. Trang này không cần đăng nhập. API key LLM của học viên chỉ lưu trên trình duyệt (BYOK) và được gửi kèm từng request.

flowchart TD
    A([Mở /personalized-path]) --> B[Bước 1 · Chọn nền tảng<br/>non-tech / tech-base / đã học AI]
    B --> C[Bước 2 · Số phút rảnh hôm nay<br/>+ bài lab tiếp theo]
    C --> D[Bước 3 · Ghi chú tuỳ chọn<br/>'Bạn đang vướng gì?']
    D --> F[Bấm Tạo lộ trình<br/>POST /api/roadmap]
    F --> R{Luật cứng}
    R -- dưới 30 phút / lab lạ --> H
    R -- làm hộ / đáp án / gia hạn / điểm --> I
    R -- hợp lệ --> E{Gọi được LLM?}
    E -- không có key / lỗi / sai schema --> K[Kế hoạch từ luật tĩnh<br/>nhãn 'Gợi ý mặc định']
    K --> G
    E -- được --> S{AI trả về}
    S -- plan --> G[Bước 4 · Checklist ≤3 việc<br/>lý do · thời lượng · link]
    S -- clarify / confidence thấp --> H[Một câu hỏi lại] -- Sửa thời gian / bài lab --> C
    S -- refuse --> I[Lời từ chối<br/>+ gợi ý liên hệ Lab Coach] -- Sửa ghi chú --> D
    G --> J[Tick / bỏ / đổi thứ tự<br/>lưu trên trình duyệt]
    J --> Z([Bắt đầu học])
Tình huốngHọc viên thấy gì
Đủ thông tinDòng chẩn đoán, checklist tối đa 3 việc, nhãn AI hoặc Gợi ý mặc định · chưa cá nhân hoá bằng AI
Dưới 30 phút / bài lab chưa có trong catalog / ghi chú mâu thuẫn với nền tảngMột câu hỏi lại, kèm nút quay về bước 2
Nhờ làm hộ, xin đáp án, gia hạn, điểm, hoặc "bỏ qua hướng dẫn"Lời từ chối, gợi ý liên hệ Lab Coach, kèm nút sửa ghi chú
Không có key, LLM lỗi hoặc trả sai định dạngKế hoạch từ luật tĩnh, gắn nhãn "Gợi ý mặc định" và một dòng thông báo

Chi tiết màn hình: docs/05-ui-flow.md.

🛠️ Luồng vận hành (quản trị)

Lát cắt dự thi không có giao diện admin và không có phân quyền quản trị. Trang /admin là màn hình tĩnh của dự án nền, không dùng trong demo. Việc "quản trị" do nhóm làm trực tiếp trên repo:

flowchart LR
    A[Có bài lab mới<br/>hoặc link hỏng] --> B[Sửa catalog<br/>planner-catalog.ts]
    B --> C[Mở PR]
    C --> D{CI verify<br/>+ review CODEOWNERS}
    D -- đỏ / cần sửa --> B
    D -- xanh + duyệt --> E[Merge vào main]
    E --> P[PR main → production]
    P --> F[Vercel deploy web thật]
    E --> G[Chạy lại golden set<br/>ghi eval/run_results.md]
    H[Phản hồi người dùng thử] --> I[Ghi validation/log.md<br/>+ spec.md §9] --> B
ViệcAi làmỞ đâu
Thêm hoặc sửa tài liệu lab (chỉ link công khai)Đức (Minh hỗ trợ)codebase/src/data/planner-catalog.ts
Sửa prompt, guardrailĐứccodebase/src/lib/prompts/, docs/04-ai-pipeline.md
Chạy eval sau mỗi lần đổi prompt hoặc catalogĐứceval/run_results.md
Ghi nhận phản hồi, quyết định thay đổiKhoavalidation/log.md
spec.md §9
DeployWeb thật chỉ cập nhật khi merge vào nhánh production (mở PR mainproduction). Merge vào main chỉ tạo bản xem thửVercel, Root Directory = codebase

🏗️ Kiến trúc

flowchart LR
    U[Học viên] --> W[Trang Lộ trình cá nhân hoá<br/>/personalized-path]
    W -->|POST /api/roadmap<br/>header: key người dùng| R[Route handler]
    R -->|validate zod · luật cứng| R
    R --> C[(Catalog)]
    R -->|prompt + catalog rút gọn,<br/>không gửi URL| L[LLM router]
    L --> P{{Gemini / OpenAI / Claude / ...}}
    R -->|lọc item theo catalog,<br/>gắn link từ catalog| W
    R -.lỗi / không key.-> B[Baseline<br/>luật tĩnh]
    W --> S[(localStorage)]
  • Mọi lời gọi LLM đều đi qua codebase/src/lib/llm/router.ts. Router hỗ trợ 7 provider, thử lần lượt theo thứ tự FPT → Gemini → OpenAI → Claude → DeepSeek → Groq → Cerebras (chỉ những provider có key), tự thử lại khi lỗi tạm thời và chuyển sang provider khác khi một provider lỗi. Key sai (401/403) thì dừng và báo lỗi.
  • Server không lưu, không log API key.
  • Link hiển thị cho học viên chỉ lấy từ catalog, không bao giờ lấy từ chữ do LLM sinh ra.
LớpCông nghệTrạng thái
FrontendNext.js 15 (App Router) · React 19 · TypeScript (strict) · Tailwind CSS 3 · lucide-react · GSAP · PWAĐang chạy
AILLM router đa nhà cung cấp, người dùng tự mang key (BYOK): FPT AI Factory · Gemini · OpenAI · Claude · DeepSeek · Groq · Cerebras · embedding Gemini 768 chiềuAI Mentor (/personalized-path) và API của AI Helpdesk (/api/chat): chạy thật
Dữ liệuSupabase Postgres + pgvector · Row Level Security · migration SQL (codebase/supabase/migrations/)Đang chạy (chỉ Chat)
Validate & hiển thịzod · react-hook-form · react-markdown + rehype-sanitizeĐang chạy
Tích hợp mở rộngDiscord Activity API (/api/integrations/discord/activity), hỗ trợ Dual-Mode (Mock Sandbox & Live Webhook) ghi nhận +5 XPĐang chạy
Kiểm thử & CIVitest · Husky pre-push (npm run verify) · GitHub Actions verify trên mọi PR và push vào mainĐang chạy
Backend phụ.NET 10 Clean Architecture · EF Core · Postgres + Qdrant (docker-compose)Chưa tích hợp

Xem thêm:

🚦 Trạng thái prototype

PhầnTrạng tháiGhi chú
Lộ trình cá nhân hoá (phần được chấm, do AI Mentor thực hiện), trang /personalized-path✅ AI chạy thậtLuồng 4 bước gọi LLM thật qua /api/roadmap. Bộ kiểm định mở rộng 50/50 case = 100% theo mô hình Khách hàng kép: 40 case Nỗi đau Học viên (B2C: non-tech/tech-base/AI, quỹ thời gian thực tế, giải quyết triệt để 52 tin phân mảnh tài liệu E1, 0 link ngoài) và 10 case Nỗi đau Hệ thống VLearn & Ban vận hành (B2B: chặn leak code mẫu/đáp án/testcase ẩn, chặn bypass deadline LMS, chặn prompt injection, xử lý an toàn Broken Link/Mã lab 404 chống crash 500, chặn DoS token request 0 phút). Xem eval/run_results.md. Baseline luật tĩnh đạt 50/50 (100%) làm baseline & fallback an toàn (baseline-planner.ts)
AI Helpdesk — chatbox nổi ở mọi trang, gọi /api/chat (RAG có trích dẫn)✅ AI chạy thậtƯu tiên trả lời từ FAQ đã xác thực; câu cần tra sâu thì dùng LLM và cần API key. Có eval (codebase/tests/eval/). Là tính năng nền, không thuộc phần được chấm
Wizard lộ trình 4 sprint tại /learning?mode=ai_roadmap (menu "Lộ Trình AI Mentor")🎭 MockQuy tắc chạy trên trình duyệt, không gọi AI. Không thuộc phần được chấm
Form khảo sát 12 câu hỏi, trang /contact✅ Chạy thậtGửi về Google Sheet qua /api/contact/survey; dùng để thu bằng chứng, không thuộc lát cắt được chấm. Phân tích: survey-data-review.md
Hạn mức AI Helpdesk cho khách: 10 câu/ngày✅ Đã có code, ⚠️ chưa đủ mạnh trên web thậtKhách chưa đăng nhập hỏi tối đa 10 câu/ngày; đăng nhập thì không giới hạn. Khi chưa deploy backend, bộ đếm nằm trong bộ nhớ server nên chỉ chặn được một phần
Đăng ký chờ duyệt, trang /admin/approvals✅ Đã có code, ⚠️ chưa deploy backendĐăng ký xong phải chờ quản trị viên duyệt mới đăng nhập được. Cần backend .NET chạy thật
Khoá Lộ trình cá nhân hoá cho người chưa đăng nhập✅ Đã có code, tắt cho tới khi có backendChỉ bật khi đã cấu hình địa chỉ backend, để web thật không bị khoá
Gói Pro, chứng chỉ, cây kỹ năng, /admin (trừ trang duyệt tài khoản)🎭 MockKhông thuộc phạm vi thi
Tích hợp Discord Activity (+5 XP), API /api/integrations/discord/activity✅ Chạy thật (Dual-Mode)Ghi nhận hoạt động tự học (+5 XP/lượt) theo chuẩn kênh #activity của server AI20K Build Phase - Cohort 4. Mặc định chạy Mock Sandbox (trả về preview payload chuẩn) phục vụ chấm điểm; tự động chuyển Live khi có DISCORD_WEBHOOK_URL. 13 unit tests đạt 100%. Chi tiết: docs/feature-discord-api.md
Backend .NET (codebase/backend-core/, codebase/database/)⚠️ Chưa deployĐăng ký/duyệt tài khoản, hạn mức khách, và các endpoint ghi danh/tiến độ/chứng chỉ/thanh toán (lấy người dùng từ token, không nhận userId từ request) đã code xong. Có Dockerfile; tài khoản Railway hết hạn dùng thử nên chưa đưa lên được. Xem docs/06-backend-dotnet.md

🗂️ Cấu trúc repo

K4-3A-e403-Vinonymus/
├── README.md          ← file này (README duy nhất)
├── spec.md            ← AI Spec — rubric chấm R1–R4
├── demo-slides.pdf    ← slide 6 trang (CP5 — chưa có, nộp trước 13:00 · 18/9)
├── .github/           ← CI verify, CODEOWNERS, mẫu PR/issue
├── docs/              ← toàn bộ tài liệu dự án — xem docs/00-muc-luc.md
├── codebase/          ← prototype (Next.js app + backend .NET chưa tích hợp)
├── eval/              ← golden set + kết quả các lượt chạy (R4)
├── validation/        ← nhật ký cho người ngoài dùng thử (R6)
└── reflection/        ← mỗi thành viên 1 file

▶️ Chạy thử

Bản đã deploy:

Test nhanh API Discord Activity (+5 XP):

# Gửi activity học tập (chế độ Sandbox Preview không cần webhook secret)
curl -X POST https://k4-3a-e403-vinonymus.kailabs.io.vn/api/integrations/discord/activity \
  -H "Content-Type: application/json" \
  -d "{\"student_id\":\"HV02733\",\"action_type\":\"generate_path\",\"topic\":\"Lab 02\",\"duration_minutes\":45}"

Chạy local: cần Node.js 22+ và một API key LLM miễn phí. Nên dùng Gemini, lấy key ở Google AI Studio.

cd codebase
npm install                  # đồng thời cài hook pre-push
cp .env.example .env.local   # điền Supabase nếu cần dùng Chat; không commit file này
npm run dev                  # http://localhost:3000/personalized-path
  • API key nhập ở trang Cài đặt trong app. Key chỉ lưu trên trình duyệt (localStorage), không lưu ở server.
  • Không cần chạy backend .NET — để trống các biến *_BACKEND_CORE_URL trong .env.local thì Lộ trình cá nhân hoá vẫn mở tự do, không bắt đăng nhập.
  • Kiểm tra toàn bộ: npm run verify (lint + typecheck + test + audit + build).

Deploy Vercel: Import repo → Root Directory = codebase → Framework Next.js (tự nhận) → Deploy. Trang Lộ trình cá nhân hoá (/personalized-path) không bắt buộc biến môi trường: không có key nào thì trả gợi ý mặc định. Lưu ý nếu đặt GEMINI_API_KEY (hoặc key provider khác) trên Vercel, server sẽ dùng key đó cho mọi request không kèm key của học viên. AI Helpdesk cần NEXT_PUBLIC_SUPABASE_URL, NEXT_PUBLIC_SUPABASE_ANON_KEY, SUPABASE_SERVICE_ROLE_KEY (đặt trong Vercel, không commit).

🤝 Quy trình làm việc nhóm

  1. Nhận việc: tab Issues → Assigned to me. Mỗi issue có đúng một người phụ trách và thuộc một milestone CP.
  2. Làm trên branch riêng: feat/…, fix/…, docs/…, chore/…. Không push thẳng vào main.
  3. Mở PR theo mẫu có sẵn, ghi Closes #<số issue>. CODEOWNERS tự gán người review theo thư mục.
  4. CI verify (lint, typecheck, test, audit, build) phải xanh thì mới merge. Hook pre-push cũng chạy verify ngay trên máy.
  5. Đổi prompt thì chạy lại golden set và ghi vào eval/run_results.md. Đổi theo phản hồi người dùng thì ghi vào spec.md §9.

Quy ước code cho cả người và AI agent: AGENTS.md.

📅 Tiến độ checkpoint

"Đã nộp" = đã nộp form checkpoint đúng hạn (điều kiện lấy điểm mốc, xem 04-rubric.md). "% Issue" = tỷ lệ issue đã đóng trong milestone tương ứng — số này không tự lên 100% khi nộp form, chỉ tăng khi các task con thực sự đóng. Cập nhật tay khi đóng issue, xem số hiện tại tại Milestones.

MốcHạnTrạng thái nộp% IssueViệc
CP1 · Canvas + repo19:30 · 16/9✅ Đã nộp100% (1/1)Milestone
CP2 · Luồng hoạt động21:00 · 16/9✅ Đã nộp (mock demo trên Vercel)100% (6/6)Milestone
CP3 · Video thao tác + số đo16:00 · 17/9✅ Đã nộp (eval 19/20)100% (11/11)Milestone
CP4 · Chốt spec.md21:00 · 17/9✅ Đã nộp (khoá Quality Bar 19/20)100% (9/9)Milestone
CP5 · Slide PDF + video dự phòng13:00 · 18/9⏳ Đang làm (hạn 13:00 · 18/9)0% (0/8)Milestone
CP6 · Thuyết trình17:30 · 18/9⏳ Chiều 18/90% (0/5)Milestone

Xem thêm:

📚 Bản đồ tài liệu

Muốn biếtĐọc
Vì sao chọn bài toán này, bằng chứng, chuẩn "đạt"spec.md
Hệ thống phải làm được gì (FR/NFR/AC)docs/01-SRS.md
Kiến trúc, luồng dữ liệudocs/02-kien-truc.md
Hợp đồng API (/api/roadmap, /api/chat)docs/03-api.md
Đặc tả API & Tích hợp Discord Activity (+5 XP)docs/feature-discord-api.md
Prompt, guardrail, LLM routerdocs/04-ai-pipeline.md
Luồng người dùngdocs/05-ui-flow.md
Kế hoạch kiến trúc AI Access & BYOKdocs/07-ai-access-plan.md
Ai làm gì, hạn nàodocs/hackathon/tasks.md
Kế hoạch sửa cấu trúc repo & quy trìnhdocs/hackathon/repo-fix-plan.md
Tiến độ checkpoint, canvas CP1docs/hackathon/
Bằng chứng mining từ tin nhắn Discord & Chatlogdocs/research/evidence-mining.md
Phân tích dữ liệu khảo sát 45 học viên thậtdocs/research/survey-data-review.md
Dashboard biểu đồ khảo sát trực quan (HTML)docs/research/survey-dashboard.html
Báo cáo rà soát chất lượng 53 file FAQdocs/reports/faq-audit-report.md
Kết quả kiểm định tự động (50/50 cases = 100%)eval/run_results.md
Nhật ký người dùng ngoài thử nghiệm (R6)validation/log.md
Quy ước PR bắt buộc ở gốc repoPR.md
Sơ đồ luồng vai trò hệ thống (Mermaid)role-flow.mmd
Quy ước code cho người và AI agentAGENTS.md
Tài liệu cũ của dự án nền (không phản ánh lát cắt thi)docs/legacy/

🔒 Bảo mật dữ liệu

Repo không chứa data pack của chương trình (data/ bị chặn trong .gitignore), không chứa câu trả lời khảo sát gốc, không chứa API key. Bằng chứng chỉ ghi mã tham chiếu (M#####, T#####) và trích ngắn.


📋 Đề bài & luật thi — bản gốc từ BTC (bấm để mở)

Nhóm copy nguyên file README này về repo của mình, rồi điền bảng trên. Cột Phần việc đảm nhiệm ghi càng cụ thể càng tốt.

  • Thời lượng: 47,5 giờ từ phát đề đến thuyết trình (ca 3A) — LAB 5 (phát đề + build) · LEC 6 (tiếp tục build theo ca) · LAB 6 (vòng thi)
  • Nhóm: 3-4 người · thi theo phòng (E403 / E402), chia cụm rồi chung kết phòng — xem Thể thức thi
  • Chia cụm theo bàn, không cần chung đề tài. Chủ đề tự chọn trong khuôn khổ đề bài
  • Nhóm nhỏ thì chọn lát cắt nhỏ, và phải có khảo sát nỗi đau thật — đây là chỗ ăn điểm nặng nhất

Bắt đầu từ đâu?

  1. Đọc 01-challenge-brief.md để hiểu khung chung và 5 tiêu chí, rồi tracks/README.md để chọn track và đề.
  2. Mở 02-guide.md — hướng dẫn từng giai đoạn, đứng ở đâu đọc mục đó.
  3. Viết spec theo 03-ai-spec-template.md — deliverable trung tâm của cả sự kiện.
  4. Đọc 04-rubric.md ngay từ đầu — biết trước bài được chấm theo tiêu chí nào.
File / thư mụcNội dung
01-challenge-brief.mdĐề bài: bảng 5 track · lát cắt · ràng buộc chung · 5 tiêu chí nghiệm thu
02-guide.mdHướng dẫn 5 giai đoạn: khám phá → spec → build → đo & validate → demo
03-ai-spec-template.mdTemplate AI Spec (nộp tại hạn chốt spec — xem Lịch)
04-rubric.mdRubric 100 điểm (25 nộp checkpoint + 67 chấm bài + 8 điểm R6) + checklist xác minh 6 mốc
tracks/5 track, mỗi đề cùng một khung mục: A VLearn Tutor · B Trợ lý Discord · C Lesson Studio · D Học tập thích ứng & tương tác · E Làn mở (trong phạm vi AI20k) — bắt đầu từ tracks/README.md
data/Dữ liệu thật đã ẩn danh: vlearn-pack/ (chatlog VLearn tutor + 6 transcript bài giảng + 2 bộ slide bản hackathon) và discord-pack/ (tin nhắn Discord khoá 4 + bản tin bot) — dùng để tìm bằng chứng và xây golden set. Đọc data/README.md trước
further-reading/Tài liệu tham khảo có tóm lược tiếng Việt: Mom Test (phỏng vấn), PAIR Guidebook (Google, 6 chương), HAX Toolkit (Microsoft, 18 nguyên tắc), JTBD Playbook + worksheet — bắt đầu từ further-reading/README.md

Lịch — 6 checkpoint (ca 3A · 47,5 giờ)

MốcCần hoàn thànhHạn (ca 3A)
Khai mạc 17:30 · phát đề 18:0016/9
CP1Canvas 4 ô + đội trưởng + link repo GitHub công khai19:30 · 16/9
CP2Cho thấy luồng hoạt động — bấm thử được, hoặc sơ đồ luồng21:00 · 16/9
CP3Video thao tác 30 giây + số đo (thử bao nhiêu, đúng bao nhiêu)16:00 · 17/9
CP4Chốt spec.mdkhoá chuẩn "đạt" · tự khai phần chưa xong21:00 · 17/9
CP5Slide PDF + video demo dự phòng cho buổi pitch — nộp cuối13:00 · 18/9
CP6Thuyết trình · không nộp thêm17:30 · 18/9

CP1 đến CP5 mỗi mốc 5 điểm. Nộp đúng hạn được đủ, nộp muộn là 0 điểm mốc đó — không bù được bằng mốc khác.

Làm bài lúc nào

Thời gian tự làmNgoài giờ học, và trong buổi LEC ngày 17/9
Coach hỗ trợTrên lớp và trên Discord
Buổi LAB 18/9 · 17:30–21:00Đây là vòng thi, không phải giờ làm bài

Hai phòng cùng ca dùng chung lịch mốc. Năm link form phát đủ từ đầu — xong mốc nào nộp mốc đó, không phải chờ.

Giải thích từng mốc

CP1 · Chốt Canvas + repo

Để làm gì: chốt rõ làm cho ai và giải vấn đề gì trước khi bắt tay vào code. Bỏ qua bước này thì hay gặp cảnh làm xong mới nhận ra không ai cần đến.

Nộp:

  • Canvas điền đủ 4 ô theo mẫu trong 01-challenge-brief.md
  • Họ tên và mã học viên của đội trưởng
  • Link repo GitHub đã để công khai
  • Khai báo willing user — người sẵn sàng cho nhóm thử sản phẩm ở CP5. Cần ít nhất 2 người, khai từ đây

Khai willing user ngay từ CP1, đừng để đến CP5. Khối R6 ở CP5 yêu cầu có ít nhất 2 willing user đã khai ở mốc này. Đến lúc cần mới đi tìm người thì không kịp.


CP2 · Cho thấy luồng hoạt động

Để làm gì: nhìn được cả luồng từ đầu đến cuối — người dùng bấm gì trước, thấy gì sau, kết thúc ở đâu. Vẽ ra giấy thì phát hiện chỗ hổng trong mười phút; code xong mới thấy thì mất cả buổi sửa.

Nộp một trong ba thứ, thứ nào cũng được:

  • Bản mock bấm được — Figma, trang tĩnh, Canva, bất cứ thứ gì click qua lại được
  • Sơ đồ luồng vẽ tay hay vẽ máy, miễn thấy rõ các bước
  • Video quay màn hình đi hết một lượt

Chưa cần AI chạy thật — cái đó để CP3. Mốc này để nhẹ, chỉ cần cho thấy nhóm đang đi hướng nào.


CP3 · Video thao tác + số đo

Để làm gì: biết sản phẩm của mình đang đúng đến đâu. Có con số thì mới biết nên sửa chỗ nào tiếp, và lúc pitch cũng có cái để nói thay vì nói suông.

Nộp hai thứ:

1 · Video thao tác — 30 giây, quay màn hình. Bấm thật trên sản phẩm, thấy AI trả kết quả thật. Không cần dựng, không cần lồng tiếng.

2 · Số đo — thử bao nhiêu lần, đúng được bao nhiêu.

Đây là con số cho biết sản phẩm tốt đến đâu. Cách làm:

1. Chuẩn bị một bộ câu thử  — ví dụ 20 câu hỏi người dùng hay hỏi
2. Cho sản phẩm chạy hết 20 câu đó
3. Đếm bao nhiêu câu ra kết quả đạt chuẩn nhóm tự đặt
Chưa đạtĐạt
"Sản phẩm chạy tốt""Thử 21 câu, 13 câu trả đúng có dẫn nguồn, 8 câu sai hoặc bịa"
"Độ chính xác cao""Thử 30 file, 24 file tóm tắt đúng ý chính, 6 file bỏ sót"

Số xấu vẫn được đủ điểm — miễn là số thật. 13 trên 21 mà phân tích được vì sao 8 câu kia sai thì ăn điểm cao hơn "chạy tốt" không có gì chứng minh.


CP4 · Chốt spec.md

Để làm gì: chốt "thế nào là đạt" trước khi biết kết quả. Đặt chuẩn sau khi đã thấy kết quả thì con số không nói lên điều gì — và người nghe cũng biết vậy.

Nộp:

  • Link spec.md đã chốt — trong đó nhóm tự chốt "thế nào là đạt" cho sản phẩm mình
  • Tự khai phần nào chưa làm xong

Sau 21:00 hôm đó không sửa chuẩn "đạt" được nữa.

Khai thiếu không bị trừ điểm. Giấu mới bị.


CP5 · Slide + video dự phòng

Để làm gì: đảm bảo buổi pitch chạy được dù mạng hỏng hay máy chết. Đây cũng là hạn nộp cuối — sau mốc này không nộp thêm gì.

Nộp:

  • Slide 6 trang, xuất ra PDF theo 02-guide.md §5.1. Nộp PDF chứ không nộp link — link hay hỏng quyền đúng lúc cần
  • Video demo dự phòng — quay sẵn phần demo. Nếu hôm pitch mạng chết thì BTC chiếu video này và không trừ điểm

CP3 và CP5 là hai video khác nhau: CP3 chứng minh sản phẩm chạy — quay ngắn, quay thô cũng được. CP5 là bản sao lưu để buổi pitch không chết vì mạng — quay đúng phần định demo trên sân khấu.


CP6 · Thuyết trình

Không nộp gì. Ngày này chỉ để trình bày.

Giám khảo có thể hỏi bất kỳ thành viên nào về phần có tên người đó trong bảng phân công.

MốcForm nộp
CP1(cập nhật lúc khai mạc)
CP2(cập nhật lúc khai mạc)
CP3(cập nhật lúc khai mạc)
CP4(cập nhật lúc khai mạc)
CP5(cập nhật lúc khai mạc)

Đội trưởng nộp form thay cả nhóm — một phiếu cho cả nhóm ở mỗi mốc, không phải mỗi thành viên tự nộp. 25 điểm nộp là điểm chung của nhóm: mọi thành viên cùng được hoặc cùng mất.

⚠️ Cả 5 mốc phải nộp bằng cùng một mã học viên của đội trưởng. BTC ghép 5 phiếu của nhóm lại với nhau dựa trên mã học viên người nộp. Mốc này người A nộp, mốc kia người B nộp thì hệ thống hiểu là hai nhóm khác nhau, và nhóm mất điểm ở những mốc lệch.

Chọn đội trưởng là người chắc chắn có mặt và theo được cả năm mốc. Nếu bất khả kháng phải đổi người nộp, báo coach ngay trong buổi.

Link được công bố tại khai mạc, ghim trên Discord và đăng trên VLearn — hai nơi, cùng một bộ link.

Thể thức thi

  • 2 ca × 2 phòng = 4 cuộc thi độc lập, chấm và trao giải riêng từng phòng; mỗi phòng một tổ giám khảo. Không thi liên phòng, liên khoá.
  • E403 (~230 người): 6 cụm thi, mỗi nhóm 6 phút ở vòng cụm → 6 đội vào chung kết phòng → Top 3.
  • E402 (~120 người): 5 cụm thi, mỗi nhóm 7 phút ở vòng cụm → 5 đội vào chung kết phòng → Top 2.
  • Giám khảo có thể hỏi bất kỳ thành viên — ai cũng phải hiểu bài (vibe-coding rule).
  • Số nhóm mỗi cụm là ước tính; thể lệ chi tiết vòng cụm và chung kết công bố lúc khai mạc.

Vòng cụm — game đầu tư

Mỗi đội có 100 điểm vốn, đội trưởng đại diện xem và đầu tư. Đội nhận nhiều vốn nhất cụm đi tiếp vào chung kết phòng.

Hai luật: không được đầu tư vào đội mình · tổng phải đúng 100, thừa hoặc thiếu là phiếu không được tính.

Chia cho mấy đội là tuỳ — dồn hết vào một đội cũng được. Mẹo: trong lúc xem thì ghi số dự định ra giấy nháp, xem xong cả cụm mới cân đối lại rồi điền form.

Chung kết phòng

Sau khi chốt danh sách, các đội có 10–15 phút chuẩn bị. Thứ tự trình bày quay ngẫu nhiên tại chỗ.

Mỗi đội 10 phút: 7 phút trình bày + 3 phút hỏi đáp.

Cả phòng bình chọn — mỗi người đánh giá từng đội một cách độc lập, không giới hạn số đội được bầu.

Giải thưởng

Giải theo phòng — mỗi lớp 5 đội, hai lớp 10 đội:

LớpE403E402Tổng
3ATop 3Top 25 đội
3BTop 3Top 25 đội

Điểm thưởng cộng vào bài lab ngày 5 và ngày 6, cho mỗi thành viên:

Ai đượcCộng
Giải Nhất của phòng+10
Giải Nhì của phòng+5
Giải Ba — chỉ E403+3
Vào chung kết nhưng không có giải+2
Đội đầu tư nhiều điểm nhất và sớm nhất vào đội giải Nhất+2

Mỗi phòng E403 có 7 đội được cộng điểm, E402 có 6 đội — không chỉ riêng đội vô địch.

Dòng cuối chỉ có một đội mỗi phòng: xét điểm đầu tư cao nhất trước, bằng nhau thì lấy đội nộp phiếu sớm hơn theo dấu thời gian của form.

Giải theo track — 4 giải, chấm chung cả hai lớp:

  • Track A · VLearn Tutor và Track D · Học tập thích ứng & tương tác: 2 giải, do team VLearn chọn.
  • Track C · Lesson Studio: 2 giải, do team Studio chọn.

Hai team chấm ngay tại buổi trình bày. Một đội có thể vừa vào Top phòng vừa nhận giải track. Phần thưởng cụ thể sẽ được công bố sau.

Mỗi mốc cần show gì và được xác minh thế nào: xem bảng trong 04-rubric.md.

Nộp bài

Tạo repo mới — không fork repo đề bài

Nhóm tạo một repo hoàn toàn mới và trống. Không fork, không clone repo này rồi push lên.

Lý do: fork mang theo cả thư mục data/, mà repo nộp bài bắt buộc phải công khai — nghĩa là dữ liệu thật của khoá học sẽ lên mạng. Vi phạm thẳng điều 2 và điều 3 của quy định bảo mật bên dưới.

Nhóm chỉ cần lấy đúng một file từ repo này: 03-ai-spec-template.md, copy vào repo mình và đặt tên spec.md. Mọi thứ còn lại là tài liệu đọc, mở tại đây là đủ.

Cách đặt tên repo

K4-<mã lớp>-<phòng>-<tên nhóm>
Ví dụCủa nhóm nào
K4-3A-E403-StudyPulseLớp 3A · phòng E403 · nhóm StudyPulse
K4-3A-E402-LearnLoopLớp 3A · phòng E402 · nhóm LearnLoop

Ba phần đầu bắt buộc đúng. Phòng là phòng nhóm đang ngồi thi.

Tên nhóm ở cuối đặt gì cũng được — viết liền, không dấu, không khoảng trắng.

Repo phải để công khai. Thử mở bằng cửa sổ ẩn danh — mở được thì mới đúng. Để riêng tư là giám khảo không chấm được bài.

Cấu trúc repo

Spec chốt tại hạn chốt spec (xem Lịch); bản hoàn chỉnh trước CP6.

repo/
├── README.md          ← copy file này, điền bảng thành viên ở đầu
├── spec.md            ← AI Spec theo 03-ai-spec-template.md
├── demo-slides.pdf    ← slide 6 trang theo 02-guide.md §5.1
├── codebase/          ← prototype (ghi rõ phần nào mock)
├── eval/              ← golden set + bảng kết quả các lượt chạy
├── validation/        ← nhật ký cho người ngoài dùng thử (R6 — không làm thì trần điểm 92)
└── reflection/        ← mỗi người 1 file

README.md của nhóm

Copy nguyên file README này về repo của mình, rồi điền bảng thành viên ở đầu file. Không cần viết thêm gì khác.

Mã học viên phải đúng — đây là căn cứ đối chiếu điểm.

Chấm điểm

Tổng 100 điểm = 25 điểm nộp checkpoint + 67 điểm chấm bài nộp + 8 điểm R6 (cho người ngoài dùng thử). Chi tiết từng ý điểm: 04-rubric.md.

25 điểm nộp — mỗi checkpoint 5 điểm (CP1-CP5): nộp đúng hạn → 5 điểm · nộp muộn → 0 điểm cho mốc đó. Đội trưởng nộp thay cả nhóm — đây là điểm chung của nhóm, không phải điểm cá nhân.

67 điểm chấm + 8 điểm R6 — trên file trong repo, mỗi con điểm trỏ về một chỗ:

KhốiĐiểmChấm trên file nào
R1 · Bằng chứng & impact15spec.md §1-§2 + log khảo sát
R2 · Lát cắt & thiết kế15spec.md §4
R3 · Chỗ khó & kịch bản rủi ro11spec.md §5-§6
R4 · Kiểm thử15spec.md §7 + eval/
R5 · Prototype chạy được8codebase/ + demo
R6 · Cho người ngoài dùng thử8validation/
R7 · Quy trình & repo3cấu trúc repo

Ba khối nặng nhất — R1, R2, R4 — đều nằm trong spec.md. Viết spec tử tế là ăn 45 trên 67 điểm.

R6 · Cho người ngoài dùng thử — 8 điểm

Không làm thì trần điểm là 92. Vì 25 + 67 = 92, cộng R6 mới đủ 100.

Làm ở CP5, lưu trong thư mục validation/.

Người dùng chê cũng được tính đủ điểm. Mục đích là xem giải pháp có ăn thua không — ra kết quả nào cũng ghi nhận, miễn là bằng chứng thật. Phát hiện sản phẩm chưa ổn rồi sửa còn dễ ăn điểm hơn, vì có chỗ cụ thể để nói.

Hai ví dụ thật từ kỳ trước:

Nhóm MeaterBeat phát hiện học viên non-IT lúng túng không biết bấm nút nào, AI trả lời chậm — tức là giải pháp chưa ổn. Họ thêm tooltip hướng dẫn, thêm loading spinner, và giải trình phần độ trễ không sửa được vì phụ thuộc API. Đủ điểm.

Nhóm VLearn Recall phát hiện đúng như giả định: người ta nhớ chủ đề nhưng không nhớ nằm ở slide hay bài giảng — tức là giải pháp đi đúng hướng. Họ giữ nguyên thiết kế source-first và bổ sung thêm câu thử. Cũng đủ điểm.

Phải có đủ bốn thứ:

5 người ngoài nhóm dùng thửtrong đó 2 người đã khai từ CP1
Quote nguyên vănchép đúng lời họ nói, kể cả viết sai chính tả
Bảng nhật kýai thử · giao task gì · kẹt ở đâu · quote · quyết định
Ít nhất 1 thay đổighi vào §9 Changelog trong spec.md. Giữ nguyên thì nói rõ vì sao

Cuối bảng viết 4 dòng: chủ đề lặp nhiều nhất · sẽ sửa gì trước demo · giữ nguyên gì và vì sao · gì để dành sau.

Quote thế nào mới ăn điểm:

Chưa đạtĐạt
"Demo này ok rồi đấy""Mình muốn tìm thông tin về code cho ReAct"

Bên trái là lời khen xã giao. Bên phải là lời người dùng nói lúc đang cố làm việc — nhìn vào biết ngay họ vướng ở đâu.

Muốn có quote như vậy: giao task rồi ngồi im xem họ làm, đừng hỏi "sản phẩm này hay không".

Ba điều nên biết trước khi làm:

  • Điểm dựa trên chuỗi quyết định và bằng chứng, không dựa trên mức độ hoành tráng của sản phẩm.
  • Kết quả đo ghi nhận trung thực — kể cả khi không đạt mục tiêu nhóm tự đặt — vẫn được tính đủ điểm. Số liệu bị chỉnh sửa hoặc che giấu sẽ không được tính.
  • Reflection cá nhân chấm riêng theo rubric của khoá. Điểm vòng demo, chấm chéo trong cụm và thưởng thêm (nếu có) theo thể lệ công bố lúc khai mạc.

Luật chung

  1. Prototype có 3 mức Sketch / Mock / Working — mức nào cũng bắt buộc ≥1 lời gọi AI chạy thật. Đây là thứ phải thấy được trong video thao tác ở CP3.
  2. Vibe-coding rule: dùng AI để build thoải mái, nhưng không giải thích được phần có tên mình thì phần đó 0 điểm (giám khảo hỏi bất kỳ thành viên khi thuyết trình).
  3. Quality bar chốt tại hạn chốt spec (21:00 17/9, tại CP4) và giữ nguyên sau đó.
  4. Chỉ dùng dữ liệu trong data/ hoặc dữ liệu giả tự sinh — không dùng dữ liệu thật của người thật. Không commit API key.
  5. Tuân thủ quy định bảo mật dữ liệu bên dưới — đây là điều kiện để được cấp data.

Bảo mật dữ liệu được cung cấp

Dữ liệu trong data/ là dữ liệu thật của khoá học (đã ẩn danh), cấp riêng cho hackathon này. Khi nhận data, nhóm cam kết:

  1. Chỉ dùng trong phạm vi hackathon — cho việc tìm bằng chứng, xây golden set và build prototype. Không dùng cho mục đích khác.
  2. Không chia sẻ ra ngoài khoá học — không đăng lên mạng xã hội, không gửi cho người ngoài, không đưa vào bất kỳ dataset hay repo công khai nào.
  3. Không commit data pack vào repo nộp bài — repo nhóm chỉ chứa trích dẫn ngắn để minh hoạ (vài dòng); golden set trích từ data ghi rõ mã đoạn/mã hội thoại thay vì dán nguyên văn dài.
  4. Cẩn trọng khi đưa data vào công cụ ngoài — chỉ đưa phần tối thiểu cần cho việc đang làm; lưu ý API/công cụ free tier có thể dùng dữ liệu để huấn luyện (xem 02-guide.md §3.4).
  5. Không cố suy ngược danh tính từ dữ liệu đã ẩn danh (S####, T#####, D####, [HV], [học viên]). Riêng discord-pack/: người trong đó là bạn cùng khoá — tuyệt đối không đoán/hỏi "tin này của ai"; trích dẫn tối đa 2 câu mỗi ví dụ (xem data/discord-pack/README.md).
  6. Sau sự kiện, xoá các bản sao data pack khỏi máy cá nhân và các công cụ đã upload nếu ban tổ chức yêu cầu.

Vi phạm được xử lý theo quy định của khoá và có thể ảnh hưởng trực tiếp đến điểm của nhóm.

Contributors

Dokhacgiakhoa

65 commits

jansulubituu

2 commits

Dokhacgiakhoa/K4-3A-e403-Vinonymus

Mini Hackathon

TypeScript

0

81 commits

updated Sep 17, 2026

See the code

README

Vinonymus — Adaptive Learning System: AI Mentor & AI Helpdesk

Mini Hackathon AI · Batch 04 · Lớp 3A · Phòng E403 · Cụm C2 · Track E — Làn mở (trong phạm vi AI20k) SPEC → Prototype → Demo. Đây không phải cuộc thi code — đây là cuộc thi tư duy sản phẩm AI.

verify

Trang chủ hệ thốnghttps://k4-3a-e403-vinonymus.kailabs.io.vn
Demo Lộ trình cá nhân hoá (Phần chấm thi)https://k4-3a-e403-vinonymus.kailabs.io.vn/personalized-path
Bản demo dự phòng (Vercel)https://k4-3a-e403-vinonymus.vercel.app/personalized-path
AI Spec (Tài liệu chấm chính thức)spec.md
Đặc tả yêu cầu hệ thống (SRS)docs/01-SRS.md
Kiến trúc & Luồng dữ liệudocs/02-kien-truc.md
Kiểm định Eval 50 case (100%)eval/run_results.md
Tích hợp Discord Activity (+5 XP)docs/feature-discord-api.md
Việc của nhómMilestones theo checkpoint

Adaptive Learning System cho học viên Khoá 4, gồm 2 AI:

AINgười dùng có trò chuyện không?Làm gìHiện ra ở đâuVai trò trong cuộc thi
AI MentorKhông. AI thực thi, chạy phía sauĐọc thông tin của học viên, đọc tài liệu giảng viên tải lên, phân tích CV để ra bài test năng lực, phân tích điểm test để xây lộ trình học (chi tiết bên dưới)Tính năng Lộ trình cá nhân hoá tại /personalized-pathPhần được chấm (demo scope) là tính năng này, theo spec.md
AI HelpdeskCó. Là AI duy nhất người dùng nói chuyệnTra cứu, giải đáp về tài liệu và lộ trình học, có trích dẫn nguồnChatbox (widget chat nổi)Tính năng nền, không thuộc phần chấm. Chatbox đã gọi AI thật (xem Trạng thái)

AI Mentor làm 4 việc (trạng thái thật tính đến 17/9):

#Việc của AI MentorTrạng thái
1Đọc thông tin đầu vào của học viên⚠️ Một phần: đọc nền tảng tự khai, số phút rảnh, bài lab, ghi chú. Chưa đọc từ hồ sơ đăng nhập
2Đọc tài liệu giảng viên tải lên, phân tích rồi đưa vào thư viện tài liệu❌ Chưa làm: thư viện do nhóm tự soạn tay; chưa có giao diện giảng viên
3Phân tích CV của học viên để ra bài test năng lực online❌ Chưa có AI: màn hình mẫu chạy quy tắc cố định
4Phân tích điểm test để xây lộ trình học từ thư viện⚠️ Một phần: đã chọn tài liệu từ thư viện theo nền tảng tự khai, chưa theo điểm test

Với tính năng Lộ trình cá nhân hoá (Personalized Learning Path):

  1. Học viên chọn nền tảng của mình (non-tech, tech-base hoặc đã học AI).
  2. Học viên cho biết hôm nay rảnh bao nhiêu phútbài lab tiếp theo là gì.
  3. AI Mentor chọn ra tối đa 3 việc cần làm trước. Mỗi việc có lý do, thời lượng và link tài liệu lấy từ catalog đã kiểm chứng.
  4. Học viên tick, bỏ hoặc đổi thứ tự trước khi bắt đầu học.

Mục lục

👥 Thành viên & phân công

Nhóm: Vinonymus · Lớp: 3A · Phòng: E403 · Cụm: C2 · Track: E — Làn mở (trong phạm vi AI20k)

Họ và TênMã Học ViênVai trò chínhGitHubPhần việc đảm nhiệm trong dự ánViệc được giao
Đỗ Khắc Gia Khoa (đội trưởng)02733PM@DokhacgiakhoaChốt Canvas & lát cắt, khảo sát nỗi đau, viết spec.md, điều phối checkpoint & nộp form, slide + pitch, validation (R6)Issues
Trần Nhật Minh02483BE@minh-tran-2611Backend/API cho prototype (/api/roadmap), tích hợp lời gọi AI qua LLM router, CI, quản lý biến môi trường (không commit key)Issues
Đinh Ngọc Đức02935AI@dinhngocduc1311Thiết kế prompt/pipeline AI, catalog tài liệu, xây golden set & chạy eval (eval/), phân tích lỗi và kịch bản rủi roIssues
Nguyễn Việt Thành02924FE@thanhnvhust514Giao diện & luồng người dùng, mock bấm được (CP2), quay video thao tác CP3 và video demo dự phòng CP5Issues

Bảng phân công chi tiết theo từng checkpoint (người phụ trách, người hỗ trợ, hạn): docs/hackathon/tasks.md.


🎯 Sản phẩm

Người dùng: học viên Khoá 4 tự học trước mỗi buổi lab/workshop, gồm cả người có nền tảng kỹ thuật (tech) và không có (non-tech).

Vấn đề: tài liệu nằm rải rác ở Discord, Zoom, Drive, VLearn và GitHub. Học viên không biết phần nào là trọng tâm so với quỹ thời gian mình có, nên dễ làm bài sát hạn hoặc nộp muộn.

Bằng chứng (chi tiết và cách đếm ở spec.md §1 và thư mục docs/research/):

  • 8.8% lượt chat VLearn (1.189/13.494) là xin tóm tắt hoặc xin chỉ trọng tâm thay vì tự đọc hết.
  • AI Tutor hiện tại chỉ chủ động gợi ý bước học tiếp theo ở 0.13% lượt (18/13.494).
  • Khảo sát form (n = 82 học viên): 87% không tự xác định được phần cần học bù trước buổi lab; 93% gặp tài liệu rải rác; 93% tự khai mất ít nhất 15 phút mỗi buổi chỉ để gom tài liệu.
  • Phỏng vấn (n = 2): cả 2 người đều gặp cùng kiểu khó khăn. Một người mất 20–25 phút mỗi buổi chỉ để gom link; người kia có 45 phút mà slide dài hơn 60 trang.

Phần được chấm (demo scope), tóm trong một câu: Một học viên Khoá 4 cần lên kế hoạch tự học cho bài lab tiếp theo · được AI Mentor chẩn đoán nền tảng (non-tech / tech-base / AI) và quỹ thời gian rảnh · để đề xuất tối đa 3 đầu việc trọng tâm kèm link tài liệu · giúp học viên hoàn thành bài đúng hạn.

Mức tự động hoá: conditional. AI chỉ đề xuất và giải thích; học viên tự tick, chọn hoặc sửa trước khi làm. Khi thông tin không đủ, AI hỏi lại thay vì tự đoán.

Nguyên tắc thiết kế:

Nguyên tắcThể hiện trong sản phẩm
Giải thích đượcMỗi việc có một dòng lý do và link nguồn
Người dùng quyết định cuốiChecklist tick, bỏ, đổi thứ tự được; AI không tự làm thay
Biết mình không biếtDưới 30 phút, bài lab lạ hoặc ghi chú mâu thuẫn thì hỏi lại
Không vượt phạm viChỉ hiện link có trong catalog; từ chối các yêu cầu làm hộ, xin đáp án, xin gia hạn, xin điểm

Không làm: thanh toán, chứng chỉ; nộp bài hộ hay đổi deadline; thay AI Tutor VLearn; lưu lịch sử học dài hạn.

🧭 Luồng người dùng

Học viên mở trang Lộ trình cá nhân hoá tại /personalized-path. Trang này không cần đăng nhập. API key LLM của học viên chỉ lưu trên trình duyệt (BYOK) và được gửi kèm từng request.

flowchart TD
    A([Mở /personalized-path]) --> B[Bước 1 · Chọn nền tảng<br/>non-tech / tech-base / đã học AI]
    B --> C[Bước 2 · Số phút rảnh hôm nay<br/>+ bài lab tiếp theo]
    C --> D[Bước 3 · Ghi chú tuỳ chọn<br/>'Bạn đang vướng gì?']
    D --> F[Bấm Tạo lộ trình<br/>POST /api/roadmap]
    F --> R{Luật cứng}
    R -- dưới 30 phút / lab lạ --> H
    R -- làm hộ / đáp án / gia hạn / điểm --> I
    R -- hợp lệ --> E{Gọi được LLM?}
    E -- không có key / lỗi / sai schema --> K[Kế hoạch từ luật tĩnh<br/>nhãn 'Gợi ý mặc định']
    K --> G
    E -- được --> S{AI trả về}
    S -- plan --> G[Bước 4 · Checklist ≤3 việc<br/>lý do · thời lượng · link]
    S -- clarify / confidence thấp --> H[Một câu hỏi lại] -- Sửa thời gian / bài lab --> C
    S -- refuse --> I[Lời từ chối<br/>+ gợi ý liên hệ Lab Coach] -- Sửa ghi chú --> D
    G --> J[Tick / bỏ / đổi thứ tự<br/>lưu trên trình duyệt]
    J --> Z([Bắt đầu học])
Tình huốngHọc viên thấy gì
Đủ thông tinDòng chẩn đoán, checklist tối đa 3 việc, nhãn AI hoặc Gợi ý mặc định · chưa cá nhân hoá bằng AI
Dưới 30 phút / bài lab chưa có trong catalog / ghi chú mâu thuẫn với nền tảngMột câu hỏi lại, kèm nút quay về bước 2
Nhờ làm hộ, xin đáp án, gia hạn, điểm, hoặc "bỏ qua hướng dẫn"Lời từ chối, gợi ý liên hệ Lab Coach, kèm nút sửa ghi chú
Không có key, LLM lỗi hoặc trả sai định dạngKế hoạch từ luật tĩnh, gắn nhãn "Gợi ý mặc định" và một dòng thông báo

Chi tiết màn hình: docs/05-ui-flow.md.

🛠️ Luồng vận hành (quản trị)

Lát cắt dự thi không có giao diện admin và không có phân quyền quản trị. Trang /admin là màn hình tĩnh của dự án nền, không dùng trong demo. Việc "quản trị" do nhóm làm trực tiếp trên repo:

flowchart LR
    A[Có bài lab mới<br/>hoặc link hỏng] --> B[Sửa catalog<br/>planner-catalog.ts]
    B --> C[Mở PR]
    C --> D{CI verify<br/>+ review CODEOWNERS}
    D -- đỏ / cần sửa --> B
    D -- xanh + duyệt --> E[Merge vào main]
    E --> P[PR main → production]
    P --> F[Vercel deploy web thật]
    E --> G[Chạy lại golden set<br/>ghi eval/run_results.md]
    H[Phản hồi người dùng thử] --> I[Ghi validation/log.md<br/>+ spec.md §9] --> B
ViệcAi làmỞ đâu
Thêm hoặc sửa tài liệu lab (chỉ link công khai)Đức (Minh hỗ trợ)codebase/src/data/planner-catalog.ts
Sửa prompt, guardrailĐứccodebase/src/lib/prompts/, docs/04-ai-pipeline.md
Chạy eval sau mỗi lần đổi prompt hoặc catalogĐứceval/run_results.md
Ghi nhận phản hồi, quyết định thay đổiKhoavalidation/log.md
spec.md §9
DeployWeb thật chỉ cập nhật khi merge vào nhánh production (mở PR mainproduction). Merge vào main chỉ tạo bản xem thửVercel, Root Directory = codebase

🏗️ Kiến trúc

flowchart LR
    U[Học viên] --> W[Trang Lộ trình cá nhân hoá<br/>/personalized-path]
    W -->|POST /api/roadmap<br/>header: key người dùng| R[Route handler]
    R -->|validate zod · luật cứng| R
    R --> C[(Catalog)]
    R -->|prompt + catalog rút gọn,<br/>không gửi URL| L[LLM router]
    L --> P{{Gemini / OpenAI / Claude / ...}}
    R -->|lọc item theo catalog,<br/>gắn link từ catalog| W
    R -.lỗi / không key.-> B[Baseline<br/>luật tĩnh]
    W --> S[(localStorage)]
  • Mọi lời gọi LLM đều đi qua codebase/src/lib/llm/router.ts. Router hỗ trợ 7 provider, thử lần lượt theo thứ tự FPT → Gemini → OpenAI → Claude → DeepSeek → Groq → Cerebras (chỉ những provider có key), tự thử lại khi lỗi tạm thời và chuyển sang provider khác khi một provider lỗi. Key sai (401/403) thì dừng và báo lỗi.
  • Server không lưu, không log API key.
  • Link hiển thị cho học viên chỉ lấy từ catalog, không bao giờ lấy từ chữ do LLM sinh ra.
LớpCông nghệTrạng thái
FrontendNext.js 15 (App Router) · React 19 · TypeScript (strict) · Tailwind CSS 3 · lucide-react · GSAP · PWAĐang chạy
AILLM router đa nhà cung cấp, người dùng tự mang key (BYOK): FPT AI Factory · Gemini · OpenAI · Claude · DeepSeek · Groq · Cerebras · embedding Gemini 768 chiềuAI Mentor (/personalized-path) và API của AI Helpdesk (/api/chat): chạy thật
Dữ liệuSupabase Postgres + pgvector · Row Level Security · migration SQL (codebase/supabase/migrations/)Đang chạy (chỉ Chat)
Validate & hiển thịzod · react-hook-form · react-markdown + rehype-sanitizeĐang chạy
Tích hợp mở rộngDiscord Activity API (/api/integrations/discord/activity), hỗ trợ Dual-Mode (Mock Sandbox & Live Webhook) ghi nhận +5 XPĐang chạy
Kiểm thử & CIVitest · Husky pre-push (npm run verify) · GitHub Actions verify trên mọi PR và push vào mainĐang chạy
Backend phụ.NET 10 Clean Architecture · EF Core · Postgres + Qdrant (docker-compose)Chưa tích hợp

Xem thêm:

🚦 Trạng thái prototype

PhầnTrạng tháiGhi chú
Lộ trình cá nhân hoá (phần được chấm, do AI Mentor thực hiện), trang /personalized-path✅ AI chạy thậtLuồng 4 bước gọi LLM thật qua /api/roadmap. Bộ kiểm định mở rộng 50/50 case = 100% theo mô hình Khách hàng kép: 40 case Nỗi đau Học viên (B2C: non-tech/tech-base/AI, quỹ thời gian thực tế, giải quyết triệt để 52 tin phân mảnh tài liệu E1, 0 link ngoài) và 10 case Nỗi đau Hệ thống VLearn & Ban vận hành (B2B: chặn leak code mẫu/đáp án/testcase ẩn, chặn bypass deadline LMS, chặn prompt injection, xử lý an toàn Broken Link/Mã lab 404 chống crash 500, chặn DoS token request 0 phút). Xem eval/run_results.md. Baseline luật tĩnh đạt 50/50 (100%) làm baseline & fallback an toàn (baseline-planner.ts)
AI Helpdesk — chatbox nổi ở mọi trang, gọi /api/chat (RAG có trích dẫn)✅ AI chạy thậtƯu tiên trả lời từ FAQ đã xác thực; câu cần tra sâu thì dùng LLM và cần API key. Có eval (codebase/tests/eval/). Là tính năng nền, không thuộc phần được chấm
Wizard lộ trình 4 sprint tại /learning?mode=ai_roadmap (menu "Lộ Trình AI Mentor")🎭 MockQuy tắc chạy trên trình duyệt, không gọi AI. Không thuộc phần được chấm
Form khảo sát 12 câu hỏi, trang /contact✅ Chạy thậtGửi về Google Sheet qua /api/contact/survey; dùng để thu bằng chứng, không thuộc lát cắt được chấm. Phân tích: survey-data-review.md
Hạn mức AI Helpdesk cho khách: 10 câu/ngày✅ Đã có code, ⚠️ chưa đủ mạnh trên web thậtKhách chưa đăng nhập hỏi tối đa 10 câu/ngày; đăng nhập thì không giới hạn. Khi chưa deploy backend, bộ đếm nằm trong bộ nhớ server nên chỉ chặn được một phần
Đăng ký chờ duyệt, trang /admin/approvals✅ Đã có code, ⚠️ chưa deploy backendĐăng ký xong phải chờ quản trị viên duyệt mới đăng nhập được. Cần backend .NET chạy thật
Khoá Lộ trình cá nhân hoá cho người chưa đăng nhập✅ Đã có code, tắt cho tới khi có backendChỉ bật khi đã cấu hình địa chỉ backend, để web thật không bị khoá
Gói Pro, chứng chỉ, cây kỹ năng, /admin (trừ trang duyệt tài khoản)🎭 MockKhông thuộc phạm vi thi
Tích hợp Discord Activity (+5 XP), API /api/integrations/discord/activity✅ Chạy thật (Dual-Mode)Ghi nhận hoạt động tự học (+5 XP/lượt) theo chuẩn kênh #activity của server AI20K Build Phase - Cohort 4. Mặc định chạy Mock Sandbox (trả về preview payload chuẩn) phục vụ chấm điểm; tự động chuyển Live khi có DISCORD_WEBHOOK_URL. 13 unit tests đạt 100%. Chi tiết: docs/feature-discord-api.md
Backend .NET (codebase/backend-core/, codebase/database/)⚠️ Chưa deployĐăng ký/duyệt tài khoản, hạn mức khách, và các endpoint ghi danh/tiến độ/chứng chỉ/thanh toán (lấy người dùng từ token, không nhận userId từ request) đã code xong. Có Dockerfile; tài khoản Railway hết hạn dùng thử nên chưa đưa lên được. Xem docs/06-backend-dotnet.md

🗂️ Cấu trúc repo

K4-3A-e403-Vinonymus/
├── README.md          ← file này (README duy nhất)
├── spec.md            ← AI Spec — rubric chấm R1–R4
├── demo-slides.pdf    ← slide 6 trang (CP5 — chưa có, nộp trước 13:00 · 18/9)
├── .github/           ← CI verify, CODEOWNERS, mẫu PR/issue
├── docs/              ← toàn bộ tài liệu dự án — xem docs/00-muc-luc.md
├── codebase/          ← prototype (Next.js app + backend .NET chưa tích hợp)
├── eval/              ← golden set + kết quả các lượt chạy (R4)
├── validation/        ← nhật ký cho người ngoài dùng thử (R6)
└── reflection/        ← mỗi thành viên 1 file

▶️ Chạy thử

Bản đã deploy:

Test nhanh API Discord Activity (+5 XP):

# Gửi activity học tập (chế độ Sandbox Preview không cần webhook secret)
curl -X POST https://k4-3a-e403-vinonymus.kailabs.io.vn/api/integrations/discord/activity \
  -H "Content-Type: application/json" \
  -d "{\"student_id\":\"HV02733\",\"action_type\":\"generate_path\",\"topic\":\"Lab 02\",\"duration_minutes\":45}"

Chạy local: cần Node.js 22+ và một API key LLM miễn phí. Nên dùng Gemini, lấy key ở Google AI Studio.

cd codebase
npm install                  # đồng thời cài hook pre-push
cp .env.example .env.local   # điền Supabase nếu cần dùng Chat; không commit file này
npm run dev                  # http://localhost:3000/personalized-path
  • API key nhập ở trang Cài đặt trong app. Key chỉ lưu trên trình duyệt (localStorage), không lưu ở server.
  • Không cần chạy backend .NET — để trống các biến *_BACKEND_CORE_URL trong .env.local thì Lộ trình cá nhân hoá vẫn mở tự do, không bắt đăng nhập.
  • Kiểm tra toàn bộ: npm run verify (lint + typecheck + test + audit + build).

Deploy Vercel: Import repo → Root Directory = codebase → Framework Next.js (tự nhận) → Deploy. Trang Lộ trình cá nhân hoá (/personalized-path) không bắt buộc biến môi trường: không có key nào thì trả gợi ý mặc định. Lưu ý nếu đặt GEMINI_API_KEY (hoặc key provider khác) trên Vercel, server sẽ dùng key đó cho mọi request không kèm key của học viên. AI Helpdesk cần NEXT_PUBLIC_SUPABASE_URL, NEXT_PUBLIC_SUPABASE_ANON_KEY, SUPABASE_SERVICE_ROLE_KEY (đặt trong Vercel, không commit).

🤝 Quy trình làm việc nhóm

  1. Nhận việc: tab Issues → Assigned to me. Mỗi issue có đúng một người phụ trách và thuộc một milestone CP.
  2. Làm trên branch riêng: feat/…, fix/…, docs/…, chore/…. Không push thẳng vào main.
  3. Mở PR theo mẫu có sẵn, ghi Closes #<số issue>. CODEOWNERS tự gán người review theo thư mục.
  4. CI verify (lint, typecheck, test, audit, build) phải xanh thì mới merge. Hook pre-push cũng chạy verify ngay trên máy.
  5. Đổi prompt thì chạy lại golden set và ghi vào eval/run_results.md. Đổi theo phản hồi người dùng thì ghi vào spec.md §9.

Quy ước code cho cả người và AI agent: AGENTS.md.

📅 Tiến độ checkpoint

"Đã nộp" = đã nộp form checkpoint đúng hạn (điều kiện lấy điểm mốc, xem 04-rubric.md). "% Issue" = tỷ lệ issue đã đóng trong milestone tương ứng — số này không tự lên 100% khi nộp form, chỉ tăng khi các task con thực sự đóng. Cập nhật tay khi đóng issue, xem số hiện tại tại Milestones.

MốcHạnTrạng thái nộp% IssueViệc
CP1 · Canvas + repo19:30 · 16/9✅ Đã nộp100% (1/1)Milestone
CP2 · Luồng hoạt động21:00 · 16/9✅ Đã nộp (mock demo trên Vercel)100% (6/6)Milestone
CP3 · Video thao tác + số đo16:00 · 17/9✅ Đã nộp (eval 19/20)100% (11/11)Milestone
CP4 · Chốt spec.md21:00 · 17/9✅ Đã nộp (khoá Quality Bar 19/20)100% (9/9)Milestone
CP5 · Slide PDF + video dự phòng13:00 · 18/9⏳ Đang làm (hạn 13:00 · 18/9)0% (0/8)Milestone
CP6 · Thuyết trình17:30 · 18/9⏳ Chiều 18/90% (0/5)Milestone

Xem thêm:

📚 Bản đồ tài liệu

Muốn biếtĐọc
Vì sao chọn bài toán này, bằng chứng, chuẩn "đạt"spec.md
Hệ thống phải làm được gì (FR/NFR/AC)docs/01-SRS.md
Kiến trúc, luồng dữ liệudocs/02-kien-truc.md
Hợp đồng API (/api/roadmap, /api/chat)docs/03-api.md
Đặc tả API & Tích hợp Discord Activity (+5 XP)docs/feature-discord-api.md
Prompt, guardrail, LLM routerdocs/04-ai-pipeline.md
Luồng người dùngdocs/05-ui-flow.md
Kế hoạch kiến trúc AI Access & BYOKdocs/07-ai-access-plan.md
Ai làm gì, hạn nàodocs/hackathon/tasks.md
Kế hoạch sửa cấu trúc repo & quy trìnhdocs/hackathon/repo-fix-plan.md
Tiến độ checkpoint, canvas CP1docs/hackathon/
Bằng chứng mining từ tin nhắn Discord & Chatlogdocs/research/evidence-mining.md
Phân tích dữ liệu khảo sát 45 học viên thậtdocs/research/survey-data-review.md
Dashboard biểu đồ khảo sát trực quan (HTML)docs/research/survey-dashboard.html
Báo cáo rà soát chất lượng 53 file FAQdocs/reports/faq-audit-report.md
Kết quả kiểm định tự động (50/50 cases = 100%)eval/run_results.md
Nhật ký người dùng ngoài thử nghiệm (R6)validation/log.md
Quy ước PR bắt buộc ở gốc repoPR.md
Sơ đồ luồng vai trò hệ thống (Mermaid)role-flow.mmd
Quy ước code cho người và AI agentAGENTS.md
Tài liệu cũ của dự án nền (không phản ánh lát cắt thi)docs/legacy/

🔒 Bảo mật dữ liệu

Repo không chứa data pack của chương trình (data/ bị chặn trong .gitignore), không chứa câu trả lời khảo sát gốc, không chứa API key. Bằng chứng chỉ ghi mã tham chiếu (M#####, T#####) và trích ngắn.


📋 Đề bài & luật thi — bản gốc từ BTC (bấm để mở)

Nhóm copy nguyên file README này về repo của mình, rồi điền bảng trên. Cột Phần việc đảm nhiệm ghi càng cụ thể càng tốt.

  • Thời lượng: 47,5 giờ từ phát đề đến thuyết trình (ca 3A) — LAB 5 (phát đề + build) · LEC 6 (tiếp tục build theo ca) · LAB 6 (vòng thi)
  • Nhóm: 3-4 người · thi theo phòng (E403 / E402), chia cụm rồi chung kết phòng — xem Thể thức thi
  • Chia cụm theo bàn, không cần chung đề tài. Chủ đề tự chọn trong khuôn khổ đề bài
  • Nhóm nhỏ thì chọn lát cắt nhỏ, và phải có khảo sát nỗi đau thật — đây là chỗ ăn điểm nặng nhất

Bắt đầu từ đâu?

  1. Đọc 01-challenge-brief.md để hiểu khung chung và 5 tiêu chí, rồi tracks/README.md để chọn track và đề.
  2. Mở 02-guide.md — hướng dẫn từng giai đoạn, đứng ở đâu đọc mục đó.
  3. Viết spec theo 03-ai-spec-template.md — deliverable trung tâm của cả sự kiện.
  4. Đọc 04-rubric.md ngay từ đầu — biết trước bài được chấm theo tiêu chí nào.
File / thư mụcNội dung
01-challenge-brief.mdĐề bài: bảng 5 track · lát cắt · ràng buộc chung · 5 tiêu chí nghiệm thu
02-guide.mdHướng dẫn 5 giai đoạn: khám phá → spec → build → đo & validate → demo
03-ai-spec-template.mdTemplate AI Spec (nộp tại hạn chốt spec — xem Lịch)
04-rubric.mdRubric 100 điểm (25 nộp checkpoint + 67 chấm bài + 8 điểm R6) + checklist xác minh 6 mốc
tracks/5 track, mỗi đề cùng một khung mục: A VLearn Tutor · B Trợ lý Discord · C Lesson Studio · D Học tập thích ứng & tương tác · E Làn mở (trong phạm vi AI20k) — bắt đầu từ tracks/README.md
data/Dữ liệu thật đã ẩn danh: vlearn-pack/ (chatlog VLearn tutor + 6 transcript bài giảng + 2 bộ slide bản hackathon) và discord-pack/ (tin nhắn Discord khoá 4 + bản tin bot) — dùng để tìm bằng chứng và xây golden set. Đọc data/README.md trước
further-reading/Tài liệu tham khảo có tóm lược tiếng Việt: Mom Test (phỏng vấn), PAIR Guidebook (Google, 6 chương), HAX Toolkit (Microsoft, 18 nguyên tắc), JTBD Playbook + worksheet — bắt đầu từ further-reading/README.md

Lịch — 6 checkpoint (ca 3A · 47,5 giờ)

MốcCần hoàn thànhHạn (ca 3A)
Khai mạc 17:30 · phát đề 18:0016/9
CP1Canvas 4 ô + đội trưởng + link repo GitHub công khai19:30 · 16/9
CP2Cho thấy luồng hoạt động — bấm thử được, hoặc sơ đồ luồng21:00 · 16/9
CP3Video thao tác 30 giây + số đo (thử bao nhiêu, đúng bao nhiêu)16:00 · 17/9
CP4Chốt spec.mdkhoá chuẩn "đạt" · tự khai phần chưa xong21:00 · 17/9
CP5Slide PDF + video demo dự phòng cho buổi pitch — nộp cuối13:00 · 18/9
CP6Thuyết trình · không nộp thêm17:30 · 18/9

CP1 đến CP5 mỗi mốc 5 điểm. Nộp đúng hạn được đủ, nộp muộn là 0 điểm mốc đó — không bù được bằng mốc khác.

Làm bài lúc nào

Thời gian tự làmNgoài giờ học, và trong buổi LEC ngày 17/9
Coach hỗ trợTrên lớp và trên Discord
Buổi LAB 18/9 · 17:30–21:00Đây là vòng thi, không phải giờ làm bài

Hai phòng cùng ca dùng chung lịch mốc. Năm link form phát đủ từ đầu — xong mốc nào nộp mốc đó, không phải chờ.

Giải thích từng mốc

CP1 · Chốt Canvas + repo

Để làm gì: chốt rõ làm cho ai và giải vấn đề gì trước khi bắt tay vào code. Bỏ qua bước này thì hay gặp cảnh làm xong mới nhận ra không ai cần đến.

Nộp:

  • Canvas điền đủ 4 ô theo mẫu trong 01-challenge-brief.md
  • Họ tên và mã học viên của đội trưởng
  • Link repo GitHub đã để công khai
  • Khai báo willing user — người sẵn sàng cho nhóm thử sản phẩm ở CP5. Cần ít nhất 2 người, khai từ đây

Khai willing user ngay từ CP1, đừng để đến CP5. Khối R6 ở CP5 yêu cầu có ít nhất 2 willing user đã khai ở mốc này. Đến lúc cần mới đi tìm người thì không kịp.


CP2 · Cho thấy luồng hoạt động

Để làm gì: nhìn được cả luồng từ đầu đến cuối — người dùng bấm gì trước, thấy gì sau, kết thúc ở đâu. Vẽ ra giấy thì phát hiện chỗ hổng trong mười phút; code xong mới thấy thì mất cả buổi sửa.

Nộp một trong ba thứ, thứ nào cũng được:

  • Bản mock bấm được — Figma, trang tĩnh, Canva, bất cứ thứ gì click qua lại được
  • Sơ đồ luồng vẽ tay hay vẽ máy, miễn thấy rõ các bước
  • Video quay màn hình đi hết một lượt

Chưa cần AI chạy thật — cái đó để CP3. Mốc này để nhẹ, chỉ cần cho thấy nhóm đang đi hướng nào.


CP3 · Video thao tác + số đo

Để làm gì: biết sản phẩm của mình đang đúng đến đâu. Có con số thì mới biết nên sửa chỗ nào tiếp, và lúc pitch cũng có cái để nói thay vì nói suông.

Nộp hai thứ:

1 · Video thao tác — 30 giây, quay màn hình. Bấm thật trên sản phẩm, thấy AI trả kết quả thật. Không cần dựng, không cần lồng tiếng.

2 · Số đo — thử bao nhiêu lần, đúng được bao nhiêu.

Đây là con số cho biết sản phẩm tốt đến đâu. Cách làm:

1. Chuẩn bị một bộ câu thử  — ví dụ 20 câu hỏi người dùng hay hỏi
2. Cho sản phẩm chạy hết 20 câu đó
3. Đếm bao nhiêu câu ra kết quả đạt chuẩn nhóm tự đặt
Chưa đạtĐạt
"Sản phẩm chạy tốt""Thử 21 câu, 13 câu trả đúng có dẫn nguồn, 8 câu sai hoặc bịa"
"Độ chính xác cao""Thử 30 file, 24 file tóm tắt đúng ý chính, 6 file bỏ sót"

Số xấu vẫn được đủ điểm — miễn là số thật. 13 trên 21 mà phân tích được vì sao 8 câu kia sai thì ăn điểm cao hơn "chạy tốt" không có gì chứng minh.


CP4 · Chốt spec.md

Để làm gì: chốt "thế nào là đạt" trước khi biết kết quả. Đặt chuẩn sau khi đã thấy kết quả thì con số không nói lên điều gì — và người nghe cũng biết vậy.

Nộp:

  • Link spec.md đã chốt — trong đó nhóm tự chốt "thế nào là đạt" cho sản phẩm mình
  • Tự khai phần nào chưa làm xong

Sau 21:00 hôm đó không sửa chuẩn "đạt" được nữa.

Khai thiếu không bị trừ điểm. Giấu mới bị.


CP5 · Slide + video dự phòng

Để làm gì: đảm bảo buổi pitch chạy được dù mạng hỏng hay máy chết. Đây cũng là hạn nộp cuối — sau mốc này không nộp thêm gì.

Nộp:

  • Slide 6 trang, xuất ra PDF theo 02-guide.md §5.1. Nộp PDF chứ không nộp link — link hay hỏng quyền đúng lúc cần
  • Video demo dự phòng — quay sẵn phần demo. Nếu hôm pitch mạng chết thì BTC chiếu video này và không trừ điểm

CP3 và CP5 là hai video khác nhau: CP3 chứng minh sản phẩm chạy — quay ngắn, quay thô cũng được. CP5 là bản sao lưu để buổi pitch không chết vì mạng — quay đúng phần định demo trên sân khấu.


CP6 · Thuyết trình

Không nộp gì. Ngày này chỉ để trình bày.

Giám khảo có thể hỏi bất kỳ thành viên nào về phần có tên người đó trong bảng phân công.

MốcForm nộp
CP1(cập nhật lúc khai mạc)
CP2(cập nhật lúc khai mạc)
CP3(cập nhật lúc khai mạc)
CP4(cập nhật lúc khai mạc)
CP5(cập nhật lúc khai mạc)

Đội trưởng nộp form thay cả nhóm — một phiếu cho cả nhóm ở mỗi mốc, không phải mỗi thành viên tự nộp. 25 điểm nộp là điểm chung của nhóm: mọi thành viên cùng được hoặc cùng mất.

⚠️ Cả 5 mốc phải nộp bằng cùng một mã học viên của đội trưởng. BTC ghép 5 phiếu của nhóm lại với nhau dựa trên mã học viên người nộp. Mốc này người A nộp, mốc kia người B nộp thì hệ thống hiểu là hai nhóm khác nhau, và nhóm mất điểm ở những mốc lệch.

Chọn đội trưởng là người chắc chắn có mặt và theo được cả năm mốc. Nếu bất khả kháng phải đổi người nộp, báo coach ngay trong buổi.

Link được công bố tại khai mạc, ghim trên Discord và đăng trên VLearn — hai nơi, cùng một bộ link.

Thể thức thi

  • 2 ca × 2 phòng = 4 cuộc thi độc lập, chấm và trao giải riêng từng phòng; mỗi phòng một tổ giám khảo. Không thi liên phòng, liên khoá.
  • E403 (~230 người): 6 cụm thi, mỗi nhóm 6 phút ở vòng cụm → 6 đội vào chung kết phòng → Top 3.
  • E402 (~120 người): 5 cụm thi, mỗi nhóm 7 phút ở vòng cụm → 5 đội vào chung kết phòng → Top 2.
  • Giám khảo có thể hỏi bất kỳ thành viên — ai cũng phải hiểu bài (vibe-coding rule).
  • Số nhóm mỗi cụm là ước tính; thể lệ chi tiết vòng cụm và chung kết công bố lúc khai mạc.

Vòng cụm — game đầu tư

Mỗi đội có 100 điểm vốn, đội trưởng đại diện xem và đầu tư. Đội nhận nhiều vốn nhất cụm đi tiếp vào chung kết phòng.

Hai luật: không được đầu tư vào đội mình · tổng phải đúng 100, thừa hoặc thiếu là phiếu không được tính.

Chia cho mấy đội là tuỳ — dồn hết vào một đội cũng được. Mẹo: trong lúc xem thì ghi số dự định ra giấy nháp, xem xong cả cụm mới cân đối lại rồi điền form.

Chung kết phòng

Sau khi chốt danh sách, các đội có 10–15 phút chuẩn bị. Thứ tự trình bày quay ngẫu nhiên tại chỗ.

Mỗi đội 10 phút: 7 phút trình bày + 3 phút hỏi đáp.

Cả phòng bình chọn — mỗi người đánh giá từng đội một cách độc lập, không giới hạn số đội được bầu.

Giải thưởng

Giải theo phòng — mỗi lớp 5 đội, hai lớp 10 đội:

LớpE403E402Tổng
3ATop 3Top 25 đội
3BTop 3Top 25 đội

Điểm thưởng cộng vào bài lab ngày 5 và ngày 6, cho mỗi thành viên:

Ai đượcCộng
Giải Nhất của phòng+10
Giải Nhì của phòng+5
Giải Ba — chỉ E403+3
Vào chung kết nhưng không có giải+2
Đội đầu tư nhiều điểm nhất và sớm nhất vào đội giải Nhất+2

Mỗi phòng E403 có 7 đội được cộng điểm, E402 có 6 đội — không chỉ riêng đội vô địch.

Dòng cuối chỉ có một đội mỗi phòng: xét điểm đầu tư cao nhất trước, bằng nhau thì lấy đội nộp phiếu sớm hơn theo dấu thời gian của form.

Giải theo track — 4 giải, chấm chung cả hai lớp:

  • Track A · VLearn Tutor và Track D · Học tập thích ứng & tương tác: 2 giải, do team VLearn chọn.
  • Track C · Lesson Studio: 2 giải, do team Studio chọn.

Hai team chấm ngay tại buổi trình bày. Một đội có thể vừa vào Top phòng vừa nhận giải track. Phần thưởng cụ thể sẽ được công bố sau.

Mỗi mốc cần show gì và được xác minh thế nào: xem bảng trong 04-rubric.md.

Nộp bài

Tạo repo mới — không fork repo đề bài

Nhóm tạo một repo hoàn toàn mới và trống. Không fork, không clone repo này rồi push lên.

Lý do: fork mang theo cả thư mục data/, mà repo nộp bài bắt buộc phải công khai — nghĩa là dữ liệu thật của khoá học sẽ lên mạng. Vi phạm thẳng điều 2 và điều 3 của quy định bảo mật bên dưới.

Nhóm chỉ cần lấy đúng một file từ repo này: 03-ai-spec-template.md, copy vào repo mình và đặt tên spec.md. Mọi thứ còn lại là tài liệu đọc, mở tại đây là đủ.

Cách đặt tên repo

K4-<mã lớp>-<phòng>-<tên nhóm>
Ví dụCủa nhóm nào
K4-3A-E403-StudyPulseLớp 3A · phòng E403 · nhóm StudyPulse
K4-3A-E402-LearnLoopLớp 3A · phòng E402 · nhóm LearnLoop

Ba phần đầu bắt buộc đúng. Phòng là phòng nhóm đang ngồi thi.

Tên nhóm ở cuối đặt gì cũng được — viết liền, không dấu, không khoảng trắng.

Repo phải để công khai. Thử mở bằng cửa sổ ẩn danh — mở được thì mới đúng. Để riêng tư là giám khảo không chấm được bài.

Cấu trúc repo

Spec chốt tại hạn chốt spec (xem Lịch); bản hoàn chỉnh trước CP6.

repo/
├── README.md          ← copy file này, điền bảng thành viên ở đầu
├── spec.md            ← AI Spec theo 03-ai-spec-template.md
├── demo-slides.pdf    ← slide 6 trang theo 02-guide.md §5.1
├── codebase/          ← prototype (ghi rõ phần nào mock)
├── eval/              ← golden set + bảng kết quả các lượt chạy
├── validation/        ← nhật ký cho người ngoài dùng thử (R6 — không làm thì trần điểm 92)
└── reflection/        ← mỗi người 1 file

README.md của nhóm

Copy nguyên file README này về repo của mình, rồi điền bảng thành viên ở đầu file. Không cần viết thêm gì khác.

Mã học viên phải đúng — đây là căn cứ đối chiếu điểm.

Chấm điểm

Tổng 100 điểm = 25 điểm nộp checkpoint + 67 điểm chấm bài nộp + 8 điểm R6 (cho người ngoài dùng thử). Chi tiết từng ý điểm: 04-rubric.md.

25 điểm nộp — mỗi checkpoint 5 điểm (CP1-CP5): nộp đúng hạn → 5 điểm · nộp muộn → 0 điểm cho mốc đó. Đội trưởng nộp thay cả nhóm — đây là điểm chung của nhóm, không phải điểm cá nhân.

67 điểm chấm + 8 điểm R6 — trên file trong repo, mỗi con điểm trỏ về một chỗ:

KhốiĐiểmChấm trên file nào
R1 · Bằng chứng & impact15spec.md §1-§2 + log khảo sát
R2 · Lát cắt & thiết kế15spec.md §4
R3 · Chỗ khó & kịch bản rủi ro11spec.md §5-§6
R4 · Kiểm thử15spec.md §7 + eval/
R5 · Prototype chạy được8codebase/ + demo
R6 · Cho người ngoài dùng thử8validation/
R7 · Quy trình & repo3cấu trúc repo

Ba khối nặng nhất — R1, R2, R4 — đều nằm trong spec.md. Viết spec tử tế là ăn 45 trên 67 điểm.

R6 · Cho người ngoài dùng thử — 8 điểm

Không làm thì trần điểm là 92. Vì 25 + 67 = 92, cộng R6 mới đủ 100.

Làm ở CP5, lưu trong thư mục validation/.

Người dùng chê cũng được tính đủ điểm. Mục đích là xem giải pháp có ăn thua không — ra kết quả nào cũng ghi nhận, miễn là bằng chứng thật. Phát hiện sản phẩm chưa ổn rồi sửa còn dễ ăn điểm hơn, vì có chỗ cụ thể để nói.

Hai ví dụ thật từ kỳ trước:

Nhóm MeaterBeat phát hiện học viên non-IT lúng túng không biết bấm nút nào, AI trả lời chậm — tức là giải pháp chưa ổn. Họ thêm tooltip hướng dẫn, thêm loading spinner, và giải trình phần độ trễ không sửa được vì phụ thuộc API. Đủ điểm.

Nhóm VLearn Recall phát hiện đúng như giả định: người ta nhớ chủ đề nhưng không nhớ nằm ở slide hay bài giảng — tức là giải pháp đi đúng hướng. Họ giữ nguyên thiết kế source-first và bổ sung thêm câu thử. Cũng đủ điểm.

Phải có đủ bốn thứ:

5 người ngoài nhóm dùng thửtrong đó 2 người đã khai từ CP1
Quote nguyên vănchép đúng lời họ nói, kể cả viết sai chính tả
Bảng nhật kýai thử · giao task gì · kẹt ở đâu · quote · quyết định
Ít nhất 1 thay đổighi vào §9 Changelog trong spec.md. Giữ nguyên thì nói rõ vì sao

Cuối bảng viết 4 dòng: chủ đề lặp nhiều nhất · sẽ sửa gì trước demo · giữ nguyên gì và vì sao · gì để dành sau.

Quote thế nào mới ăn điểm:

Chưa đạtĐạt
"Demo này ok rồi đấy""Mình muốn tìm thông tin về code cho ReAct"

Bên trái là lời khen xã giao. Bên phải là lời người dùng nói lúc đang cố làm việc — nhìn vào biết ngay họ vướng ở đâu.

Muốn có quote như vậy: giao task rồi ngồi im xem họ làm, đừng hỏi "sản phẩm này hay không".

Ba điều nên biết trước khi làm:

  • Điểm dựa trên chuỗi quyết định và bằng chứng, không dựa trên mức độ hoành tráng của sản phẩm.
  • Kết quả đo ghi nhận trung thực — kể cả khi không đạt mục tiêu nhóm tự đặt — vẫn được tính đủ điểm. Số liệu bị chỉnh sửa hoặc che giấu sẽ không được tính.
  • Reflection cá nhân chấm riêng theo rubric của khoá. Điểm vòng demo, chấm chéo trong cụm và thưởng thêm (nếu có) theo thể lệ công bố lúc khai mạc.

Luật chung

  1. Prototype có 3 mức Sketch / Mock / Working — mức nào cũng bắt buộc ≥1 lời gọi AI chạy thật. Đây là thứ phải thấy được trong video thao tác ở CP3.
  2. Vibe-coding rule: dùng AI để build thoải mái, nhưng không giải thích được phần có tên mình thì phần đó 0 điểm (giám khảo hỏi bất kỳ thành viên khi thuyết trình).
  3. Quality bar chốt tại hạn chốt spec (21:00 17/9, tại CP4) và giữ nguyên sau đó.
  4. Chỉ dùng dữ liệu trong data/ hoặc dữ liệu giả tự sinh — không dùng dữ liệu thật của người thật. Không commit API key.
  5. Tuân thủ quy định bảo mật dữ liệu bên dưới — đây là điều kiện để được cấp data.

Bảo mật dữ liệu được cung cấp

Dữ liệu trong data/ là dữ liệu thật của khoá học (đã ẩn danh), cấp riêng cho hackathon này. Khi nhận data, nhóm cam kết:

  1. Chỉ dùng trong phạm vi hackathon — cho việc tìm bằng chứng, xây golden set và build prototype. Không dùng cho mục đích khác.
  2. Không chia sẻ ra ngoài khoá học — không đăng lên mạng xã hội, không gửi cho người ngoài, không đưa vào bất kỳ dataset hay repo công khai nào.
  3. Không commit data pack vào repo nộp bài — repo nhóm chỉ chứa trích dẫn ngắn để minh hoạ (vài dòng); golden set trích từ data ghi rõ mã đoạn/mã hội thoại thay vì dán nguyên văn dài.
  4. Cẩn trọng khi đưa data vào công cụ ngoài — chỉ đưa phần tối thiểu cần cho việc đang làm; lưu ý API/công cụ free tier có thể dùng dữ liệu để huấn luyện (xem 02-guide.md §3.4).
  5. Không cố suy ngược danh tính từ dữ liệu đã ẩn danh (S####, T#####, D####, [HV], [học viên]). Riêng discord-pack/: người trong đó là bạn cùng khoá — tuyệt đối không đoán/hỏi "tin này của ai"; trích dẫn tối đa 2 câu mỗi ví dụ (xem data/discord-pack/README.md).
  6. Sau sự kiện, xoá các bản sao data pack khỏi máy cá nhân và các công cụ đã upload nếu ban tổ chức yêu cầu.

Vi phạm được xử lý theo quy định của khoá và có thể ảnh hưởng trực tiếp đến điểm của nhóm.

Contributors

Dokhacgiakhoa

65 commits

jansulubituu

2 commits

Languages

TypeScript

88.6%

Python

5.5%

C#

2.9%

HTML

1.2%