openapi: "3.0.3"
info:
  title: Keyword Research API — ylishi.tools
  description: >
    Amazon 关键词研究 API。支持亚马逊自动建议、ASIN 反向查询、
    Google Trends 集成、关键词竞争度评估与分析。
    基于 Flask + SQLite，部署在 kw.ylishi.tools。
  version: "1.0.0"
  contact:
    name: ylishi.tools
    url: https://ylishi.tools
servers:
  - url: https://kw.ylishi.tools
    description: Production server
paths:
  /api/suggest:
    get:
      summary: Amazon 关键词建议
      description: 从 Amazon Autocomplete API 获取关键词建议（支持多站点/深度扩展）
      operationId: kwSuggest
      parameters:
        - name: keyword
          in: query
          required: true
          schema: { type: string }
          example: "wireless earbuds"
          description: 种子关键词
        - name: market
          in: query
          schema: { type: string, default: "US", enum: [US, CA, UK, DE, FR, JP] }
          description: 亚马逊站点
        - name: deep
          in: query
          schema: { type: string, default: "0", enum: ["0", "1"] }
          description: "设为1进行深度扩展（对前3建议再扩展一层）"
      responses:
        "200":
          description: 关键词建议
          content:
            application/json:
              schema:
                type: object
                properties:
                  suggestions: { type: array, items: { type: string } }
                  keyword: { type: string }
                  market: { type: string }
                  total: { type: integer, description: "建议总数（deep模式）" }
  /api/asin:
    get:
      summary: ASIN 反向关键词查询
      description: 从 Amazon Listing 页面提取关键词（标题/要点/描述/元关键词加权）
      operationId: kwAsin
      parameters:
        - name: asin
          in: query
          required: true
          schema: { type: string }
          example: "B0XXXXXX123"
          description: Amazon ASIN（10-12字符）
        - name: market
          in: query
          schema: { type: string, default: "com" }
          description: 亚马逊域名后缀（com/co.uk/de/co.jp 等）
      responses:
        "200":
          description: 提取的关键词
          content:
            application/json:
              schema:
                type: object
                properties:
                  asin: { type: string }
                  title: { type: string }
                  keywords: { type: array, items: { type: object, properties: { keyword: { type: string }, weight: { type: integer } } } }
                  keyphrases: { type: array, items: { type: string }, description: "多词短语推荐" }
                  url: { type: string }
  /api/trends:
    get:
      summary: Google Trends 关键词趋势
      description: 获取关键词的12个月搜索趋势数据
      operationId: kwTrends
      parameters:
        - name: keywords
          in: query
          required: true
          schema: { type: string }
          example: "wireless earbuds,bluetooth earphones"
          description: "逗号分隔的关键词（最多10个，每次5个批次自动处理）"
      responses:
        "200":
          description: 趋势数据
          content:
            application/json:
              schema:
                type: object
                properties:
                  trends:
                    type: object
                    additionalProperties:
                      type: object
                      properties:
                        trend: { type: array, items: { type: integer }, description: "每周interest值" }
                        average: { type: number }
                        min: { type: integer }
                        max: { type: integer }
                        current: { type: integer }
                        direction: { type: string, enum: [up, down, stable] }
                  keywords: { type: array, items: { type: string } }
  /api/competition:
    get:
      summary: 关键词竞争度评估
      description: 启发式+Amazon搜索结果+建议数综合评估竞争度
      operationId: kwCompetition
      parameters:
        - name: keyword
          in: query
          required: true
          schema: { type: string }
        - name: market
          in: query
          schema: { type: string, default: "US" }
      responses:
        "200":
          description: 竞争度分析
          content:
            application/json:
              schema:
                type: object
                properties:
                  keyword: { type: string }
                  competition_level:
                    type: string
                    enum: [very_low, low, medium, high, very_high]
                  competition_score: { type: integer, description: "0-100评分" }
                  result_count: { type: integer, description: "Amazon搜索返回量" }
                  result_count_display: { type: string }
                  ad_density: { type: integer }
                  word_count: { type: integer }
                  is_estimated: { type: boolean }
  /api/analyze:
    post:
      summary: 完整关键词分析
      description: 一键分析：建议词提取 → Google Trends → 竞争度评估
      operationId: kwFullAnalyze
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                keyword: { type: string, example: "wireless earbuds" }
                market: { type: string, default: "US" }
      responses:
        "200":
          description: 完整分析报告
  /api/batch-analyze:
    post:
      summary: 批量关键词对比
      description: 比较多个关键词的趋势和竞争度（最多10个）
      operationId: kwBatchAnalyze
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                keywords: { type: string, description: "每行一个关键词（最多10个）" }
      responses:
        "200":
          description: 对比结果
  /api/export:
    post:
      summary: 导出关键词数据为CSV
      operationId: kwExport
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                keywords: { type: array, items: { type: object }, description: "关键词数据列表" }
      responses:
        "200":
          description: CSV文件
  /api/cache/stats:
    get:
      summary: 缓存统计
      operationId: kwCacheStats
      responses:
        "200":
          description: 缓存统计
  /api/cache/clear:
    post:
      summary: 清除缓存
      operationId: kwCacheClear
      responses:
        "200":
          description: 清除成功
