openapi: 3.0.3
info:
  title: Cloudflare 解算服务 API
  description: |
    自建 Cloudflare 验证解算 API。提交 url 与可选 sitekey 后，返回 cf_clearance、Turnstile token、Cookie、User-Agent 等结果。
  version: 1.0.0
servers:
  - url: /
    description: 当前访问地址
tags:
  - name: 解算任务
    description: 提交任务与查询结果
  - name: 控制台
    description: 任务列表与统计信息
paths:
  /v1/health:
    get:
      tags: [解算任务]
      summary: 健康检查
      responses:
        '200':
          description: 服务正常
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok: {type: boolean, description: 服务是否可用}
                  queue: {type: integer, description: 当前队列长度}
  /v1/solve:
    post:
      tags: [解算任务]
      summary: 提交解算任务
      description: 提交目标 URL，可选传入 Turnstile sitekey、代理和超时时间。
      security: [{ApiKeyAuth: []}]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [url]
              properties:
                url: {type: string, format: uri, description: 需要解算的目标页面 URL}
                sitekey: {type: string, description: Turnstile sitekey，用于自动注入验证组件}
                timeout: {type: integer, default: 60000, description: 超时时间，单位毫秒}
                proxy: {type: string, format: uri, description: 代理地址，例如 http://user:pass@ip:port}
      responses:
        '202': {description: 任务已接受}
        '400': {description: 请求参数错误}
        '401': {description: API Key 缺失或无效}
        '429': {description: 请求触发限流}
  /v1/result/{taskID}:
    get:
      tags: [解算任务]
      summary: 查询任务结果
      security: [{ApiKeyAuth: []}]
      parameters:
        - name: taskID
          in: path
          required: true
          description: 任务 ID
          schema: {type: string}
      responses:
        '200':
          description: 任务结果
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResultResponse'
        '404': {description: 任务不存在}
  /v1/tasks:
    get:
      tags: [控制台]
      summary: 获取任务列表
      security: [{ApiKeyAuth: []}]
      responses:
        '200': {description: 任务列表}
  /v1/stats:
    get:
      tags: [控制台]
      summary: 获取统计信息
      security: [{ApiKeyAuth: []}]
      responses:
        '200': {description: 统计信息}
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: 在请求头中传入 SOLVER_API_KEY
  schemas:
    ResultResponse:
      type: object
      properties:
        task_id: {type: string, description: 任务 ID}
        status: {type: string, enum: [pending, running, completed, failed], description: 任务状态}
        solution: {$ref: '#/components/schemas/Solution'}
        error: {type: string, description: 错误信息}
        duration_ms: {type: integer, description: 任务耗时，单位毫秒}
    Solution:
      type: object
      properties:
        url: {type: string, description: 最终访问 URL}
        status: {type: integer, description: HTTP 状态码}
        cookies: {type: array, description: 返回的 Cookie 列表, items: {$ref: '#/components/schemas/Cookie'}}
        userAgent: {type: string, description: 浏览器 User-Agent}
        turnstile_token: {type: string, description: Turnstile 验证令牌}
        response: {type: string, description: 页面响应内容}
    Cookie:
      type: object
      properties:
        name: {type: string, description: Cookie 名称}
        value: {type: string, description: Cookie 值}
        domain: {type: string, description: Cookie 域名}
        path: {type: string, description: Cookie 路径}
        expires: {type: number, description: 过期时间戳}
        httpOnly: {type: boolean, description: 是否为 HttpOnly}
        secure: {type: boolean, description: 是否仅 HTTPS 传输}
        sameSite: {type: string, description: SameSite 策略}
