优化

2026-08-17 17:49:06 +08:00
parent 50d9d81740
commit cdc41bc843
2 changed files with 93 additions and 4 deletions
@@ -92,6 +92,44 @@ paths:
                oneOf:
                  - $ref: '#/components/schemas/FeeSourceEventResultEnvelope'
                  - $ref: '#/components/schemas/ErrorEnvelope'
+  /internal/exports/v1/{exportType}/batches:
+    post:
+      servers:
+        - url: /
+      operationId: provideFinanceExportBatch
+      summary: 向 File 下载中心提供 Finance 导出批次
+      description: >-
+        仅供 File Service 使用；按任务、申请人、完整筛选参数签名并校验 snapshotToken。
+        exportType 固定业务方向，参数不得包含 page、pageSize 或 direction（费用来源列表除外）。
+      x-authentication: X-Internal-Service-Token
+      parameters:
+        - $ref: '#/components/parameters/InternalServiceToken'
+        - name: exportType
+          in: path
+          required: true
+          schema:
+            type: string
+            enum:
+              - FINANCE_CUSTOMER_ACCOUNT_LIST
+              - FINANCE_CUSTOMER_ACCOUNT_LEDGER
+              - FINANCE_FEE_SOURCE_LIST
+              - FINANCE_RECONCILIATION_STATEMENT_LIST
+              - FINANCE_RECEIVABLE_SETTLEMENT_LIST
+              - FINANCE_RECEIVABLE_SETTLEMENT_DETAIL
+              - FINANCE_PAYABLE_SETTLEMENT_LIST
+              - FINANCE_PAYABLE_SETTLEMENT_DETAIL
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: {$ref: '#/components/schemas/FinanceExportBatchRequest'}
+      responses:
+        '200':
+          description: 版本化导出批次；首批返回 columns、totalRows 和 snapshotToken。
+          content:
+            application/json:
+              schema: {$ref: '#/components/schemas/FinanceExportBatchEnvelope'}
+        '403': {description: 内部服务令牌无效。}
  /platform/finance/v1/accounts:
    get:
      operationId: listDerivedCustomerAccounts
@@ -589,6 +627,55 @@ components:
      schema: {type: string, minLength: 1, maxLength: 128}
      description: 完整规范化 method/path/customer/body 哈希；同参重放，异参冲突。
  schemas:
+    FinanceExportBatchRequest:
+      type: object
+      required: [taskId, tenantId, appCode, requestedBy, dispatchVersion, parameters, limit]
+      properties:
+        taskId: {type: string, pattern: '^[1-9][0-9]*$'}
+        tenantId: {type: string, enum: ['0']}
+        appCode: {type: string, enum: [PLATFORM]}
+        requestedBy: {type: string, pattern: '^[1-9][0-9]*$'}
+        dispatchVersion: {type: integer, minimum: 1}
+        parameters:
+          type: object
+          description: >-
+            ACCOUNT_LIST: customerId?, status?；ACCOUNT_LEDGER: customerId, businessType?, startDate?, endDate?；
+            FEE_SOURCE_LIST: customerId?, direction?, status?, reviewStatus?, settlementIncluded?, statementGenerated?,
+            businessDateFrom?, businessDateTo?, keyword?；RECONCILIATION_STATEMENT_LIST: customerId?, status?, billNo?,
+            containerNo?, periodStartFrom?, periodStartTo?, periodEndFrom?, periodEndTo?, settled?, lastPaymentFrom?,
+            lastPaymentTo?, createdFrom?, createdTo?；AR_LIST: customerId?, status?, settlementNo?；AP_LIST 另含
+            supplierName?；所有 DETAIL 仅 settlementId。业务 ID 为十进制字符串，日期为 YYYY-MM-DD。
+          additionalProperties: true
+        cursor: {type: string, nullable: true, description: 非负十进制偏移量。}
+        snapshotToken: {type: string, nullable: true, description: 首批为空，后续批次必须原样回传。}
+        limit: {type: integer, minimum: 1, maximum: 500}
+    FinanceExportColumn:
+      type: object
+      required: [key, title, type]
+      properties:
+        key: {type: string}
+        title: {type: string}
+        type: {type: string, enum: [STRING, INTEGER, DECIMAL, BOOLEAN, DATE, DATETIME]}
+        width: {type: integer, nullable: true}
+    FinanceExportBatch:
+      type: object
+      required: [schemaVersion, schemaHash, snapshotToken, columns, rows, nextCursor, hasMore]
+      properties:
+        schemaVersion: {type: integer, enum: [1]}
+        schemaHash: {type: string}
+        snapshotToken: {type: string}
+        columns: {type: array, items: {$ref: '#/components/schemas/FinanceExportColumn'}}
+        rows: {type: array, items: {type: object, additionalProperties: true}}
+        nextCursor: {type: string}
+        hasMore: {type: boolean}
+        totalRows: {type: integer, format: int64, nullable: true}
+    FinanceExportBatchEnvelope:
+      type: object
+      required: [code, message, data]
+      properties:
+        code: {type: string, example: '200'}
+        message: {type: string}
+        data: {$ref: '#/components/schemas/FinanceExportBatch'}
    Id:
      type: string
      pattern: '^[1-9][0-9]*$'