docs: record lightweight attribution design references

README.md

@@ -10,7 +10,7 @@
 
 | 仓库 | 角色 |
 |---|---|
-| `quant_engine` | **纯回测核心**（alpha + execution + indicators + data_adapter + backtest + metrics） |
+| `quant_engine` | **纯研究核心**（alpha + execution + ledger + attribution + risk + metrics） |
 | `research_results` | 业务集成（47 个 proj 调度 + 注册 + 平台对接） |
 | `tushare2db_pro_aoge` | 数据层（行情 ELT） |
 | `research_platform` | 展示层（FastAPI + Next.js） |
@@ -25,10 +25,11 @@
 - `backtest` — weight-based 多日仿真（rebalance_table / compute_nav / compare_to_benchmark）
 - `portfolio_construction` — 多期因子分数 → Top-K → 等权目标权重表
 - `research_pipeline` — 因子日 → 下一真实交易日 → 显式执行价 → 日末估值 → 成本后绩效（防前视编排）
-- `metrics` — 绩效（年化收益 / 波动率 / Sharpe / 最大回撤 / Calmar）
+- `attribution` — 基于实际成交后持仓的隔夜 / 日内 / 交易成本逐日收益归因与闭合审计
+- `metrics` — 绝对绩效 + 严格日期对齐的 TE / IR / alpha / beta 基准相对绩效
 - `factor_library` — 通用方法（turnover / winsorize / IC / OLS / jb_test）
 - `portfolio_decomp` — 组合分解（risk_parity / mean_variance / 因子归因）
-- `risk` — 风险指标（边际 / 风险贡献）
+- `risk` — ndarray 低层风险公式 + 标签安全、可分组的 Euler 成分风险分解
 - `perf_stats` — 详细绩效（与 metrics 并存）
 - `logging` — 统一 logger（标准库 + 可选 loguru）
 
@@ -124,6 +125,15 @@ print(factor_backtest.stats())
 print(factor_backtest.execution.ledger_frame)
 print(factor_backtest.execution.trades_frame)
 
+# 所有分析都以实际成交后的 Ledger 为事实源，不直接使用目标权重伪造结果。
+attribution = factor_backtest.return_attribution()
+print(attribution.asset_contributions)
+print(attribution.transaction_cost)
+print(attribution.residual)  # 应接近 0；否则说明贡献未闭合到账本收益
+
+# benchmark_returns 必须与成本后 factor_backtest.returns 使用完全相同的日期索引。
+print(factor_backtest.benchmark_stats(benchmark_returns))
+
 # run_weight_backtest 是低层算子：只接受收益区间开始前已经生效的持仓权重。
 # 不要把 signal-date 的 factor_scores/decision_weights 直接传给它。
 backtest = run_weight_backtest(

docs/OPEN_SOURCE_REFERENCES.md

@@ -0,0 +1,24 @@
+# Open-source design references
+
+本项目采用“借鉴稳定语义、保留轻量实现”的策略。引入新量化能力前先检查成熟
+开源案例；除非维护成本和许可证收益明确优于本地小型实现，否则不增加框架级依赖。
+
+## 2026-08-21：成交后归因与相对绩效
+
+| 项目 | 借鉴内容 | 当前决策 |
+|---|---|---|
+| [Qlib](https://github.com/microsoft/qlib) | 信号时间与交易时间分离、成本前后超额收益分开报告 | 借鉴语义；不引入完整框架 |
+| [Zipline](https://github.com/quantopian/zipline) | Ledger / transaction / portfolio value 状态模型 | 以现有 `ExecutionSimulationResult` 承担事实源 |
+| [empyrical](https://github.com/quantopian/empyrical) | beta 协方差口径、alpha 几何年化、年化因子 | 移植小型公式；不增加老旧运行时依赖 |
+| [Riskfolio-Lib](https://github.com/dcajasn/Riskfolio-Lib) | Euler component risk 与分组/因子风险贡献 | 只实现当前需要的 pandas/numpy 标签安全封装 |
+| [PyPortfolioOpt](https://github.com/PyPortfolio/PyPortfolioOpt) | 协方差估计与优化器解耦 | 留作未来风险模型适配器参考 |
+
+当前核心不新增依赖。逐日收益归因必须从实际换仓前后持仓、成交记录、执行价和
+收盘估值推导；因子分数与目标权重只是意图，不能作为成交后归因事实源。
+
+## hikyuu 的定位
+
+[hikyuu](https://github.com/fasiondog/hikyuu) 的 SG / MM / CN / PG 部件化思想、
+A 股交易约束和系统组合方式仍有借鉴价值；但其完整 C++/Python 运行时、对象模型和
+数据体系不适合作为本项目核心依赖。当前原则是按真实研究链路吸收边界设计，不复制
+其框架层级，也不为了“架构完整”预先建设尚无端到端需求的抽象。