编码规范 · Vibe-Trading Wiki

公共返回类型统一建模为 frozen dataclass（如 SectorEffect/BrinsonResult/MertonResult/FactorReturnFit/StyleDrift），并通过只读属性暴露派生量（total_effect、credit_spread_bp 等）。
对外函数参数采用 keyword-only 签名（如 altman_z_score 的六个财务比率），避免位置参数顺序错误导致静默计算错误。
输入校验集中在函数入口处抛出 ValueError，明确说明非法原因（权重和不等、收益率低于 -100%、参与率为负、方向非 ±1 等），而非返回 NaN。
可配置常量以模块级大写常量形式暴露（DEFAULT_WEIGHT_SUM_TOLERANCE、SPREAD_INPUT_UNITS、STYLE_FACTOR_DEFINITIONS、DEFAULT_SLIPPAGE_BPS 等），供调用方覆盖默认行为。
单位处理显式化：通过 SPREAD_INPUT_UNITS 映射与 _bp_multiplier 将 yield/bp/percent 统一换算为 basis points，避免历史模板中隐含单位的歧义。
数值稳健性优先：Carino 因子在回报差小于 ε 时退化为对称极限形式；Merton 求解在 log 空间进行并用 fsolve 多次 restart；Winsorise 后再做 z-score 防止极值扭曲截面标准化。