Cách frontend vận hành

Frontend là ứng dụng Next.js App Router, dùng React, TypeScript, Tailwind và Zustand. Nó sở hữu trải nghiệm và state UI; backend là nguồn sự thật cho mọi điểm chẩn đoán, ưu tiên và cho lịch học — thuật toán xếp lịch không còn nằm ở browser.

1. Source map

2. Route model

Trang diagnostic/explain thuộc luồng legacy và không phải Agent 2 hiện hành.

Ngoài luồng trên còn có /login, /register, /dashboard/onboarding, /dashboard/history, /dashboard/feedback, khu /admin và /docs — bộ tài liệu này, phục vụ ngay trong cùng một deployment thay vì một app riêng.

3. API boundary

frontend/src/lib/api/ là biên gọi FastAPI:

• gắn Bearer token nếu có;
• áp timeout;
• parse lỗi validation;
• giữ wire types cho diagnostic/priority/study;
• không tính lại server score.

4. State ownership

5. Scoped persistence — lưu theo phạm vi

• Guest có ID ẩn danh trong localStorage.
• User đăng nhập dùng user.id làm scope.
• Khi đổi scope, store không được trộn state của guest với user khác.
• Pending diagnostic question được resume từ server, không tin bản sao local.

6. Diagnostic UI rules

• Raw 1–3: hiển thị not_assessed, không suy mastery.
• Raw 4–5: mở verification screen.
• next_question=null: đọc status trước khi kết luận.
• mastery=null: UI không gắn nhãn yếu/mạnh dựa trên số sao.
• Disclaimer phải được hiển thị cùng kết quả.

7. Priority & Planner

Frontend nhận PrioritySetResponse và giữ riêng:

• priority_items;
• capacity_contexts;
• ranking_explanations;
• warnings/disclaimer.

Lịch học do backend tính: frontend dựng PlanScheduleRequest bằng buildPlanScheduleRequest, gọi POST /api/v1/plan/schedule qua frontend/src/lib/api/plan.ts, rồi đổi response thành view bằng planToScheduleDays. generateSchedule còn lại trong planner.ts chỉ là roadmap mẫu tĩnh của onboarding, không phải allocator thứ hai. Không dựng lại thuật toán xếp lịch ở browser: một Priority Set chỉ được cho ra một lịch. Công thức Planner được mô tả tại Temporal Planner.

8. Study Workspace

Các view:

• document;
• mind map;
• flashcards;
• quiz.

Frontend có rich pre-built dataset làm fallback. Backend có thể trả content cache hoặc sinh bằng RAG + LLM.

9. Validation commands

cd frontend
npm run typecheck
npm run lint
npm run test:run
npm run validate:docs
npm run test:docs
npm run build
npm run test:e2e

Unit/component tests kiểm tra contract và logic UI. validate:docs kiểm tra frontmatter và liên kết của content/docs/; test:docs chạy hai test tooling bằng node --test (chúng nằm ngoài Vitest run). E2E sử dụng API mock nên không thay thế integration test thật với FastAPI/PostgreSQL.

10. Thuật ngữ

• App Router — bộ định tuyến ứng dụng: mô hình route theo thư mục của Next.js.
• State ownership — quyền sở hữu trạng thái: lớp nào có quyền tạo/sửa một giá trị.
• Hydration — khôi phục state: nạp state đã persist khi app chạy ở browser.
• Wire contract — hợp đồng truyền qua mạng: kiểu JSON giữa frontend và backend.
• Fallback dataset — dữ liệu dự phòng: nội dung dùng khi backend không sẵn sàng.