# 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
```

25 项离线测试通过，包括原 18 项测试和新增的时间边界、缓存上限、可变订单、信号顺序、原生注解回归测试。
测试使用模拟客户端、临时 SQLite 数据库，不启动真实交易。

同一 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 数据字段；这些是使既有撤单、成交对账测试恢复的接口修复。

审查还发现既有 `strategy/zt/boot.py` 向做 T 的 `manage_positions`、`open_signal` 提交的参数与函数签名不匹配。
本次未改其调度和资金流程，因此 25 项测试通过不代表该既有做 T 启动路径已可用于实盘。