2569718930@qq.com
138 lines
3.6 KiB
Markdown
138 lines
3.6 KiB
Markdown
# 前端交付与重构报告（2026-03-12）
|
||
|
||
## 1. 报告目的
|
||
|
||
本报告用于说明当前线上前端（`frontend/`）的真实实现状态，替代旧版“单次改版完成报告”。
|
||
|
||
---
|
||
|
||
## 2. 当前前端架构
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
B["Browser"] --> N["Next.js App Router (Vercel)"]
|
||
N --> RH["Route Handlers /api/*"]
|
||
RH --> F["FastAPI (VPS)"]
|
||
|
||
N --> STORE["Dashboard Store"]
|
||
STORE --> MAP["MapCanvas"]
|
||
STORE --> SIDEBAR["CitySidebar"]
|
||
STORE --> PANEL["DetailPanel + Modal"]
|
||
```
|
||
|
||
### 2.1 组件分层（实际）
|
||
|
||
- 页面入口：`frontend/app/page.tsx` + `frontend/components/dashboard/DashboardEntry.tsx`
|
||
- 核心容器：`frontend/components/dashboard/PolyWeatherDashboard.tsx`
|
||
- 主要视图：
|
||
- `MapCanvas.tsx`
|
||
- `CitySidebar.tsx`
|
||
- `DetailPanel.tsx`
|
||
- `FutureForecastModal.tsx`
|
||
- `HistoryModal.tsx`
|
||
- `GuideModal.tsx`
|
||
- 状态管理：`frontend/hooks/useDashboardStore.tsx`
|
||
|
||
---
|
||
|
||
## 3. 本轮已落地能力
|
||
|
||
### 3.1 侧栏风险分组折叠（已完成）
|
||
|
||
- 按 `high / medium / low / other` 分组展示城市。
|
||
- 分组支持折叠/展开。
|
||
- 保留“本地时间”和“峰值时间”显示。
|
||
- 折叠状态持久化到 `localStorage`（`polyWeather_sidebar_groups_v1`）。
|
||
|
||
### 3.2 选中城市状态持久化（已完成）
|
||
|
||
- 最近一次选中城市持久化到 `localStorage`（`polyWeather_selected_city_v1`）。
|
||
- 页面刷新后自动恢复。
|
||
|
||
### 3.3 未来日期分析与市场扫描（已完成）
|
||
|
||
- 前端通过 `target_date` 调用 `/api/city/{name}/detail`。
|
||
- 未来日期 modal 可展示对应日期的模型概率与市场扫描。
|
||
|
||
### 3.4 市场概率分布去重保护（已完成）
|
||
|
||
- 后端温度桶去重后，前端仍保留兜底去重逻辑。
|
||
- 避免“同温度重复四行”导致的可视化误导。
|
||
|
||
### 3.5 可访问性修复（已完成）
|
||
|
||
- 解决详情侧栏关闭时 `aria-hidden` 焦点冲突。
|
||
- 方案：`inert` + `activeElement.blur()`。
|
||
|
||
### 3.6 图标与性能观测（已完成）
|
||
|
||
- 已接入 favicon/Apple touch icon/manifest。
|
||
- 已集成 Vercel Speed Insights 与 Analytics。
|
||
|
||
---
|
||
|
||
## 4. 缓存与性能策略（当前状态）
|
||
|
||
### 4.1 BFF HTTP 缓存（Vercel）
|
||
|
||
- `/api/cities`：`ETag` + `s-maxage=300`
|
||
- `/api/city/{name}/summary`：`ETag` + `s-maxage=20`
|
||
- `/api/history/{name}`：`ETag` + `s-maxage=60`
|
||
- `summary?force_refresh=true`：`Cache-Control: no-store`
|
||
|
||
### 4.2 前端本地缓存
|
||
|
||
- `sessionStorage`：城市详情缓存（5 分钟 TTL + revision 探测）
|
||
- 请求去重：并发请求合并（pending request map）
|
||
- `localStorage`：选中城市 + 侧栏折叠状态
|
||
|
||
### 4.3 当前明确未做
|
||
|
||
- Service Worker Cache API
|
||
- IndexedDB
|
||
|
||
---
|
||
|
||
## 5. 验收记录
|
||
|
||
### 5.1 前端缓存验收脚本
|
||
|
||
```bash
|
||
./scripts/validate_frontend_cache.sh "https://polyweather-pro.vercel.app"
|
||
```
|
||
|
||
当前结果：`PASS (14 passed)`。
|
||
|
||
### 5.2 自动化测试
|
||
|
||
```bash
|
||
.\\venv\\Scripts\\python.exe -m pytest -q
|
||
```
|
||
|
||
当前结果：`31 passed`。
|
||
|
||
---
|
||
|
||
## 6. 风险与改进点
|
||
|
||
1. `frontend/.next` 构建产物在本地可见，需继续确保不进入版本管理。
|
||
2. 前端缓存策略已覆盖 P0+P1，但离线能力仍未建设（无 SW/IndexedDB）。
|
||
3. 多源数据仍依赖后端聚合延迟，前端仅能做缓存与降噪，不可替代后端刷新节奏。
|
||
|
||
---
|
||
|
||
## 7. 结论
|
||
|
||
当前前端已从“单体页面”演进为组件化 dashboard，具备：
|
||
|
||
- 风险分组侧栏与状态持久化
|
||
- 未来日期分析与市场扫描联动
|
||
- BFF 标准缓存头（`ETag/304`）
|
||
- 可访问性修复与基础性能观测
|
||
|
||
可以支持继续推进商业化接入，但支付相关能力仍需后端与权限体系配套完成。
|
||
|
||
---
|
||
|
||
最后更新：`2026-03-12`
|