# 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** |