docs(api): 同步计费结算接口契约

重新生成 OpenAPI，补充估价字段、任务计费状态、管理员结算查询与审计重试接口。
2026-07-21 00:26:11 +08:00
parent 62d25fcb11
commit c879de18e2
2 changed files with 732 additions and 0 deletions
@@ -85,6 +85,29 @@ definitions:
          $ref: '#/definitions/store.BaseModel'
        type: array
    type: object
+  httpapi.BillingSettlementListResponse:
+    properties:
+      items:
+        items:
+          $ref: '#/definitions/store.BillingSettlement'
+        type: array
+      page:
+        example: 1
+        type: integer
+      pageSize:
+        example: 50
+        type: integer
+      total:
+        example: 42
+        type: integer
+    type: object
+  httpapi.BillingSettlementRetryResponse:
+    properties:
+      auditLog:
+        $ref: '#/definitions/store.AuditLog'
+      settlement:
+        $ref: '#/definitions/store.BillingSettlement'
+    type: object
  httpapi.CatalogProviderListResponse:
    properties:
      items:
@@ -1599,6 +1622,47 @@ definitions:
      status:
        type: string
    type: object
+  store.BillingSettlement:
+    properties:
+      action:
+        type: string
+      amount:
+        type: number
+      attempts:
+        type: integer
+      completedAt:
+        type: string
+      createdAt:
+        type: string
+      currency:
+        type: string
+      id:
+        type: string
+      lastErrorCode:
+        type: string
+      lastErrorMessage:
+        type: string
+      lockedAt:
+        type: string
+      lockedBy:
+        type: string
+      manualReviewReason:
+        type: string
+      nextAttemptAt:
+        type: string
+      payload:
+        additionalProperties: {}
+        type: object
+      pricingSnapshot:
+        additionalProperties: {}
+        type: object
+      status:
+        type: string
+      taskId:
+        type: string
+      updatedAt:
+        type: string
+    type: object
  store.CatalogProvider:
    properties:
      capabilitySchema:
@@ -1890,9 +1954,19 @@ definitions:
        items:
          $ref: '#/definitions/store.TaskAttempt'
        type: array
+      billingCurrency:
+        type: string
+      billingSettledAt:
+        type: string
+      billingStatus:
+        type: string
      billingSummary:
        additionalProperties: {}
        type: object
+      billingUpdatedAt:
+        type: string
+      billingVersion:
+        type: string
      billings:
        items: {}
        type: array
@@ -1908,6 +1982,8 @@ definitions:
        type: string
      errorMessage:
        type: string
+      executionLeaseExpiresAt:
+        type: string
      finalChargeAmount:
        type: number
      finishedAt:
@@ -1931,6 +2007,9 @@ definitions:
        type: string
      newMessageCount:
        type: integer
+      pricingSnapshot:
+        additionalProperties: {}
+        type: object
      remoteTaskId:
        type: string
      remoteTaskPayload:
@@ -1939,10 +2018,14 @@ definitions:
      request:
        additionalProperties: {}
        type: object
+      requestFingerprint:
+        type: string
      requestId:
        type: string
      requestedModel:
        type: string
+      reservationAmount:
+        type: number
      resolvedModel:
        type: string
      responseDurationMs:
@@ -2850,12 +2933,17 @@ definitions:
        type: string
      platformName:
        type: string
+      pricingSnapshot:
+        additionalProperties: {}
+        type: object
      provider:
        type: string
      providerModelName:
        type: string
      queueKey:
        type: string
+      requestFingerprint:
+        type: string
      requestId:
        type: string
      requestSnapshot:
@@ -2882,6 +2970,10 @@ definitions:
        type: integer
      taskId:
        type: string
+      upstreamSubmissionStatus:
+        type: string
+      upstreamSubmissionUpdatedAt:
+        type: string
      usage:
        additionalProperties: {}
        type: object
@@ -4264,6 +4356,106 @@ paths:
      summary: 列出定价规则
      tags:
      - pricing
+  /api/admin/runtime/billing-settlements:
+    get:
+      description: 管理端分页查询待结算、重试失败和人工复核记录。
+      parameters:
+      - description: 结算状态
+        in: query
+        name: status
+        type: string
+      - description: 动作：settle 或 release
+        in: query
+        name: action
+        type: string
+      - default: 1
+        description: 页码
+        in: query
+        name: page
+        type: integer
+      - default: 50
+        description: 每页数量
+        in: query
+        name: pageSize
+        type: integer
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/httpapi.BillingSettlementListResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/httpapi.ErrorEnvelope'
+        "401":
+          description: Unauthorized
+          schema:
+            $ref: '#/definitions/httpapi.ErrorEnvelope'
+        "403":
+          description: Forbidden
+          schema:
+            $ref: '#/definitions/httpapi.ErrorEnvelope'
+        "500":
+          description: Internal Server Error
+          schema:
+            $ref: '#/definitions/httpapi.ErrorEnvelope'
+      security:
+      - BearerAuth: []
+      summary: 查询计费结算队列
+      tags:
+      - billing
+  /api/admin/runtime/billing-settlements/{settlementId}/retry:
+    post:
+      description: Manager 使用单值 Idempotency-Key 将重试失败或人工复核记录重新放入队列，并记录审计日志。
+      parameters:
+      - description: 结算记录 ID
+        in: path
+        name: settlementId
+        required: true
+        type: string
+      - description: 幂等键
+        in: header
+        name: Idempotency-Key
+        required: true
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/httpapi.BillingSettlementRetryResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/httpapi.ErrorEnvelope'
+        "401":
+          description: Unauthorized
+          schema:
+            $ref: '#/definitions/httpapi.ErrorEnvelope'
+        "403":
+          description: Forbidden
+          schema:
+            $ref: '#/definitions/httpapi.ErrorEnvelope'
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/httpapi.ErrorEnvelope'
+        "409":
+          description: Conflict
+          schema:
+            $ref: '#/definitions/httpapi.ErrorEnvelope'
+        "500":
+          description: Internal Server Error
+          schema:
+            $ref: '#/definitions/httpapi.ErrorEnvelope'
+      security:
+      - BearerAuth: []
+      summary: 重试计费结算
+      tags:
+      - billing
  /api/admin/runtime/model-rate-limits:
    get:
      description: 管理端查看平台模型维度的限流和冷却状态。
@@ -6432,6 +6624,10 @@ paths:
        in: header
        name: X-Async
        type: boolean
+      - description: 可选请求幂等键；同一用户范围内唯一
+        in: header
+        name: Idempotency-Key
+        type: string
      - description: AI 任务请求，字段随任务类型变化
        in: body
        name: input
@@ -6537,6 +6733,10 @@ paths:
        in: header
        name: X-Async
        type: boolean
+      - description: 可选请求幂等键；同一用户范围内唯一
+        in: header
+        name: Idempotency-Key
+        type: string
      - description: AI 任务请求，字段随任务类型变化
        in: body
        name: input
@@ -6598,6 +6798,10 @@ paths:
        in: header
        name: X-Async
        type: boolean
+      - description: 可选请求幂等键；同一用户范围内唯一
+        in: header
+        name: Idempotency-Key
+        type: string
      - description: AI 任务请求，字段随任务类型变化
        in: body
        name: input
@@ -6732,6 +6936,10 @@ paths:
        in: header
        name: X-Async
        type: boolean
+      - description: 可选请求幂等键；同一用户范围内唯一
+        in: header
+        name: Idempotency-Key
+        type: string
      - description: AI 任务请求，字段随任务类型变化
        in: body
        name: input
@@ -6989,6 +7197,10 @@ paths:
        in: header
        name: X-Async
        type: boolean
+      - description: 可选请求幂等键；同一用户范围内唯一
+        in: header
+        name: Idempotency-Key
+        type: string
      - description: AI 任务请求，字段随任务类型变化
        in: body
        name: input
@@ -7153,6 +7365,10 @@ paths:
        in: header
        name: X-Async
        type: boolean
+      - description: 可选请求幂等键；同一用户范围内唯一
+        in: header
+        name: Idempotency-Key
+        type: string
      - description: AI 任务请求，字段随任务类型变化
        in: body
        name: input
@@ -7214,6 +7430,10 @@ paths:
        in: header
        name: X-Async
        type: boolean
+      - description: 可选请求幂等键；同一用户范围内唯一
+        in: header
+        name: Idempotency-Key
+        type: string
      - description: AI 任务请求，字段随任务类型变化
        in: body
        name: input
@@ -7473,6 +7693,10 @@ paths:
        in: header
        name: X-Async
        type: boolean
+      - description: 可选请求幂等键；同一用户范围内唯一
+        in: header
+        name: Idempotency-Key
+        type: string
      - description: AI 任务请求，字段随任务类型变化
        in: body
        name: input
@@ -7534,6 +7758,10 @@ paths:
        in: header
        name: X-Async
        type: boolean
+      - description: 可选请求幂等键；同一用户范围内唯一
+        in: header
+        name: Idempotency-Key
+        type: string
      - description: AI 任务请求，字段随任务类型变化
        in: body
        name: input
@@ -8062,6 +8290,10 @@ paths:
        in: header
        name: X-Async
        type: boolean
+      - description: 可选请求幂等键；同一用户范围内唯一
+        in: header
+        name: Idempotency-Key
+        type: string
      - description: AI 任务请求，字段随任务类型变化
        in: body
        name: input
