优化

财务管理/openapi/finance-phase1-five-pages-v1.yaml

@@ -130,6 +130,22 @@ paths:
       responses:
         '200': {$ref: '#/components/responses/CustomerAccountReadResponse'}
         '404': {$ref: '#/components/responses/BusinessError'}
+  /platform/finance/v1/customer-accounts/{customerId}/summary:
+    get:
+      operationId: getCustomerAccountSummary
+      summary: 查询客户正式结算口径财务汇总
+      description: >-
+        固定 CNY。累计应收、已收和未结清仅聚合本客户非 VOIDED 的正式 RECEIVABLE
+        fin_settlement；待出账仅聚合合格且尚未进入非 VOIDED 对账单的应收费用来源；
+        未结应付仅聚合本客户非 VOIDED 的正式 PAYABLE fin_settlement。
+      x-permission: platform:finance:customer-account:list
+      x-customer-isolation: 所有聚合子查询都必须使用 customerId 约束，空客户返回零值。
+      parameters:
+        - $ref: '#/components/parameters/CustomerId'
+      responses:
+        '200': {$ref: '#/components/responses/CustomerAccountSummaryResponse'}
+        '400': {$ref: '#/components/responses/BusinessError'}
+        '403': {$ref: '#/components/responses/BusinessError'}
   /platform/finance/v1/accounts/{customerId}/ledger:
     get:
       operationId: listDerivedCustomerAccountLedger
@@ -687,6 +703,19 @@ components:
         entries:
           type: array
           items: {$ref: '#/components/schemas/AccountEntryRead'}
+    CustomerAccountSummary:
+      type: object
+      required: [customerId, currency, totalReceivable, receivedAmount, outstandingReceivable, pendingBilling, outstandingPayable, asOf, lastChangedAt]
+      properties:
+        customerId: {$ref: '#/components/schemas/Id'}
+        currency: {type: string, enum: [CNY]}
+        totalReceivable: {$ref: '#/components/schemas/Money'}
+        receivedAmount: {$ref: '#/components/schemas/Money'}
+        outstandingReceivable: {$ref: '#/components/schemas/Money'}
+        pendingBilling: {$ref: '#/components/schemas/Money'}
+        outstandingPayable: {$ref: '#/components/schemas/Money'}
+        asOf: {type: string, format: date-time}
+        lastChangedAt: {type: string, format: date-time}
     AccountEntryRead:
       type: object
       required: [entryType, resourceId, resourceNo, occurredAt, debitAmount, creditAmount, currency, status]
@@ -1277,6 +1306,15 @@ components:
             code: {type: string, example: '200'}
             message: {type: string}
             data: {$ref: '#/components/schemas/CustomerAccountRead'}
+    CustomerAccountSummaryEnvelope:
+      allOf:
+        - $ref: '#/components/schemas/TraceMeta'
+        - type: object
+          required: [code, message, data]
+          properties:
+            code: {type: string, example: '200'}
+            message: {type: string}
+            data: {$ref: '#/components/schemas/CustomerAccountSummary'}
     FeePoolReadEnvelope:
       allOf:
         - $ref: '#/components/schemas/TraceMeta'
@@ -1380,6 +1418,9 @@ components:
     CustomerAccountReadResponse:
       description: 当前固定 DTO 客户账户及流水。
       content: {application/json: {schema: {$ref: '#/components/schemas/CustomerAccountReadEnvelope'}}}
+    CustomerAccountSummaryResponse:
+      description: 客户正式结算口径财务汇总。
+      content: {application/json: {schema: {$ref: '#/components/schemas/CustomerAccountSummaryEnvelope'}}}
     FeePoolReadResponse:
       description: 当前固定 DTO 客户应收应付费用池。
       content: {application/json: {schema: {$ref: '#/components/schemas/FeePoolReadEnvelope'}}}