219 lines
6.4 KiB
Markdown
219 lines
6.4 KiB
Markdown
# 涨停连板概览接口文档
|
||
|
||
## 1. 接口说明
|
||
|
||
- 接口名称：涨停连板概览
|
||
- 请求方式：`GET`
|
||
- 请求路径：`/api/v1/limit-board/overview`
|
||
- 接口用途：查询指定交易日的涨停股票，按连板高度分组返回，并附带近 30 个交易日的每日最高连板数。
|
||
|
||
## 2. 请求参数
|
||
|
||
| 参数名 | 类型 | 必填 | 示例 | 说明 |
|
||
| --- | --- | --- | --- | --- |
|
||
| `trade_date` | `string` | 是 | `2026-04-24` | 交易日，格式固定为 `YYYY-MM-DD` |
|
||
|
||
请求示例：
|
||
|
||
```http
|
||
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. 响应示例
|
||
|
||
```json
|
||
{
|
||
"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. 空数据说明
|
||
|
||
当指定交易日没有涨停数据时，返回：
|
||
|
||
```json
|
||
{
|
||
"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` 参数时：
|
||
|
||
```json
|
||
{
|
||
"error": "trade_date 参数不能为空"
|
||
}
|
||
```
|
||
|
||
当服务端内部异常时：
|
||
|
||
```json
|
||
{
|
||
"error": "具体错误信息"
|
||
}
|
||
```
|