股票数据 API

模块: stocks

本模块包含 12 个API端点。

📋 端点列表

• ➕ POST /api/v1/stock-data - Create Stock Data
• 🔍 GET /api/v1/stock-data - Get Stock Data List
• 🔍 GET /api/v1/stock-data/{code}/{timestamp} - Get Stock Data
• 🔍 GET /api/v1/stock-codes - Get Stock Codes
• 🗑️ DELETE /api/v1/stock-data/{code} - Delete Stock Data
• ➕ POST /api/v1/stock-import/import - Import Stock Data
• 🔍 GET /api/v1/stock-import/import/{task_id}/status - Get Import Status
• 🗑️ DELETE /api/v1/stock-import/import/{task_id} - Cancel Import Task
• ➕ POST /api/v1/stock-calendar/{symbol}/init - Init Calendar
• 🔍 GET /api/v1/stock-calendar/{symbol} - Get Calendar
• 🔍 GET /api/v1/stock-calendar/{symbol}/missing - Get Missing Dates
• ➕ POST /api/v1/stock-calendar/{symbol}/verify - Verify Data Integrity

---

📖 详细说明

➕ Create Stock Data

创建股票数据

请求方式: POST /api/v1/stock-data

请求体:

// 参考模型: StockDataCreate
- `code` (string) - **必填** - 股票代码
- `open` (number) - **必填** - 开盘价
- `high` (number) - **必填** - 最高价
- `low` (number) - **必填** - 最低价
- `close` (number) - **必填** - 收盘价
- `volume` (integer) - **必填** - 成交量
- `turnover` (number) - **必填** - 成交额
- `timestamp` (integer) - **必填** - 时间戳(UNIX时间戳)
- `trade_session` (object) - **必填** - 交易时段
  - 类型: `TradeSession`

响应:

错误响应:

• 422: Validation Error

---

🔍 Get Stock Data List

获取股票数据列表（支持多周期）

请求方式: GET /api/v1/stock-data

查询参数:

• code (string) - 可选 - 股票代码筛选
• start_date (string) - 可选 - 开始日期（ISO格式）
• end_date (string) - 可选 - 结束日期（ISO格式）
• trade_session (string) - 可选 - 交易时段筛选
• period (string) - 可选 - 数据周期: 1m/5m/1h/1d，默认 1h
• sort_by (string) - 可选 - 排序字段
• sort_order (string) - 可选 - 排序方式: asc/desc
• page (integer) - 可选 - 页码
• page_size (integer) - 可选 - 每页数量
• timezone (string) - 可选 - 时区

响应:

// 参考模型: StockDataResponse
- `data` (array) - **必填** - 股票数据列表
- `total` (integer) - **必填** - 总数量
- `page` (integer) - **必填** - 当前页码
- `page_size` (integer) - **必填** - 每页数量
- `total_pages` (integer) - **必填** - 总页数

错误响应:

• 422: Validation Error

---

🔍 Get Stock Data

获取单条股票数据

请求方式: GET /api/v1/stock-data/{code}/{timestamp}

路径参数:

• code (string) - 必填 -
• timestamp (integer) - 必填 -

响应:

// 参考模型: StockData
- `code` (string) - **必填** - 股票代码
- `open` (number) - **必填** - 开盘价
- `high` (number) - **必填** - 最高价
- `low` (number) - **必填** - 最低价
- `close` (number) - **必填** - 收盘价
- `volume` (integer) - **必填** - 成交量
- `turnover` (number) - **必填** - 成交额
- `timestamp` (integer) - **必填** - 时间戳(UNIX时间戳)
- `trade_session` (object) - **必填** - 交易时段
  - 类型: `TradeSession`

错误响应:

• 422: Validation Error

---

🔍 Get Stock Codes

获取所有股票代码

请求方式: GET /api/v1/stock-codes

响应:

// 参考模型: StockCodeList
- `codes` (array) - **必填** - 股票代码列表

---

🗑️ Delete Stock Data

删除指定时间范围内的股票数据

• 如果指定 period，只删除该周期数据
• 如果不指定 period，删除所有周期数据

请求方式: DELETE /api/v1/stock-data/{code}

路径参数:

• code (string) - 必填 -

查询参数:

• start_date (string) - 必填 - 开始日期（ISO格式）
• end_date (string) - 必填 - 结束日期（ISO格式）
• period (string) - 可选 - 数据周期: 1m/5m/1h/1d，不指定则删除所有周期
• timezone (string) - 可选 - 时区

响应:

错误响应:

• 422: Validation Error

---

➕ Import Stock Data

导入股票数据（支持多周期）

• periods: 要导入的周期列表，默认 [“1m”, “5m”, “1h”, “1d”]
• 同一股票同时只能有一个导入任务

请求方式: POST /api/v1/stock-import/import

请求体:

// 参考模型: StockImportRequest
- `symbol` (string) - **必填** - 股票代码
- `start_date` (string) - **必填** - 开始日期（ISO格式）
- `end_date` (string) - **必填** - 结束日期（ISO格式）
- `timezone` (string) - 可选 - 时区
- `periods` (array) - 可选 - 要导入的周期列表，默认全部

