openapi: "3.0.3"
info:
  title: Profit Dashboard API — ylishi.tools
  description: >
    跨境电商利润追踪 API。支持多店铺、多ASIN的利润核算、
    数据导入导出、自动化周报/月报邮件推送。
    基于 Flask + SQLite，部署在 profit.ylishi.tools。
  version: "1.0.0"
  contact:
    name: ylishi.tools
    url: https://ylishi.tools
servers:
  - url: https://profit.ylishi.tools
    description: Production server
paths:
  /api/health:
    get:
      summary: 健康检查
      operationId: health
      responses:
        "200":
          description: 服务状态
          content:
            application/json:
              schema:
                type: object
                properties:
                  status: { type: string, example: "ok" }
                  stats:
                    type: object
                    properties:
                      stores: { type: integer }
                      records: { type: integer }
  /api/stores:
    get:
      summary: 获取店铺列表
      operationId: listStores
      responses:
        "200":
          description: 店铺列表
          content:
            application/json:
              schema:
                type: object
                properties:
                  stores:
                    type: array
                    items:
                      $ref: "#/components/schemas/Store"
    post:
      summary: 创建店铺
      operationId: createStore
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [name]
              properties:
                name: { type: string, example: "Amazon US Store" }
                platform: { type: string, example: "amazon", enum: [amazon, ebay, shopify, etsy, walmart, tiktok] }
                currency: { type: string, example: "USD", default: "USD" }
                notes: { type: string, example: "Main US account" }
      responses:
        "200":
          description: 创建成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  store: { $ref: "#/components/schemas/Store" }
  /api/stores/{storeId}:
    parameters:
      - name: storeId
        in: path
        required: true
        schema: { type: string }
    put:
      summary: 更新店铺
      operationId: updateStore
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name: { type: string }
                platform: { type: string }
                currency: { type: string }
                notes: { type: string }
      responses:
        "200":
          description: 更新成功
    delete:
      summary: 删除店铺（含关联记录）
      operationId: deleteStore
      responses:
        "200":
          description: 删除成功
  /api/records:
    get:
      summary: 获取财务记录
      operationId: listRecords
      parameters:
        - name: store_id
          in: query
          schema: { type: string }
          description: 筛选店铺
        - name: limit
          in: query
          schema: { type: integer, default: 500, maximum: 5000 }
        - name: offset
          in: query
          schema: { type: integer, default: 0 }
        - name: sort
          in: query
          schema: { type: string, enum: [date, revenue, profit, created_at], default: "date" }
        - name: order
          in: query
          schema: { type: string, enum: [ASC, DESC], default: "DESC" }
      responses:
        "200":
          description: 记录列表
          content:
            application/json:
              schema:
                type: object
                properties:
                  records:
                    type: array
                    items:
                      $ref: "#/components/schemas/Record"
    post:
      summary: 创建财务记录
      operationId: createRecord
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [store_id, revenue, cogs]
              properties:
                store_id: { type: string, description: "店铺ID" }
                date: { type: string, format: date, example: "2026-07-15" }
                asin: { type: string, example: "B0XXXXXXXX" }
                product_name: { type: string }
                revenue: { type: number, format: float }
                cogs: { type: number, format: float, description: "货品成本" }
                platform_fees: { type: number, format: float, default: 0 }
                shipping: { type: number, format: float, default: 0 }
                other_costs: { type: number, format: float, default: 0 }
                notes: { type: string }
      responses:
        "200":
          description: 创建成功
  /api/records/{recordId}:
    parameters:
      - name: recordId
        in: path
        required: true
        schema: { type: string }
    put:
      summary: 更新记录
      operationId: updateRecord
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                date: { type: string, format: date }
                asin: { type: string }
                product_name: { type: string }
                revenue: { type: number }
                cogs: { type: number }
                platform_fees: { type: number }
                shipping: { type: number }
                other_costs: { type: number }
                notes: { type: string }
      responses:
        "200":
          description: 更新成功
    delete:
      summary: 删除记录
      operationId: deleteRecord
      responses:
        "200":
          description: 删除成功
  /api/summary:
    get:
      summary: 总览统计
      operationId: getSummary
      parameters:
        - name: store_id
          in: query
          schema: { type: string }
        - name: days
          in: query
          schema: { type: integer, default: 90 }
      responses:
        "200":
          description: 统计摘要
  /api/summary/by_store:
    get:
      summary: 按店铺汇总
      operationId: summaryByStore
      parameters:
        - name: days
          in: query
          schema: { type: integer, default: 90 }
      responses:
        "200":
          description: 各店铺统计
  /api/summary/by_asin:
    get:
      summary: 按ASIN汇总
      operationId: summaryByAsin
      parameters:
        - name: days
          in: query
          schema: { type: integer, default: 90 }
      responses:
        "200":
          description: 各ASIN统计
  /api/summary/daily:
    get:
      summary: 每日趋势
      operationId: dailySummary
      parameters:
        - name: days
          in: query
          schema: { type: integer, default: 90 }
        - name: store_id
          in: query
          schema: { type: string }
      responses:
        "200":
          description: 每日数据
  /api/export:
    get:
      summary: 导出CSV
      operationId: exportCsv
      responses:
        "200":
          description: CSV格式数据
  /api/import:
    post:
      summary: 导入CSV
      operationId: importCsv
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                csv: { type: string, description: "CSV格式数据" }
      responses:
        "200":
          description: 导入结果
  /api/email-config:
    get:
      summary: 获取邮件配置
      operationId: getEmailConfig
      responses:
        "200":
          description: 邮件配置
    post:
      summary: 设置邮件配置
      operationId: setEmailConfig
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                enabled: { type: boolean }
                smtp_host: { type: string }
                smtp_port: { type: integer, default: 587 }
                smtp_user: { type: string }
                smtp_pass: { type: string }
                to_email: { type: string, format: email }
                from_name: { type: string }
      responses:
        "200":
          description: 保存成功
  /api/report:
    get:
      summary: 预览报表
      operationId: previewReport
      parameters:
        - name: days
          in: query
          schema: { type: integer, default: 7 }
        - name: store_id
          in: query
          schema: { type: string }
      responses:
        "200":
          description: 报表HTML
  /api/send-report:
    post:
      summary: 发送邮件报表
      operationId: sendReport
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                days: { type: integer, default: 7 }
                store_id: { type: string }
      responses:
        "200":
          description: 发送结果
components:
  schemas:
    Store:
      type: object
      properties:
        id: { type: string }
        name: { type: string }
        platform: { type: string, enum: [amazon, ebay, shopify, etsy, walmart, tiktok] }
        currency: { type: string, default: "USD" }
        notes: { type: string }
    Record:
      type: object
      properties:
        id: { type: string }
        store_id: { type: string }
        store_name: { type: string }
        platform: { type: string }
        currency: { type: string }
        date: { type: string, format: date }
        asin: { type: string }
        product_name: { type: string }
        revenue: { type: number }
        cogs: { type: number }
        platform_fees: { type: number }
        shipping: { type: number }
        other_costs: { type: number }
        notes: { type: string }
        created_at: { type: string, format: date-time }
