PolyWeather/FRONTEND_REDESIGN_REPORT.md

前端交付与重构报告（2026-03-12）

1. 报告目的

本报告用于说明当前线上前端（frontend/）的真实实现状态，替代旧版“单次改版完成报告”。

---

2. 当前前端架构

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 前端缓存验收脚本

./scripts/validate_frontend_cache.sh "https://polyweather-pro.vercel.app"

当前结果：PASS (14 passed)。

5.2 自动化测试

.\\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