优化

firstleg/src/main/resources/openapi/firstleg-v1.yaml

@@ -70,6 +70,30 @@ paths:
                 requireInboundCodePrefix: {type: boolean}
       responses:
         '200': {description: 成功时 data 返回 channelCode；requireInboundCodePrefix=true 时同时返回 inboundCodePrefix}
+  /internal/firstleg/v1/inbounds/{inboundId}/fees/{feeId}/source-snapshot:
+    get:
+      summary: Finance 按入库费用来源版本精确回查不可变快照
+      description: sourceVersion 必填；只返回 sourceFeeId 与该版本精确匹配的已发布费用，不回退到其他版本。
+      security:
+        - internalServiceToken: []
+      parameters:
+        - {name: inboundId, in: path, required: true, schema: {type: integer, format: int64, minimum: 1}}
+        - {name: feeId, in: path, required: true, schema: {type: integer, format: int64, minimum: 1}}
+        - {name: sourceVersion, in: query, required: true, schema: {type: integer, minimum: 1}}
+      responses:
+        '200': {description: 成功时 data 为 FinanceFeeSourceSnapshot；不存在精确版本时返回业务错误}
+  /internal/firstleg/v1/containers/{containerId}/fees/{feeId}/source-snapshot:
+    get:
+      summary: Finance 按柜次费用来源版本精确回查不可变快照
+      description: sourceVersion 必填；只返回 sourceFeeId 与该版本精确匹配的已发布费用，不回退到当前可变版本。
+      security:
+        - internalServiceToken: []
+      parameters:
+        - {name: containerId, in: path, required: true, schema: {type: integer, format: int64, minimum: 1}}
+        - {name: feeId, in: path, required: true, schema: {type: integer, format: int64, minimum: 1}}
+        - {name: sourceVersion, in: query, required: true, schema: {type: integer, minimum: 1}}
+      responses:
+        '200': {description: 成功时 data 为 FinanceFeeSourceSnapshot；不存在精确版本时返回业务错误}
   /api/platform/v1/first-leg/customer-dimension-config:
     get:
       summary: 查询客户固定四箱规尺寸配置
@@ -1495,10 +1519,9 @@ components:
       description: 单证聚合状态；DO/PU 无完成动作，因此只返回 MISSING 或 UPLOADED
     ContainerSaveRequest:
       type: object
-      required: [cabinetNo, warehouseId, warehouseName, containerType, capacityCbm, maxWeightKg]
+      required: [warehouseId, warehouseName, containerType, capacityCbm, maxWeightKg]
       properties:
         containerNo: {type: string, maxLength: 64, nullable: true}
-        cabinetNo: {type: string, maxLength: 64}
         warehouseId: {type: string, pattern: '^[1-9][0-9]*$'}
         warehouseName: {type: string, maxLength: 128}
         billOfLadingNo: {type: string, maxLength: 128, nullable: true}
@@ -1820,3 +1843,39 @@ components:
         expectedSourceVersion: {type: integer, minimum: 1}
         businessDate: {type: string, format: date}
         amount: {type: number, minimum: 0}
+    FinanceFeeSourceSnapshot:
+      type: object
+      description: Finance 消费的版本化费用来源快照；supplierCategory 为空表示仅约束供应商 ACTIVE，非空才约束明确类别。
+      required: [tenantId, sourceType, feeId, feeVersion, customerId, customerName, feeItemName, direction, businessDate, currency, totalAmount, reviewStatus, publicationStatus, sourceHash, snapshotVersion]
+      properties:
+        tenantId: {type: integer, format: int64}
+        sourceType: {type: string, enum: [INBOUND_FEE, CONTAINER_FEE]}
+        feeId: {type: integer, format: int64}
+        feeVersion: {type: integer, minimum: 1}
+        inboundId: {type: integer, format: int64, nullable: true}
+        inboundCode: {type: string, nullable: true}
+        orderId: {type: integer, format: int64, nullable: true}
+        containerId: {type: integer, format: int64, nullable: true}
+        containerBookingId: {type: integer, format: int64, nullable: true}
+        containerNo: {type: string, nullable: true}
+        customerId: {type: integer, format: int64}
+        customerName: {type: string}
+        supplierId: {type: integer, format: int64, nullable: true}
+        supplierName: {type: string, nullable: true}
+        supplierCategory: {type: string, enum: [BOOKING, CUSTOMS, TRUCKING, CERTIFICATE], nullable: true, description: PAYABLE供应商类别约束；为空时仅要求供应商ACTIVE}
+        feeItemId: {type: integer, format: int64, nullable: true}
+        feeItemCode: {type: string, nullable: true}
+        feeItemName: {type: string}
+        direction: {type: string, enum: [RECEIVABLE, PAYABLE]}
+        businessDate: {type: string, format: date}
+        currency: {type: string, enum: [CNY]}
+        totalAmount: {type: number, minimum: 0}
+        reviewStatus: {type: string, enum: [APPROVED]}
+        publicationStatus: {type: string, enum: [PUBLISHED]}
+        publishedAt: {type: string, format: date-time, nullable: true}
+        chargeableQuantity: {type: number, nullable: true}
+        chargeUnit: {type: string, nullable: true}
+        actualGrossWeightKg: {type: number, nullable: true}
+        actualVolumeCbm: {type: number, nullable: true}
+        sourceHash: {type: string}
+        snapshotVersion: {type: integer, minimum: 1}