截面选基板块 — 启动性能与耗时拆解分析

文档目标

拆解「截面选基」(/cross-section) 从点击到首屏可用的完整耗时，定位主要耗时来源，给出可落地的优化方案（首屏优先 / 分块加载 / 缓存），目标把首屏等待从当前的 5~14 秒 压到 3 秒以内（理想 1 秒内）。

> 本文只做现状梳理 + 方案设计，不含代码改动。方案确认后再进入实现。

一句话结论

首屏慢的根因是「一个巨型接口 _format_snapshot 一次性 eager 计算全部数据，阻塞整页渲染」，外加「第二个接口 etf-kline-batch 每次重复读 109 个文件且完全无缓存」。

• snapshot 冷启动 5.2~9.3s（仅 30s 缓存，超时即全量重算）；
• etf-kline-batch（109 个 code）每次都要 4~5s，且紧跟在 snapshot 之后串行阻塞表格填充。
• 两者叠加 ⇒ 用户每次打开实际等待 ≈ 9~14 秒。

> 关键洞察：_format_snapshot 里最贵的「相关性 Top10 全量计算」（占 ~58% 时间）只在用户点击 r=0.88 ▼ 时才用到，属于典型的「首屏不该算」。

---

一、首屏加载链路（现状）

页面 /cross-section 由 unified_server.py 路由渲染，模板为 CROSS_SECTION_PAGE（L10788-L13362）。

前端初始化 loadSnapshot() 触发以下请求链：

点击 /cross-section
  │
  ├─ ① GET /cross-section                 (HTML 外壳 184KB, 24ms)   ← 快
  │
  └─ ② GET /api/cross-section/snapshot    (5.2~9.3s 冷 / 0.1s 热)   ← 阻塞首屏 ⛔
        │  返回 391KB JSON（含全部排名109 + 持仓11 + 关注20 + regime历史 + 择时明细）
        │  前端 renderMetaBar → renderPortfolio → renderRanking（排名/持仓骨架先出）
        │
        ├─ ③ GET /api/etf-kline-batch?codes=<109只>&range=7d  (4~5s, 无缓存) ← 阻塞表格单元格填充 ⛔
        │        .then → updatePortfolioCells / updateRankingCells / loadWatchlist
        │
        ├─ ④ GET /api/black-swan            (0.01s, 300s缓存)        ← 快
        └─ ⑤ GET /api/etf-kline-batch?codes=<Top20>&range=3m  (K线预览)

用户感知：③ 完成前，持仓/排名表格的涨跌幅、K线等单元格是空的（rankLoading / wlLoading 遮罩）。所以真正"可用"的时间 = ② + ③ ≈ 9~14 秒。

---

二、实测耗时（本机 127.0.0.1:8765，服务运行中）

关键结论

• snapshot 的缓存 TTL 只有 30 秒（L9299）——只要隔 30s 再打开就全量重算，这就是"每次点开都慢"的直接原因。
• etf-kline-batch 完全没有跨请求缓存（_get_etf_kline_batch_json），每次都要重新读 109 个文件的磁盘数据，每次都付 4~5s。
• 快照数据每日仅更新数次，但其缓存 TTL 却只有 30s，缓存策略与数据更新频率严重不匹配。

---

三、后端 _format_snapshot 内部分段耗时（cProfile）

用 cProfile 对 _format_snapshot（L9317-L10478）做单次冷路径剖析（独立进程，单次约 2.9s）：

数据块规模（响应体 391KB 构成）

---

四、根因拆解

根因 1：单体大函数 eager 计算，全部阻塞首屏

_format_snapshot 是一个 ~1160 行的大函数，在一次请求内同步算完：排名、持仓、关注、新鲜度、regime 历史、择时明细、相关性……前端必须等全部算完才拿到任何数据。没有「先返回骨架、后补细节」的机制。

根因 2：相关性 Top10 全量计算，但只在点击时才用

_corr_top_list(code) 对每个组合/关注品种，遍历全部 14 个锚点各自 load 一段序列并算 120 日相关性（共 615 次 _corr_ret）。

• 结果显示：anchor_corr_top 字段在前端只出现在点击行内 toggleCorrTop(...) 的 onclick 参数里（L12083、L12860）——不点开就白算。
• 唯一"首屏必需"的是单个锚点的相关系数 anchor_confidence（L9699-L9709），却被迫算了全部 14 个锚点。

根因 3：缓存 TTL（30s）与数据更新频率（每日数次）不匹配

快照数据每天只更新几次，但缓存 30 秒即失效 ⇒ 用户隔一会儿再打开就重算 → 反复付 5~9s。

根因 4：etf-kline-batch 无任何缓存，每次重读 109 个文件

_get_etf_kline_batch_json 用 8 线程读 109 个 code 的磁盘数据（_load_kline_df_from_cache），无内存/响应级缓存，且首屏一次性请求全部 109 只（持仓 + 全部排名 + 关注），而不是只请求首屏可见的部分。

根因 5：两套独立的序列加载器，重复读盘

_corr_close（请求级缓存）与 _wl_load_close（另一个请求级缓存）各自调用 DataCacheManager.load，同一个 proxy 序列可能被读两遍；相关性矩阵结果也没有跨请求复用。

根因 6：payload 偏大（391KB）

regime_history（173KB）与 rankings（82KB）是最大块。虽然计算不贵，但 391KB 的 JSON 传输 + 解析在移动端也有成本，且这些数据并非首屏刚需。

---

五、优化方案（分阶段）

P0 — 快赢（改动小、收益大，预计首屏 → 3s 内）

> P0-1 + P0-2 + P0-3 组合后，热路径首屏预计可到 1s 内，冷路径（当日首次）预计 3s 内。

