修改二板涨停情况查询，新增按条件筛选

docs/download-second-board-profit-csv.md

@@ -1,69 +1,182 @@
-# 二板早盘次日盈利 CSV 下载接口文档
+# 二板早盘次日盈利接口文档
 
 ## 1. 接口说明
 
-- 接口名称：二板早盘次日盈利 CSV 下载
-- 请求方式：`GET`
-- 请求路径：`/api/v1/download/limit-board/second-board-profit-csv`
-- 接口用途：下载符合二板早盘开盘阈值条件的股票明细，并查看后一交易日是否盈利。
+本页包含二板早盘次日盈利的列表查询接口和 CSV 下载接口。两个接口使用同一套查询条件和同一套返回字段；列表接口分页，CSV 下载接口导出筛选后的全量数据。
 
-## 2. 请求参数
+业务筛选基础条件：
+
+- T-2 交易日无涨停。
+- T-1 交易日涨停。
+- T 交易日涨停。
+
+## 2. 接口地址
+
+| 接口名称 | 请求方式 | 请求路径 | 说明 |
+| --- | --- | --- | --- |
+| 二板早盘次日盈利列表查询 | `GET` | `/api/v1/limit-board/second-board-profit` | 前端页面分页展示数据 |
+| 二板早盘次日盈利 CSV 下载 | `GET` | `/api/v1/download/limit-board/second-board-profit-csv` | 下载筛选条件范围内的全量 CSV 数据 |
+
+## 3. 请求参数
 
 | 参数名 | 类型 | 必填 | 默认值 | 示例 | 说明 |
 | --- | --- | --- | --- | --- | --- |
-| `start_date` | `string` | 否 | `2020-01-01` | `2026-01-01` | 开始交易日期，格式固定为 `YYYY-MM-DD` |
-| `end_date` | `string` | 否 | `2026-12-31` | `2026-12-31` | 结束交易日期，格式固定为 `YYYY-MM-DD` |
+| `tradeStartDate` | `string` | 否 | `2020-01-01` | `2026-01-01` | 交易日开始日期，格式固定为 `YYYY-MM-DD` |
+| `tradeEndDate` | `string` | 否 | `2026-12-31` | `2026-12-31` | 交易日结束日期，格式固定为 `YYYY-MM-DD` |
+| `limitUpTimeFilterType1` | `string` | 否 | 空 | `>=` | T 日首次涨停时间第一组筛选操作符，支持 `<`、`>`、`<=`、`>=`、`=` |
+| `limitUpTimeFilterValue1` | `string` | 否 | 空 | `09:30:00` | T 日首次涨停时间第一组筛选值 |
+| `limitUpTimeFilterType2` | `string` | 否 | 空 | `<` | T 日首次涨停时间第二组筛选操作符，支持 `<`、`>`、`<=`、`>=`、`=` |
+| `limitUpTimeFilterValue2` | `string` | 否 | 空 | `11:00:00` | T 日首次涨停时间第二组筛选值 |
+| `openPctChgFilterType1` | `string` | 否 | 空 | `>=` | T 日开盘涨跌幅第一组筛选操作符，支持 `<`、`>`、`<=`、`>=`、`=` |
+| `openPctChgFilterValue1` | `number` | 否 | 空 | `-2` | T 日开盘涨跌幅第一组筛选值，按 `(T日开盘价 - T-1收盘价) / T-1收盘价 * 100` 计算 |
+| `openPctChgFilterType2` | `string` | 否 | 空 | `<=` | T 日开盘涨跌幅第二组筛选操作符，支持 `<`、`>`、`<=`、`>=`、`=` |
+| `openPctChgFilterValue2` | `number` | 否 | 空 | `3` | T 日开盘涨跌幅第二组筛选值，按 `(T日开盘价 - T-1收盘价) / T-1收盘价 * 100` 计算 |
+| `page` | `int` | 否 | `1` | `1` | 仅列表接口支持，页码从 1 开始 |
+| `pageSize` | `int` | 否 | `10` | `20` | 仅列表接口支持，每页数量 |
 
-- `start_date` 可以等于 `end_date`，用于下载单日数据。
-- `end_date` 不能早于 `start_date`。
+兼容说明：CSV 下载接口仍兼容旧参数 `start_date` 和 `end_date`，建议新调用统一使用 `tradeStartDate` 和 `tradeEndDate`。
 
