feat: fully migrate frontend to a React component-driven architecture and expand project documentation.

frontend/README.md

@@ -1,4 +1,4 @@
-# PolyWeather Frontend
+# PolyWeather Frontend
 
 This directory is the only web frontend in production.
 
@@ -8,21 +8,23 @@ Production URL:
 ## Stack
 
 - Next.js App Router
+- React (component-driven dashboard)
 - Tailwind CSS
-- Lucide React
-- shadcn/ui base layer
-- Legacy dashboard shell loaded from `public/legacy/index.html`
+- Leaflet (map runtime)
+- Chart.js (charts with manual lifecycle wrapper)
+- Typed store + typed data client
 
 ## Production Model
 
-- Vercel serves the web UI
-- FastAPI on VPS serves API only
+- Vercel serves the web UI and BFF route handlers
+- FastAPI on VPS serves weather APIs only
 - The old FastAPI static website has been removed
-- The production page shell is still the legacy dashboard embedded by `app/page.tsx`
+- The production page shell is React-driven (`components/dashboard/*`), with no runtime dependency on `public/static/app.js`
 
 Current request flow:
 - Browser -> Vercel frontend
-- Vercel route handlers -> FastAPI API
+- React store/client -> Next route handlers
+- Next route handlers -> FastAPI API
 
 ## Local Development
 
@@ -51,12 +53,14 @@ Examples:
 Thin BFF routes currently exposed by Next:
 - `GET /api/cities`
 - `GET /api/city/[name]`
+- `GET /api/city/[name]/summary`
 - `GET /api/history/[name]`
 
 Current frontend behavior:
-- `/` keeps the world overview layout
-- City clicks stay inside the same layout and load the right-side panel
-- Future forecast dates open a modal instead of mutating the base panel
+- `/` keeps the world overview layout and initial city temperatures preload
+- Marker click: focus map + open right city card + render nearby stations
+- Right-card "今日日内分析": opens modal and freezes map motion
+- Blank-map click: closes right card only, without resetting camera
 
 ## Vercel Deployment
 
@@ -68,7 +72,7 @@ Current frontend behavior:
 ## Notes
 
 - Backend CORS must allow `https://polyweather-pro.vercel.app`
-- The page shell currently embeds the legacy dashboard HTML from `public/legacy/index.html`
-- If you change files under `public/static`, deploy to Vercel to make them live
+- City detail cache TTL is 5 minutes with revision probe; manual refresh bypasses cache
+- UI layout and sizing remain aligned with the legacy visual contract after React migration
 
 Last updated: 2026-03-09