openapi: "3.0.3"
info:
  title: PPC Analyzer API — ylishi.tools
  description: >
    Amazon PPC 广告分析 API。支持多广告活动管理、效果追踪、
    ACOS/ROAS/CTR/CVR 自动计算、智能优化建议。
    基于 Flask + SQLite，部署在 ppc.ylishi.tools。
  version: "1.0.0"
  contact:
    name: ylishi.tools
    url: https://ylishi.tools
servers:
  - url: https://ppc.ylishi.tools
    description: Production server
paths:
  /api/health:
    get:
      summary: 健康检查
      operationId: ppcHealth
      responses:
        "200":
          description: 服务状态
          content:
            application/json:
              schema:
                type: object
                properties:
                  status: { type: string, example: "ok" }
                  service: { type: string, example: "ppc-analyzer" }
  /api/campaigns:
    get:
      summary: 获取广告活动列表
      operationId: listCampaigns
      responses:
        "200":
          description: 活动列表
          content:
            application/json:
              schema:
                type: object
                properties:
                  campaigns:
                    type: array
                    items: { $ref: "#/components/schemas/Campaign" }
    post:
      summary: 创建广告活动
      operationId: createCampaign
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [name]
              properties:
                name: { type: string, example: "Summer Sale Auto Targeting" }
                store: { type: string }
                platform: { type: string, default: "amazon" }
                notes: { type: string }
      responses:
        "201":
          description: 创建成功
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: "#/components/schemas/Campaign"
  /api/campaigns/{campaignId}:
    parameters:
      - name: campaignId
        in: path
        required: true
        schema: { type: string }
        description: 广告活动ID
    delete:
      summary: 删除广告活动（含关联记录）
      operationId: deleteCampaign
      responses:
        "200":
          description: 删除成功
  /api/records:
    get:
      summary: 获取广告表现记录
      operationId: listPpcRecords
      parameters:
        - name: campaign_id
          in: query
          schema: { type: string }
          description: 筛选广告活动
        - name: limit
          in: query
          schema: { type: integer, default: 100, maximum: 500 }
      responses:
        "200":
          description: 记录列表
          content:
            application/json:
              schema:
                type: object
                properties:
                  records:
                    type: array
                    items: { $ref: "#/components/schemas/PpcRecord" }
    post:
      summary: 创建广告表现记录
      operationId: createPpcRecord
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [campaign_id]
              properties:
                campaign_id: { type: string }
                date: { type: string, format: date, example: "2026-07-15" }
                impressions: { type: integer, default: 0 }
                clicks: { type: integer, default: 0 }
                spend: { type: number, format: float, default: 0, description: "广告花费" }
                sales: { type: number, format: float, default: 0, description: "销售额" }
                orders: { type: integer, default: 0 }
                notes: { type: string }
      responses:
        "201":
          description: 创建成功（含自动计算的指标 + 优化建议）
  /api/records/{recordId}:
    parameters:
      - name: recordId
        in: path
        required: true
        schema: { type: string }
    delete:
      summary: 删除广告记录
      operationId: deletePpcRecord
      responses:
        "200":
          description: 删除成功
  /api/analyze:
    get:
      summary: PPC 综合分析
      description: 返回汇总指标、平均值、30天趋势图、优化建议列表
      operationId: analyzePpc
      parameters:
        - name: campaign_id
          in: query
          schema: { type: string }
          description: 可选，筛选特定活动
      responses:
        "200":
          description: 完整分析报告
          content:
            application/json:
              schema:
                type: object
                properties:
                  total:
                    type: object
                    properties:
                      spend: { type: number, description: "总花费" }
                      sales: { type: number, description: "总销售额" }
                      clicks: { type: integer }
                      impressions: { type: integer }
                      orders: { type: integer }
                      acos: { type: number, description: "ACOS 百分比" }
                      roas: { type: number, description: "ROAS 倍数" }
                      cpc: { type: number, description: "单次点击成本" }
                      ctr: { type: number, description: "点击率 百分比" }
                      cvr: { type: number, description: "转化率 百分比" }
                  avg: { type: object, description: "日均指标" }
                  trend: { type: array, description: "近30天趋势数据" }
                  advice: { type: array, description: "优化建议列表" }
components:
  schemas:
    Campaign:
      type: object
      properties:
        id: { type: string }
        name: { type: string }
        store: { type: string }
        platform: { type: string, default: "amazon" }
        notes: { type: string }
        created_at: { type: string, format: date-time }
    PpcRecord:
      type: object
      properties:
        id: { type: string }
        campaign_id: { type: string }
        date: { type: string, format: date }
        impressions: { type: integer }
        clicks: { type: integer }
        spend: { type: number }
        sales: { type: number }
        orders: { type: integer }
        acos: { type: number, description: "Advertising Cost of Sale (%)" }
        roas: { type: number, description: "Return on Ad Spend (x)" }
        cpc: { type: number, description: "Cost Per Click" }
        ctr: { type: number, description: "Click-Through Rate (%)" }
        cvr: { type: number, description: "Conversion Rate (%)" }
        notes: { type: string }
        created_at: { type: string, format: date-time }
