feat: add guide

2026-08-22 08:24:38 +07:00
parent dd9ed73a02
commit 271fdb2521
6 changed files with 1310 additions and 0 deletions
@@ -0,0 +1,222 @@
+# APLP Frontend (React) — Phases
+
+| | |
+| --- | --- |
+| **Module** | `aplp.frontend.react` |
+| **Role** | Web application cho learner (`aplp-web`) |
+| **Status** | Draft |
+| **Backend** | `aplp.backend.spring` (Java/Spring Boot) |
+
+Frontend triển khai theo các phase của [APLP-Project-Phases](../../aplp.backend.spring/APLP-Project-Phases.md). Document này ánh xạ từng phase sang công việc frontend.
+
+> Nguyên tắc: frontend là client mỏng (thin client), gọi API của backend. Frontend **không** chứa business rules của domain; chỉ chứa UX/UI logic.
+
+---
+
+## 1. Phase 0 — Foundation (Frontend)
+
+### Objective
+
+Dựng khung ứng dụng, auth flow, routing, chuẩn hóa giao tiếp API với backend.
+
+> ✅ Phase 0 hoàn tất. Stack đã confirm (Vite, React 19, TS, React Router, axios, React Query, Zustand, Tailwind). Auth flow + api client + ProtectedRoute đang hoạt động.
+
+### Features
+
+| Feature | Priority |
+| --- | --- |
+| Khởi tạo React app (Vite \[candidate\] + TypeScript) | Must |
+| Routing (react-router) | Must |
+| Auth flow: login/logout/refresh + token storage | Must |
+| API client layer (axios/fetch wrapper, error handling) | Must |
+| Layout/App shell & ProtectedRoute | Must |
+| Theme & UI base (candidate: Tailwind / component lib) | Should |
+| State management base (candidate: Zustand/React Query) | Should |
+| Environment config (`VITE_*`) | Must |
+
+### Completion Criteria
+
+- Đăng nhập/đăng xuất chạy được, token quản lý đúng, route bảo vệ hoạt động.
+- API layer chuẩn, gọi được backend local.
+
+---
+
+## 2. Phase 1 — Identity & Learner
+
+### Objective
+
+Hiển thị và cho học viên quản lý hồ sơ, preferences, learning goals.
+
+### Features
+
+| Feature | Priority |
+| --- | --- |
+| Trang hồ sơ learner (view/edit) | Must |
+| Form learning preferences | Should |
+| Quản lý learning goals (CRUD) | Should |
+
+---
+
+## 3. Phase 2 — Content & Course
+
+### Objective
+
+Browsing + chi tiết course từ content model (backend/LMS).
+
+### Features
+
+| Feature | Priority |
+| --- | --- |
+| Course catalog & search cơ bản | Must |
+| Course detail page (structure module/lesson) | Must |
+| Enroll/select course | Should |
+
+---
+
+## 4. Phase 3 — Learning Experience
+
+### Objective
+
+Trải nghiệm học từ đầu tới cuối trong UI.
+
+### Features
+
+| Feature | Priority |
+| --- | --- |
+| Player/lesson view cho learning activity | Must |
+| Start / continue / resume đúng lesson | Must |
+| Navigation giữa lessons (next/prev, course map) | Must |
+| Đánh dấu hoàn thành & feedback ngay | Must |
+| Progress thanh / module state | Should |
+
+---
+
+## 5. Phase 4 — Assessment & Progress
+
+### Objective
+
+Learner làm assessment, xem kết quả và tiến độ trong UI.
+
+### Features
+
+| Feature | Priority |
+| --- | --- |
+| Màn hình làm assessment (câu hỏi, lựa chọn) | Must |
+| Submit & hiển thị kết quả/score | Must |
+| Hiển thị learning progress & history | Must |
+| Retake flow (nếu business cho phép — OQ-005) | Should |
+
+---
+
+## 6. Phase 5 — Adaptive Learning
+
+### Objective
+
+Hiển thị learner state, mastery và hoạt động được đề xuất tiếp theo từ backend.
+
+### Features
+
+| Feature | Priority |
+| --- | --- |
+| Hiển thị mastery / knowledge state | Must |
+| Hiển thị "next activity" đề xuất | Must |
+| Prerequisite lock/unlock state trong UI | Should |
+
+> Frontend chỉ **hiển thị** giao diện theo quyết định của backend; **không** tính toán adaptive bên client.
+
+---
+
+## 7. Phase 6 — Personalization & Recommendation
+
+### Objective
+
+Hiển thị các đề xuất/path được cá nhân hóa.
+
+### Features
+
+| Feature | Priority |
+| --- | --- |
+| Block "Recommended for you" | Should |
+| Personalized path view | Could |
+| Cho phép learner xác nhận/bỏ qua đề xuất | Should |
+
+---
+
+## 8. Phase 7 — Learning Assistance
+
+### Objective
+
+UI cho AI assistance: hint, explanation, Q&A, feedback (backend-driven).
+
+### Features
+
+| Feature | Priority |
+| --- | --- |
+| Hint/explanation panel trong lesson | Should |
+| Chat/Q&A box (RAG backend) | Could |
+| Feedback hiển thị sau assessment | Should |
+
+---
+
+## 9. Phase 8 — Productization
+
+### Objective
+
+UI cho subscription/plan, notification, account.
+
+### Features
+
+| Feature | Priority |
+| --- | --- |
+| Trang plan/subscription | Should |
+| Notification UI | Should |
+| Account management | Should |
+
+---
+
+## 10. Phase 9 — Scale & Evolution
+
+### Objective
+
+Performance, caching client, observability.
+
+### Features
+
+| Feature | Priority |
+| --- | --- |
+| Data fetching caching (React Query) | Should |
+| Code splitting / lazy loading | Should |
+| Error boundary & monitoring (sentry-like) | Should |
+
+---
+
+## 11. MVP (Frontend)
+
+> **Một learner có thể dùng UI này học một course hoàn chỉnh.**
+
+MVP frontend bao gồm:
+
+```
+Auth + App shell
+ Course catalog/detail
+ Lesson player
+ Progress display
+ Assessment UI
+ (adaptive simple — optional)
+```
+
+Ngoài MVP: AI assistance, recommendation nâng cao, subscription UI.
+
+## 12. Open Questions (Frontend-specific)
+
+> Phase 0 đã confirm: Vite, TypeScript, React Router, axios, TanStack Query + Zustand, Tailwind CSS, Vitest + Testing Library, no SSR, no PWA.
+
+| ID | Question | Impact | Status |
+| --- | --- | --- | --- |
+| FE-001 | Vite hay CRA / framework khác? | Setup | **Resolved: Vite** |
+| FE-002 | TypeScript có bắt buộc? | Quality | **Resolved: có** |
+| FE-003 | Component library nào (Tailwind/MUI/etc)? | UX consistency | **Resolved: Tailwind CSS** |
+| FE-004 | State management: React Query + Zustand/Redux? | Data flow | **Resolved: React Query + Zustand** |
+| FE-005 | SSR/SSG có cần (SEO)? | Architecture | **Resolved: không cho MVP** |
+| FE-006 | I18n cho UI? | UX | Open |
+| FE-007 | Có cần PWA/offline? | UX | **Resolved: không cho MVP** |