单股同花顺主力大单查询

来源同步：/Users/mac/Projects/chatgpt-codex/doc/api_MonitorThsBigorder.md

所属接口集：同花顺主力大单

请求 URL

GET /v1/api/monitor/ths_bigorder

认证方式

Bearer Token（详见 认证与签名）

接口概述

按交易日路由数据源：

场景	数据源
交易日当天	源接口 {THS_MAIN_MONITOR_BASE_URL}/api/v1/main-monitor/{code}
非交易日的上一个交易日	同上（源接口只保留这一天，含 price_series）
更早的历史交易日	MySQL monitor_ths_bigorder_detail 拼成同源结构

日级聚合（对齐 monitor/agg）见 同花顺日级大单聚合：GET /v1/api/monitor/agg_ths。

Level2 盘口订阅见 同花顺 Level2 盘口推送：wss://stock-data-api.aibot6.cn/ws/ths/level2/orderbook/。
Level2 DDE 透传见 同花顺 Level2 DDE：GET /v1/api/monitor/ths_level2_dde。

设计目标：源接口路径仍尽量快（少改写）；历史路径字段结构与源接口对齐（含 include_items / nature）。

相对腾讯大单链路（monitor/agg / monitor:dadan）更细：明细区分 主力主买 / 主力被买 / 主力主卖 / 主力被卖 四种性质。

上游的 price_series（按时间的分时涨幅序列）与 items（主力大单明细）一并返回；price_series 始终保留字段。历史 MySQL：若入库时已写入明细 change_pct，会重建简版 price_series；否则为空数组 []。

请求参数

参数	类型	必填	说明
code	string	是	6 位股票代码，如 002741；也接受 002741.SZ。别名：stock_code / codes（多码时仅取第一个）
trade_day	string	否	按日查询：YYYYMMDD 或 YYYY-MM-DD。别名：day。省略时走「源接口日」
include_items	int	否	默认保留明细；传 0 时去掉 items（price_series 仍会返回，历史为空数组）
nature	string	否	过滤明细：active_buy,passive_buy,active_sell,passive_sell（源接口与 MySQL 路径均支持）

源接口日最快：只传 code，不要带 nature / include_items=0。

路由规则

1. 源接口日 = 今天是交易日则今天；否则为上一个交易日（交易日历 _is_trading_day）
2. 未传 trade_day，或 trade_day 等于源接口日 → 读 Redis 缓存（Key：{REDIS_KEY_PREFIX}:ths:bigorder:{code6}）；软新鲜度内不打源；过期才拉源回写；拉源失败不覆盖旧缓存
3. trade_day 早于源接口日 → 直接读 MySQL（不经 Redis 缓存；按该日精确匹配，不自动回落到周五）
4. 源接口 JSON 本身无 trade_day：本接口补写
5. 扫 items[] 第一条可解析的 original_time：
   • "HH:MM:SS" → 日历今天（当天数据）
   • "YYYY-MM-DD HH:MM:SS" → 该日期（历史数据）
6. items 为空（如开盘前）→ 兜底日历今天（is_trading 只表示是否交易时段，不用于推断交易日）
7. MySQL 入库行必有 trade_day，历史响应直接用库字段

接口说明

• 数据源：MARKET_CONF.THS_MAIN_MONITOR_BASE_URL（默认 http://192.168.7.50:8802）
• 超时：THS_MAIN_MONITOR_TIMEOUT_SEC（默认 2 秒）；HTTP 无重试、keep-alive 连接池
• 源路径缓存：THS_BIGORDER_POLL_MS（默认 5000，软新鲜度）；Redis Key {prefix}:ths:bigorder:{code6}；硬 TTL THS_REDIS_TTL_SEC（默认 86400）
• data.source："ths"（源接口/缓存）或 "mysql"（历史，直读库不缓存）
• data.trade_day：YYYY-MM-DD
• data.free_float_shares：流通股本（股）。仅读 Redis
  {REDIS_KEY_PREFIX}:monitor:bigdata:{YYYYMMDD}:{code6} 的 free_float_shares；
  交易日用当天、非交易日用上个交易日；无值不兜底（字段为 null）
• price_series
• 输出时按 time 正序（最早在前），格式 YYYYMMDDHHmm
• Redis 写入前同样正序规范化

字段	类型	说明
time	string	时间点，格式 YYYYMMDDHHmm，如 202608120930
change_pct	float	该时点相对昨收的涨跌幅（百分比数值）

• items
• 输出 / Redis 缓存：按 time 倒序（最新在前）

• ingest_ths_bigorder_detail 入库：按 time 正序写入（不改动已落库的历史正式数据；仅影响新采集顺序）

• 四种明细性质

nature	raw_nature
active_buy	主力主买
passive_buy	主力被买
active_sell	主力主卖
passive_sell	主力被卖

• 汇总口径
• 源接口：main_buy / main_sell / main_net 透传
• MySQL：main_buy = trade_type=1（或 buy natures）的 amount 之和；main_sell = trade_type=2；main_net = 买 − 卖
• flow_state / flow_state_code（与 GET /v1/api/strategy/flow 同算法）
• 对完整 items + price_series 选取 bigorder_1（pick_auction_bigorder_1），再 classify_flow_state
• 在 include_items=0 / nature 过滤前计算，避免删明细影响判定
• 未能分类时两字段均为 null
• 码表见 资金流策略（如 accumulation→吸筹、washout→洗盘）
• 字段名对齐：code / name / price / change_pct / is_trading / price_series / items / volume_lot / flow_state / flow_state_code 等
• 历史：顶层 change_pct 为 null，is_trading 为 false；name/price 取自明细；items[].change_pct 为入库字段；price_series 由明细重建（旧数据未回填则为 []）
• 源接口不可用或 success=false 时（源接口路径）返回 HTTP 503；历史无明细时仍 200，返回空 items 与 0 汇总

响应格式示例（源接口）

{
  "code": 1,
  "message": "success",
  "data": {
    "success": true,
    "source": "ths",
    "code": "002741",
    "name": "光华科技",
    "price": 25.49,
    "change_pct": 2.25,
    "is_trading": false,
    "trade_day": "2026-08-14",
    "free_float_shares": 19405918000,
    "main_buy": 87427400,
    "main_sell": 76638300,
    "main_net": 10789100,
    "flow_state": "高承接拉升",
    "flow_state_code": "high_absorption_rally",
    "price_series": [
      {"time": "202608120930", "change_pct": 0.6017},
      {"time": "202608120931", "change_pct": -0.2006}
    ],
    "items": [
      {
        "nature": "active_buy",
        "raw_nature": "主力主买",
        "volume_lot": 338,
        "amount": 861562,
        "price": 25.49,
        "time": "15:00:00",
        "original_time": "15:00:00",
        "trade_type": "1"
      }
    ]
  }
}

响应格式示例（历史 MySQL）

{
  "code": 1,
  "message": "success",
  "data": {
    "success": true,
    "source": "mysql",
    "code": "002741",
    "name": "光华科技",
    "price": 25.49,
    "change_pct": null,
    "is_trading": false,
    "trade_day": "2026-08-12",
    "free_float_shares": 19405918000,
    "main_buy": 861562,
    "main_sell": 0,
    "main_net": 861562,
    "flow_state": null,
    "flow_state_code": null,
    "price_series": [],
    "items": [
      {
        "nature": "active_buy",
        "raw_nature": "主力主买",
        "volume_lot": 338,
        "amount": 861562,
        "price": 25.49,
        "time": "15:00:00",
        "original_time": "15:00:00",
        "trade_type": "1"
      }
    ]
  }
}

返回状态

状态码	说明
200	成功
400	参数错误（缺少/非法 code，或非法 trade_day）
401	未认证
403	无权限
503	上游同花顺服务不可用（仅源接口路径）

环境变量

变量	默认	说明
THS_MAIN_MONITOR_BASE_URL	http://192.168.7.50:8802	源服务根地址
THS_MAIN_MONITOR_TIMEOUT_SEC	2	请求超时秒（无重试）
THS_BIGORDER_POLL_MS	5000	源接口写 Redis / 软新鲜度（毫秒）
THS_REDIS_TTL_SEC	86400	ths:bigorder:* Redis 键硬过期（秒，默认 24h）

---