perf(energy): SWR 缓存 + 自调度刷新，氢能总览 6s → 13ms

接口侧：
- cache.ts 改为 stale-while-revalidate：每个 key 自调度，TTL 到期前 5s 后台刷新，用户永远命中热缓存
- 闲置 10 分钟后停止调度，避免空跑
- loader 失败保留旧值 + 10s 后退避重试
- 所有 4 个端点支持 ?force=1 强制绕过缓存

前端 HydrogenOverview：
- 顶部加 RefreshCw 按钮（强刷绕过缓存），带旋转动画
- 显示"更新于 X 秒前"相对时间
- 刷新中：顶部 0.5px 流光进度条，不替换内容、不闪烁
- 60s 静默自动刷新（命中后端热缓存）

实测：cold 6.1s → 命中 13ms（470× 提速）

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

src/modules/energy/HydrogenOverview.tsx

@@ -1,8 +1,9 @@
-import { useEffect, useState } from 'react';
+import { useCallback, useEffect, useRef, useState } from 'react';
 import {
   BarChart, Bar, XAxis, YAxis, ResponsiveContainer, Cell, PieChart, Pie, Tooltip, LabelList, Legend,
 } from 'recharts';
-import { Fuel, Wallet, CalendarDays, Sparkles, TrendingUp } from 'lucide-react';
+import { Fuel, Wallet, CalendarDays, Sparkles, TrendingUp, RefreshCw } from 'lucide-react';
+import { motion, AnimatePresence } from 'motion/react';
 import { fetchHydrogenOverview, type HydrogenOverviewResponse } from './api';
 import RotatingFooterHint from '../../components/RotatingFooterHint';
 
@@ -87,16 +88,37 @@ export default function HydrogenOverview() {
   const [data, setData] = useState<HydrogenOverviewResponse | null>(null);
   const [error, setError] = useState<string | null>(null);
   const [year, setYear] = useState<number | null>(null);
+  const [refreshing, setRefreshing] = useState(false);
+  const [lastRefreshAt, setLastRefreshAt] = useState<number>(0);
+  const refreshSeq = useRef(0);
 
+  const load = useCallback(async (selectedYear: number | null, force: boolean) => {
+    const seq = ++refreshSeq.current;
+    setRefreshing(true);
+    try {
+      const d = await fetchHydrogenOverview(selectedYear ?? undefined, force);
+      if (seq !== refreshSeq.current) return; // outdated
+      setData(d);
+      setError(null);
+      setLastRefreshAt(Date.now());
+    } catch (e) {
+      if (seq !== refreshSeq.current) return;
+      setError(e instanceof Error ? e.message : String(e));
+    } finally {
+      if (seq === refreshSeq.current) setRefreshing(false);
+    }
+  }, []);
+
+  // 初始加载 + 年份切换：用 force=false 命中热缓存
+  useEffect(() => { void load(year, false); }, [year, load]);
+
+  // 客户端兜底自动刷新：每 60s 静默拉一次（命中后端热缓存，几乎零成本）
   useEffect(() => {
-    let cancelled = false;
-    fetchHydrogenOverview(year ?? undefined)
-      .then(d => { if (!cancelled) setData(d); })
-      .catch(e => { if (!cancelled) setError(e instanceof Error ? e.message : String(e)); });
-    return () => { cancelled = true; };
-  }, [year]);
+    const t = setInterval(() => { void load(year, false); }, 60_000);
+    return () => clearInterval(t);
+  }, [year, load]);
 
