优化

order/src/main/resources/db/phase1-order-extension.sql

@@ -61,6 +61,15 @@ CALL phase1_add_column('ord_order_cargo', 'shipment_id', "VARCHAR(64) NULL COMME
 CALL phase1_add_column('ord_order_cargo', 'reference_id', "VARCHAR(64) NULL COMMENT 'Cargo Amazon Reference ID'");
 CALL phase1_add_column('ord_order_cargo', 'product_image_file_id', "BIGINT UNSIGNED NULL COMMENT 'Product image logical file ID'");
 
+-- 货物级字段上线前，FBA 编号只保存在主单；回填后提交校验可统一按每条货物执行。
+UPDATE ord_order_cargo cargo
+JOIN ord_order orders ON orders.id = cargo.order_id AND orders.tenant_id = cargo.tenant_id
+SET cargo.shipment_id = COALESCE(NULLIF(cargo.shipment_id, ''), orders.shipment_id),
+    cargo.reference_id = COALESCE(NULLIF(cargo.reference_id, ''), orders.reference_id)
+WHERE orders.destination_type = 'FBA'
+  AND ((cargo.shipment_id IS NULL OR cargo.shipment_id = '')
+    OR (cargo.reference_id IS NULL OR cargo.reference_id = ''));
+
 DROP PROCEDURE phase1_add_column;
 
 -- 已有订单库的幂等记录迁移，和订单写入处于同一个本地事务。

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

@@ -2,7 +2,7 @@ openapi: 3.0.3
 info:
   title: 柏悦头程订单 API
   description: 业务成功和失败均使用 HTTP 200；仅响应体 code 为字符串 "200" 时表示成功，其他 code 表示失败。
-  version: 1.4.0
+  version: 1.5.0
 security:
   - bearerAuth: []
 paths:
@@ -241,12 +241,53 @@ components:
       description: 报价包税维度；独立于订单 taxMode 的买单/退税语义
     FirstLegOrderDraft:
       type: object
-      required: [pricingTaxMode]
+      required: [pricingTaxMode, cargoes]
       properties:
         pricingTaxMode: {$ref: '#/components/schemas/PricingTaxMode'}
+        cargoes:
+          type: array
+          minItems: 1
+          items: {$ref: '#/components/schemas/FirstLegOrderCargo'}
       description: >-
         订单保存请求中的完整字段以服务端 FirstLegOrderSaveRequest 为准；pricingTaxMode
         是新建和编辑订单的必填报价维度；历史存量订单的响应字段仍允许为空。
+    FirstLegOrderCargo:
+      type: object
+      required: [cargoName, packageType, packageCount, grossWeightKg, volumeCbm]
+      properties:
+        skuNo: {type: string, maxLength: 64}
+        cargoName: {type: string, maxLength: 128}
+        cargoNameEn: {type: string, maxLength: 128}
+        productImageFileId: {type: string, pattern: '^[1-9][0-9]*$'}
+        hsCode: {type: string, maxLength: 20, description: 报关 HS CODE}
+        customsHsCode: {type: string, maxLength: 20, description: 清关 HS CODE}
+        lengthCm: {type: number, minimum: 0, description: 箱规长（厘米）}
+        widthCm: {type: number, minimum: 0, description: 箱规宽（厘米）}
+        heightCm: {type: number, minimum: 0, description: 箱规高（厘米）}
+        unitsPerPackage: {type: integer, minimum: 1, description: 每箱数量}
+        packageCount: {type: integer, minimum: 1, description: 箱数}
+        grossWeightKg: {type: number, exclusiveMinimum: true, minimum: 0, description: 总毛重}
+        volumeCbm: {type: number, exclusiveMinimum: true, minimum: 0, description: 总体积}
+        totalQuantity: {type: integer, minimum: 1, description: 总数量}
+        netWeightKg: {type: number, exclusiveMinimum: true, minimum: 0, description: 总净重}
+        unitDeclaredValue: {type: number, minimum: 0, description: 清关申报单价（USD）}
+        declaredValue: {type: number, minimum: 0, description: 清关申报金额（USD）}
+        material: {type: string, maxLength: 128}
+        usage: {type: string, maxLength: 128}
+        model: {type: string, maxLength: 64}
+        brand: {type: string, maxLength: 64}
+        productLengthCm: {type: number, minimum: 0}
+        productWidthCm: {type: number, minimum: 0}
+        productHeightCm: {type: number, minimum: 0}
+        shipmentId: {type: string, maxLength: 64}
+        referenceId: {type: string, maxLength: 64}
+        upcNo: {type: string, maxLength: 64}
+        cargoRemark: {type: string, maxLength: 500}
+        packageType: {type: string, maxLength: 32}
+        dangerousGoods: {type: boolean}
+      description: >-
+        原型货物明细字段。FBA 货物的 skuNo、upcNo、shipmentId、referenceId 由服务端按每条货物校验；
+        productImageFileId 必须属于当前登录客户。
     FirstLegOrderSummary:
       type: object
       properties: