ADR-0002：历史成交明细增加可选批量返回

状态：Accepted 日期：2026-09-12

背景

历史成交完整分页会将每条已解析的记录构造成 Python TradeTick，并转换逐条时间。 本机实验中，原接口增加 Slot 后吞吐未明显增长；跳过对象包装后，单进程随 Slot 增加获得明显收益。 批量原型在 75 秒测试中支持完整字段回放一致性和按列成交量汇总，但全部转换回对象后多数性能优势消失。 这些数值依赖机器、服务器和负载，不作为稳定吞吐保证。

决策

• 新增 client.trades.history_batch() 和 all_history_batch()，支持单个代码和代码列表。
• 保留所有既有方法签名、默认行为和 TradePage / TradeTick 类型。
• TradeBatch 持有不可变的扁平字段块，按列取值和按下标筛选不生成逐条对象。
• tick() / to_page() 是显式对象转换出口；项目 JSON 序列化对批量结果输出原 TradePage 的结构，并支付全部转换成本。
• 池化、Socket 和 pin transport 增加可选的直接批量转换能力。每次请求选择各自转换路径，不修改客户端全局转换状态。
• 原 Transport 协议不增加必需方法。自定义 transport 只有 execute() 时，可由既有 TradePage 转换为 TradeBatch；该回退路径没有省去原先的对象构造成本。
• 复用 Rust 0x0fc6 解析和原私有 DTO ABI，不新增协议、不改变 ABI、不引入第三方数组库。
• 完整分页反转页顺序、保留页内顺序。共享页字段块，避免在合并阶段逐条包装。

后果

旧用户无需迁移。主动选择批量入口的用户可以按列读取、筛选后仅转换部分记录。 TradeBatch 不冒充 TradePage，没有依赖隐式迭代完成全量对象构造的行为；内部 _blocks 不是公开格式。 字段列读取和筛选仍会分配结果，用户不应把此路径理解为零拷贝、无限内存或固定倍数提速。 此次只接入历史成交；当日成交及其他接口需另行验证，不自动推广。

验证

测试覆盖同一原始响应的新旧字段等价、JSON 等价、分页顺序和上限、空结果、代码列表、 新旧请求并发隔离、Socket/池/pin 转换及生命周期、自定义 transport 回退与按列访问不创建对象。 性能测量区分批量字段处理和全量对象物化，不将省略物化的结果等同于旧接口的端到端吞吐。