优化

2026-08-17 19:51:58 +08:00
parent 1b0133f1fb
commit 139eb1e494
3 changed files with 122 additions and 14 deletions
@@ -217,15 +217,58 @@ paths:
        '400': {$ref: '#/components/responses/BusinessError'}
        '403': {$ref: '#/components/responses/BusinessError'}
        '404': {$ref: '#/components/responses/BusinessError'}
-  /platform/finance/v1/fee-pool:
+  /platform/finance/v1/fee-sources:
    get:
      operationId: listFinanceFeeSources
-      summary: 查询客户应收应付费用来源池
+      summary: 分页查询客户应收应付费用来源
+      x-permission: platform:finance:customer-arap:list
+      parameters:
+        - name: page
+          in: query
+          schema: {type: integer, minimum: 1, default: 1}
+        - name: pageSize
+          in: query
+          schema: {type: integer, minimum: 1, maximum: 200, default: 20}
+        - name: customerId
+          in: query
+          schema: {$ref: '#/components/schemas/Id'}
+        - name: direction
+          in: query
+          schema: {$ref: '#/components/schemas/FeeDirection'}
+        - name: status
+          in: query
+          schema: {type: string, enum: [AVAILABLE, LOCKED, BILLED, VOIDED, SUPERSEDED]}
+        - name: reviewStatus
+          in: query
+          schema: {$ref: '#/components/schemas/ReviewStatus'}
+        - name: settlementIncluded
+          in: query
+          schema: {type: boolean}
+        - name: statementGenerated
+          in: query
+          schema: {type: boolean}
+        - name: businessDateFrom
+          in: query
+          schema: {type: string, format: date}
+        - name: businessDateTo
+          in: query
+          schema: {type: string, format: date}
+        - name: keyword
+          in: query
+          schema: {type: string, maxLength: 200}
+      responses:
+        '200': {$ref: '#/components/responses/FeeSourcePageResponse'}
+        '400': {$ref: '#/components/responses/BusinessError'}
+        '403': {$ref: '#/components/responses/BusinessError'}
+  /platform/finance/v1/fee-pool:
+    get:
+      operationId: listLegacyFinanceFeePool
+      summary: 查询旧版费用池（非五页事实源）
+      deprecated: true
      x-permission: platform:finance:customer-arap:list
      parameters:
        - name: customerId
          in: query
-          required: true
          schema: {$ref: '#/components/schemas/Id'}
        - name: direction
          in: query
@@ -316,7 +359,7 @@ paths:
      parameters:
        - name: customerId
          in: query
-          required: true
+          required: false
          schema: {$ref: '#/components/schemas/Id'}
      responses:
        '200': {$ref: '#/components/responses/StatementListReadResponse'}
@@ -726,7 +769,8 @@ components:
      enum: [RECEIVABLE, PAYABLE]
    FeeSourceType:
      type: string
-      enum: [INBOUND_FEE, CONTAINER_FEE]
+      minLength: 1
+      description: 来源系统定义的费用来源类型；Finance 原样保留，当前已知 INBOUND_FEE、CONTAINER_FEE，后续可接入海外仓等来源类型
    ReviewStatus:
      type: string
      enum: [PENDING, APPROVED, REJECTED]
@@ -833,10 +877,12 @@ components:
        remark: {type: string}
    FeeSource:
      type: object
-      required: [feeSourceId, sourceType, sourceFeeId, sourceVersion, direction, customerId, businessDate, feeItemName, amount, currency, reviewStatus, settlementIncluded, sourceStatus, statementGenerated]
+      required: [feeSourceId, sourceSystem, sourceType, sourceFeeId, sourceVersion, direction, customerId, businessDate, feeItemName, amount, currency, reviewStatus, settlementIncluded, sourceStatus, statementGenerated]
      properties:
        feeSourceId: {$ref: '#/components/schemas/Id'}
+        sourceSystem: {type: string, minLength: 1}
        sourceType: {$ref: '#/components/schemas/FeeSourceType'}
+        sourceBusinessId: {type: string, description: 来源系统内可展示的正式业务标识；不得用 Finance 技术主键替代}
        sourceFeeId: {$ref: '#/components/schemas/Id'}
        sourceVersion: {type: integer, minimum: 1}
        direction: {$ref: '#/components/schemas/FeeDirection'}
@@ -844,6 +890,7 @@ components:
        customerName: {type: string}
        supplierId: {$ref: '#/components/schemas/Id'}
        supplierName: {type: string}
+        orderId: {$ref: '#/components/schemas/Id'}
        inboundId: {$ref: '#/components/schemas/Id'}
        inboundCode: {type: string}
        containerId: {$ref: '#/components/schemas/Id'}
