Merge remote-tracking branch 'origin/test' into dev

# Conflicts:
#	firstleg/src/main/java/com/baiyue/firstleg/client/OrderCargoClient.java
#	order/src/main/java/com/baiyue/order/controller/InternalOrderCargoController.java
#	order/src/test/java/com/baiyue/order/controller/InternalOrderCargoControllerTest.java

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

@@ -165,7 +165,7 @@ paths:
   /api/platform/v1/inbounds/{inboundId}/fees/published:
     put:
       summary: 调整初算或已发布费用
-      description: 需要 firstleg:fba-pricing:adjust 权限；人工修改计费量、单价和附加费，小计与总额由服务端重算并生成新版本，不回退 WAIT_SPLIT 状态。调整 CALCULATED/CONFIRMED 时生成新的 CALCULATED 版本；调整 SENT 时生成新的 SENT 版本并发布调整事件。
+      description: 需要 firstleg:fba-pricing:adjust 权限；计费量只能在系统原计费量上下10%范围内（含边界），请求必须携带当前费用版本、必填原因及二次确认标志，越界或并发冲突返回A0409。小计与总额由服务端重算并生成新版本，不回退 WAIT_SPLIT 状态。调整 CALCULATED/CONFIRMED 时生成新的 CALCULATED 版本；调整 SENT 时生成新的 SENT 版本并发布调整事件。
       parameters: [{$ref: '#/components/parameters/TenantId'}, {$ref: '#/components/parameters/InboundId'}, {$ref: '#/components/parameters/IdempotencyKey'}]
       requestBody:
         required: true
@@ -184,7 +184,7 @@ paths:
       responses: {'200': {description: 成功或业务失败, content: {application/json: {schema: {$ref: '#/components/schemas/InboundFeeDetailListApiResponse'}}}}, '403': {description: 无权限}}
     post:
       summary: 新增 MANUAL 其他费用
-      description: 只允许创建 MANUAL 来源；FBA_PRICING 由系统从 fl_inbound_fee 派生。
+      description: 只允许创建 MANUAL 来源；FBA_PRICING 由系统从 fl_inbound_fee 派生。费用项目 PRIVATE_LAST_MILE_DELIVERY 是独立的私人仓尾程派送费，仅 destinationType=PRIVATE 的入库单可创建；服务端按稳定 feeCode 校验，不按中文名称判断。
       parameters: [{$ref: '#/components/parameters/AccountId'}, {$ref: '#/components/parameters/InboundId'}]
       requestBody: {required: true, content: {application/json: {schema: {$ref: '#/components/schemas/InboundFeeDetailSaveRequest'}}}}
       responses: {'200': {description: 成功或业务失败, content: {application/json: {schema: {$ref: '#/components/schemas/InboundFeeDetailApiResponse'}}}}, '403': {description: 无权限}}
@@ -330,6 +330,10 @@ components:
         actualWeightKg: {type: number, nullable: true}
         actualVolumeCbm: {type: number, nullable: true}
         convertedQuantity: {type: number, nullable: true}
+        baselineChargeableQuantity: {type: number, description: 系统按权威测量与生效报价计算的原计费量，人工调整后保持不变}
+        lowerChargeableQuantity: {type: number, description: 允许人工调整的计费量下界，包含边界}
+        upperChargeableQuantity: {type: number, description: 允许人工调整的计费量上界，包含边界}
+        tolerancePercent: {type: number, enum: [10.00], description: 相对系统原计费量允许的上下偏差百分比}
         chargeableQuantity: {type: number, nullable: true}
         chargeUnit: {type: string, nullable: true}
         unitPrice: {type: number, nullable: true}
@@ -466,16 +470,22 @@ components:
         timestamp: {type: string, format: date-time, nullable: true}
     AdjustFeeRequest:
       type: object
-      required: [expectedFeeVersion, chargeableQuantity, unitPrice, additionalAmount, reason]
+      required: [expectedFeeVersion, chargeableQuantity, unitPrice, additionalAmount, reason, toleranceConfirmed]
       properties:
         expectedFeeVersion: {type: integer, minimum: 1}
         chargeableQuantity: {type: number, minimum: 0, exclusiveMinimum: true, description: 计费量，单位沿用当前费用快照的 chargeUnit}
         unitPrice: {type: number, minimum: 0, description: 人工确认单价}
         additionalAmount: {type: number, minimum: 0, multipleOf: 0.01}
         reason: {type: string, minLength: 1, maxLength: 500}
+        toleranceConfirmed: {type: boolean, enum: [true], description: 前端展示上下界并由操作员二次确认后固定传true；服务端仍会重新校验范围与版本}
     CalculateRequest:
       type: object
-      properties: {pricingAt: {type: string, format: date-time, description: 缺省为服务端当前时间}}
+      properties:
+        pricingAt: {type: string, format: date-time, description: 缺省为服务端当前时间}
+        selectedWeightKg: {type: number, exclusiveMinimum: true, minimum: 0, nullable: true, description: 选定的权威重量快照}
+        selectedVolumeCbm: {type: number, exclusiveMinimum: true, minimum: 0, nullable: true, description: 选定的权威体积快照}
+        weightSource: {type: string, maxLength: 32, nullable: true}
+        volumeSource: {type: string, maxLength: 32, nullable: true}
     CustomerRuleVersionRequest:
       type: object
       required: [ruleCode, customerId, customerName, businessType, chargeMode, taxMode, conversionFactor, roundingScale, roundingMode, currency, effectiveFrom]
