aplp.frontend.web/README.md

# aplp.frontend.react

Frontend (React) cho **APLP — Adaptive Personal Learning Platform** (learner application `aplp-web`).

React 19 + TypeScript + Vite · Client mỏng (thin client) gọi API của backend `aplp.backend.web`. Frontend **không** chứa business rules; mọi quyết định domain (mastery, progress, adaptive) đến từ backend.

## Stack

| Lĩnh vực | Công nghệ |
| --- | --- |
| Framework | React 19 |
| Language | TypeScript |
| Build | Vite 8 |
| Routing | React Router 7 |
| HTTP client | Axios (wrapper tại `src/api`) |
| Server-state | TanStack Query |
| Client-state | Zustand |
| Styling | Tailwind CSS 4 |
| Lint | oxlint |
| Format | Prettier |
| Test | Vitest + Testing Library |

## Quick Start

Prerequisite: Node.js 18+ (LTS khuyến nghị).

```bash
npm install
cp .env.example .env   # chỉnh VITE_API_BASE_URL nếu cần
npm run dev            # mở địa chỉ Vite (mặc định http://localhost:5173)
```

Backend chạy local để API hoạt động (xem `docs/SETUP.md`).

## Scripts

| Lệnh | Mô tả |
| --- | --- |
| `npm run dev` | Dev server (Vite) |
| `npm run build` | Typecheck + production build |
| `npm run preview` | Preview production build |
| `npm run lint` | Lint (oxlint) |
| `npm run format` / `format:check` | Format bằng Prettier |
| `npm run typecheck` | Typecheck (tsc) |
| `npm test` / `test:watch` | Unit test (Vitest) |

## Structure

```text
src/
├── app/           # app entry, router, providers, layout, pages
├── api/           # api client (axios), token storage
├── features/      # feature modules (auth, learner, course, ...)
│   └── auth/      #   api, components, hooks, pages, store
├── shared/        # shared components, hooks, config
└── types/         # shared types / DTO contracts
```

Chi tiết: [docs/ARCHITECTURE.md](./docs/ARCHITECTURE.md), [docs/CONVENTIONS.md](./docs/CONVENTIONS.md).

## Auth Flow

- Access token lưu **in-memory** (`src/api/tokenStorage.ts`), không persist vào storage trình duyệt.
- Refresh token do backend quản lý (HttpOnly cookie); client không chạm tới.
- `401` → api client tự gọi `/auth/refresh` rồi retry request gốc (không loop trên endpoint auth).
- Route bảo vệ qua `ProtectedRoute` (redirect `/login` nếu chưa đăng nhập).

Chi tiết: [docs/PHASES.md](./docs/PHASES.md) (Phase 0).

## Documents

| Tài liệu | Mô tả |
| --- | --- |
| [docs/PHASES.md](./docs/PHASES.md) | Công việc frontend theo từng phase APLP |
| [docs/ARCHITECTURE.md](./docs/ARCHITECTURE.md) | Kiến trúc: folder structure, data flow, auth |
| [docs/CONVENTIONS.md](./docs/CONVENTIONS.md) | Coding conventions |
| [docs/SETUP.md](./docs/SETUP.md) | Setup / khởi tạo dự án |

Backend: [aplp.backend.spring](../aplp.backend.spring) — kế hoạch phase tổng thể: [APLP-Project-Phases.md](../aplp.backend.spring/APLP-Project-Phases.md).

## Status

Phase 0 (Foundation) — hoàn tất. Xem danh sách completion criteria tại [docs/PHASES.md](./docs/PHASES.md).