优化

财务管理/openapi/finance-f1-manual-v1.yaml

@@ -1,7 +1,7 @@
 openapi: 3.0.3
 info:
   title: Finance F1 Manual AR API
-  version: 1.2.0
+  version: 1.3.0
   description: >-
     F1 人工账单、收款和成本目标契约。仅 CNY；平台财务可写；客户只读且仅可见
     ISSUED、PARTIALLY_PAID、PAID 账单。整柜成本由 Finance 根据 containerId 调用
@@ -239,6 +239,32 @@ paths:
           $ref: '#/components/responses/CostResponse'
         '409':
           $ref: '#/components/responses/IdempotencyConflict'
+  /platform/finance/v1/container-settlement-details:
+    get:
+      summary: 按客户和柜次查询已结算柜费及成本分摊
+      description: >-
+        为装柜清单柜费页提供固定请求量聚合。服务端校验柜次在 Finance 快照中的客户归属，
+        以集合查询一次返回已进入 PAID 正式结算或 FIRSTLEG_DIRECT_PAID 已确认成本的
+        CONTAINER_FEE 来源 ID，以及该客户在该柜下的全部成本及不可变分摊明细。
+        不返回整张结算单、其他客户数据或平台凭证。
+      x-permissions-all-of:
+        - platform:finance:cost:view
+        - platform:finance:settlement-ar:list
+        - platform:finance:settlement-ap:list
+      x-query-count: 3 fixed set-based SQL statements
+      x-customer-isolation: customerId 与 containerBookingId 必须在 Finance 费用来源或成本快照中存在真实归属关系。
+      security:
+        - platformFinance: []
+      parameters:
+        - $ref: '#/components/parameters/RequiredCustomerId'
+        - $ref: '#/components/parameters/ContainerBookingId'
+      responses:
+        '200':
+          $ref: '#/components/responses/ContainerSettlementDetailsResponse'
+        '403':
+          $ref: '#/components/responses/BusinessError'
+        '404':
+          $ref: '#/components/responses/BusinessError'
   /platform/finance/v1/vouchers:
     post:
       summary: 上传财务凭证图片
@@ -334,6 +360,13 @@ components:
       required: false
       schema:
         $ref: '#/components/schemas/Id'
+    ContainerBookingId:
+      name: containerBookingId
+      in: query
+      required: true
+      description: Firstleg 真实货柜 containerBookingId，不是装柜计划 loadingPlanId。
+      schema:
+        $ref: '#/components/schemas/Id'
     IdempotencyKey:
       name: Idempotency-Key
       in: header
@@ -930,6 +963,50 @@ components:
         createdAt:
           type: string
           format: date-time
+    ContainerSettlementDetails:
+      type: object
+      required: [customerId, containerBookingId, settledSourceFeeIds, costs]
+      properties:
+        customerId: {$ref: '#/components/schemas/Id'}
+        containerBookingId: {$ref: '#/components/schemas/Id'}
+        settledSourceFeeIds:
+          type: array
+          uniqueItems: true
+          items: {$ref: '#/components/schemas/Id'}
+        costs:
+          type: array
+          items: {$ref: '#/components/schemas/ContainerSettlementCost'}
+    ContainerSettlementCost:
+      type: object
+      required: [costId, costNo, costType, costOrigin, containerBookingId, feeItemName, amount, currency, status, allocations]
+      properties:
+        costId: {$ref: '#/components/schemas/Id'}
+        costNo: {type: string}
+        costType: {type: string, enum: [SINGLE_ORDER, CONTAINER_SHARED, SOURCE_DIRECT_PAID]}
+        costOrigin: {type: string, enum: [MANUAL, FIRSTLEG_DIRECT_PAID, BUSINESS_DIRECT_PAID]}
+        sourceFeeId: {$ref: '#/components/schemas/Id'}
+        sourceFeeVersion: {type: integer, minimum: 1}
+        containerBookingId: {$ref: '#/components/schemas/Id'}
+        supplierName: {type: string}
+        feeItemName: {type: string}
+        amount: {$ref: '#/components/schemas/Money'}
+        currency: {type: string, enum: [CNY]}
+        status: {type: string, enum: [DRAFT, CONFIRMED, VOIDED]}
+        allocations:
+          type: array
+          items: {$ref: '#/components/schemas/ContainerSettlementCostAllocation'}
+    ContainerSettlementCostAllocation:
+      type: object
+      required: [allocationId, orderId, volumeCbm, totalVolumeCbm, allocationRate, allocatedAmount, roundingAdjustment]
+      properties:
+        allocationId: {$ref: '#/components/schemas/Id'}
+        orderId: {$ref: '#/components/schemas/Id'}
+        inboundId: {$ref: '#/components/schemas/Id'}
+        volumeCbm: {$ref: '#/components/schemas/Money'}
+        totalVolumeCbm: {$ref: '#/components/schemas/Money'}
+        allocationRate: {type: string, pattern: '^(0|1|0\.[0-9]{1,10})$'}
+        allocatedAmount: {$ref: '#/components/schemas/Money'}
+        roundingAdjustment: {type: boolean}
     CustomerTerms:
       type: object
       required:
@@ -1122,6 +1199,15 @@ components:
             data:
               type: array
               items: {$ref: '#/components/schemas/Cost'}
+    ContainerSettlementDetailsEnvelope:
+      allOf:
+        - $ref: '#/components/schemas/ResponseMeta'
+        - type: object
+          required: [code, message, data]
+          properties:
+            code: {type: string, example: '200'}
+            message: {type: string}
+            data: {$ref: '#/components/schemas/ContainerSettlementDetails'}
     CustomerTermsEnvelope:
       allOf:
         - $ref: '#/components/schemas/ResponseMeta'
@@ -1191,6 +1277,11 @@ components:
       content:
         application/json:
           schema: {$ref: '#/components/schemas/CostListEnvelope'}
+    ContainerSettlementDetailsResponse:
+      description: 柜级已结算来源与成本分摊聚合结果。
+      content:
+        application/json:
+          schema: {$ref: '#/components/schemas/ContainerSettlementDetailsEnvelope'}
     CustomerTermsResponse:
       description: 客户账期结果。
       content: