Merge pull request #186 from rookiewu417/docs/backtest-tracks-map

docs: 补回测入口地图 + 修正集成修复后的过时断言

Author: rookiewu417

docs/concepts/architecture.md

@@ -107,6 +107,22 @@ graph TD
 
 多市场数据源与适配细节见[多市场](multi-market.md)。
 
+### 回测入口
+
+回测**引擎只有一个**（`daily/evaluation/backtest.py` 的单一日环 + 单一约束核 `apply_trade_constraints_batch`），但入口按语义分两轨：
+
+| 入口 | 轨 | 权重从哪来 | 回答的问题 |
+|---|---|---|---|
+| `fz factor eval` | 信号轨（毛口径，不撮合） | 纯向量化截面统计，不建仓 | 因子有没有预测力 |
+| `fz factor backtest` | 交易轨（净口径） | 日环内按当日因子截面**动态**生成 | 单因子做成策略，扣成本还赚不赚 |
+| `fz combine backtest` | 交易轨 | 同上，输入换成多因子组合分数面板 | 组合分数的可实现净值 |
+| `fz sim run` | 交易轨 | **预置**：组合优化器落盘的目标权重 | 优化器给的权重执行出来如何 |
+| `fz strategies run` | 交易轨 | **预置**：规则型策略生成的权重产物 | 择时/轮动/分层建仓策略的表现 |
+
+前两类的持仓是策略配置的函数，策略逻辑在引擎内逐日算；后两类走 `PrecomputedWeightsStrategy`，权重表是**输入**，引擎只负责按 T+1 执行，因此结果能追溯到一份确定的权重产物（`weights.parquet` + `manifest.json` 的 `signal_date`/`status`）。注意 `sim` 对预置权重**不再二次施加仓位约束**——它假定约束已在产物生成端（优化器或策略）完成。
+
+同一因子在两轨下的结论可能相反（实测 `momentum_20d` / csi300 / 2024H1：信号轨毛多空 +10.82%，交易轨净 −2.14%），**引用收益数字前先说清是哪条轨**。
+
 ---
 
 ## 模块职责
@@ -129,7 +145,7 @@ graph TD
 | `reports/` | 2,259 | 信号轨/交易轨报告 + 组合 Dashboard 渲染 |
 | `ops/` | 514 | 无人值守 8 阶段日链路 |
 | `config/` | 496 | 配置模型与路径常量 |
-| `strategies/` | 470 | 规则型策略实验（择时/轮动），**CLI 不可达** |
+| `strategies/` | 853 | 规则型策略（择时/轮动/分层建仓），经 `fz strategies run` 接入模拟交易回测 |
 | `sim/` | 272 | 模拟交易（复用日频回测引擎） |
 | `dataio/` | 260 | 数据迁移脚手架，由 `tools/` 脚本调用，**非运行时 IO 层** |
 | `server/` | 207 | 只读 REST API + Web 页（dev extras） |

docs/guides/risk-and-portfolio.md

@@ -124,11 +124,12 @@ pixi run -- fz risk build --start 20200101 --end 20241231 --universe all_a \
 
 ### 别踩的坑
 
-> ⚠️ **`fz risk build` 的产物当前没有下游消费方。**
-> `RISK_MODELS_DIR` 在全仓只有一个生产者（`pipelines/risk_build.py`），`src/` 内**零读取方**。
-> `fz portfolio build` **不会**去读 `workspace/risk_models/`，而是在进程内自建一个 `RiskModel()` 重算（`cli/main.py` 的 `_cmd_portfolio_build()`）。
+> ⚠️ **调过 `risk build` 的参数，就必须给 `portfolio build` 传 `--risk-dir`。**
+> `fz portfolio build --risk-dir workspace/risk_models/<run_id>`（仅 A 股）会读上面这批 parquet 复用；
+> **不传时**它在进程内自建一个全默认参数的 `RiskModel()`（`cli/main.py` 的 `_cmd_portfolio_build()`），
+> 你在 `risk build` 上调的 `--cov-half-life` / `--nw-lags` / `--spec-half-life` / `--spec-shrinkage` **不会**传到组合这边。
 >
-> 也就是说这两条命令看起来像流水线的上下游，实际是**各自独立**的。`fz risk build` 的用途是产出可审计的风险模型快照供人查看与分析，不是 `portfolio build` 的前置步骤——跳过它直接 `portfolio build` 完全可行，结果不受影响。想复用磁盘上的风险模型需要自己写代码加载。
+> 两种用法都合法：跳过 `risk build` 直接 `portfolio build` 仍然可行（默认参数自建），`risk build` 的产物也仍是可审计的风险模型快照。要让调参生效、或想省掉重算，就走 `--risk-dir`。
 
 > ⚠️ **回归窗口需要预热。** `momentum` 用 252 日滚动窗、`volatility` 用 60 日窗。如果只拉 `[start, end]` 的行情，窗口早期这些因子全空，模型会静默退化成少数几个非滚动因子。CLI 已经自动补足：`load_risk_inputs`（`pipelines/risk_build.py`）会往前多拉 **420 个日历日**（`risk_lookback_start`，约覆盖 252 个交易日 + 春节余量），回归区间本身不变。**自己调 `RiskModel.build` 时必须自己补这段历史。**