新增接口及接口文档

docs/stock-analyze.md

@@ -0,0 +1,108 @@
+# 涨停表现分析接口文档
+
+## 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_data.status = 1` 的涨停股票。
+- `start_date` 用于确定样本池，即当日涨停股票。
+- `end_date` 用于限定后续表现统计区间。
+- 如果某只股票在区间内只有涨停当天数据，则不会进入最终结果。
+
+## 7. 空数据说明
+
+当指定交易日没有涨停股票，返回空数组：
+
+```json
+[]
+```
+
+## 8. 错误响应
+
+当请求体绑定失败时：
+
+```json
+{
+  "error": "参数错误"
+}
+```
+
+当服务端内部异常时：
+
+```json
+{
+  "error": "具体错误信息"
+}
+```