openapi: 3.0.0
info:
  title: 支付管理API
  description: 支付管理相关接口文档
  version: 1.0.0

paths:
  /api/payments:
    get:
      summary: 获取支付列表
      description: 获取系统中的支付列表，支持分页（需要认证）
      security:
        - bearerAuth: []
      parameters:
        - name: skip
          in: query
          description: 跳过的记录数
          required: false
          schema:
            type: integer
            default: 0
        - name: limit
          in: query
          description: 返回的记录数
          required: false
          schema:
            type: integer
            default: 100
      responses:
        '200':
          description: 成功返回支付列表
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Payment'
        '401':
          description: 未授权
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: 服务器内部错误
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      summary: 创建支付
      description: 创建一个新的支付（需要认证）
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentCreate'
      responses:
        '200':
          description: 成功创建支付
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Payment'
        '400':
          description: 请求参数验证失败
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: 未授权
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: 服务器内部错误
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /api/payments/{id}:
    get:
      summary: 获取支付详情
      description: 根据支付ID获取支付详细信息（需要认证）
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          description: 支付ID
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: 成功返回支付信息
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Payment'
        '401':
          description: 未授权
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: 支付未找到
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: 服务器内部错误
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    put:
      summary: 更新支付信息
      description: 根据支付ID更新支付信息（需要认证）
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          description: 支付ID
          required: true
          schema:
            type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentUpdate'
      responses:
        '200':
          description: 成功更新支付信息
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Payment'
        '400':
          description: 请求参数验证失败
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: 未授权
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: 支付未找到
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: 服务器内部错误
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      summary: 删除支付
      description: 根据支付ID删除支付（需要认证）
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          description: 支付ID
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: 成功删除支付
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Payment'
        '401':
          description: 未授权
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: 支付未找到
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: 服务器内部错误
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

components:
  schemas:
    Payment:
      type: object
      properties:
        id:
          type: integer
          description: 支付ID
        payment_no:
          type: string
          description: 支付编号
        order_id:
          type: integer
          description: 关联订单ID
        amount:
          type: number
          format: float
          description: 支付金额
        payment_type:
          type: string
          enum: [advance, final]
          description: 支付类型
        payment_method:
          type: string
          enum: [alipay, wechat, bank]
          description: 支付方式
        status:
          type: string
          enum: [pending, paid, failed, refunded]
          description: 支付状态
        transaction_id:
          type: string
          description: 第三方交易ID
        paid_at:
          type: string
          format: date-time
          description: 支付时间
        remark:
          type: string
          description: 备注
        created_at:
          type: string
          format: date-time
          description: 创建时间
        updated_at:
          type: string
          format: date-time
          description: 更新时间
      required:
        - id
        - payment_no
        - order_id
        - amount
        - payment_type
        - payment_method
        - status
        - created_at
        - updated_at

    PaymentCreate:
      type: object
      properties:
        order_id:
          type: integer
          description: 关联订单ID
        amount:
          type: number
          format: float
          description: 支付金额
        payment_type:
          type: string
          enum: [advance, final]
          description: 支付类型
        payment_method:
          type: string
          enum: [alipay, wechat, bank]
          description: 支付方式
        status:
          type: string
          enum: [pending, paid, failed, refunded]
          description: 支付状态
        transaction_id:
          type: string
          description: 第三方交易ID
        paid_at:
          type: string
          format: date-time
          description: 支付时间
        remark:
          type: string
          description: 备注
      required:
        - order_id
        - amount
        - payment_type
        - payment_method

    PaymentUpdate:
      type: object
      properties:
        order_id:
          type: integer
          description: 关联订单ID
        amount:
          type: number
          format: float
          description: 支付金额
        payment_type:
          type: string
          enum: [advance, final]
          description: 支付类型
        payment_method:
          type: string
          enum: [alipay, wechat, bank]
          description: 支付方式
        status:
          type: string
          enum: [pending, paid, failed, refunded]
          description: 支付状态
        transaction_id:
          type: string
          description: 第三方交易ID
        paid_at:
          type: string
          format: date-time
          description: 支付时间
        remark:
          type: string
          description: 备注

    Error:
      type: object
      properties:
        error:
          type: string
          description: 错误信息
      required:
        - error

  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT