go/docs/limit-board-overview.md

涨停连板概览接口文档

1. 接口说明

• 接口名称：涨停连板概览
• 请求方式：GET
• 请求路径：/api/v1/limit-board/overview
• 接口用途：查询指定交易日的涨停股票，按连板高度分组返回，并附带近 30 个交易日的每日最高连板数。

2. 请求参数

参数名	类型	必填	示例	说明
trade_date	string	是	2026-04-24	交易日，格式固定为 YYYY-MM-DD

请求示例：

GET /api/v1/limit-board/overview?trade_date=2026-04-24

3. 响应说明

3.1 顶层字段

字段名	类型	说明
trade_date	string	查询的交易日
summary	object	当日涨停摘要信息
recent_max_board_stats	array	近 30 个交易日每天的最高连板数
groups	array	按连板高度分组后的股票列表，已按板数从高到低排序

3.2 summary 字段

字段名	类型	说明
max_board_count	int	当天最高连板数
limit_count	int	当天涨停股票总数
group_count	int	当天连板分组数量

3.3 recent_max_board_stats 字段

字段名	类型	说明
trade_date	string	交易日
max_board_count	int	该交易日市场最高连板数

3.4 groups 字段

字段名	类型	说明
board_count	int	当前分组对应的连板数
label	string	当前分组显示文案，如 首板、二板、三板
count	int	当前分组内股票数量
stocks	array	当前分组内的股票列表

3.5 groups[].stocks 字段

字段名	类型	说明
symbol	string	股票代码
ts_code	string	TS 股票代码
name	string	股票名称
market	string	所属板块或市场信息
trade_date	string	交易日
close	number	收盘价
limit_price	number	理论涨停价
pct_chg	number	当日涨跌幅
ak_amount	number | null	AKShare 成交额
ak_float_market_value	number | null	AKShare 流通市值
ak_total_market_value	number | null	AKShare 总市值
ak_turnover_rate	number | null	AKShare 换手率
ak_seal_amount	number | null	AKShare 封板资金
ak_first_limit_time	string | null	Tushare 首次封板时间，可能为 09:35:12 或 93200 这类紧凑格式
ak_last_limit_time	string | null	AKShare 最后封板时间
ak_break_limit_count	int | null	AKShare 炸板次数
ak_limit_up_stat	string | null	AKShare 涨停统计
ak_limit_up_days	int | null	AKShare 连板数
ak_industry	string | null	AKShare 所属行业
vol	int | null	成交量
board_count	int	该股票对应的连续涨停板数
board_label	string	连板展示文案，如 首板、二板
display_status	string	页面可直接使用的状态文案，当前与 board_label 一致

4. 响应示例

{
  "trade_date": "2026-04-24",
  "summary": {
    "max_board_count": 4,
    "limit_count": 23,
    "group_count": 4
  },
  "recent_max_board_stats": [
    {
      "trade_date": "2026-03-16",
      "max_board_count": 2
    },
    {
      "trade_date": "2026-03-17",
      "max_board_count": 3
    },
    {
      "trade_date": "2026-04-24",
      "max_board_count": 4
    }
  ],
  "groups": [
    {
      "board_count": 4,
      "label": "四板",
      "count": 1,
      "stocks": [
        {
          "symbol": "000001",
          "ts_code": "000001.SZ",
          "name": "示例股份",
          "market": "主板",
          "trade_date": "2026-04-24",
          "close": 12.35,
          "limit_price": 12.35,
          "pct_chg": 10.01,
          "ak_amount": 1523000000,
          "ak_float_market_value": 8245000000,
          "ak_total_market_value": 12678000000,
          "ak_turnover_rate": 18.64,
          "ak_seal_amount": 286000000,
          "ak_first_limit_time": "09:35:12",
          "ak_last_limit_time": "14:42:08",
          "ak_break_limit_count": 2,
          "ak_limit_up_stat": "4天4板",
          "ak_limit_up_days": 4,
          "ak_industry": "软件开发",
          "vol": 123456789,
          "board_count": 4,
          "board_label": "四板",
          "display_status": "四板"
        }
      ]
    }
  ]
}

5. 排序规则

• groups 按 board_count 从大到小排序。
• 每个分组内的 stocks 按 pct_chg 从大到小排序。
• 如果 pct_chg 相同，则按 ts_code 升序排序。
• recent_max_board_stats 按交易日升序排序。

6. 业务规则

• 只统计 stock_limit_combined_data.final_status = 1 的记录，即涨停股票。
• 连板数的计算会结合 trade_calendar 开市日历处理，不会被周末或节假日打断。
• 首板、二板、三板等分组由后端直接计算，前端不需要二次处理。
• summary.max_board_count 即当天涨停强度最高的板数。
• recent_max_board_stats 返回截至查询日近 30 个交易日的每日最高连板数。

7. 空数据说明

当指定交易日没有涨停数据时，返回：

{
  "trade_date": "2026-04-24",
  "summary": {
    "max_board_count": 0,
    "limit_count": 0,
    "group_count": 0
  },
  "recent_max_board_stats": [
    {
      "trade_date": "2026-03-16",
      "max_board_count": 2
    }
  ],
  "groups": []
}

说明：

• 如果 trade_date 是有效交易日，即使当天没有涨停数据，仍会返回近 30 个交易日的 recent_max_board_stats。
• 如果 trade_date 本身不是有效交易日，则返回空的 recent_max_board_stats 和空的 groups。

8. 前端对接建议

• 页面顶部可直接使用 summary 展示摘要卡片：
  • 当天最高连板数
  • 当天涨停总数
  • 当天分组数
• 趋势图可直接使用 recent_max_board_stats：
  • X 轴使用 trade_date
  • Y 轴使用 max_board_count
• 页面主体直接遍历 groups 渲染分组区块：
  • 分组标题使用 label
  • 分组数量使用 count
  • 股票列表使用 stocks

9. 错误响应

当缺少 trade_date 参数时：

{
  "error": "trade_date 参数不能为空"
}

当服务端内部异常时：

{
  "error": "具体错误信息"
}