优化

order/src/main/resources/db/order.sql

@@ -19,6 +19,7 @@ CREATE TABLE IF NOT EXISTS ord_order (
   destination_warehouse_id BIGINT UNSIGNED NULL COMMENT '目的仓逻辑ID',
   destination_warehouse_name VARCHAR(128) NOT NULL COMMENT '目的仓名称快照',
   expected_ship_date DATE NULL COMMENT '预计发运日期',
+  expected_arrival_at DATETIME(3) NULL COMMENT '客户申报预计到货时间',
   customer_remark VARCHAR(1000) NULL COMMENT '客户可见备注',
   pickup_method VARCHAR(24) NULL COMMENT '取货方式',
   requested_pickup_at DATETIME(3) NULL COMMENT '客户要求平台上门提货的预约时间',
@@ -28,6 +29,7 @@ CREATE TABLE IF NOT EXISTS ord_order (
   receiving_time VARCHAR(128) NULL COMMENT '国内收货仓收货时间快照',
   channel_code VARCHAR(64) NULL COMMENT '渠道编码',
   channel_name VARCHAR(128) NULL COMMENT '渠道名称快照',
+  channel_changed TINYINT(1) NOT NULL DEFAULT 0 COMMENT '订单历史上是否由平台变更过渠道',
   carrier_id BIGINT UNSIGNED NULL COMMENT '船司逻辑ID快照',
   carrier_name VARCHAR(128) NULL COMMENT '船司名称快照',
   tax_mode VARCHAR(24) NULL COMMENT '买单或退税',

order/src/main/resources/db/platform-order-declaration-edit.sql

@@ -0,0 +1,22 @@
+-- 尚未执行。测试库执行前需获得当前轮 SQL 授权。
+USE baiyue_order;
+
+ALTER TABLE ord_order
+  ADD COLUMN expected_arrival_at DATETIME(3) NULL COMMENT '客户申报预计到货时间' AFTER expected_ship_date,
+  ADD COLUMN channel_changed TINYINT(1) NOT NULL DEFAULT 0 COMMENT '订单历史上是否由平台变更过渠道' AFTER channel_name;
+
+USE baiyue_iam;
+
+INSERT INTO iam_permission
+  (id, tenant_id, app_code, permission_type, parent_id, permission_code, permission_name,
+   route_path, http_method, sort_no, status, deleted)
+VALUES
+  (5102027, 0, 'PLATFORM', 'BUTTON', 5102010, 'platform:order:declaration:edit',
+   '修改客户申报资料', NULL, NULL, 121, 'ACTIVE', 0)
+ON DUPLICATE KEY UPDATE permission_name = VALUES(permission_name), parent_id = VALUES(parent_id),
+  sort_no = VALUES(sort_no), status = 'ACTIVE', deleted = 0;
+
+INSERT INTO iam_role_permission (role_id, permission_id, tenant_id)
+SELECT role_id, 5102027, 0
+FROM (SELECT 4000001 AS role_id UNION ALL SELECT 4000003 AS role_id) roles
+ON DUPLICATE KEY UPDATE tenant_id = VALUES(tenant_id);

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

@@ -206,6 +206,25 @@ paths:
       responses:
         '200': {description: 备注添加成功或业务失败，按响应体 code 判断}
         '403': {description: 需要 platform:order:note 权限}
+  /api/platform/v1/orders/{orderId}/declaration:
+    put:
+      summary: 版本化修改客户原始申报资料
+      description: >-
+        需要 platform:order:declaration:edit。货物使用订单内 itemNo 定位，不接受货物数据库 ID；
+        不允许修改客户、国内收货仓、订单号、入仓码、状态、仓库/PDA/设备实测、测量审核或计费事实。
+        审核通过订单仅在尚无测量、同柜组、分柜、装柜或计费事实时受理，并通过
+        ORDER_DECLARATION_UPDATED_V1 Outbox 快照同步 Firstleg；消费者按 eventId 幂等、version 顺序应用。
+      parameters:
+        - $ref: '#/components/parameters/UnifiedOrderId'
+        - $ref: '#/components/parameters/UnifiedTenantId'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: {$ref: '#/components/schemas/OrderDeclarationUpdateRequest'}
+      responses:
+        '200': {description: 成功返回新版本、渠道历史标记和字段级前后值；版本冲突或存在不可逆履约事实时响应体业务码为 A0409}
+        '403': {description: 无权限或非平台身份}
   /api/merchant/v1/orders:
     get:
       summary: 客户统一订单列表
@@ -553,6 +572,43 @@ components:
         fbaCode: {type: string, maxLength: 64}
         createdFrom: {type: string, format: date-time}
         createdTo: {type: string, format: date-time}
+    OrderDeclarationUpdateRequest:
+      type: object
+      required: [expectedVersion, cargoes]
+      properties:
+        expectedVersion: {type: integer, minimum: 0}
+        customerRemark: {type: string, nullable: true, maxLength: 1000}
+        expectedArrivalAt: {type: string, format: date-time, nullable: true}
+        channelCode: {type: string, maxLength: 64, description: 与 channelName 同时传；变更时重新校验价格渠道，入仓码保持不变}
+        channelName: {type: string, maxLength: 128}
+        cargoes: {type: array, minItems: 1, maxItems: 500, items: {$ref: '#/components/schemas/OrderDeclarationCargo'}}
+    OrderDeclarationCargo:
+      type: object
+      required: [itemNo, cargoName, packageCount, totalQuantity, lengthCm, widthCm, heightCm, grossWeightKg, volumeCbm]
+      properties:
+        itemNo: {type: integer, minimum: 1, maximum: 500, description: 订单内稳定货物行号}
+        cargoName: {type: string, maxLength: 128}
+        cargoNameEn: {type: string, nullable: true, maxLength: 128}
+        skuNo: {type: string, nullable: true, maxLength: 64}
+        model: {type: string, nullable: true, maxLength: 64}
+        packageCount: {type: integer, minimum: 1}
+        totalQuantity: {type: integer, minimum: 1}
+        lengthCm: {type: number, minimum: 0.01}
+        widthCm: {type: number, minimum: 0.01}
+        heightCm: {type: number, minimum: 0.01}
+        grossWeightKg: {type: number, minimum: 0.001}
+        volumeCbm: {type: number, minimum: 0.0001}
+        netWeightKg: {type: number, nullable: true, minimum: 0.001}
+        hsCode: {type: string, nullable: true, maxLength: 20}
+        customsHsCode: {type: string, nullable: true, maxLength: 20}
+        unitsPerPackage: {type: integer, nullable: true, minimum: 1}
+        unitDeclaredValue: {type: number, nullable: true, minimum: 0}
+        declaredValue: {type: number, nullable: true, minimum: 0}
+        currency: {type: string, nullable: true, pattern: '^[A-Z]{3}$'}
+        material: {type: string, nullable: true, maxLength: 128}
+        usage: {type: string, nullable: true, maxLength: 128}
+        brand: {type: string, nullable: true, maxLength: 64}
+        cargoRemark: {type: string, nullable: true, maxLength: 500}
     TenantOrderStatisticsResponse:
       type: object
       required: [tenantId, totalSubmittedOrders, currentMonthSubmittedOrders, monthStart, nextMonthStart, zoneId, asOf]
@@ -616,6 +672,7 @@ components:
         customerName: {type: string, nullable: true}
         channelCode: {type: string, nullable: true, description: 稳定物流渠道编码，仅供业务校验；直接来自当前 Order 或 Firstleg 权威快照，不由 channelName 推导}
         channelName: {type: string, nullable: true}
+        channelChanged: {type: boolean, description: 当前订单历史上是否由平台变更过渠道}
         receivingWarehouseId: {type: integer, format: int64, nullable: true}
         receivingWarehouseName: {type: string, nullable: true}
         destinationWarehouseId: {type: integer, format: int64, nullable: true}
@@ -627,8 +684,9 @@ components:
         totalPackageCount: {type: integer, nullable: true, description: 无入仓事实时为当前订单有效货物箱数合计；存在入仓业务单元后为该单元履约总箱数，拆分后不以父单原始箱数覆盖}
         recommendedPalletType: {type: string, nullable: true, description: 当前无列表级权威事实时返回 null，不得返回固定托盘类型}
         locationCodes: {type: string, nullable: true}
-        actualGrossWeightKg: {type: number, nullable: true, description: Firstleg 实测毛重；来源 actualGrossWeightKg，不以净重回退}
-        actualVolumeCbm: {type: number, nullable: true}
+        expectedVolumeCbm: {type: number, nullable: true, description: Order 客户申报货物体积合计，不得与实测体积混用}
+        actualGrossWeightKg: {type: number, nullable: true, description: 仅 Firstleg 实测毛重；无实测时返回 null}
+        actualVolumeCbm: {type: number, nullable: true, description: 仅 Firstleg 实测体积；无实测时返回 null}
         expectedArrivalAt: {type: string, format: date-time, nullable: true}
         feeReviewStatus: {type: string, nullable: true, description: Firstleg 入仓费用审核快照；财务状态不在本字段表达}
         companyName: {type: string, nullable: true}