openapi: "3.0.3"
info:
  title: 净影短视频解析 API
  description: 视频解析服务，支持 20+ 中国社交平台去水印解析
  version: "1.0.0"

servers:
  - url: http://localhost:8080
    description: 本地开发

paths:
  /api/v1/health:
    get:
      summary: 健康检查
      operationId: health
      responses:
        "200":
          description: 服务健康
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: ok
                  version:
                    type: string
                    example: "1.0.0"
                  platforms:
                    type: integer
                    example: 23

  /api/v1/platforms:
    get:
      summary: 支持平台列表
      operationId: platforms
      responses:
        "200":
          description: 平台列表
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: success
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/Platform"

  /api/v1/parse:
    get:
      summary: 解析分享链接
      operationId: parseURL
      parameters:
        - name: url
          in: query
          required: true
          description: 视频分享链接或包含链接的分享文案
          schema:
            type: string
      responses:
        "200":
          description: 解析成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: success
                  data:
                    $ref: "#/components/schemas/VideoParseInfo"
        "400":
          description: 参数错误或平台不支持
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: 认证失败（启用 Basic Auth 时）
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "422":
          description: 解析失败（平台接口异常）
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "429":
          description: 请求过于频繁
          headers:
            Retry-After:
              schema:
                type: integer
              description: 建议等待秒数
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: 服务器内部错误
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

    post:
      summary: 解析分享链接（推荐）
      description: 使用 JSON 提交分享链接或完整分享文案，避免链接出现在查询字符串中。
      operationId: parseURLPost
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [url]
              properties:
                url:
                  type: string
                  description: 视频分享链接或包含链接的分享文案
                  example: https://v.douyin.com/xxxxx/
      responses:
        "200":
          description: 解析成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: success
                  data:
                    $ref: "#/components/schemas/VideoParseInfo"
        "400":
          description: 请求体错误或平台不支持
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: 认证失败（启用 Basic Auth 时）
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "422":
          description: 解析失败（平台接口异常）
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "429":
          description: 请求过于频繁
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: 服务器内部错误
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /api/v1/parse/{source}/{video_id}:
    get:
      summary: 根据视频 ID 解析
      operationId: parseID
      parameters:
        - name: source
          in: path
          required: true
          description: 平台标识
          schema:
            type: string
        - name: video_id
          in: path
          required: true
          description: 视频 ID
          schema:
            type: string
      responses:
        "200":
          description: 解析成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: success
                  data:
                    $ref: "#/components/schemas/VideoParseInfo"
        "400":
          description: 参数错误或平台不支持
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: 认证失败（启用 Basic Auth 时）
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "422":
          description: 解析失败
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "429":
          description: 请求过于频繁
          headers:
            Retry-After:
              schema:
                type: integer
              description: 建议等待秒数
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: 服务器内部错误
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /api/v1/miniprogram/login:
    post:
      summary: 微信小程序登录
      operationId: miniProgramLogin
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [code]
              properties:
                code:
                  type: string
                  description: wx.login 返回的临时登录凭证
      responses:
        "200":
          description: 登录成功，返回会话凭证和用户积分资料
        "503":
          description: 微信登录服务未配置或调用失败

  /api/v1/miniprogram/profile:
    get:
      summary: 获取积分、签到状态和今日免费额度
      operationId: miniProgramProfile
      security:
        - bearerAuth: []
      responses:
        "200":
          description: 用户资料
        "401":
          description: 登录凭证无效或过期

  /api/v1/miniprogram/sign:
    post:
      summary: 每日签到
      description: 每日获得1积分；连续签到天数为7的倍数时额外获得3至10随机积分。
      operationId: miniProgramSign
      security:
        - bearerAuth: []
      responses:
        "200":
          description: 签到成功
        "409":
          description: 当天已签到

  /api/v1/miniprogram/parse:
    post:
      summary: 小程序解析分享链接
      description: 每人每天前3次成功解析免费，之后每次消耗1积分；解析失败自动退回额度或积分。
      operationId: miniProgramParse
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [url]
              properties:
                url:
                  type: string
                use_point:
                  type: boolean
                  description: 免费额度用完后，是否确认消耗1积分
      responses:
        "200":
          description: 解析成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: success
                  data:
                    $ref: "#/components/schemas/VideoParseInfo"
        "400":
          description: 请求体错误或平台不支持
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "422":
          description: 解析失败
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /api/v1/media/{token}:
    get:
      summary: 获取小程序媒体临时文件
      operationId: miniProgramMedia
      parameters:
        - name: token
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: 媒体文件流
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        "404":
          description: 临时地址不存在或已过期
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: mini-program-session
  schemas:
    VideoParseInfo:
      type: object
      properties:
        author:
          type: object
          properties:
            uid:
              type: string
            name:
              type: string
            avatar:
              type: string
        title:
          type: string
        video_url:
          type: string
        music_url:
          type: string
        cover_url:
          type: string
        images:
          type: array
          nullable: true
          items:
            type: object
            properties:
              url:
                type: string
              live_photo_url:
                type: string

    Platform:
      type: object
      properties:
        source:
          type: string
        name:
          type: string
        url_parse:
          type: boolean
        id_parse:
          type: boolean

    ErrorResponse:
      type: object
      properties:
        status:
          type: string
          example: error
        error:
          type: object
          properties:
            code:
              type: string
              enum:
                - MISSING_PARAMETER
                - UNSUPPORTED_URL
                - UNSUPPORTED_SOURCE
                - ID_PARSE_NOT_SUPPORTED
                - PARSE_FAILED
                - UNAUTHORIZED
                - RATE_LIMITED
                - INTERNAL_ERROR
                - MEDIA_TOKEN_EXPIRED
                - MEDIA_FETCH_FAILED
                - LOGIN_REQUIRED
                - WECHAT_LOGIN_FAILED
                - POINT_REQUIRED
                - INSUFFICIENT_POINTS
                - ALREADY_SIGNED
            message:
              type: string
