{ "openapi": "3.0.0", "info": { "title": "Daily Stock Analysis API", "description": "A股/港股/美股自选股智能分析系统 API\n\n## 功能模块\n- 股票分析：触发 AI 智能分析\n- 历史记录：查询历史分析报告\n- 股票数据：获取行情数据\n\n## 认证方式\n当前版本暂无认证要求", "version": "1.0.0", "contact": { "name": "Daily Stock Analysis Team" } }, "servers": [ { "url": "http://localhost:8000", "description": "本地开发服务器" } ], "tags": [ { "name": "Health", "description": "健康检查接口" }, { "name": "Analysis", "description": "股票分析相关接口" }, { "name": "History", "description": "历史记录相关接口" } ], "paths": { "/": { "get": { "tags": [ "Health" ], "summary": "API 根路由", "description": "返回 API 运行状态信息", "operationId": "root", "responses": { "200": { "description": "API 正常运行", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RootResponse" } } } } } } }, "/api/health": { "get": { "tags": [ "Health" ], "summary": "健康检查", "description": "用于负载均衡器或监控系统检查服务状态", "operationId": "healthCheck", "responses": { "200": { "description": "服务健康", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthResponse" } } } } } } }, "/api/v1/analysis/analyze": { "post": { "tags": [ "Analysis" ], "summary": "触发股票分析", "description": "启动 AI 智能分析任务，支持单只或多只股票批量分析", "operationId": "triggerAnalysis", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyzeRequest" } } } }, "responses": { "200": { "description": "分析完成（同步模式）", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalysisResult" } } } }, "202": { "description": "分析任务已接受（异步模式）", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskAccepted" } } } }, "400": { "description": "请求参数错误", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "股票正在分析中，拒绝重复提交", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DuplicateTaskError" } } } }, "500": { "description": "分析失败", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/analysis/tasks": { "get": { "tags": [ "Analysis" ], "summary": "获取分析任务列表", "description": "获取当前所有分析任务，支持按状态筛选。返回进行中和最近完成的任务。", "operationId": "getAnalysisTasks", "parameters": [ { "name": "status", "in": "query", "description": "筛选状态：pending, processing, completed, failed（支持逗号分隔多个）", "schema": { "type": "string", "example": "pending,processing" } }, { "name": "limit", "in": "query", "description": "返回数量限制", "schema": { "type": "integer", "default": 20, "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "任务列表", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskListResponse" } } } } } } }, "/api/v1/analysis/tasks/stream": { "get": { "tags": [ "Analysis" ], "summary": "任务状态 SSE 流", "description": "通过 Server-Sent Events 实时推送任务状态变化。\n\n## 事件类型\n- `connected`: 连接成功\n- `task_created`: 新任务创建\n- `task_started`: 任务开始执行\n- `task_completed`: 任务完成\n- `task_failed`: 任务失败\n- `heartbeat`: 心跳（每 30 秒）", "operationId": "taskStream", "responses": { "200": { "description": "SSE 事件流", "content": { "text/event-stream": { "schema": { "type": "string", "example": "event: task_created\ndata: {\"task_id\": \"abc123\", \"stock_code\": \"600519\", \"status\": \"pending\"}\n\n" } } } } } } }, "/api/v1/history": { "get": { "tags": [ "History" ], "summary": "获取历史分析列表", "description": "分页获取历史分析记录摘要，支持按股票代码和日期范围筛选", "operationId": "getHistoryList", "parameters": [ { "name": "stock_code", "in": "query", "description": "股票代码筛选", "schema": { "type": "string" } }, { "name": "start_date", "in": "query", "description": "开始日期 (YYYY-MM-DD)", "schema": { "type": "string", "format": "date" } }, { "name": "end_date", "in": "query", "description": "结束日期 (YYYY-MM-DD)", "schema": { "type": "string", "format": "date" } }, { "name": "page", "in": "query", "description": "页码（从 1 开始）", "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "limit", "in": "query", "description": "每页数量", "schema": { "type": "integer", "default": 20, "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "历史记录列表", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HistoryListResponse" } } } } } } }, "/api/v1/history/{query_id}": { "get": { "tags": [ "History" ], "summary": "获取历史报告详情", "description": "根据 query_id 获取完整的历史分析报告", "operationId": "getHistoryDetail", "parameters": [ { "name": "query_id", "in": "path", "required": true, "description": "分析记录唯一标识", "schema": { "type": "string" } } ], "responses": { "200": { "description": "报告详情", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalysisReport" } } } }, "404": { "description": "报告不存在", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/history/{query_id}/news": { "get": { "tags": [ "History" ], "summary": "获取历史报告关联新闻", "description": "根据 query_id 获取关联的新闻情报列表（为空也返回 200）", "operationId": "getHistoryNews", "parameters": [ { "name": "query_id", "in": "path", "required": true, "description": "分析记录唯一标识", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "返回数量限制", "schema": { "type": "integer", "default": 20, "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "新闻情报列表", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewsIntelResponse" } } } }, "500": { "description": "服务器错误", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } } }, "components": { "schemas": { "RootResponse": { "type": "object", "properties": { "message": { "type": "string", "example": "Daily Stock Analysis API is running" }, "version": { "type": "string", "example": "1.0.0" } }, "required": [ "message" ] }, "HealthResponse": { "type": "object", "properties": { "status": { "type": "string", "example": "ok" }, "timestamp": { "type": "string", "format": "date-time" } }, "required": [ "status" ] }, "AnalyzeRequest": { "type": "object", "properties": { "stock_code": { "type": "string", "description": "单只股票代码", "example": "600519" }, "stock_codes": { "type": "array", "description": "多只股票代码（与 stock_code 二选一）", "items": { "type": "string" }, "example": [ "600519", "000858" ] }, "report_type": { "type": "string", "enum": [ "simple", "detailed" ], "default": "detailed", "description": "报告类型" }, "force_refresh": { "type": "boolean", "default": false, "description": "是否强制刷新（忽略缓存）" }, "async_mode": { "type": "boolean", "default": false, "description": "是否使用异步模式" } } }, "AnalysisResult": { "type": "object", "properties": { "query_id": { "type": "string", "description": "分析记录唯一标识" }, "stock_code": { "type": "string" }, "stock_name": { "type": "string" }, "report": { "$ref": "#/components/schemas/AnalysisReport" }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "query_id", "stock_code", "report", "created_at" ] }, "TaskAccepted": { "type": "object", "properties": { "task_id": { "type": "string", "description": "任务 ID，用于查询状态" }, "status": { "type": "string", "enum": [ "pending", "processing" ], "example": "pending" }, "message": { "type": "string", "example": "Analysis task accepted" } }, "required": [ "task_id", "status" ] }, "TaskStatus": { "type": "object", "properties": { "task_id": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "processing", "completed", "failed" ] }, "progress": { "type": "integer", "description": "进度百分比 (0-100)" }, "result": { "$ref": "#/components/schemas/AnalysisResult" }, "error": { "type": "string", "description": "错误信息（仅在 failed 时存在）" } }, "required": [ "task_id", "status" ] }, "TaskInfo": { "type": "object", "description": "任务详情（用于任务列表和 SSE 事件）", "properties": { "task_id": { "type": "string", "description": "任务 ID" }, "stock_code": { "type": "string", "description": "股票代码" }, "stock_name": { "type": "string", "description": "股票名称" }, "status": { "type": "string", "enum": [ "pending", "processing", "completed", "failed" ], "description": "任务状态" }, "progress": { "type": "integer", "minimum": 0, "maximum": 100, "description": "进度百分比" }, "message": { "type": "string", "description": "状态消息" }, "report_type": { "type": "string", "enum": [ "simple", "detailed" ], "description": "报告类型" }, "created_at": { "type": "string", "format": "date-time", "description": "创建时间" }, "started_at": { "type": "string", "format": "date-time", "description": "开始执行时间" }, "completed_at": { "type": "string", "format": "date-time", "description": "完成时间" }, "error": { "type": "string", "description": "错误信息" } }, "required": [ "task_id", "stock_code", "status", "created_at" ] }, "TaskListResponse": { "type": "object", "description": "任务列表响应", "properties": { "total": { "type": "integer", "description": "任务总数" }, "pending": { "type": "integer", "description": "等待中的任务数" }, "processing": { "type": "integer", "description": "处理中的任务数" }, "tasks": { "type": "array", "items": { "$ref": "#/components/schemas/TaskInfo" }, "description": "任务列表" } }, "required": [ "total", "pending", "processing", "tasks" ] }, "DuplicateTaskError": { "type": "object", "description": "重复任务错误响应", "properties": { "error": { "type": "string", "example": "duplicate_task", "description": "错误类型" }, "message": { "type": "string", "example": "股票 600519 正在分析中", "description": "错误信息" }, "stock_code": { "type": "string", "example": "600519", "description": "股票代码" }, "existing_task_id": { "type": "string", "example": "abc123def456", "description": "已存在的任务 ID" } }, "required": [ "error", "message", "stock_code", "existing_task_id" ] }, "HistoryListResponse": { "type": "object", "properties": { "total": { "type": "integer", "description": "总记录数" }, "page": { "type": "integer" }, "limit": { "type": "integer" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/HistoryItem" } } }, "required": [ "total", "page", "limit", "items" ] }, "NewsIntelItem": { "type": "object", "description": "新闻情报条目", "properties": { "title": { "type": "string", "description": "新闻标题" }, "snippet": { "type": "string", "description": "新闻摘要（最多50字）" }, "url": { "type": "string", "description": "新闻链接" } }, "required": [ "title", "url" ] }, "NewsIntelResponse": { "type": "object", "description": "新闻情报响应", "properties": { "total": { "type": "integer", "description": "新闻条数" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/NewsIntelItem" }, "description": "新闻列表" } }, "required": [ "total", "items" ] }, "HistoryItem": { "type": "object", "description": "历史记录摘要（列表展示用）", "properties": { "query_id": { "type": "string" }, "stock_code": { "type": "string" }, "stock_name": { "type": "string" }, "report_type": { "type": "string" }, "sentiment_score": { "type": "integer", "minimum": 0, "maximum": 100 }, "operation_advice": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "query_id", "stock_code", "created_at" ] }, "AnalysisReport": { "type": "object", "description": "完整分析报告", "properties": { "meta": { "type": "object", "description": "元信息", "properties": { "query_id": { "type": "string" }, "stock_code": { "type": "string" }, "stock_name": { "type": "string" }, "report_type": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } } }, "summary": { "type": "object", "description": "概览区（首屏展示）", "properties": { "analysis_summary": { "type": "string", "description": "关键结论" }, "operation_advice": { "type": "string", "description": "操作建议" }, "trend_prediction": { "type": "string", "description": "趋势预测" }, "sentiment_score": { "type": "integer", "description": "情绪评分 (0-100)" }, "sentiment_label": { "type": "string", "description": "情绪标签", "enum": [ "极度悲观", "悲观", "中性", "乐观", "极度乐观" ] } } }, "strategy": { "type": "object", "description": "策略点位区", "properties": { "ideal_buy": { "type": "string", "description": "理想买入价" }, "secondary_buy": { "type": "string", "description": "第二买入价" }, "stop_loss": { "type": "string", "description": "止损价" }, "take_profit": { "type": "string", "description": "止盈价" } } }, "details": { "type": "object", "description": "详情区（可折叠）", "properties": { "news_content": { "type": "string", "description": "新闻摘要" }, "raw_result": { "type": "object", "description": "原始分析结果（JSON）" }, "context_snapshot": { "type": "object", "description": "分析时上下文快照（JSON）" } } } }, "required": [ "meta", "summary" ] }, "StockQuote": { "type": "object", "description": "股票实时行情", "properties": { "stock_code": { "type": "string" }, "stock_name": { "type": "string" }, "current_price": { "type": "number" }, "change": { "type": "number", "description": "涨跌额" }, "change_percent": { "type": "number", "description": "涨跌幅 (%)" }, "open": { "type": "number" }, "high": { "type": "number" }, "low": { "type": "number" }, "prev_close": { "type": "number" }, "volume": { "type": "number", "description": "成交量（股）" }, "amount": { "type": "number", "description": "成交额（元）" }, "update_time": { "type": "string", "format": "date-time" } }, "required": [ "stock_code", "current_price" ] }, "ErrorResponse": { "type": "object", "properties": { "error": { "type": "string", "description": "错误类型" }, "message": { "type": "string", "description": "错误详情" }, "detail": { "type": "object", "description": "附加错误信息" } }, "required": [ "error", "message" ] } } } }