做什么（One-liner）

BLCV 批量扫描：对一组 tickers 并行跑 4 维度 BLCV 分析（V/B/C/L）+ 加权合成 + 降序排序 + 分配 rank 编号，输出 top_pick 与完整 ranking。股票池 shortlist 核心工具。

怎么用

Canvas 拖 blcv_equity_scan_v1，填 symbols list（必填）+ 可选 weights + 可选 peers_map（每个 ticker 的同行）。输出 {count, top_pick, results[], logic_lineage}。

典型用法：

scan_full(["META", "AAPL", "GOOG", "MSFT", "AMZN"])
→ count=5, top_pick="NVDA" (e.g.), ranked 1-5 by blcv_score desc

核心公式

本质是 score_single 的 map + sort:

for sym in symbols:
    result = score_single(sym, weights, peers_map.get(sym))  # 4 dim + compose
    results.append(result)

ranking = sorted(results, key=blcv_score, reverse=True)    # stable sort
for i, r in enumerate(ranking):
    r.rank = i + 1

top_pick = ranking[0].symbol if ranking else None

底层 score_single 公式（详见 blcv_score_v1 card）：

blcv_raw = (wB×B + wL×L + wC×C + wV×V) / Σw
if industry ∈ avoided: blcv_raw ×= 0.6
blcv_score = round(clamp(blcv_raw, 0, 100), 2)

假设与适用场景

假设：yfinance 可用 + 4 dimension analyzer 假设 + DEFAULT_WEIGHTS + hardcoded thresholds。

适用：美股 shortlist、peer basket、factor investing 排序、quarterly review。

不适用：100+ symbols（慢）、非美、多因子归因、time-series BLCV。

输入 / 输出契约

{symbols: list[str], weights?: dict, peers_map?: dict[sym, list[sym]]} → {count: int, top_pick: str | null, results: list[{symbol, rank, blcv_score, signal, dimension_scores, margin_of_safety, details, ...}], logic_lineage: list[str]}。

Per-symbol exception → {symbol, error, blcv_score: 0} 进 ranking 末尾。

已知局限

1. 顺序执行无并发 — N 标的 = N 次 yfinance call
2. 失败 symbol 以 blcv_score=0 出现在 ranking 末尾（非排除）—— caller 需检查 error 字段
3. DEFAULT_WEIGHTS / industry penalty ×0.6 / signal thresholds 全 hardcoded
4. Stable sort 等分时按输入序 → UI 可能 confusing
5. 无 caching（同 symbol 两次 scan 两次 fetch）
6. peers_map optional → 不提供时 C 维度 peer_comparison=null

参考文献

Graham-Dodd (1934) 批量 screening 方法论 + Fama-French (1992) 因子投资排序 framework + Asness et al. (2013) 多因子实证。详见 frontmatter。

Golden Test

tests/golden/fixtures/tier2/blcv_equity_scan/，yfinance-snapshot integration regression (single-symbol wrapper path)。1e-6 tolerance。6 tests：

• matches_snapshot — 全 output 深比对
• determinism — 5 reruns byte-identical
• rank_assignment — multi-symbol（shared snapshot → equal scores）ranks=[1,2,3] 与 stable sort
• empty_symbols — N=0 → count=0, top_pick=null, results=[]
• logic_lineage_format — ["BLCV full scan", "symbols=AAPL,MSFT"]
• result_preserves_rank_field — 每 result 有 rank int 字段

底层 4 维度 golden 独立（tier1/blcv_financials, tier1/blcv_business, tier2/blcv_compete, tier2/blcv_leadership）—— 本 test 聚焦 wrapper 机制。

Changelog

• 1.0.0 (2026-04-20) — 首次 Active（Tier 2 batch 4, batch wrapper）