@@ -8136,6 +8368,10 @@ paths:
        in: header
        name: X-Async
        type: boolean
+      - description: 可选请求幂等键；同一用户范围内唯一
+        in: header
+        name: Idempotency-Key
+        type: string
      - description: AI 任务请求，字段随任务类型变化
        in: body
        name: input
@@ -8197,6 +8433,10 @@ paths:
        in: header
        name: X-Async
        type: boolean
+      - description: 可选请求幂等键；同一用户范围内唯一
+        in: header
+        name: Idempotency-Key
+        type: string
      - description: AI 任务请求，字段随任务类型变化
        in: body
        name: input
@@ -8258,6 +8498,10 @@ paths:
        in: header
        name: X-Async
        type: boolean
+      - description: 可选请求幂等键；同一用户范围内唯一
+        in: header
+        name: Idempotency-Key
+        type: string
      - description: AI 任务请求，字段随任务类型变化
        in: body
        name: input
@@ -8336,6 +8580,10 @@ paths:
        in: header
        name: X-Async
        type: boolean
+      - description: 可选请求幂等键；同一用户范围内唯一
+        in: header
+        name: Idempotency-Key
+        type: string
      - description: AI 任务请求，字段随任务类型变化
        in: body
        name: input
@@ -8449,6 +8697,10 @@ paths:
        in: header
        name: X-Async
        type: boolean
+      - description: 可选请求幂等键；同一用户范围内唯一
+        in: header
+        name: Idempotency-Key
+        type: string
      - description: AI 任务请求，字段随任务类型变化
        in: body
        name: input
@@ -8510,6 +8762,10 @@ paths:
        in: header
        name: X-Async
        type: boolean
+      - description: 可选请求幂等键；同一用户范围内唯一
+        in: header
+        name: Idempotency-Key
+        type: string
      - description: AI 任务请求，字段随任务类型变化
        in: body
        name: input
@@ -8890,6 +9146,10 @@ paths:
        in: header
        name: X-Async
        type: boolean
+      - description: 可选请求幂等键；同一用户范围内唯一
+        in: header
+        name: Idempotency-Key
+        type: string
      - description: AI 任务请求，字段随任务类型变化
        in: body
        name: input
@@ -8995,6 +9255,10 @@ paths:
        in: header
        name: X-Async
        type: boolean
+      - description: 可选请求幂等键；同一用户范围内唯一
+        in: header
+        name: Idempotency-Key
+        type: string
      - description: AI 任务请求，字段随任务类型变化
        in: body
        name: input
@@ -9056,6 +9320,10 @@ paths:
        in: header
        name: X-Async
        type: boolean
+      - description: 可选请求幂等键；同一用户范围内唯一
+        in: header
+        name: Idempotency-Key
+        type: string
      - description: AI 任务请求，字段随任务类型变化
        in: body
        name: input
@@ -9117,6 +9385,10 @@ paths:
        in: header
        name: X-Async
        type: boolean
+      - description: 可选请求幂等键；同一用户范围内唯一
+        in: header
+        name: Idempotency-Key
+        type: string
      - description: AI 任务请求，字段随任务类型变化
        in: body
        name: input
@@ -9178,6 +9450,10 @@ paths:
        in: header
        name: X-Async
        type: boolean
+      - description: 可选请求幂等键；同一用户范围内唯一
+        in: header
+        name: Idempotency-Key
+        type: string
      - description: AI 任务请求，字段随任务类型变化
        in: body
        name: input
@@ -9291,6 +9567,10 @@ paths:
        in: header
        name: X-Async
        type: boolean
+      - description: 可选请求幂等键；同一用户范围内唯一
+        in: header
+        name: Idempotency-Key
+        type: string
      - description: AI 任务请求，字段随任务类型变化
        in: body
        name: input
@@ -9352,6 +9632,10 @@ paths:
        in: header
        name: X-Async
        type: boolean
+      - description: 可选请求幂等键；同一用户范围内唯一
+        in: header
+        name: Idempotency-Key
+        type: string
      - description: AI 任务请求，字段随任务类型变化
        in: body
        name: input
@@ -9450,6 +9734,10 @@ paths:
        in: header
        name: X-Async
        type: boolean
+      - description: 可选请求幂等键；同一用户范围内唯一
+        in: header
+        name: Idempotency-Key
+        type: string
      - description: AI 任务请求，字段随任务类型变化
        in: body
        name: input
@@ -9577,6 +9865,10 @@ paths:
        in: header
        name: X-Async
        type: boolean
+      - description: 可选请求幂等键；同一用户范围内唯一
+        in: header
+        name: Idempotency-Key
+        type: string
      - description: AI 任务请求，字段随任务类型变化
        in: body
        name: input