P1 — 首屏拆分（分块/分 type 加载）

把 snapshot 拆成「首屏必需」+「延迟块」，前端并行/按需拉取：

对应后端可新增 /api/cross-section/snapshot/basic、/watchlist、/regime-history 等子接口，复用同一份缓存计算，避免重复。

P2 — 架构级（预热与复用）

• 收盘后后台预热：快照每日更新数次，更新完成后主动生成并写入缓存（含相关性矩阵），用户首访直接命中。
• 相关性矩阵缓存：把「品种 × 锚点」的 120 日相关系数矩阵按日缓存（跨请求共享），不用每次重算。
• 合并序列加载器：把 _corr_close 与 _wl_load_close 统一为一个请求级 loader，proxy 序列只读一次。
• 消除重复 to_datetime：序列加载时一次性建好时间索引，避免 799 次重复转换。
• 磁盘缓存：etf-kline-batch 的原始 DataFrame 读到内存 LRU（数据日内有效）。

---

六、目标与验收标准

验收方式：本机 curl -w "%{time_total}" 多次取样 + 浏览器实测首屏 rankLoading/wlLoading 遮罩消失时间；改动后必须手机实测纵向滑动与首屏加载。

---

七、风险与回归点

• 相关性口径：P0-2 把「14 锚点取一个」改成「单锚点直算」时，必须保证与现展示值一致（尤其多锚品种 159518/XOP、159941/QQQ 走的是 _multi_anchor_conf，不能被单锚逻辑覆盖）。
• 缓存一致性：拉长 TTL 后，快照更新（每日数次）需主动失效缓存，否则用户看到旧数据 → 建议「写快照时清缓存」或按数据版本号失效。
• 首屏拆分的降级：拆分后若某块接口失败，首屏不能整页空白，需保留骨架 + 局部错误提示。
• CSS 转义：改动 CROSS_SECTION_PAGE 内联 CSS 时，花括号必须双写 {{ }}（.format() 渲染）。
• 部署：改完必须发布到 https://quant.aohan.net，不能只跑本地。

---

八、已实施变更记录

2026-10-11 — 快照/相关性改「后台预热缓存」（P0-1 变体）

背景：用户反馈「相关性现场计算有问题，数据接口大多是日级别，不该每次进页面重算；改成每 15 分钟算一次、进页面直接命中缓存即可」。

方案：不做「按需计算（P0-2）」这类涉及口径改动的改造，先走最稳的缓存路线 —— 后台线程每 15 分钟主动重算并刷新缓存，用户请求直接命中，不现场计算。

代码改动（unified_server.py）：

验证结果（本机 127.0.0.1:8765，重启后）：

• 预热线程日志：[unified] 截面选基快照预热线程已启动 + [snapshot-prewarm] 已预热快照 2026-10-09（耗时 15.4s）（首次含 danjuan 网络刷新）。
• 快照接口：run1=0.061s、run2=0.604s、run3=0.085s（均命中缓存，<1s）—— 改造前冷启动 5.2~9.3s。
• 公网 https://quant.aohan.net/api/cross-section/snapshot：HTTP 200（含公网往返/隧道开销约 3.5s）。

未处理（本轮范围外）：~~etf-kline-batch（109 codes, 7d）本机仍 3.18~3.63s，是首屏剩余的 4~5s 瓶颈~~ → 见下方 2026-10-11(2)。

2026-10-11(2) — etf-kline-batch 改「同款预热缓存」

背景：用户要求「你说的这个（etf-kline-batch）也改成一样的缓存」。根因：_get_etf_kline_batch_json 对 100+ 个 code 逐个 DataCacheManager.load_best → pd.read_csv（_load_kline_df_from_cache、load_best），无任何内存缓存，每次请求都重读 109 个文件。

方案：与快照完全同款 —— (range, codes) 响应缓存 + 由同一个预热线程每 15 分钟一并刷新。

代码改动（unified_server.py）：

验证结果（本机 127.0.0.1:8765，重启后）：

• 预热日志：[snapshot-prewarm] 已预热 K线批量 7d×109（耗时 4.7s） + 已预热 K线预览 3m×20（耗时 1.1s）。
• 按前端完全相同的 code 组合（109 个）复测：7d×109 = 0.005~0.019s，3m×20 = 0.011~0.021s（改造前 3.2~4.5s，命中缓存）。
• 公网 https://quant.aohan.net/api/cross-section/snapshot 仍约 3~4s —— 该耗时是 391KB payload 经 Cloudflare 隧道的传输开销（非服务端计算），属 P1 payload 瘦身范畴，与本次缓存无关。

---

九、TODO（实时性 / 后续）

• TODO(实时性)：当前快照/相关性按 15 分钟粒度缓存，满足日级数据即可。若后续对相关性/快照提出实时性要求（例如盘中需实时相关性），再改为「按请求增量刷新」或缩短 TTL / 提供强制刷新接口。
• TODO(P0-3)：~~etf-kline-batch 加响应级缓存（按 (codes, range)，5~15 分钟）~~ ✅ 已完成（2026-10-11(2)） —— (range, codes) 响应缓存 + 预热线程 15 分钟刷新。
• TODO(公网传输)：snapshot 391KB 经隧道传输约 3~4s（服务端已缓存）。若要进一步压公网首屏，需做 P1 的 payload 瘦身（拆分 regime_history/rankings 等大块）或开启 gzip。
• TODO(P0-2)：相关性改为「按需计算」（首屏只算单锚 anchor_confidence，anchor_corr_top 点击时再拉），需保证口径与现展示一致。当前用缓存绕开，暂不实施。
• TODO(缓存一致性)：快照更新（每日数次）时主动失效缓存，或按数据版本号失效，避免 TTL 窗口内看到旧数据。