@@ -668,5 +678,6 @@ components:
         destinationName: {type: string, maxLength: 128, nullable: true}
         destinationRegion: {type: string, enum: [WEST, CENTRAL, EAST]}
         pricingTaxMode: {$ref: '#/components/schemas/PricingTaxMode'}
+        chargeMode: {type: string, enum: [KG, CBM], description: 包税报价固定为KG；不包税报价必须与客户当前计费规则一致}
         actualWeightKg: {type: number, minimum: 0}
         actualVolumeCbm: {type: number, minimum: 0}

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

@@ -916,6 +916,8 @@ paths:
         grossWeightKg/netWeightKg。两类证据不得合并为无明细归属的统一图片列表。
         actualGrossWeightKg 是服务端确认后的实测毛重，actualNetWeightKg 是扣除托盘皮重后的货物净重；
         两者语义独立，消费者不得互相回退，也不得根据图片或 OCR 值自行重算。
+        inboundCode 是当前入库详情唯一入仓码；每条 items 按 inboundDetailId 返回 Order 权威
+        fbaShipmentNo，并保留独立 scannedShipmentId，匹配失败返回空且禁止两者互相回退或覆盖。
       parameters:
         - {name: tenantId, in: query, required: true, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
         - {name: inboundId, in: path, required: true, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
@@ -931,7 +933,9 @@ paths:
       summary: 保存测量草稿
       description: >-
         原单据号码、申报毛重和申报体积由服务端从客户订单生成快照，客户端不得提交覆盖；
-        actualGoodsName 默认使用客户货物品名汇总，但允许测量人员修正。
+        actualGoodsName 默认使用客户货物品名汇总，但允许测量人员修正。仅允许 WAIT_MEASURE、MEASURING
+        或 MEASURE_REJECTED 状态保存；进入 MEASURE_PENDING 后整批测量冻结，确认箱数修正使用
+        measurement/items/{itemId}/confirmed-package-count 明细专用接口。
       parameters:
         - {name: tenantId, in: query, required: true, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
         - {name: inboundId, in: path, required: true, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
@@ -1750,10 +1754,12 @@ components:
       type: object
       description: >-
         单条尺寸测量明细。id 是稳定 measurementItemId；intelligentImageFileId 仅表示该明细的
-        尺寸测量原图，不得与 weightResults.fileId 混用。
+        尺寸测量原图，不得与 weightResults.fileId 混用。fbaShipmentNo 是按 inboundDetailId
+        从 Order 货物明细实时读取的权威货件编号；scannedShipmentId 是独立设备实扫证据，二者不得回退或覆盖。
       required: [id]
       properties:
         id: {type: string, pattern: '^[1-9][0-9]*$', description: 稳定 measurementItemId}
+        inboundCode: {type: string, nullable: true, description: 当前测量详情唯一权威入仓码，与根对象inboundCode一致}
         inboundDetailId: {type: string, pattern: '^[1-9][0-9]*$', nullable: true}
         itemNo: {type: string, nullable: true}
         boxSpecification: {type: string, nullable: true}
@@ -1782,7 +1788,8 @@ components:
         coefficientMode: {type: string, enum: [ACTUAL, ADD, MULTIPLY], nullable: true}
         remark: {type: string, nullable: true}
         boxCode: {type: string, nullable: true}
-        scannedShipmentId: {type: string, nullable: true}
+        fbaShipmentNo: {type: string, nullable: true, description: Order货物明细按inboundDetailId匹配的权威FBA货件编号；匹配失败为空}
+        scannedShipmentId: {type: string, nullable: true, description: 设备实扫Shipment ID；仅作现场证据，不覆盖或回退fbaShipmentNo}
         confirmedPackageCount: {type: integer, nullable: true}
         machineNo: {type: string, nullable: true}
         deviceMeasuredAt: {type: string, format: date-time, nullable: true}
@@ -1794,7 +1801,7 @@ components:
       required: [inboundId, inboundVersion, items, weightResults]
       properties:
         inboundId: {type: string, pattern: '^[1-9][0-9]*$'}
-        inboundCode: {type: string, nullable: true}
+        inboundCode: {type: string, nullable: true, description: 当前测量详情唯一入仓码，UI业务主展示字段}
         companyName: {type: string, nullable: true}
         channelCode: {type: string, nullable: true}
         channelName: {type: string, nullable: true}

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

@@ -361,6 +361,8 @@ components:
         itemId: {$ref: '#/components/schemas/LongId'}
         accountId: {$ref: '#/components/schemas/LongId'}
         customerName: {type: string, nullable: true, description: 客户名称快照}
+        customsTaxMode: {type: string, enum: [TAX_REFUND, BUY_DECLARATION], nullable: true, description: 订单/入仓片段冻结的报关方式；不根据退税文件推断}
+        taxRefundFlag: {type: boolean, nullable: true, description: customsTaxMode为TAX_REFUND时为true、BUY_DECLARATION时为false；缺少权威事实时为null}
         orderId: {$ref: '#/components/schemas/LongId'}
         orderNo: {type: string, description: 订单号快照}
         inboundId: {$ref: '#/components/schemas/LongId'}