-请求示例：
+筛选规则：
+
+- 每个筛选项最多支持两组条件，第一组为 `Type1 + Value1`，第二组为 `Type2 + Value2`。
+- 四个值都可以为空；当某组 `Type` 和 `Value` 都为空时，该组条件不生效。
+- 如果某组条件生效，`Type` 和 `Value` 必须同时填写。
+- 两组条件同时存在时按 AND 关系过滤，可用于表达区间，例如 `>=09:30:00` 且 `<11:00:00`。
+- 时间值支持 `HH:MM`、`HH:MM:SS`、`HHMM`、`HHMMSS` 格式。
+- 实际请求 URL 中 `<`、`>`、`=` 等字符建议做 URL 编码，例如 `>=` 编码为 `%3E%3D`，`<` 编码为 `%3C`。
+- 后端也兼容数组式传参，例如 `limitUpTimeFilter[]=%3E%3D&limitUpTimeFilter[]=09:30:00&limitUpTimeFilter[]=%3C&limitUpTimeFilter[]=11:00:00`，数组四个值的含义依次等同于 `Type1`、`Value1`、`Type2`、`Value2`。
+
+## 4. 请求示例
+
+列表查询：
 
 ```http
-GET /api/v1/download/limit-board/second-board-profit-csv?start_date=2026-01-01&end_date=2026-12-31
+GET /api/v1/limit-board/second-board-profit?tradeStartDate=2026-01-01&tradeEndDate=2026-12-31&page=1&pageSize=10
 ```
 
-单日下载示例：
+带筛选条件的列表查询：
 
 ```http
-GET /api/v1/download/limit-board/second-board-profit-csv?start_date=2026-04-29&end_date=2026-04-29
+GET /api/v1/limit-board/second-board-profit?tradeStartDate=2026-04-01&tradeEndDate=2026-04-30&limitUpTimeFilterType1=%3E%3D&limitUpTimeFilterValue1=09:30:00&limitUpTimeFilterType2=%3C&limitUpTimeFilterValue2=11:00:00&openPctChgFilterType1=%3E%3D&openPctChgFilterValue1=-2&openPctChgFilterType2=%3C%3D&openPctChgFilterValue2=3&page=1&pageSize=20
 ```
 
-## 3. 响应说明
+CSV 下载：
+
+```http
+GET /api/v1/download/limit-board/second-board-profit-csv?tradeStartDate=2026-04-01&tradeEndDate=2026-04-30&limitUpTimeFilterType1=%3E%3D&limitUpTimeFilterValue1=09:30:00&limitUpTimeFilterType2=%3C&limitUpTimeFilterValue2=11:00:00&openPctChgFilterType1=%3E%3D&openPctChgFilterValue1=-2&openPctChgFilterType2=%3C%3D&openPctChgFilterValue2=3
+```
+
+## 5. 列表响应
+
+| 字段名 | 类型 | 说明 |
+| --- | --- | --- |
+| `trade_start_date` | `string` | 查询交易日开始日期 |
+| `trade_end_date` | `string` | 查询交易日结束日期 |
+| `limit_up_time_filter_type1` | `string` | 首次涨停时间第一组筛选操作符 |
+| `limit_up_time_filter_value1` | `string` | 首次涨停时间第一组筛选值 |
+| `limit_up_time_filter_type2` | `string` | 首次涨停时间第二组筛选操作符 |
+| `limit_up_time_filter_value2` | `string` | 首次涨停时间第二组筛选值 |
+| `open_pct_chg_filter_type1` | `string` | T 日开盘涨跌幅第一组筛选操作符 |
+| `open_pct_chg_filter_value1` | `string` | T 日开盘涨跌幅第一组筛选值 |
+| `open_pct_chg_filter_type2` | `string` | T 日开盘涨跌幅第二组筛选操作符 |
+| `open_pct_chg_filter_value2` | `string` | T 日开盘涨跌幅第二组筛选值 |
+| `page` | `int` | 当前页码 |
+| `page_size` | `int` | 每页数量 |
+| `total` | `int` | 筛选后的总记录数 |
+| `total_pages` | `int` | 总页数 |
+| `list` | `array` | 当前页数据 |
+
+`list[]` 字段：
+
+| 字段名 | 类型 | CSV 列名 | 说明 |
+| --- | --- | --- | --- |
+| `trade_date` | `string` | `交易日` | T 日交易日 |
+| `ts_code` | `string` | `股票代码` | TS 股票代码 |
+| `name` | `string` | `股票简称` | 股票简称 |
+| `market` | `string` | `市场` | 市场信息 |
+| `industry` | `string` | `行业` | 所属行业 |
+| `next_open_profitable` | `string` | `T+1开盘是否盈利` | T+1 开盘收益大于 0 时为 `是`，否则为 `否`；无次日数据时为 `无次日数据` |
+| `next_close_profitable` | `string` | `T+1收盘是否盈利` | T+1 收盘收益大于 0 时为 `是`，否则为 `否`；无次日数据时为 `无次日数据` |
+| `next_intraday_profitable` | `string` | `T+1盘中是否可盈利` | T+1 最高收益大于 0 时为 `是`，否则为 `否`；无次日数据时为 `无次日数据` |
+| `next_high_profit_pct` | `number \| null` | `T+1最高盈利%` | T+1 最高价相对 T 日收盘价的收益率百分比 |
+| `next_low_profit_pct` | `number \| null` | `T+1最低盈利%` | T+1 最低价相对 T 日收盘价的收益率百分比 |
+| `break_limit_count` | `int \| null` | `开板次数` | T 日开板次数 |
+| `turnover_rate_pct` | `number \| null` | `换手率%` | T 日换手率 |
+| `first_limit_time` | `string` | `首次涨停时间` | T 日首次涨停时间，格式化为 `HH:MM:SS` |
+| `seal_amount` | `number \| null` | `封单额` | T 日封单额 |
+| `amount` | `number \| null` | `成交额` | T 日成交额 |
+
+响应示例：
+
+```json
+{
+  "trade_start_date": "2026-04-01",
+  "trade_end_date": "2026-04-30",
+  "limit_up_time_filter_type1": ">=",
+  "limit_up_time_filter_value1": "09:30:00",
+  "limit_up_time_filter_type2": "<",
+  "limit_up_time_filter_value2": "11:00:00",
+  "open_pct_chg_filter_type1": ">=",
+  "open_pct_chg_filter_value1": "-2",
+  "open_pct_chg_filter_type2": "<=",
+  "open_pct_chg_filter_value2": "3",
+  "page": 1,
+  "page_size": 10,
+  "total": 26,
+  "total_pages": 3,
+  "list": [
+    {
+      "trade_date": "2026-04-24",
+      "ts_code": "000001.SZ",
+      "name": "示例股份",
+      "market": "主板",
+      "industry": "软件开发",
+      "next_open_profitable": "是",
+      "next_close_profitable": "否",
+      "next_intraday_profitable": "是",
+      "next_high_profit_pct": 4.21,
+      "next_low_profit_pct": -2.15,
+      "break_limit_count": 2,
+      "turnover_rate_pct": 18.64,
+      "first_limit_time": "09:35:12",
+      "seal_amount": 286000000,
+      "amount": 1523000000
+    }
+  ]
+}
+```
+
+## 6. CSV 响应
 
 - 响应类型：`text/csv; charset=utf-8`
 - 响应头：`Content-Disposition: attachment; filename="limit_second_board_profit_YYYYMMDD_YYYYMMDD_daily_detail.csv"`
 - CSV 文件带 UTF-8 BOM，便于 Excel 直接打开中文列名。