-  if (error) {
+  if (error && !data) {
     return <div className="bg-red-50 text-red-600 rounded-2xl border border-red-100 p-4 text-sm">加载失败：{error}</div>;
   }
   if (!data) {
@@ -133,25 +155,36 @@ export default function HydrogenOverview() {
   }));
 
   return (
-    <div className="flex flex-col gap-3">
-      {/* 顶部说明条 + 年份切换 */}
+    <div className="flex flex-col gap-3 relative">
+      {/* 顶部说明条 + 年份切换 + 刷新按钮 */}
       <div className="bg-white rounded-xl border border-slate-100 px-3 py-1.5 text-[11px] text-slate-400 flex items-center justify-between gap-2">
-        <span>数据自 2025-01-01 起 · 每分钟刷新</span>
-        <div className="flex items-center gap-1 bg-slate-50 rounded-lg p-0.5">
-          {availableYears.map(y => {
-            const active = y === activeYear;
-            return (
-              <button
-                key={y}
-                onClick={() => setYear(y)}
-                className={`px-2 py-0.5 text-[11px] font-bold rounded-md transition-all ${
-                  active ? 'bg-white text-blue-600 shadow-sm' : 'text-slate-400 hover:text-slate-600'
-                }`}
-              >
-                {y}
-              </button>
-            );
-          })}
+        <span className="truncate">{lastRefreshAt ? `更新于 ${formatRelative(lastRefreshAt)}` : '数据自 2025-01-01 起'}</span>
+        <div className="flex items-center gap-2 flex-shrink-0">
+          <div className="flex items-center gap-1 bg-slate-50 rounded-lg p-0.5">
+            {availableYears.map(y => {
+              const active = y === activeYear;
+              return (
+                <button
+                  key={y}
+                  onClick={() => setYear(y)}
+                  className={`px-2 py-0.5 text-[11px] font-bold rounded-md transition-all ${
+                    active ? 'bg-white text-blue-600 shadow-sm' : 'text-slate-400 hover:text-slate-600'
+                  }`}
+                >
+                  {y}
+                </button>
+              );
+            })}
+          </div>
+          <button
+            onClick={() => void load(year, true)}
+            disabled={refreshing}
+            className="flex items-center gap-1 px-2 py-0.5 rounded-lg bg-blue-50 text-blue-600 hover:bg-blue-100 disabled:opacity-60 disabled:cursor-not-allowed transition-colors"
+            title="手动刷新（绕过缓存）"
+          >
+            <RefreshCw size={11} className={refreshing ? 'animate-spin' : ''} strokeWidth={2.6} />
+            <span className="text-[11px] font-bold">刷新</span>
+          </button>
         </div>
       </div>
 
@@ -489,10 +522,43 @@ export default function HydrogenOverview() {
       )}
 
       <RotatingFooterHint />
+
+      {/* 刷新中：透明遮罩 + 顶部进度条（不替换内容，避免闪烁） */}
+      <AnimatePresence>
+        {refreshing && data && (
+          <motion.div
+            key="refresh-overlay"
+            initial={{ opacity: 0 }}
+            animate={{ opacity: 1 }}
+            exit={{ opacity: 0 }}
+            transition={{ duration: 0.2 }}
+            className="fixed top-0 left-0 right-0 h-0.5 z-50 pointer-events-none overflow-hidden"
+          >
+            <motion.div
+              className="h-full bg-gradient-to-r from-blue-400 via-cyan-400 to-blue-400"
+              initial={{ x: '-100%' }}
+              animate={{ x: '100%' }}
+              transition={{ duration: 1.2, repeat: Infinity, ease: 'linear' }}
+              style={{ width: '40%' }}
+            />
+          </motion.div>
+        )}
+      </AnimatePresence>
     </div>
   );
 }
 
+function formatRelative(ts: number): string {
+  const s = Math.max(0, Math.floor((Date.now() - ts) / 1000));
+  if (s < 5) return '刚刚';
+  if (s < 60) return `${s} 秒前`;
+  const m = Math.floor(s / 60);
+  if (m < 60) return `${m} 分钟前`;
+  const h = Math.floor(m / 60);
+  if (h < 24) return `${h} 小时前`;
+  return new Date(ts).toLocaleString('zh-CN', { hour12: false });
+}
+
 function HydrogenOverviewSkeleton() {
   return (
     <div className="flex flex-col gap-3 animate-pulse">

src/modules/energy/api.ts

@@ -19,9 +19,12 @@ export interface HydrogenOverviewResponse {
   year: number;
 }
 
-export function fetchHydrogenOverview(year?: number): Promise<HydrogenOverviewResponse> {
-  const q = year ? `?year=${year}` : '';
-  return fetchJson<HydrogenOverviewResponse>(`${BASE}/hydrogen/overview${q}`);
+export function fetchHydrogenOverview(year?: number, force = false): Promise<HydrogenOverviewResponse> {
+  const params = new URLSearchParams();
+  if (year) params.set('year', String(year));
+  if (force) params.set('force', '1');
+  const q = params.toString();
+  return fetchJson<HydrogenOverviewResponse>(`${BASE}/hydrogen/overview${q ? `?${q}` : ''}`);
 }
 
 export function fetchHydrogenDaily(range: DateQuickPick, customer: CustomerType): Promise<HydrogenDailyRow[]> {