优化

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

@@ -304,8 +304,6 @@ components:
         currency: {type: string, pattern: '^[A-Z]{3}$'}
         amount: {type: number, minimum: 0}
         supplierId: {type: string, nullable: true}
-        supplierName: {type: string, maxLength: 200, nullable: true, readOnly: true}
-        supplierCategory: {type: string, enum: [BOOKING, CUSTOMS, TRUCKING, CERTIFICATE], nullable: true}
         remark: {type: string, maxLength: 500, nullable: true}
     InboundFeeDetailVersionRequest:
       type: object
@@ -332,7 +330,7 @@ components:
         direction: {type: string, enum: [RECEIVABLE, PAYABLE]}
         supplierId: {type: string, nullable: true}
         supplierName: {type: string, nullable: true, readOnly: true}
-        supplierCategory: {type: string, enum: [BOOKING, CUSTOMS, TRUCKING, CERTIFICATE], nullable: true}
+        supplierCategory: {type: string, enum: [BOOKING, CUSTOMS, TRUCKING, CERTIFICATE], nullable: true, description: 费用项目供应商类别约束快照；为空表示仅要求供应商ACTIVE}
         businessDate: {type: string, format: date}
         customerId: {type: string, nullable: true}
         customerName: {type: string, nullable: true}

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

@@ -100,7 +100,7 @@ components:
         category: {type: string, maxLength: 64}
         tradeScope: {type: string, enum: [DOMESTIC, INTERNATIONAL]}
         feeCode: {type: string, maxLength: 50, pattern: '^[A-Za-z0-9_-]+$'}
-        supplierCategory: {type: string, enum: [BOOKING, CUSTOMS, TRUCKING, CERTIFICATE], nullable: true, description: pickupPayable或warehousePayable为true时必填}
+        supplierCategory: {type: string, enum: [BOOKING, CUSTOMS, TRUCKING, CERTIFICATE], nullable: true, description: PAYABLE供应商类别约束；为空时可选任意ACTIVE Warehouse Supplier}
         feeTypeName: {type: string, maxLength: 128}
         pickupPayable: {type: boolean}
         pickupReceivable: {type: boolean}
@@ -116,7 +116,7 @@ components:
         category: {type: string}
         tradeScope: {type: string, enum: [DOMESTIC, INTERNATIONAL]}
         feeCode: {type: string}
-        supplierCategory: {type: string, enum: [BOOKING, CUSTOMS, TRUCKING, CERTIFICATE], nullable: true}
+        supplierCategory: {type: string, enum: [BOOKING, CUSTOMS, TRUCKING, CERTIFICATE], nullable: true, description: PAYABLE供应商类别约束；为空时可选任意ACTIVE Warehouse Supplier}
         feeTypeName: {type: string}
         pickupPayable: {type: boolean}
         pickupReceivable: {type: boolean}

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}

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

@@ -29,7 +29,7 @@ paths:
           application/json:
             schema: {$ref: '#/components/schemas/SaveRequest'}
       responses:
-        '200': {description: Created appointment, content: {application/json: {schema: {$ref: '#/components/schemas/DetailStableReferences'}}}}
+        '200': {description: Created appointment, content: {application/json: {schema: {$ref: '#/components/schemas/DetailEnvelope'}}}}
   /api/platform/v1/truck-appointments/{id}:
     parameters: [{$ref: '#/components/parameters/AppointmentId'}]
     get:
@@ -138,6 +138,18 @@ components:
     IdempotencyKey: {name: Idempotency-Key, in: header, required: true, schema: {type: string, maxLength: 128}}
     RequestHash: {name: X-Request-Hash, in: header, required: false, schema: {type: string, pattern: '^[0-9a-fA-F]{64}$'}}
   schemas:
+    DetailEnvelope:
+      type: object
+      required: [code, message, data, timestamp]
+      properties:
+        code: {type: string, example: '200'}
+        message: {type: string}
+        data:
+          allOf: [{$ref: '#/components/schemas/DetailStableReferences'}]
+          nullable: true
+        requestId: {type: string, nullable: true}
+        traceId: {type: string, nullable: true}
+        timestamp: {type: string, format: date-time}
     AttachmentRequest:
       type: object
       required: [fileId, attachmentType]