"""演示：获取历史逐笔成交数据。

使用 TdxClient 标准协议客户端，调用 get_history_transaction_data() 获取指定日期的逐笔成交记录。
date 参数为 YYYYMMDD 格式的整数（如 20250110），支持分页查询。

DataFrame 列说明:
  datetime   str     成交时间 "HH:MM:SS"（协议精度仅到分钟）
  price      float   成交价格（元）
  vol        int     成交量（股）
  num        int     成交笔数（该笔成交包含的撮合笔数）
  buyorsell  int     成交方向: 0=买盘, 1=卖盘, 2=中性/撮合, 8=集合竞价

数据特点:
  - start=0 表示获取最近 count 条，向后翻页递增 start
  - 历史数据覆盖范围与服务器数据保留策略有关
  - 可用于历史成交分布分析、大单统计、资金流向计算等
"""

from easy_tdx import Market, TdxClient

with TdxClient.from_best_host() as c:
    date = 20250110
    df = c.get_history_transaction_data(Market.SH, "600000", date, 0, 20)
    df["方向"] = df["buyorsell"].map({0: "买", 1: "卖", 2: "中性", 8: "集合竞价"})
    print(f"浦发银行 {date} 最近 {len(df)} 笔成交:")
    print(df[["datetime", "price", "vol", "方向"]].to_string(index=False))

# 运行结果:
# 浦发银行 20250110 最近 20 笔成交:
#             datetime  price   vol 方向
# 2025-01-10 14:56:00  10.25  1000   买
# 2025-01-10 14:56:00  10.25   200   买
# 2025-01-10 14:56:00  10.24   500   卖
# 2025-01-10 14:56:00  10.25   300   买
# 2025-01-10 14:56:00  10.24   800   卖
# 2025-01-10 14:56:00  10.25   100   买
# 2025-01-10 14:57:00  10.25   500   中性
# 2025-01-10 14:57:00  10.25   200   中性
# 2025-01-10 14:57:00  10.25   400   中性
# 2025-01-10 14:57:00  10.25   100   中性
# 2025-01-10 14:57:00  10.24   300   中性
# 2025-01-10 14:57:00  10.25   600   中性
# 2025-01-10 14:57:00  10.25   150   中性
# 2025-01-10 14:57:00  10.24   250   中性
# 2025-01-10 14:57:00  10.25   350   中性
# 2025-01-10 14:57:00  10.25   400   中性
# 2025-01-10 14:58:00  10.25   200   中性
# 2025-01-10 14:58:00  10.25   100   中性
# 2025-01-10 14:58:00  10.25   300   中性
# 2025-01-10 14:59:00  10.25  5000  集合竞价