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.
Adaptive Learning System cho học viên Khoá 4, gồm 2 AI:
| AI | Người dùng có trò chuyện không? | Làm gì | Hiện ra ở đâu | Vai trò trong cuộc thi |
|---|
| AI Mentor | Khô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 /learning-path | Phần được chấm (demo scope) là tính năng này, theo spec.md |
| AI Helpdesk | Có. Là AI duy nhất người dùng nói chuyện | Tra cứu, giải đáp về tài liệu và lộ trình học, có trích dẫn nguồn | Chatbox (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 Mentor | Trạ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 |
| 3 | Phâ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 |
| 4 | Phâ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):
- Học viên chọn nền tảng của mình (non-tech, tech-base hoặc đã học AI).
- Học viên cho biết hôm nay rảnh bao nhiêu phút và bài lab tiếp theo là gì.
- 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.
- 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ên | Mã Học Viên | Vai trò chính | GitHub | Phần việc đảm nhiệm trong dự án | Việc được giao |
|---|
| Đỗ Khắc Gia Khoa (đội trưởng) | 02733 | PM · Backend · Giao diện Student/Viewer | @Dokhacgiakhoa | Chố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 Minh | 02483 | Database | @minh-tran-2611 | Backend/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 Đức | 02935 | AI Helpdesk · Giao diện Admin/Lecturer | @dinhngocduc1311 | Thiế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 ro | Issues |
| Nguyễn Việt Thành | 02924 | AI Mentor | @thanhnvhust514 | Giao 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 CP5 | Issues |
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.
Từ 18/9 phân vai lại để xây hệ thống 4 vai trò — Khoa làm backend .NET và giao diện Student/Viewer, Minh làm database, Đức làm AI Helpdesk và giao diện Admin/Lecturer, Thành làm AI Mentor. Mỗi vai trò có giao diện riêng. Danh sách task: docs/hackathon/tasks-he-thong-4-vai-tro.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ắc | Thể hiện trong sản phẩm |
|---|
| Giải thích được | Mỗi việc có một dòng lý do và link nguồn |
| Người dùng quyết định cuối | Checklist tick, bỏ, đổi thứ tự được; AI không tự làm thay |
| Biết mình không biết | Dướ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 vi | Chỉ 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ệ thống có 4 vai trò. Ai đăng nhập bằng tài khoản nào thì thấy luồng của vai trò đó.
| # | Vai trò | Là ai | Vào được gì | Tình trạng |
|---|
| 1 | Viewer — khách chưa đăng nhập | Người lạ vừa mở web | Xem trang giới thiệu, danh mục lab; hỏi AI Helpdesk ở chatbox, tối đa 10 câu/ngày. Không mở được Lộ trình cá nhân hoá | ✅ Đã làm |
| 2 | Student — học viên đã đăng nhập | Học viên Khoá 4, tài khoản đã được duyệt | Hỏi AI Helpdesk không giới hạn + dùng Lộ trình cá nhân hoá (/learning-path) | ✅ Đã làm (phần được chấm nằm ở đây) |
| 3 | Lecturer — giảng viên | Người soạn giáo trình | Tải tài liệu lên để AI Mentor đọc vào thư viện tài liệu | ❌ Chưa có giao diện. Vai trò Lecture mới có trong backend; thư viện hiện do nhóm soạn tay trong planner-catalog.ts |
| 4 | Admin | Nhóm Vinonymus | Duyệt tài khoản đăng ký mới tại /admin/approvals (đồng ý / từ chối) | ⚠️ Giao diện xong, chờ deploy backend |
Vì sao phải chờ duyệt: đăng ký xong không được đăng nhập ngay. Tài khoản ở trạng thái chờ duyệt cho tới khi Admin bấm đồng ý. Mục đích là giữ AI Helpdesk miễn phí làm cửa mở cho người lạ, còn phần tốn tiền gọi AI thì chỉ mở cho người thật.
Lưu ý khi chạy thử: việc bắt đăng nhập chỉ bật khi đã khai báo địa chỉ backend (NEXT_PUBLIC_BACKEND_CORE_URL). Backend .NET chưa deploy, nên web thật hiện chạy mở — ai vào cũng dùng được như Student. Xem Trạng thái prototype.
flowchart TD
V([Mở web]) --> Q{Đã đăng nhập chưa?}
Q -- Chưa --> V1[1 · VIEWER<br/>Xem trang giới thiệu, danh mục lab<br/>Hỏi AI Helpdesk · 10 câu/ngày]
V1 --> V2{Muốn dùng Lộ trình cá nhân hoá?}
V2 -- Có --> V3[Đăng ký tài khoản] --> V4[Chờ Admin duyệt] --> A2
V2 -- Không --> V1
Q -- Rồi --> R{Vai trò}
R -- Student --> S1[2 · STUDENT<br/>AI Helpdesk không giới hạn<br/>+ Lộ trình cá nhân hoá] --> S2
R -- Lecturer --> L1[3 · LECTURER<br/>Tải tài liệu lên<br/>chưa có giao diện] -.- L2[AI Mentor đọc tài liệu<br/>vào thư viện]
R -- Admin --> A1[4 · ADMIN<br/>/admin/approvals]
A1 --> A2{Duyệt tài khoản mới} -- Đồng ý --> S1
A2 -- Từ chối --> X([Không đăng nhập được])
L2 -.-> S2[Lộ trình lấy tài liệu từ thư viện]
Sơ đồ chi tiết ở mức API cho cả 4 vai trò: role-flow.mmd.
Luồng Student — phần được chấm
Đây là luồng được demo và chấm điểm. Học viên mở Lộ trình cá nhân hoá tại /learning-path. 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ở /learning-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ống | Học viên thấy gì |
|---|
| Đủ thông tin | Dò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ảng | Mộ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ạng | Kế 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ị)
Ngoài việc duyệt tài khoản ở /admin/approvals (xem bảng vai trò bên trên), phần quản trị còn lại — thêm bài lab, sửa link tài liệu, sửa prompt — nhóm làm trực tiếp trên repo chứ chưa có giao diện. Các trang /admin khác là màn hình tĩnh của dự án nền, không dùng trong demo.
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ệc | Ai 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 | Đức | codebase/src/lib/prompts/, docs/04-ai-pipeline.md |
| Chạy eval sau mỗi lần đổi prompt hoặc catalog | Đức | eval/run_results.md |
| Ghi nhận phản hồi, quyết định thay đổi | Khoa | validation/log.mdspec.md §9 |
| Deploy | Web thật chỉ cập nhật khi merge vào nhánh production (mở PR main → production). 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/>/learning-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ớp | Công nghệ | Trạng thái |
|---|
| Frontend | Next.js 15 (App Router) · React 19 · TypeScript (strict) · Tailwind CSS 3 · lucide-react · GSAP · PWA | Đang chạy |
| AI | LLM 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ều | AI Mentor (/learning-path) và API của AI Helpdesk (/api/chat): chạy thật |
| Dữ liệu | Supabase 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ộng | Discord 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ử & CI | Vitest · 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ần | Trạng thái | Ghi chú |
|---|
Lộ trình cá nhân hoá (phần được chấm, do AI Mentor thực hiện), trang /learning-path | ✅ AI chạy thật | Luồ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") | 🎭 Mock | Quy 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ật | Gử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ật | Khá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 |
🗂️ 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/learning-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á (/learning-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
- 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.
- Làm trên branch riêng:
feat/…, fix/…, docs/…, chore/…. Không push thẳng vào main.
- Mở PR theo mẫu có sẵn, ghi
Closes #<số issue>. CODEOWNERS tự gán người review theo thư mục.
- 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.
- Đổ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ốc | Hạn | Trạng thái nộp | % Issue | Việc |
|---|
| CP1 · Canvas + repo | 19:30 · 16/9 | ✅ Đã nộp | 100% (1/1) | Milestone |
| CP2 · Luồng hoạt động | 21:00 · 16/9 | ✅ Đã nộp (mock demo trên Vercel) | 100% (6/6) | Milestone |
| CP3 · Video thao tác + số đo | 16:00 · 17/9 | ✅ Đã nộp (eval 19/20) | 100% (11/11) | Milestone |
CP4 · Chốt spec.md | 21:00 · 17/9 | ✅ Đã nộp (khoá Quality Bar 19/20) | 100% (9/9) | Milestone |
| CP5 · Slide PDF + video dự phòng | 13:00 · 18/9 | ⏳ Đang làm (hạn 13:00 · 18/9) | 0% (0/8) | Milestone |
| CP6 · Thuyết trình | 17:30 · 18/9 | ⏳ Chiều 18/9 | 0% (0/5) | Milestone |
Xem thêm:
📚 Bản đồ tài liệu
🔒 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.
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?
- Đọc
01-challenge-brief.md để hiểu khung chung và 5 tiêu chí, rồi tracks/README.md để chọn track và đề.
- Mở
02-guide.md — hướng dẫn từng giai đoạn, đứng ở đâu đọc mục đó.
- Viết spec theo
03-ai-spec-template.md — deliverable trung tâm của cả sự kiện.
- Đọ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ục | Nộ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.md | Hướng dẫn 5 giai đoạn: khám phá → spec → build → đo & validate → demo |
03-ai-spec-template.md | Template AI Spec (nộp tại hạn chốt spec — xem Lịch) |
04-rubric.md | Rubric 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ốc | Cần hoàn thành | Hạn (ca 3A) |
|---|
| — | Khai mạc 17:30 · phát đề 18:00 | 16/9 |
| CP1 | Canvas 4 ô + đội trưởng + link repo GitHub công khai | 19:30 · 16/9 |
| CP2 | Cho thấy luồng hoạt động — bấm thử được, hoặc sơ đồ luồng | 21:00 · 16/9 |
| CP3 | Video thao tác 30 giây + số đo (thử bao nhiêu, đúng bao nhiêu) | 16:00 · 17/9 |
| CP4 | Chốt spec.md — khoá chuẩn "đạt" · tự khai phần chưa xong | 21:00 · 17/9 |
| CP5 | Slide PDF + video demo dự phòng cho buổi pitch — nộp cuối | 13:00 · 18/9 |
| CP6 | Thuyết trình · không nộp thêm | 17: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àm | Ngoà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.
Link nộp
| Mốc | Form 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ớp | E403 | E402 | Tổng |
|---|
| 3A | Top 3 | Top 2 | 5 đội |
| 3B | Top 3 | Top 2 | 5 độ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 được | Cộ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-StudyPulse | Lớp 3A · phòng E403 · nhóm StudyPulse |
K4-3A-E402-LearnLoop | Lớ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ểm | Chấm trên file nào |
|---|
| R1 · Bằng chứng & impact | 15 | spec.md §1-§2 + log khảo sát |
| R2 · Lát cắt & thiết kế | 15 | spec.md §4 |
| R3 · Chỗ khó & kịch bản rủi ro | 11 | spec.md §5-§6 |
| R4 · Kiểm thử | 15 | spec.md §7 + eval/ |
| R5 · Prototype chạy được | 8 | codebase/ + demo |
| R6 · Cho người ngoài dùng thử | 8 | validation/ |
| R7 · Quy trình & repo | 3 | cấ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ăn | ché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 đổi | ghi 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
- 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.
- 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).
- Quality bar chốt tại hạn chốt spec (21:00 17/9, tại CP4) và giữ nguyên sau đó.
- 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.
- 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:
- 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.
- 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.
- 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.
- 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).
- 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).
- 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.
