优化

2026-09-01 21:09:33 +08:00
parent 47723c7c0f
commit e82cefe493
25 changed files with 712 additions and 40 deletions
@@ -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}