# 涨停表现分析接口文档

## 1. 接口说明

- 接口名称：涨停表现分析
- 请求方式：`POST`
- 请求路径：`/api/v1/stock/analyze`
- 接口用途：基于指定涨停日，分析当日涨停股票在后续区间内的表现。

## 2. 请求参数

请求体类型：`application/json`

| 参数名 | 类型 | 必填 | 示例 | 说明 |
| --- | --- | --- | --- | --- |
| `start_date` | `string` | 是 | `2026-04-24` | 涨停发生日，格式 `YYYY-MM-DD` |
| `end_date` | `string` | 是 | `2026-05-30` | 统计截止日，格式 `YYYY-MM-DD` |

请求示例：

```http
POST /api/v1/stock/analyze
Content-Type: application/json

{
  "start_date": "2026-04-24",
  "end_date": "2026-05-30"
}
```

## 3. 响应说明

返回值为数组，每个元素代表一只在 `start_date` 涨停的股票。

| 字段名 | 类型 | 说明 |
| --- | --- | --- |
| `code` | `string` | TS 股票代码 |
| `name` | `string` | 股票名称 |
| `day_open` | `number` | 涨停当日开盘价 |
| `day_high` | `number` | 涨停当日最高价 |
| `max_high` | `number` | 逻辑最高点价格 |
| `max_date` | `string` | 逻辑最高点对应日期 |
| `overall_max_high` | `number` | 统计区间内绝对最高价 |
| `overall_max_date` | `string` | 统计区间内绝对最高价对应日期 |
| `post_min_low` | `number` | 涨停日之后的最低价 |
| `drop_pct` | `number \| null` | 从逻辑高点到最低点的降幅，未跌破时为空 |
| `rebound_pct` | `number \| null` | 强势形态下的上涨幅度，或破位后的反弹幅度 |
| `close_prices` | `array[number]` | 区间内收盘价序列，用于前端绘图 |

## 4. 响应示例

```json
[
  {
    "code": "000001.SZ",
    "name": "示例股份",
    "day_open": 10.12,
    "day_high": 11.13,
    "max_high": 12.65,
    "max_date": "2026-04-29",
    "overall_max_high": 12.88,
    "overall_max_date": "2026-05-06",
    "post_min_low": 9.94,
    "drop_pct": 21.42,
    "rebound_pct": 8.36,
    "close_prices": [11.13, 10.88, 10.25, 11.02, 10.77]
  }
]
```

## 5. 排序规则

- 返回数组优先按 `drop_pct` 从大到小排序。
- `drop_pct` 不为空的股票排在前面。
- `drop_pct` 为空的股票排在后面。

## 6. 业务规则

- 仅统计 `stock_limit_combined_data.final_status = 1` 的涨停股票。
- `start_date` 用于确定样本池，即当日涨停股票。
- `end_date` 用于限定后续表现统计区间。
- 如果某只股票在区间内只有涨停当天数据，则不会进入最终结果。

## 7. 空数据说明

当指定交易日没有涨停股票，返回空数组：

```json
[]
```

## 8. 错误响应

当请求体绑定失败时：

```json
{
  "error": "参数错误"
}
```

当服务端内部异常时：

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