响应:

// 参考模型: StockImportResponse
- `task_id` (string) - **必填** - 任务ID
- `message` (string) - **必填** - 响应消息

错误响应:

• 422: Validation Error

---

🔍 Get Import Status

获取导入任务状态（包含多周期详情）

请求方式: GET /api/v1/stock-import/import/{task_id}/status

路径参数:

• task_id (string) - 必填 -

响应:

// 参考模型: StockImportStatus
- `task_id` (string) - **必填** - 任务ID
- `status` (string) - **必填** - 任务状态
- `progress` (integer) - **必填** - 进度百分比
- `message` (string) - **必填** - 状态消息
- `data_count` (integer) - 可选 - 已获取数据条数
- `overwritten_count` (integer) - 可选 - 覆盖的数据条数
- `new_count` (integer) - 可选 - 新增的数据条数
- `filtered_count` (integer) - 可选 - 过滤掉的数据条数
- `avg_daily_count` (integer) - 可选 - 平均每天数据条数
- `periods` (array) - 可选 - 导入的周期列表
- `period_results` (object) - 可选 - 各周期导入结果

错误响应:

• 422: Validation Error

---

🗑️ Cancel Import Task

取消导入任务

请求方式: DELETE /api/v1/stock-import/import/{task_id}

路径参数:

• task_id (string) - 必填 -

响应:

错误响应:

• 422: Validation Error

---

➕ Init Calendar

初始化股票日历

从 LongPort API 获取交易日历信息，创建日历条目。 已存在的条目不会被覆盖（幂等性）。

请求方式: POST /api/v1/stock-calendar/{symbol}/init

路径参数:

• symbol (string) - 必填 -

请求体:

// 参考模型: InitCalendarRequest
- `start_date` (string) - **必填** - 开始日期 (ISO 格式)
- `end_date` (string) - **必填** - 结束日期 (ISO 格式)

响应:

// 参考模型: InitCalendarResponse
- `success` (boolean) - **必填** - 是否成功
- `message` (string) - **必填** - 响应消息
- `created_count` (integer) - 可选 - 创建的条目数
- `skipped_count` (integer) - 可选 - 跳过的条目数（已存在）
- `total_days` (integer) - 可选 - 总天数
- `trading_days` (integer) - 可选 - 交易日数
- `half_days` (integer) - 可选 - 半日交易数
- `closed_days` (integer) - 可选 - 休市日数

错误响应:

• 422: Validation Error

---

🔍 Get Calendar

获取股票日历

按日期范围查询日历条目

请求方式: GET /api/v1/stock-calendar/{symbol}

路径参数:

• symbol (string) - 必填 -

查询参数:

• start_date (string) - 必填 - 开始日期 (ISO 格式)
• end_date (string) - 必填 - 结束日期 (ISO 格式)

响应:

// 参考模型: GetCalendarResponse
- `success` (boolean) - **必填** - 是否成功
- `entries` (array) - 可选 - 日历条目列表
- `total` (integer) - 可选 - 总条目数
- `trading_days` (integer) - 可选 - 交易日数
- `data_ready_days` (integer) - 可选 - 数据就绪天数

错误响应:

• 422: Validation Error

---

🔍 Get Missing Dates

获取缺失数据的日期列表

返回指定周期下数据未完整的日期

请求方式: GET /api/v1/stock-calendar/{symbol}/missing

路径参数:

• symbol (string) - 必填 -

查询参数:

• period (string) - 必填 - 周期: 1m/5m/1h/1d
• start_date (string) - 可选 - 开始日期 (ISO 格式)
• end_date (string) - 可选 - 结束日期 (ISO 格式)

响应:

// 参考模型: MissingDatesResponse
- `success` (boolean) - **必填** - 是否成功
- `period` (string) - **必填** - 周期
- `missing_dates` (array) - 可选 - 缺失日期列表
- `count` (integer) - 可选 - 缺失数量

错误响应:

• 422: Validation Error

---

➕ Verify Data Integrity

验证数据完整性

检查指定日期范围内的数据是否完整，返回覆盖率和缺失信息

请求方式: POST /api/v1/stock-calendar/{symbol}/verify

路径参数:

• symbol (string) - 必填 -

请求体:

// 参考模型: VerifyDataRequest
- `start_date` (string) - **必填** - 开始日期 (ISO 格式)
- `end_date` (string) - **必填** - 结束日期 (ISO 格式)
- `periods` (object) - 可选 - 要验证的周期，默认全部

响应:

// 参考模型: VerifyDataResponse
- `success` (boolean) - **必填** - 是否成功
- `is_ready` (boolean) - 可选 - 数据是否就绪
- `coverage_rate` (number) - 可选 - 总覆盖率
- `total_trading_days` (integer) - 可选 - 交易日总数
- `ready_days` (integer) - 可选 - 数据就绪天数
- `missing_dates` (array) - 可选 - 缺失日期
- `period_details` (object) - 可选 - 各周期详情

错误响应:

• 422: Validation Error

---