mirror of
https://github.com/handsomezhuzhu/QQuiz.git
synced 2026-04-18 14:32:54 +00:00
71 lines
1.7 KiB
Markdown
71 lines
1.7 KiB
Markdown
# Frontend Migration Plan
|
|
|
|
## Decision
|
|
|
|
The legacy Vite SPA remains in `frontend/` as a fallback.
|
|
|
|
The new frontend is being built in `web/` with:
|
|
|
|
- Next.js App Router
|
|
- TypeScript
|
|
- Tailwind CSS
|
|
- shadcn/ui component model
|
|
|
|
The abandoned ESA captcha integration has been removed from the legacy login page.
|
|
|
|
## Why a Rewrite Instead of an In-Place Port
|
|
|
|
The legacy frontend mixes too many browser-only assumptions into core runtime
|
|
boundaries:
|
|
|
|
- token storage in `localStorage`
|
|
- `window.location` redirects inside transport code
|
|
- client-only route protection
|
|
- SSE token passing in query strings
|
|
|
|
Those patterns do not map cleanly onto Next App Router and server-first auth.
|
|
|
|
## New Runtime Model
|
|
|
|
### Auth
|
|
|
|
- Login goes through Next route handlers
|
|
- Backend JWT is stored in an `HttpOnly` cookie
|
|
- Browser code never reads the raw token
|
|
|
|
### Data
|
|
|
|
- Server pages use server-side fetch helpers
|
|
- Client mutations use browser-side fetch helpers against Next proxy routes
|
|
- URL state is used for pagination and filters
|
|
|
|
### Streaming
|
|
|
|
- Browser connects to a same-origin Next progress route
|
|
- The route reads the session cookie and proxies backend SSE
|
|
- Backend URL tokens are hidden from the browser
|
|
|
|
## Directory Map
|
|
|
|
```text
|
|
web/
|
|
src/app/
|
|
src/components/
|
|
src/lib/
|
|
src/middleware.ts
|
|
```
|
|
|
|
## Migration Order
|
|
|
|
1. Auth shell, layouts, middleware, and proxy routes
|
|
2. Dashboard, exams list, questions list, and admin overview
|
|
3. Exam detail upload and progress streaming
|
|
4. Quiz and mistake-practice flows
|
|
5. Cutover, smoke testing, and legacy frontend retirement
|
|
|
|
## Non-Goals for This First Slice
|
|
|
|
- No immediate removal of the legacy `frontend/`
|
|
- No backend contract rewrite yet
|
|
- No server actions as the primary data mutation layer
|