# v0.42 独立组合前向模拟账本

入口 `/research/portfolio-paper`。研究模拟，不是交易执行、实际收益或策略准入；不提供收益保证。发布不会创建生产账户、启动观察进程或发送消息。

## 来源与两阶段时间规则

账户冻结同工作区处于 shadow 状态的 v0.40 组合定义和固定 epoch，资金及风险参数创建后不可修改。初始现金默认 10,000 模拟 USDT，处理和新增均默认关闭。旧期目标不能自动转入；启用或任何控制变更会清除意图并移动 entryAfter，必须有之后的新来源观察。

1. 登记新来源观察的目标意图；此阶段不采价格、不成交。意图记录时刻严格晚于观察时刻。
2. 后续采样服务器获取的全部币种同交易所、同一 UTC 4 小时确认收盘。收盘必须严格晚于意图持久化时刻；不是按来源建议的下一期开盘撮合。允许采样窗口为收盘后 60 秒至 10 分钟，采集时间不超过 2 分钟，不接受调用者价格或时钟。意图最长 24 小时，过期或被新目标替代时取消；不补历史漏采。

价格模型 `confirmed-4h-close-after-persisted-intent-v1`，版本 `portfolio-paper-0.42.0`，性能类别 `forward_simulated`。这是新模型，不能与 v0.38 历史开盘/盘中保护模型的结果直接合并比较。无盘口、部分成交、交易所数量精度、停牌流动性或真实订单确认模型。

## 现金与归因

共享现金、逐策略×币种数量、成本基础、已实现/未实现损益和现金流贡献。手续费及不利滑点沿用来源冻结配置。使用成本后权益求根；同币种内部策略转移按参考价，不产生外部费用，外部净买卖才收费。漂移阈值为 2 个百分点，新建仓与目标归零可绕过阈值。每个单元格贡献=净现金流+当前市值，其总和与账户损益对账；已实现+未实现同样对账。

使用浮点研究算术，相对初始资金 1e-8 容差，不是货币级精度。最小外部净订单默认 10 USDT；任何净订单不足门槛则拒绝整次自愿调仓，不部分写入。保护退出/回撤退出不受最小订单限制；这不代表真实市场可以成交。新增价格偏离来源日收盘默认不超过 5%，只限制增加，不妨碍减少。

## 风控、暂停与故障

- 独立的收盘保护封装：来源最后 15 根日线计算 14 日算术平均 True Range，入场固定 ATR。C01 为 2.1 ATR 止损/4.2 ATR 止盈；C02/C03/C04/C06 为 2 ATR 止损；C07 无保护价。仅采样 4h 收盘检查，按该收盘加滑点模拟，绝不声称盘中保护成交或按止损价成交。调整已有仓位不重置保护，同次保护退出不重新进入。
- 默认最大回撤 20%，只按采到的收盘权益检测；触发后永久锁定新增并在本次采样价模拟清仓，包括费用导致越限的情形。真实市场损失可能超过上限。风险锁定不能通过启停解除。
- 持仓期间漏采 4h 估值会明确记录缺口，并永久锁定新增，不推测缺失期间的高低点或保护退出。
- `enabled=false` 完全冻结处理、保留持仓；不是清仓。`enabled=true,allowEntry=false` 继续估值、保护退出和减仓。来源暂停/换期取消旧意图，不自动迁移。
- 价格任一失败、身份/哈希/时间不符、采价跨收盘、来源或权限/账户版本变化均拒绝最终事务，不产生部分估值/成交。并发请求由修订 CAS 和不可变事件去重；手动/运行器使用既有评估/扫描配额，每阶段与目标/收盘使用稳定计量 ID，重试不重复扣量。冷却 30 秒。

## 权限、API 与运行器

控制台独立登录与同源保护；API 独立 Bearer，不回退会话身份。所有数据按工作区隔离。研究员可创建及手动处理，所有者/管理员可启停；查看者可读取与导出。

| 方法及路径 | 权限 / 含义 |
| --- | --- |
| GET `/api/v1/paper/portfolio` | paper:read，账户摘要 |
| GET `/api/v1/paper/portfolio/detail?id=UUID&before=0` | paper:read，最近50事件，nextCursor向前分页 |
| POST `/api/v1/paper/portfolio/tick`，空对象 | paper:run，每轮最多处理一个账户的一个阶段 |
| POST `/api/v1/paper/portfolio/export`，`{id}` | paper:read，完整证据 |
| POST `/api/console/paper/portfolio` | 仅控制台创建：id、sourceReleaseId、可选 initialCash/maxDrawdownPct/minNotional/maxPriceDeviationPct |
| POST `/api/console/paper/portfolio/state` | 仅控制台审核：id、revision、enabled、allowEntry、note（5–500字） |
| POST `/api/console/paper/portfolio/run`，`{id}` | 仅控制台手动处理 |

`trendlab-shadow-runner.py --lane portfolio-paper` 使用 paper:run；需要同目录 `trendlab-runner.py` 和既有私有站点访问认证。组合目标来源另用 `--lane portfolio`。本版本不启动常驻任务，窗口外 tick 只返回 waiting/idle，不补录。

硬容量：每工作区3个新组合账户（与旧基础模拟账户另计），每账户1000事件/8 MiB证据，每工作区5000事件，单事件128 KiB，导出16 MiB。普通事件最多999且预留32 KiB供最终暂停/恢复；达到上限无法继续模拟。导出包含来源完整证据，来源容量也可能先达到限制。账户备份仍有整体8 MiB上限，过大需管理员数据库备份流程，不生成截断备份。

## 复算、恢复与回退

`node --experimental-strip-types scripts/reproduce-portfolio-paper.mts --file evidence.json --out verification.json`：核对外层/来源哈希、观察链及ATR尾部、意图关联，逐事件数值重算，核对最终状态。不会覆盖现有输出文件。明确 `sourceTargetsNumericallyRecomputed=false`、`sourceAuthenticityVerified=false`：此工具核对记录目标及模型结果，不证明交易所原始真实性，也不替代来源目标模型独立复算。

新增迁移 `0020_portfolio_forward_paper.sql`，当前共21迁移/46业务备份表/25恢复文件。恢复演练完整复算新账本，恢复副本追加暂停控制、保留持仓并取消意图，不自动重新开工。v0.41的23个恢复文件固定在 `/integration/v041/`，新schema不可直接回退到旧版本；需要按恢复与发布门禁进行兼容性判断。

测试使用隔离 D1/R2、合成行情与测试入口固定时钟，不能作为真实前向运行或浏览器点击验收证据。正式观察证据积累、准入、服务器任务编排及实盘执行均未因本功能获得授权。