@@ -911,7 +958,7 @@ components:
        expectedVersion: {type: integer, minimum: 0}
    ReconciliationSummary:
      type: object
-      required: [statementId, statementNo, customerId, customerName, periodStart, periodEnd, creditDays, currency, totalReceivable, receivedAmount, outstandingAmount, settled, status, version, createdBy, createdAt, updatedBy, updatedAt]
+      required: [statementId, statementNo, customerId, customerName, periodStart, periodEnd, creditDays, currency, lineCount, sourceCount, sourceAmount, adjustmentAmount, totalReceivable, receivedAmount, outstandingAmount, settled, status, version, createdBy, createdAt, updatedBy, updatedAt]
      properties:
        statementId: {$ref: '#/components/schemas/Id'}
        statementNo: {type: string}
@@ -921,10 +968,17 @@ components:
        periodEnd: {type: string, format: date}
        creditDays: {type: integer, minimum: 0}
        currency: {type: string, enum: [CNY]}
+        lineCount: {type: integer, minimum: 0, description: 对账单费用明细数量}
+        sourceCount: {type: integer, minimum: 0, description: 去重后的费用来源数量}
+        sourceAmount: {$ref: '#/components/schemas/Money'}
+        adjustmentAmount: {$ref: '#/components/schemas/Money'}
        totalReceivable: {$ref: '#/components/schemas/Money'}
        receivedAmount: {$ref: '#/components/schemas/Money'}
        outstandingAmount: {$ref: '#/components/schemas/Money'}
        lastReceiptAt: {type: string, format: date-time}
+        submittedAt: {type: string, format: date-time}
+        reviewedAt: {type: string, format: date-time}
+        issuedAt: {type: string, format: date-time}
        settled: {type: boolean}
        status: {$ref: '#/components/schemas/ReconciliationStatus'}
        version: {type: integer, minimum: 0}
@@ -934,6 +988,7 @@ components:
        updatedBy: {$ref: '#/components/schemas/Id'}
        updatedByName: {type: string, description: 最后修改时操作人名称快照；历史数据可能为空}
        updatedAt: {type: string, format: date-time}
+        remark: {type: string}
    ReconciliationDetail:
      allOf:
        - $ref: '#/components/schemas/ReconciliationSummary'
@@ -952,14 +1007,23 @@ components:
              items: {$ref: '#/components/schemas/ReconciliationRevision'}
    ReconciliationLine:
      type: object
-      required: [statementLineId, feeSourceId, sourceVersion, feeItemName, sourceAmount, statementAmount, currency]
+      required: [statementLineId, feeSourceId, sourceVersion, direction, sourceType, feeItemName, sourceAmount, statementAmount, currency]
      properties:
        statementLineId: {$ref: '#/components/schemas/Id'}
        feeSourceId: {$ref: '#/components/schemas/Id'}
        sourceVersion: {type: integer, minimum: 1}
        sourceHash: {type: string}
+        direction: {type: string, enum: [RECEIVABLE, PAYABLE]}
+        sourceType: {type: string, enum: [INBOUND_FEE, CONTAINER_FEE]}
+        sourceNo: {type: string}
+        orderId: {$ref: '#/components/schemas/Id'}
        inboundId: {$ref: '#/components/schemas/Id'}
        containerId: {$ref: '#/components/schemas/Id'}
+        inboundCode: {type: string}
+        containerNo: {type: string}
+        businessDate: {type: string, format: date}
+        quantity: {$ref: '#/components/schemas/Money'}
+        unitPrice: {$ref: '#/components/schemas/Money'}
        feeItemName: {type: string}
        sourceAmount: {$ref: '#/components/schemas/Money'}
        statementAmount: {$ref: '#/components/schemas/Money'}
@@ -1435,7 +1499,7 @@ components:
          properties:
            code: {type: string, example: '200'}
            message: {type: string}
-            data: {type: array, items: {$ref: '#/components/schemas/StatementRead'}}
+            data: {type: array, items: {$ref: '#/components/schemas/ReconciliationSummary'}}
    StatementDetailReadEnvelope:
      allOf:
        - $ref: '#/components/schemas/TraceMeta'
@@ -1528,7 +1592,7 @@ components:
      description: 当前固定 DTO 客户应收应付费用池。
      content: {application/json: {schema: {$ref: '#/components/schemas/FeePoolReadEnvelope'}}}
    StatementListReadResponse:
-      description: 当前固定 DTO 客户对账单列表。
+      description: 客户对账单业务摘要列表，包含期间、金额、来源数量和流程时间。
      content: {application/json: {schema: {$ref: '#/components/schemas/StatementListReadEnvelope'}}}
    StatementDetailReadResponse:
      description: 当前固定 DTO 客户对账单详情。