# Python 3.14 客户端

运行目标为 Windows x64、标准 CPython 3.14；本次验证版本为 3.14.7。
迁移仅针对本目录，QMT 服务端及其内置 Python 不变。

## 安装与运行

在 `py-client` 目录执行 PowerShell 命令：

```powershell
py -3.14 -m venv .venv
.venv/Scripts/python.exe -m pip install -r requirements.txt
.venv/Scripts/python.exe -m pip check
.venv/Scripts/python.exe main.py
```

`requirements.txt` 锁定本次在 Python 3.14 下实际验证的完整依赖版本。
不要复用 Python 3.11 的虚拟环境。`.python-version` 为支持该文件的工具声明版本。

## 优化范围与行为约束

已审查本目录全部 39 个原有 Python 源文件；只修改有适用优化或迁移需求的文件。

- 移除旧的 `from __future__ import annotations`，使用 Python 3.14 原生延迟求值注解，前向引用不再手工加引号。验证所有业务模块、类及方法注解可正常解析。
- 订单时间解析采用上限 4096 项的 LRU 缓存；每次刷新只读取一次时间和转换一次订单状态。缓存键为日期与时间原值，订单字段变化立即生效，继续使用原 `strptime` 解析规则。
- 信号时间边界解析采用上限 256 项的 LRU 缓存，当前时刻与允许交易的结果不缓存。
- 趋势、做 T 信号筛选直接查持仓字典，避免逐信号扫描持仓列表；候选顺序、重复信号及行情请求顺序不变。
- 交易时段常量复用，订单方向映射复用；避免构建单元素集合、合并校验列表和已存在状态的默认对象。
- 保持原浮点计算、价格阈值、资金规则、调度频率、线程结构、HTTP 重试、SQLite 事务及深复制隔离语义。

未启用 free-threaded Python、JIT 或多解释器线程池。现有交易任务共享客户端、锁和可变状态，切换并发模型不是等价替换。
延迟注解的运行时读取语义由原字符串注解变为按需求值，外部 SDK 调用者若需要字符串形式，应使用 `annotationlib.get_annotations(..., format=Format.STRING)`。

官方说明：[Python 3.14 延迟注解](https://docs.python.org/3.14/whatsnew/3.14.html#pep-649-pep-749-deferred-evaluation-of-annotations)。

## 验证与性能

```powershell
.venv/Scripts/python.exe -B -m unittest discover -s tests -v
.venv/Scripts/python.exe -B benchmarks/hotpaths.py
```

130 项离线测试通过，覆盖 SDK 与 API 字段契约、委托簿、配置校验、IPO 申购状态机、
ZT 轮次状态机（正T/反T）、Trend 采集任务与 Python 3.14 回归。
测试使用模拟客户端和临时目录，不启动真实交易、不访问真实接口。

同一 CPython 3.14.7、原算法与优化算法对比；每组重复 5 次取中位数：

| 场景 | 原算法 µs/次 | 优化后 µs/次 | 倍率 |
| --- | ---: | ---: | ---: |
| 订单日期解析（缓存命中） | 4.263 | 0.061 | 69.90× |
| 信号时间边界解析（缓存命中） | 0.230 | 0.045 | 5.09× |
| 交易时段判断（下午） | 0.413 | 0.183 | 2.25× |
| 订单方向解析 | 0.163 | 0.092 | 1.78× |
| 1000 持仓、2000 信号筛选 | 13127.276 | 67.827 | 193.54× |

以上是局部微基准，缓存未命中仍执行原解析逻辑；不是 3.11 对 3.14 的整轮交易加速数据。
网络及数据库耗时未纳入，未做实盘端到端性能测量。

## 基线问题

修改前 18 项测试中 12 项失败，原因是模型仅有 `get_local_order_id` 属性，调用处却使用缺失的 `local_order_id`，存储层还将属性当方法调用。
本次增加同一属性的兼容别名，并统一存储层属性访问，保留原属性名和 API 数据字段；这些是使既有撤单、成交对账测试恢复的接口修复。

## ZT 做 T 策略（2026-09 重构）

ZT 已从"本地 SQLite 重算持仓 + base/added 分桶归档"改为**正T/反T 轮次状态机**：
持仓数量只以券商快照为准，本地只记录"意图与两条腿的状态"。设计说明见
[../docs/zt.md](../docs/zt.md)。

- 新增状态文件 `{qmt_data_dir}/zt_{account_id}_rounds.json`，旧的
  `zt_{account_id}_state.db` 不再读写，保留作为审计记录。
- `libs/state.py` 及 `strategy/zt/{open,positions,profit}.py` 已删除。
- **不接管账户已有持仓**：只有本策略自己建仓（`base_source=opened`）的证券
  才被管理，其它持仓原样保留、不做 T，日志以 `[ZT跳过]`/`[ZT汇总] 未接管=N`
  体现。升级时会丢弃状态文件里旧版本留下的"接管"记录。
- `zt_sell_ratio`、`zt_buy_fall_pct`、`zt_max_price` 现在真正生效；
  新增 `zt_t_band_pct`（默认 1.0）与 `zt_max_hold_days`（默认 5）。
- ZT 日志带 `[ZT启动]/[ZT成交]/[ZT状态]/[ZT轮次]/[ZT决策]/[ZT下单]/[ZT跳过]/
  [ZT汇总]/[ZT异常]` 标签，可直接 grep 定位问题；
  其中 `[ZT决策]` 每只证券每轮一行，写明最终动作或等待原因。