2569718930@qq.com
111 lines
2.5 KiB
Markdown
111 lines
2.5 KiB
Markdown
# PolyWeather Frontend
|
|
|
|
This directory contains the production web frontend.
|
|
|
|
Production URL:
|
|
- https://polyweather-pro.vercel.app/
|
|
|
|
## Stack
|
|
|
|
- Next.js App Router
|
|
- React (dashboard component architecture)
|
|
- Tailwind CSS
|
|
- Leaflet (map)
|
|
- Chart.js
|
|
- Typed dashboard store + typed data client
|
|
|
|
## Runtime Model
|
|
|
|
- Vercel hosts UI + BFF route handlers.
|
|
- FastAPI on VPS provides weather/analysis APIs.
|
|
- Browser never calls backend directly in normal flow.
|
|
|
|
Request path:
|
|
|
|
1. Browser -> `https://polyweather-pro.vercel.app`
|
|
2. Frontend -> Next route handlers (`/api/*`)
|
|
3. Route handlers -> FastAPI (`POLYWEATHER_API_BASE_URL`)
|
|
|
|
## Local Development
|
|
|
|
```bash
|
|
cd frontend
|
|
cp .env.example .env.local
|
|
npm install
|
|
npm run dev
|
|
```
|
|
|
|
Default local URL:
|
|
- http://localhost:3000
|
|
|
|
## Required Environment Variables
|
|
|
|
```env
|
|
POLYWEATHER_API_BASE_URL=https://<your-fastapi-host>
|
|
```
|
|
|
|
Optional entitlement variables:
|
|
|
|
```env
|
|
POLYWEATHER_DASHBOARD_ACCESS_TOKEN=
|
|
POLYWEATHER_BACKEND_ENTITLEMENT_TOKEN=
|
|
```
|
|
|
|
## Route Handlers
|
|
|
|
- `GET /api/cities`
|
|
- `GET /api/city/[name]`
|
|
- `GET /api/city/[name]/summary`
|
|
- `GET /api/city/[name]/detail`
|
|
- `GET /api/history/[name]`
|
|
|
|
Cache behavior:
|
|
|
|
- `cities` / `summary` / `history` return `ETag` + `Cache-Control`.
|
|
- `summary?force_refresh=true` returns `Cache-Control: no-store`.
|
|
- `city/[name]` and `city/[name]/detail` are dynamic pass-through (no shared HTTP cache).
|
|
|
|
## Frontend State & Local Cache
|
|
|
|
- `sessionStorage`:
|
|
- city detail cache bundle (TTL 5 minutes)
|
|
- `localStorage`:
|
|
- selected city
|
|
- sidebar risk-group collapse state
|
|
- in-flight request de-duplication for city detail/summary/history/market scan
|
|
|
|
## Entitlement
|
|
|
|
- `frontend/middleware.ts` enforces dashboard/API access when `POLYWEATHER_DASHBOARD_ACCESS_TOKEN` is set.
|
|
- BFF forwards backend entitlement token via `x-polyweather-entitlement` header when configured.
|
|
|
|
## UI Notes
|
|
|
|
- Left sidebar supports risk-group collapsible sections.
|
|
- City rows keep local time and peak-time hints visible.
|
|
- Future-date modal requests market scan with `target_date`.
|
|
- Detail panel accessibility uses `inert` + blur when hidden.
|
|
|
|
## Icons & Manifest
|
|
|
|
- `frontend/app/favicon.ico`
|
|
- `frontend/app/favicon-16x16.png`
|
|
- `frontend/app/favicon-32x32.png`
|
|
- `frontend/app/apple-touch-icon.png`
|
|
- `frontend/app/site.webmanifest`
|
|
|
|
## Vercel Deployment
|
|
|
|
1. Import repo into Vercel
|
|
2. Set Root Directory = `frontend`
|
|
3. Set env vars
|
|
4. Deploy
|
|
|
|
## Verification
|
|
|
|
```bash
|
|
./scripts/validate_frontend_cache.sh "https://polyweather-pro.vercel.app"
|
|
```
|
|
|
|
Last updated: `2026-03-12`
|