mirror of
https://github.com/handsomezhuzhu/QQuiz.git
synced 2026-04-18 22:42:53 +00:00
refactor: remove legacy frontend code and implement new Next.js structure
- Deleted the old Register page and utility functions. - Removed Tailwind CSS configuration and Vite configuration files. - Added a new script for starting a single container with FastAPI and Next.js. - Updated README to reflect the current status of the Next.js frontend. - Implemented new login and registration API routes with improved error handling. - Refactored frontend API calls to use the new proxy structure. - Enhanced error handling in API response processing. - Updated components to align with the new API endpoints and structure.
This commit is contained in:
@@ -19,17 +19,17 @@ Audit date: 2026-04-17
|
||||
|
||||
### Frontend
|
||||
|
||||
- Runtime: React 18 + Vite SPA
|
||||
- Routing: `react-router-dom`
|
||||
- Auth state: client-only `localStorage` token + context
|
||||
- API transport: axios interceptor with browser redirects
|
||||
- Styling: Tailwind CSS with page-local utility classes
|
||||
- Runtime: Next.js App Router + TypeScript
|
||||
- Routing: file-system routing + middleware guards
|
||||
- Auth state: `HttpOnly` cookie managed by Next route handlers
|
||||
- API transport: server/client fetch helpers with same-origin proxy routes
|
||||
- Styling: Tailwind CSS + shadcn/ui patterns
|
||||
|
||||
### Deployment
|
||||
|
||||
- `docker-compose.yml`: development-oriented split stack
|
||||
- `docker-compose-single.yml`: monolith container with SQLite
|
||||
- `Dockerfile`: FastAPI serves the built SPA as static assets
|
||||
- `docker-compose.yml`: split development stack
|
||||
- `docker-compose-single.yml`: default single-container deployment
|
||||
- `Dockerfile`: single image running FastAPI + embedded Next.js
|
||||
|
||||
## Target Architecture
|
||||
|
||||
@@ -51,20 +51,20 @@ Audit date: 2026-04-17
|
||||
|
||||
### Deployment
|
||||
|
||||
- Split deployment becomes the primary production shape
|
||||
- Monolith mode remains secondary compatibility mode
|
||||
- Development and production Compose files must be separated
|
||||
- Single-container deployment is the primary release path
|
||||
- Split deployment remains available for development and compatibility testing
|
||||
- Development and production Compose files must stay explicitly separated
|
||||
|
||||
## Core Constraints
|
||||
|
||||
1. Do not overwrite existing uncommitted user changes in the legacy frontend.
|
||||
2. Keep the legacy `frontend/` app available until the new `web/` app reaches functional parity.
|
||||
3. Preserve backend API contracts where possible during the frontend migration.
|
||||
4. Fix deployment/documentation drift before treating new frontend work as production-ready.
|
||||
1. Preserve backend API contracts where possible across frontend changes.
|
||||
2. Keep single-container and split-stack behavior aligned on the same `web/` frontend.
|
||||
3. Fix deployment/documentation drift before treating changes as production-ready.
|
||||
4. Avoid reintroducing duplicate frontend implementations.
|
||||
|
||||
## Immediate Workstreams
|
||||
|
||||
1. Remove abandoned ESA captcha wiring from the legacy frontend.
|
||||
2. Write audit documents and freeze the migration backlog.
|
||||
3. Scaffold the new `web/` frontend without disturbing the legacy app.
|
||||
4. Fix first-order deployment issues such as health checks and documented mount paths.
|
||||
1. Keep single-container delivery using the same `web/` frontend as split deployment.
|
||||
2. Continue moving backend orchestration into typed services.
|
||||
3. Tighten health checks and deployment docs around the embedded Next runtime.
|
||||
4. Cover remaining functional gaps with smoke tests.
|
||||
|
||||
@@ -1,70 +1,50 @@
|
||||
# Frontend Migration Plan
|
||||
# Frontend Cutover Notes
|
||||
|
||||
## Decision
|
||||
|
||||
The legacy Vite SPA remains in `frontend/` as a fallback.
|
||||
`web/` is now the only frontend in the repository.
|
||||
|
||||
The new frontend is being built in `web/` with:
|
||||
The previous Vite SPA has been removed so that:
|
||||
|
||||
- Next.js App Router
|
||||
- TypeScript
|
||||
- Tailwind CSS
|
||||
- shadcn/ui component model
|
||||
- split deployment and single-container deployment use the same UI
|
||||
- documentation no longer has to describe two competing frontend stacks
|
||||
- future frontend changes only need to be implemented once
|
||||
|
||||
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
|
||||
## Runtime Model
|
||||
|
||||
### Auth
|
||||
|
||||
- Login goes through Next route handlers
|
||||
- Login goes through Next route handlers under `/frontend-api/auth/*`
|
||||
- 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
|
||||
- Server pages use server-side fetch helpers against FastAPI
|
||||
- Client mutations use browser-side fetch helpers against `/frontend-api/proxy/*`
|
||||
- FastAPI continues to own the public `/api/*` surface
|
||||
|
||||
### Streaming
|
||||
|
||||
- Browser connects to a same-origin Next progress route
|
||||
- Browser connects to `/frontend-api/exams/{examId}/progress`
|
||||
- The route reads the session cookie and proxies backend SSE
|
||||
- Backend URL tokens are hidden from the browser
|
||||
- Backend token query parameters stay hidden from the browser
|
||||
|
||||
## Directory Map
|
||||
## Deployment Outcome
|
||||
|
||||
```text
|
||||
web/
|
||||
src/app/
|
||||
src/components/
|
||||
src/lib/
|
||||
src/middleware.ts
|
||||
```
|
||||
### Split Stack
|
||||
|
||||
## Migration Order
|
||||
- `backend` serves API traffic on `:8000`
|
||||
- `web` serves Next.js on `:3000`
|
||||
|
||||
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
|
||||
### Single Container
|
||||
|
||||
## Non-Goals for This First Slice
|
||||
- the container runs both FastAPI and Next.js
|
||||
- FastAPI stays on `:8000`
|
||||
- non-API requests are proxied from FastAPI to the embedded Next server
|
||||
|
||||
- No immediate removal of the legacy `frontend/`
|
||||
- No backend contract rewrite yet
|
||||
- No server actions as the primary data mutation layer
|
||||
## Follow-up Expectations
|
||||
|
||||
1. New frontend work lands only in `web/`
|
||||
2. Single-container smoke tests must validate both UI and API paths
|
||||
3. Deployment docs must continue to describe `web/` as the sole frontend
|
||||
|
||||
Reference in New Issue
Block a user