big-qmt/docs/trend-state.md

Trend 精简状态记录（JSON v3）

记录内容

• items[code]：底仓数量、底仓均价、补仓次数、累计补仓数量和金额。补仓均价由金额除以数量得到。
• pending[code]：每只证券最多一个待确认买单，仅存订单号、类型（base/add）、预开仓数量 expected_qty 和提交时间。
• 文件仍为 {strategy}_{account_id}_state.json，内存字典访问，数据变化时原子写 JSON。

没有子单历史缓存、增量游标、counted 标记、待确认计数器或 seen_positions。

处理规则

1. 首次接管的持仓全部作为底仓；存在 pending 的证券等待自身订单对账，不从部分持仓重复导入。
2. 提交前保存 pending 和预开仓数量。保存失败回滚占位，阻止发送；异常响应保留待确认状态。
3. 订单处理中不更新账本。空快照、部分快照和缺少成交价格时继续等待；超过 180 秒定期提示核查，不自动释放。
4. 当前完整快照必须覆盖预开仓数量，所有子单明确结束，且成交金额完整，才一次记账。系统订单号用于本轮去重，不跨轮缓存子单。
5. 有成交的补仓计一次，累加实际数量和金额；部分成交后撤单也如此。完全未成交不增加补仓次数。
6. 更新账本和删除 pending 在同一次文件替换中保存，重复快照/重启不会重复记账。
7. 账本不因持仓缺席而删除。清仓后若需要同证券重新开底仓，必须先核实清仓、停机备份并清理对应 items 记录；当前未实现自动清仓判定。

SimpleCache 与 busy_keys 继续用于快速防重，本地 pending 同样阻止买入。底仓数量/补仓数量是买入成交记录，不自动分摊卖出；实际可用持仓仍以券商为准。

迁移

自动支持 v2 → v3，保存前备份为 .json.v2.bak。

v2 尚未结束的订单可能已经记入部分成交和一次补仓计数。迁移先撤回该 pending 的 applied_qty、applied_amount、counted 对账本的贡献；最终完整快照到达后再一次计入，避免重复。已完成订单的账本保持原值。原子保存失败时原 v2 文件仍可重试。

v2 子单缓存保存在备份中，v3 不继续使用；需要之后提供完整订单快照才能结束对账。expected_qty=0 的旧迁移记录仍需要核实计划量。若同一证券存在多个旧 pending，停止迁移并保留原文件，避免静默丢掉订单。

更早的无版本 JSON 不再由精简状态机自动猜测转换，会报错且不修改原文件，需先核实转换。旧文件未保存的历史累计补仓成本无法恢复。

验证与限制

已使用临时目录和替身验证：首次接管、处理中不记账、部分成交撤单、完整拆单、重复记录/重启、空持仓保留、累计成本、无变化不写盘、写盘失败回滚、拒单/零成交清理，以及 v2 增量撤回后只记一次终态成交。没有新增 tests 文件，也没有真实交易调用。

依赖柜台提供完整终态快照、正确的本地订单标识及申报量/成交字段。超时只提示人工核查，不自动查询或重发。单进程使用，未提供多进程文件互斥。