+- CSV 下载接口不分页，默认导出查询条件范围内的全部数据。
 
-## 4. CSV 字段
+CSV 字段顺序：
 
 | 字段名 | 说明 |
 | --- | --- |
-| `交易日` | 符合条件的交易日 |
-| `前一交易日` | 交易日的前一个交易日 |
-| `前二交易日` | 交易日的前两个交易日 |
-| `后一交易日` | 用于判断盈利的后一交易日 |
+| `交易日` | T 日交易日 |
 | `股票代码` | TS 股票代码 |
-| `股票简称` | 股票名称 |
+| `股票简称` | 股票简称 |
 | `市场` | 市场信息 |
 | `行业` | 所属行业 |
-| `T日开盘价` | 交易日开盘价 |
-| `T日收盘价` | 交易日收盘价 |
-| `T日涨停价` | 理论涨停价 |
-| `T-1收盘价` | 前一交易日收盘价 |
-| `开盘/T-1收盘%` | 交易日开盘价相对前一交易日收盘价的百分比 |
-| `首次涨停时间` | 交易日首次涨停时间，格式化为 `HH:MM:SS` |
-| `T+1开盘收益%` | 后一交易日开盘价相对 T 日收盘价的收益率 |
-| `T+1最高收益%` | 后一交易日最高价相对 T 日收盘价的收益率 |
-| `T+1收盘收益%` | 后一交易日收盘价相对 T 日收盘价的收益率 |
-| `T+1收盘是否盈利` | `T+1收盘收益% > 0` 时为 `是`，否则为 `否` |
-| `T+1盘中是否可盈利` | `T+1最高收益% > 0` 时为 `是`，否则为 `否` |
+| `T+1开盘是否盈利` | T+1 开盘收益大于 0 时为 `是`，否则为 `否`；无次日数据时为 `无次日数据` |
+| `T+1收盘是否盈利` | T+1 收盘收益大于 0 时为 `是`，否则为 `否`；无次日数据时为 `无次日数据` |
+| `T+1盘中是否可盈利` | T+1 最高收益大于 0 时为 `是`，否则为 `否`；无次日数据时为 `无次日数据` |
+| `T+1最高盈利%` | T+1 最高价相对 T 日收盘价的收益率百分比 |
+| `T+1最低盈利%` | T+1 最低价相对 T 日收盘价的收益率百分比 |
+| `开板次数` | T 日开板次数 |
+| `换手率%` | T 日换手率 |
+| `首次涨停时间` | T 日首次涨停时间，格式化为 `HH:MM:SS` |
+| `封单额` | T 日封单额 |
+| `成交额` | T 日成交额 |
 
-## 5. 业务规则
+## 7. 错误响应
 
-- T 日涨停。
-- T-1 交易日也涨停。
-- T-2 交易日必须不涨停。
-- T 日开盘价必须低于 T-1 收盘价的 101%。
-- T 日首次涨停时间必须早于 11:00。
-- 盈利口径默认按 T 日收盘价买入，T+1 收盘价卖出。
+```json
+{
+  "error": "参数错误"
+}
+```