feat client.

docs/state.md

@@ -0,0 +1,99 @@
+# 趋势策略状态机审计
+
+审计日期：2026-08-31
+
+## 结论
+
+当前状态机的职责明确为：按账户和策略持久化每只证券的底仓信息与**补仓业务数据**。补仓委托提交成功后立即写入状态机是必要且正确的；30 秒轮询中的对账用于用券商快照校正订单状态和接管持仓，不能替代补仓次数等业务数据的记录。
+
+状态机主链路可运行，但补仓单被撤销、拒绝或部分成交时，没有完整的状态回写规则；这会使 `added_status` 和 `added_num` 与实际成交结果不一致。该问题应在实盘前明确处理。
+
+## 数据模型与持久化
+
+状态文件路径为：`{qmt_data_dir}/{strategy}_{account_id}_state.json`。
+
+每个证券对应一个 `StateItem`：
+
+| 数据 | 含义 | 写入来源 |
+| --- | --- | --- |
+| `base_qty`、`base_cost`、`base_status` | 首次接管时的底仓数量、成本及状态 | `sync_positions()` |
+| `added_num` | 已提交的补仓次数 | 补仓委托提交成功后立即递增 |
+| `added_order_id`、`added_qty`、`added_cost`、`added_status` | 最近一笔补仓委托及状态 | 补仓提交后写入；30 秒对账尝试校正状态 |
+
+`State.save()` 先写临时文件，再以 `replace()` 原子替换正式 JSON；能避免半写入文件，但不构成“券商下单 + 本地持久化”的跨系统事务。
+
+## 运行流程
+
+```text
+启动
+  ├─ 刷新券商订单 → OrderBook.data
+  ├─ 查询持仓
+  └─ State.reconcile(持仓, 订单快照)
+
+每 30 秒的 RunOnce
+  ├─ 刷新订单；失败则本轮退出
+  ├─ 查询资产、市场、持仓
+  ├─ State.reconcile(持仓, OrderBook.data)
+  ├─ 开仓：OrderBook 方向锁防重；不写 State
+  └─ 补仓：下单成功 → 立即写 StateItem 并持久化
+```
+
+`OrderBook` 与 `State` 的边界如下：
+
+- `OrderBook.lock`：进程内的同方向未决委托锁，防止同轮或相邻轮重复提交。
+- `OrderBook.data`：本轮的进行中或完成订单快照，提供给 `State.reconcile()`。
+- `State`：跨进程保存持仓补仓层级及最近补仓记录；它不是开仓防重的唯一来源。
+
+## 对账和清理规则
+
+`State.reconcile()` 在每轮执行以下操作：
+
+1. 对尚未接管的真实持仓创建状态，记录为已完成底仓。
+2. 以 `local_order_id` 匹配本地订单号；若拆单全部为状态 `56`，将底仓或补仓状态更新为 `OK`，否则保持 `ING`。
+3. 删除不再存在真实持仓的证券状态。
+4. 保存状态文件。
+
+这意味着：持仓是状态项是否保留的最终依据；补仓计数是业务状态，不会由当前持仓反推或重置。
+
+## 发现的问题
+
+### P1：撤销、拒绝和部分成交没有完整回写规则
+
+`OrderBook.refresh()` 仅将进行中状态和完成状态 `56` 放入 `OrderBook.data`。撤销、拒绝等订单会被过滤；超时订单发出 `cancel_by_id()` 后也会直接跳过。`State.reconcile()` 因此找不到对应 `added_order_id`，只能保持原有 `added_status=ING`。
+
+影响：状态文件可能长期显示“处理中”，而 `added_num` 已经递增。系统目前未定义以下情况是否消耗补仓档位：
+
+- 委托完全拒绝；
+- 撤单且零成交；
+- 部分成交后撤单。
+
+建议：使对账可获得终态订单，或在订单簿中显式传递终态映射；为上述三种情况定义 `added_status`、`added_qty` 和 `added_num` 的最终规则，并增加回归测试。
+
+### P1：下单成功但状态文件保存失败时，重启恢复会丢失补仓层级
+
+补仓路径顺序是 `orders.place()` 成功后，再执行 `state.set()` 与 `state.save()`。若保存失败，当前进程仍有订单簿方向锁，但程序重启后状态文件不含本次补仓。`sync_positions()` 只能接管当前持仓，不能从持仓推导历史补仓次数，因此存在重复使用补仓档位的风险。
+
+建议：捕获并明确处理 `state.save()` 失败；至少将其作为不可忽略的交易一致性故障告警。若要求重启后绝不重复补仓，需要可恢复的补仓事件记录或可查询的成交历史作为补偿来源。
+
+### P2：每轮对账会执行两次状态文件写入
+
+`reconcile()` 调用 `sync_positions()`，而 `sync_positions()` 无条件 `save()`；`reconcile()` 结束时又再次 `save()`。这不改变正确性，但每 30 秒至少两次磁盘原子替换。
+
+建议：让 `sync_positions()` 返回是否发生变化，由 `reconcile()` 统一进行一次保存。
+
+### P2：底仓订单字段与当前开仓流程不一致
+
+开仓路径不再创建 `StateItem`，而首次出现真实持仓时由 `sync_positions()` 建立底仓状态。因此新开仓的 `base_order_id` 通常为空，底仓订单状态对账主要只适用于遗留/外部写入的数据。
+
+建议：保留该字段前，应明确它是否仍承担审计用途；否则可在后续数据模型整理时移除无效的底仓订单状态分支。
+
+## 测试覆盖
+
+现有测试覆盖了拆单全成后状态改为 `OK`、补仓档位边界和订单簿方向锁，但没有覆盖：
+
+- 补仓单撤销、拒绝、部分成交后的状态和次数；
+- `state.save()` 在下单成功后失败的恢复处理；
+- 启动恢复后的补仓层级保持；
+- 状态项随平仓删除的边界。
+
+在 `py-client` 目录运行 `python -m compileall -q .` 通过。现有全量单测仍有趋势替身接口不匹配及 IPO 调用契约问题，无法作为状态机全绿的证明。