Mini Hackathon
See the codeMini 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.
| Trang chủ hệ thống | https://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ệu | docs/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óm | Milestones theo checkpoint |
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 /personalized-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):
Mục lục
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 | @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 | BE | @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 | @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 | FE | @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.
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/):
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.
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ố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.
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ệ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 |
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)]
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.| 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 (/personalized-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:
docs/02-kien-truc.mddocs/03-api.mddocs/feature-discord-api.mddocs/04-ai-pipeline.md| 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 /personalized-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 /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ó backend | Chỉ 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) | 🎭 Mock | Khô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 |
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
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
localStorage), không lưu ở server.*_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.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).
feat/…, fix/…, docs/…, chore/…. Không push thẳng vào main.Closes #<số issue>. CODEOWNERS tự gán người review theo thư mục.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.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.
"Đã 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:
docs/hackathon/checkpoints.mddocs/hackathon/tasks.mddocs/hackathon/repo-fix-plan.md| 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ệu | docs/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 router | docs/04-ai-pipeline.md |
| Luồng người dùng | docs/05-ui-flow.md |
| Kế hoạch kiến trúc AI Access & BYOK | docs/07-ai-access-plan.md |
| Ai làm gì, hạn nào | docs/hackathon/tasks.md |
| Kế hoạch sửa cấu trúc repo & quy trình | docs/hackathon/repo-fix-plan.md |
| Tiến độ checkpoint, canvas CP1 | docs/hackathon/ |
| Bằng chứng mining từ tin nhắn Discord & Chatlog | docs/research/evidence-mining.md |
| Phân tích dữ liệu khảo sát 45 học viên thật | docs/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 FAQ | docs/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 repo | PR.md |
| Sơ đồ luồng vai trò hệ thống (Mermaid) | role-flow.mmd |
| Quy ước code cho người và AI agent | AGENTS.md |
| Tài liệu cũ của dự án nền (không phản ánh lát cắt thi) | docs/legacy/ |
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.
01-challenge-brief.md để hiểu khung chung và 5 tiêu chí, rồi tracks/README.md để chọn track và đề.02-guide.md — hướng dẫn từng giai đoạn, đứng ở đâu đọc mục đó.03-ai-spec-template.md — deliverable trung tâm của cả sự kiện.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 |
| 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.
| 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ờ.
Để 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:
01-challenge-brief.mdKhai 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.
Để 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:
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.
Để 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.
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:
spec.md đã chốt — trong đó nhóm tự chốt "thế nào là đạt" cho sản phẩm mìnhSau 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ị.
Để 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:
02-guide.md §5.1. Nộp PDF chứ không nộp link — link hay hỏng quyền đúng lúc cầnCP3 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.
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ố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.
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.
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 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:
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.
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à đủ.
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.
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
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.
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.
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:
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.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:
02-guide.md §3.4).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).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.
TypeScript
88.6%
Python
5.5%
C#
2.9%
HTML
1.2%
Mini Hackathon
See the codeMini 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.
| Trang chủ hệ thống | https://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ệu | docs/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óm | Milestones theo checkpoint |
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 /personalized-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):
Mục lục
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 | @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 | BE | @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 | @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 | FE | @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.
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/):
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.
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ố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.
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ệ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 |
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)]
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.| 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 (/personalized-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:
docs/02-kien-truc.mddocs/03-api.mddocs/feature-discord-api.mddocs/04-ai-pipeline.md| 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 /personalized-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 /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ó backend | Chỉ 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) | 🎭 Mock | Khô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 |
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
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
localStorage), không lưu ở server.*_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.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).
feat/…, fix/…, docs/…, chore/…. Không push thẳng vào main.Closes #<số issue>. CODEOWNERS tự gán người review theo thư mục.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.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.
"Đã 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:
docs/hackathon/checkpoints.mddocs/hackathon/tasks.mddocs/hackathon/repo-fix-plan.md| 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ệu | docs/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 router | docs/04-ai-pipeline.md |
| Luồng người dùng | docs/05-ui-flow.md |
| Kế hoạch kiến trúc AI Access & BYOK | docs/07-ai-access-plan.md |
| Ai làm gì, hạn nào | docs/hackathon/tasks.md |
| Kế hoạch sửa cấu trúc repo & quy trình | docs/hackathon/repo-fix-plan.md |
| Tiến độ checkpoint, canvas CP1 | docs/hackathon/ |
| Bằng chứng mining từ tin nhắn Discord & Chatlog | docs/research/evidence-mining.md |
| Phân tích dữ liệu khảo sát 45 học viên thật | docs/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 FAQ | docs/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 repo | PR.md |
| Sơ đồ luồng vai trò hệ thống (Mermaid) | role-flow.mmd |
| Quy ước code cho người và AI agent | AGENTS.md |
| Tài liệu cũ của dự án nền (không phản ánh lát cắt thi) | docs/legacy/ |
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.
01-challenge-brief.md để hiểu khung chung và 5 tiêu chí, rồi tracks/README.md để chọn track và đề.02-guide.md — hướng dẫn từng giai đoạn, đứng ở đâu đọc mục đó.03-ai-spec-template.md — deliverable trung tâm của cả sự kiện.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 |
| 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.
| 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ờ.
Để 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:
01-challenge-brief.mdKhai 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.
Để 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:
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.
Để 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.
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:
spec.md đã chốt — trong đó nhóm tự chốt "thế nào là đạt" cho sản phẩm mìnhSau 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ị.
Để 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:
02-guide.md §5.1. Nộp PDF chứ không nộp link — link hay hỏng quyền đúng lúc cầnCP3 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.
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ố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.
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.
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 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:
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.
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à đủ.
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.
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
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.
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.
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:
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.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:
02-guide.md §3.4).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).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.
TypeScript
88.6%
Python
5.5%
C#
2.9%
HTML
1.2%