{
  "openapi": "3.0.3",
  "info": {
    "title": "概念搜索API",
    "description": "支持语义和关键词混合搜索的概念库API，包含概念涨跌幅数据。\n\n## 功能特性\n- 支持 KNN 优化的语义搜索\n- 关键词 + 语义混合搜索\n- 概念涨跌幅数据查询\n- 股票关联概念查询\n- 概念统计排行榜\n\n## 技术栈\n- FastAPI + Elasticsearch\n- OpenAI Embedding (qwen3-embedding-8b)\n- MySQL (概念涨跌幅数据)",
    "version": "1.2.0",
    "contact": {
      "name": "ValueFrontier",
      "url": "https://valuefrontier.cn/concept-api"
    }
  },
  "servers": [
    {
      "url": "http://localhost:6801",
      "description": "本地开发服务器"
    },
    {
      "url": "https://api.valuefrontier.cn:6801",
      "description": "生产服务器"
    }
  ],
  "tags": [
    {
      "name": "Health",
      "description": "健康检查接口"
    },
    {
      "name": "Search",
      "description": "概念搜索接口"
    },
    {
      "name": "Concepts",
      "description": "概念详情接口"
    },
    {
      "name": "Stocks",
      "description": "股票相关接口"
    },
    {
      "name": "Price",
      "description": "价格数据接口"
    },
    {
      "name": "Statistics",
      "description": "统计数据接口"
    }
  ],
  "paths": {
    "/": {
      "get": {
        "tags": ["Health"],
        "summary": "健康检查",
        "description": "检查服务是否正常运行",
        "operationId": "healthCheck",
        "responses": {
          "200": {
            "description": "服务正常",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string",
                      "example": "healthy"
                    },
                    "service": {
                      "type": "string",
                      "example": "概念搜索API"
                    },
                    "version": {
                      "type": "string",
                      "example": "1.2.0"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/search": {
      "post": {
        "tags": ["Search"],
        "summary": "搜索概念库",
        "description": "支持 KNN 优化的语义搜索，混合搜索（KNN + 关键词），支持按涨跌幅、相关性等排序",
        "operationId": "searchConcepts",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SearchRequest"
              },
              "examples": {
                "semantic_search": {
                  "summary": "语义搜索示例",
                  "value": {
                    "query": "新能源汽车电池技术",
                    "size": 10,
                    "page": 1,
                    "sort_by": "change_pct",
                    "use_knn": true
                  }
                },
                "keyword_search": {
                  "summary": "关键词搜索示例",
                  "value": {
                    "query": "人工智能",
                    "size": 20,
                    "semantic_weight": 0,
                    "sort_by": "_score"
                  }
                },
                "stock_filter": {
                  "summary": "股票过滤示例",
                  "value": {
                    "query": "芯片",
                    "filter_stocks": ["600519", "贵州茅台"],
                    "size": 10
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "搜索成功",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SearchResponse"
                }
              }
            }
          },
          "500": {
            "description": "服务器错误",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPError"
                }
              }
            }
          }
        }
      }
    },
    "/concept/{concept_id}": {
      "get": {
        "tags": ["Concepts"],
        "summary": "获取概念详情",
        "description": "根据概念ID获取完整的概念信息，包含关联股票和涨跌幅数据",
        "operationId": "getConcept",
        "parameters": [
          {
            "name": "concept_id",
            "in": "path",
            "required": true,
            "description": "概念ID",
            "schema": {
              "type": "string"
            },
            "example": "concept_ai_001"
          },
          {
            "name": "trade_date",
            "in": "query",
            "required": false,
            "description": "交易日期，格式：YYYY-MM-DD，默认返回最新日期数据",
            "schema": {
              "type": "string",
              "format": "date"
            },
            "example": "2025-11-25"
          }
        ],
        "responses": {
          "200": {
            "description": "获取成功",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ConceptDetail"
                }
              }
            }
          },
          "404": {
            "description": "概念不存在",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPError"
                }
              }
            }
          }
        }
      }
    },
    "/concept/{concept_id}/price-timeseries": {
      "get": {
        "tags": ["Price"],
        "summary": "获取概念价格时间序列",
        "description": "获取指定概念在日期范围内的涨跌幅时间序列数据",
        "operationId": "getConceptPriceTimeseries",
        "parameters": [
          {
            "name": "concept_id",
            "in": "path",
            "required": true,
            "description": "概念ID",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "start_date",
            "in": "query",
            "required": true,
            "description": "开始日期，格式：YYYY-MM-DD",
            "schema": {
              "type": "string",
              "format": "date"
            },
            "example": "2025-11-01"
          },
          {
            "name": "end_date",
            "in": "query",
            "required": true,
            "description": "结束日期，格式：YYYY-MM-DD",
            "schema": {
              "type": "string",
              "format": "date"
            },
            "example": "2025-11-25"
          }
        ],
        "responses": {
          "200": {
            "description": "获取成功",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PriceTimeSeriesResponse"
                }
              }
            }
          },
          "400": {
            "description": "参数错误（开始日期晚于结束日期）"
          },
          "404": {
            "description": "未找到数据"
          }
        }
      }
    },
    "/stock/{stock_code}/concepts": {
      "get": {
        "tags": ["Stocks"],
        "summary": "获取股票关联概念",
        "description": "根据股票代码或名称查询该股票关联的所有概念",
        "operationId": "getStockConcepts",
        "parameters": [
          {
            "name": "stock_code",
            "in": "path",
            "required": true,
            "description": "股票代码或名称",
            "schema": {
              "type": "string"
            },
            "example": "600519"
          },
          {
            "name": "size",
            "in": "query",
            "required": false,
            "description": "返回概念数量",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 50
            }
          },
          {
            "name": "sort_by",
            "in": "query",
            "required": false,
            "description": "排序方式",
            "schema": {
              "type": "string",
              "enum": ["stock_count", "concept_name", "recent"],
              "default": "stock_count"
            }
          },
          {
            "name": "include_description",
            "in": "query",
            "required": false,
            "description": "是否包含概念描述",
            "schema": {
              "type": "boolean",
              "default": true
            }
          },
          {
            "name": "trade_date",
            "in": "query",
            "required": false,
            "description": "交易日期，格式：YYYY-MM-DD",
            "schema": {
              "type": "string",
              "format": "date"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "获取成功",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StockConceptsResponse"
                }
              }
            }
          }
        }
      }
    },
    "/stock/search": {
      "get": {
        "tags": ["Stocks"],
        "summary": "搜索股票",
        "description": "根据关键词搜索股票名称或代码",
        "operationId": "searchStocks",
        "parameters": [
          {
            "name": "keyword",
            "in": "query",
            "required": true,
            "description": "股票关键词",
            "schema": {
              "type": "string"
            },
            "example": "茅台"
          },
          {
            "name": "size",
            "in": "query",
            "required": false,
            "description": "返回数量",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 20
            }
          }
        ],
        "responses": {
          "200": {
            "description": "搜索成功",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StockSearchResponse"
                }
              }
            }
          }
        }
      }
    },
    "/price/latest": {
      "get": {
        "tags": ["Price"],
        "summary": "获取最新价格日期",
        "description": "获取数据库中最新的涨跌幅数据日期",
        "operationId": "getLatestPriceDate",
        "responses": {
          "200": {
            "description": "获取成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "latest_trade_date": {
                      "type": "string",
                      "format": "date",
                      "nullable": true,
                      "example": "2025-11-25"
                    },
                    "has_data": {
                      "type": "boolean",
                      "example": true
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/statistics": {
      "get": {
        "tags": ["Statistics"],
        "summary": "获取概念统计数据",
        "description": "获取概念板块统计数据，包括涨幅榜、跌幅榜、活跃榜、波动榜、连涨榜",
        "operationId": "getConceptStatistics",
        "parameters": [
          {
            "name": "days",
            "in": "query",
            "required": false,
            "description": "统计天数范围（与 start_date/end_date 互斥）",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 90
            },
            "example": 7
          },
          {
            "name": "start_date",
            "in": "query",
            "required": false,
            "description": "开始日期，格式：YYYY-MM-DD",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "end_date",
            "in": "query",
            "required": false,
            "description": "结束日期，格式：YYYY-MM-DD",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "min_stock_count",
            "in": "query",
            "required": false,
            "description": "最少股票数量过滤",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 3
            }
          }
        ],
        "responses": {
          "200": {
            "description": "获取成功",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ConceptStatisticsResponse"
                }
              }
            }
          },
          "400": {
            "description": "参数错误"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "SearchRequest": {
        "type": "object",
        "required": ["query"],
        "properties": {
          "query": {
            "type": "string",
            "description": "搜索查询文本",
            "example": "新能源汽车"
          },
          "size": {
            "type": "integer",
            "minimum": 1,
            "maximum": 100,
            "default": 10,
            "description": "每页返回结果数量"
          },
          "page": {
            "type": "integer",
            "minimum": 1,
            "default": 1,
            "description": "页码"
          },
          "search_size": {
            "type": "integer",
            "minimum": 10,
            "maximum": 1000,
            "default": 100,
            "description": "搜索数量（从ES获取的结果数），用于排序后分页"
          },
          "semantic_weight": {
            "type": "number",
            "minimum": 0,
            "maximum": 1,
            "nullable": true,
            "description": "语义搜索权重(0-1)，null表示自动计算"
          },
          "filter_stocks": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "nullable": true,
            "description": "过滤特定股票代码或名称"
          },
          "trade_date": {
            "type": "string",
            "format": "date",
            "nullable": true,
            "description": "交易日期，格式：YYYY-MM-DD"
          },
          "sort_by": {
            "type": "string",
            "enum": ["change_pct", "_score", "stock_count", "concept_name", "added_date"],
            "default": "change_pct",
            "description": "排序方式"
          },
          "use_knn": {
            "type": "boolean",
            "default": true,
            "description": "是否使用KNN搜索优化语义搜索"
          }
        }
      },
      "SearchResponse": {
        "type": "object",
        "properties": {
          "total": {
            "type": "integer",
            "description": "总结果数"
          },
          "took_ms": {
            "type": "integer",
            "description": "查询耗时（毫秒）"
          },
          "results": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ConceptResult"
            }
          },
          "search_info": {
            "type": "object",
            "description": "搜索信息",
            "properties": {
              "query": {
                "type": "string"
              },
              "cleaned_query": {
                "type": "string"
              },
              "semantic_weight": {
                "type": "number"
              },
              "keyword_weight": {
                "type": "number"
              },
              "match_type": {
                "type": "string",
                "enum": ["keyword", "semantic", "hybrid", "semantic_knn", "hybrid_knn"]
              },
              "stock_filters": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "has_embedding": {
                "type": "boolean"
              },
              "sort_by": {
                "type": "string"
              },
              "use_knn": {
                "type": "boolean"
              }
            }
          },
          "price_date": {
            "type": "string",
            "format": "date",
            "nullable": true,
            "description": "价格数据日期"
          },
          "page": {
            "type": "integer",
            "description": "当前页码"
          },
          "total_pages": {
            "type": "integer",
            "description": "总页数"
          }
        }
      },
      "ConceptResult": {
        "type": "object",
        "properties": {
          "concept_id": {
            "type": "string",
            "description": "概念ID"
          },
          "concept": {
            "type": "string",
            "description": "概念名称"
          },
          "description": {
            "type": "string",
            "nullable": true,
            "description": "概念描述"
          },
          "stocks": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/StockInfo"
            },
            "description": "关联股票列表（最多20条）"
          },
          "stock_count": {
            "type": "integer",
            "description": "关联股票总数"
          },
          "happened_times": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "nullable": true,
            "description": "发生时间列表"
          },
          "score": {
            "type": "number",
            "description": "搜索相关性分数"
          },
          "match_type": {
            "type": "string",
            "enum": ["semantic", "keyword", "hybrid", "semantic_knn", "hybrid_knn"],
            "description": "匹配类型"
          },
          "highlights": {
            "type": "object",
            "nullable": true,
            "description": "高亮匹配信息"
          },
          "price_info": {
            "$ref": "#/components/schemas/ConceptPriceInfo"
          }
        }
      },
      "StockInfo": {
        "type": "object",
        "properties": {
          "stock_name": {
            "type": "string",
            "description": "股票名称"
          },
          "stock_code": {
            "type": "string",
            "description": "股票代码"
          },
          "reason": {
            "type": "string",
            "nullable": true,
            "description": "关联原因"
          },
          "industry": {
            "type": "string",
            "nullable": true,
            "description": "所属行业"
          },
          "project": {
            "type": "string",
            "nullable": true,
            "description": "相关项目"
          }
        }
      },
      "ConceptPriceInfo": {
        "type": "object",
        "nullable": true,
        "properties": {
          "trade_date": {
            "type": "string",
            "format": "date",
            "description": "交易日期"
          },
          "avg_change_pct": {
            "type": "number",
            "nullable": true,
            "description": "平均涨跌幅(%)"
          }
        }
      },
      "ConceptDetail": {
        "type": "object",
        "properties": {
          "concept_id": {
            "type": "string"
          },
          "concept": {
            "type": "string"
          },
          "description": {
            "type": "string",
            "nullable": true
          },
          "stocks": {
            "type": "array",
            "items": {
              "type": "object"
            }
          },
          "stocks_reason": {
            "type": "object",
            "description": "股票关联原因详情"
          },
          "happened_times": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "nullable": true
          },
          "created_at": {
            "type": "string",
            "nullable": true
          },
          "price_info": {
            "$ref": "#/components/schemas/ConceptPriceInfo"
          }
        }
      },
      "StockConceptsResponse": {
        "type": "object",
        "properties": {
          "stock_code": {
            "type": "string",
            "description": "股票代码"
          },
          "stats": {
            "type": "object",
            "properties": {
              "total_concepts": {
                "type": "integer",
                "description": "关联概念总数"
              },
              "returned_concepts": {
                "type": "integer",
                "description": "返回概念数"
              },
              "stock_info": {
                "type": "object",
                "nullable": true,
                "properties": {
                  "stock_code": {
                    "type": "string"
                  },
                  "stock_name": {
                    "type": "string"
                  }
                }
              },
              "concept_categories": {
                "type": "object",
                "description": "概念分类统计"
              }
            }
          },
          "concepts": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/StockConceptInfo"
            }
          },
          "price_date": {
            "type": "string",
            "format": "date",
            "nullable": true
          }
        }
      },
      "StockConceptInfo": {
        "type": "object",
        "properties": {
          "concept_id": {
            "type": "string"
          },
          "concept": {
            "type": "string"
          },
          "stock_count": {
            "type": "integer"
          },
          "happened_times": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "nullable": true
          },
          "description": {
            "type": "string",
            "nullable": true
          },
          "stock_detail": {
            "type": "object",
            "nullable": true,
            "description": "该股票在此概念中的详细信息"
          },
          "price_info": {
            "$ref": "#/components/schemas/ConceptPriceInfo"
          }
        }
      },
      "StockSearchResponse": {
        "type": "object",
        "properties": {
          "total": {
            "type": "integer",
            "description": "搜索结果总数"
          },
          "stocks": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/StockSearchResult"
            }
          }
        }
      },
      "StockSearchResult": {
        "type": "object",
        "properties": {
          "stock_code": {
            "type": "string"
          },
          "stock_name": {
            "type": "string"
          },
          "concept_count": {
            "type": "integer",
            "description": "关联概念数量"
          }
        }
      },
      "PriceTimeSeriesResponse": {
        "type": "object",
        "properties": {
          "concept_id": {
            "type": "string"
          },
          "concept_name": {
            "type": "string"
          },
          "start_date": {
            "type": "string",
            "format": "date"
          },
          "end_date": {
            "type": "string",
            "format": "date"
          },
          "data_points": {
            "type": "integer",
            "description": "数据点数量"
          },
          "timeseries": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PriceTimeSeriesItem"
            }
          }
        }
      },
      "PriceTimeSeriesItem": {
        "type": "object",
        "properties": {
          "trade_date": {
            "type": "string",
            "format": "date"
          },
          "avg_change_pct": {
            "type": "number",
            "nullable": true,
            "description": "平均涨跌幅(%)"
          },
          "stock_count": {
            "type": "integer",
            "nullable": true,
            "description": "当日股票数量"
          }
        }
      },
      "ConceptStatisticsResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "data": {
            "$ref": "#/components/schemas/ConceptStatistics"
          },
          "params": {
            "type": "object",
            "properties": {
              "days": {
                "type": "integer"
              },
              "min_stock_count": {
                "type": "integer"
              },
              "start_date": {
                "type": "string"
              },
              "end_date": {
                "type": "string"
              }
            }
          },
          "note": {
            "type": "string",
            "nullable": true
          }
        }
      },
      "ConceptStatistics": {
        "type": "object",
        "properties": {
          "hot_concepts": {
            "type": "array",
            "description": "涨幅榜",
            "items": {
              "$ref": "#/components/schemas/ConceptStatItem"
            }
          },
          "cold_concepts": {
            "type": "array",
            "description": "跌幅榜",
            "items": {
              "$ref": "#/components/schemas/ConceptStatItem"
            }
          },
          "active_concepts": {
            "type": "array",
            "description": "活跃榜",
            "items": {
              "$ref": "#/components/schemas/ConceptStatItem"
            }
          },
          "volatile_concepts": {
            "type": "array",
            "description": "波动榜",
            "items": {
              "$ref": "#/components/schemas/ConceptStatItem"
            }
          },
          "momentum_concepts": {
            "type": "array",
            "description": "连涨榜",
            "items": {
              "$ref": "#/components/schemas/ConceptStatItem"
            }
          },
          "summary": {
            "type": "object",
            "description": "统计摘要",
            "properties": {
              "total_concepts": {
                "type": "integer"
              },
              "positive_count": {
                "type": "integer"
              },
              "negative_count": {
                "type": "integer"
              },
              "avg_change": {
                "type": "number"
              },
              "update_time": {
                "type": "string"
              },
              "date_range": {
                "type": "string"
              },
              "days": {
                "type": "integer"
              },
              "start_date": {
                "type": "string"
              },
              "end_date": {
                "type": "string"
              }
            }
          }
        }
      },
      "ConceptStatItem": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "概念名称"
          },
          "concept_id": {
            "type": "string",
            "nullable": true
          },
          "change_pct": {
            "type": "number",
            "nullable": true,
            "description": "涨跌幅"
          },
          "stock_count": {
            "type": "integer",
            "nullable": true,
            "description": "股票数量"
          },
          "news_count": {
            "type": "integer",
            "nullable": true,
            "description": "新闻数量/交易天数"
          },
          "report_count": {
            "type": "integer",
            "nullable": true
          },
          "total_mentions": {
            "type": "integer",
            "nullable": true
          },
          "volatility": {
            "type": "number",
            "nullable": true,
            "description": "波动率"
          },
          "avg_change": {
            "type": "number",
            "nullable": true
          },
          "max_change": {
            "type": "number",
            "nullable": true
          },
          "consecutive_days": {
            "type": "integer",
            "nullable": true,
            "description": "连涨天数"
          },
          "total_change": {
            "type": "number",
            "nullable": true,
            "description": "累计涨幅"
          },
          "avg_daily": {
            "type": "number",
            "nullable": true,
            "description": "日均涨幅"
          }
        }
      },
      "HTTPError": {
        "type": "object",
        "properties": {
          "detail": {
            "type": "string",
            "description": "错误详情"
          }
        }
      }
    }
  }
}