feat(firstleg): enforce pricing adjustment bounds

firstleg/src/main/resources/db/phase2-inbound-schema.sql

@@ -672,6 +672,8 @@ CREATE TABLE IF NOT EXISTS fl_inbound_fee (
   actual_weight_kg DECIMAL(18,3) NOT NULL COMMENT '试算时实际重量kg',
   actual_volume_cbm DECIMAL(18,4) NOT NULL COMMENT '试算时实际体积m3',
   converted_quantity DECIMAL(18,4) NOT NULL COMMENT '换算后的重量或体积',
+  baseline_chargeable_quantity DECIMAL(18,6) NOT NULL COMMENT '系统按权威测量与生效报价计算的原始计费量',
+  tolerance_percent DECIMAL(5,2) NOT NULL DEFAULT 10.00 COMMENT '人工调整允许的最大偏差百分比，边界包含',
   chargeable_quantity DECIMAL(18,4) NOT NULL COMMENT '最终计费量',
   charge_unit VARCHAR(16) NOT NULL COMMENT '计费单位',
   currency CHAR(3) NOT NULL COMMENT '币种',
@@ -701,6 +703,32 @@ CREATE TABLE IF NOT EXISTS fl_inbound_fee (
   CONSTRAINT fk_fee_carrier_rate FOREIGN KEY (carrier_rate_id) REFERENCES fl_carrier_fba_rate (id)
 ) ENGINE=InnoDB COMMENT='入库头程费用计算和确认快照';
 
+SET @fee_baseline_quantity_sql = IF(
+  EXISTS(SELECT 1 FROM information_schema.columns WHERE table_schema=DATABASE()
+    AND table_name='fl_inbound_fee' AND column_name='baseline_chargeable_quantity'),
+  'SELECT 1',
+  'ALTER TABLE fl_inbound_fee ADD COLUMN baseline_chargeable_quantity DECIMAL(18,6) NULL COMMENT ''系统按权威测量与生效报价计算的原始计费量'' AFTER converted_quantity'
+);
+PREPARE fee_baseline_quantity_stmt FROM @fee_baseline_quantity_sql;
+EXECUTE fee_baseline_quantity_stmt;
+DEALLOCATE PREPARE fee_baseline_quantity_stmt;
+UPDATE fl_inbound_fee
+   SET baseline_chargeable_quantity = chargeable_quantity
+ WHERE baseline_chargeable_quantity IS NULL;
+ALTER TABLE fl_inbound_fee
+  MODIFY COLUMN baseline_chargeable_quantity DECIMAL(18,6) NOT NULL
+  COMMENT '系统按权威测量与生效报价计算的原始计费量';
+
+SET @fee_tolerance_percent_sql = IF(
+  EXISTS(SELECT 1 FROM information_schema.columns WHERE table_schema=DATABASE()
+    AND table_name='fl_inbound_fee' AND column_name='tolerance_percent'),
+  'SELECT 1',
+  'ALTER TABLE fl_inbound_fee ADD COLUMN tolerance_percent DECIMAL(5,2) NOT NULL DEFAULT 10.00 COMMENT ''人工调整允许的最大偏差百分比，边界包含'' AFTER baseline_chargeable_quantity'
+);
+PREPARE fee_tolerance_percent_stmt FROM @fee_tolerance_percent_sql;
+EXECUTE fee_tolerance_percent_stmt;
+DEALLOCATE PREPARE fee_tolerance_percent_stmt;
+
 CREATE TABLE IF NOT EXISTS fl_inbound_fee_item (
   id BIGINT UNSIGNED NOT NULL COMMENT '费用明细ID',
   tenant_id BIGINT UNSIGNED NOT NULL COMMENT '客户ID和数据隔离键',

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
@@ -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}