fix(order): enforce versioned platform commands and submissions

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

@@ -626,10 +626,15 @@ paths:
   /api/merchant/v1/orders/first-leg/{id}/submit:
     post:
       summary: 提交订单
-      description: 每条货物的每箱数量、箱数和总数量均必填，且总数量必须等于每箱数量 × 箱数。
+      description: 必须携带读取详情时的expectedVersion；原键同载荷重放先返回首次成功，不重复提交。改版本/订单的同键请求与过期首次提交为A0409。每条货物的每箱数量、箱数和总数量均必填，且总数量必须等于每箱数量 × 箱数。
       parameters:
         - $ref: '#/components/parameters/OrderId'
         - $ref: '#/components/parameters/IdempotencyKey'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: {$ref: '#/components/schemas/OrderSubmitRequest'}
       responses:
         '200': {description: 成功或业务失败，按响应体 code 判断}
   /api/platform/v1/orders/first-leg:
@@ -750,28 +755,52 @@ paths:
   /api/platform/v1/orders/first-leg/{id}/submit:
     post:
       summary: 平台代客提交指定订单
-      description: 每条货物的每箱数量、箱数和总数量均必填，且总数量必须等于每箱数量 × 箱数。
+      description: 必须携带读取详情时的expectedVersion；原键同载荷重放先返回首次成功，不重复提交。改版本/订单的同键请求与过期首次提交为A0409。每条货物的每箱数量、箱数和总数量均必填，且总数量必须等于每箱数量 × 箱数。
       parameters:
         - $ref: '#/components/parameters/OrderId'
         - $ref: '#/components/parameters/TenantId'
         - $ref: '#/components/parameters/IdempotencyKey'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: {$ref: '#/components/schemas/OrderSubmitRequest'}
       responses:
         '200': {description: 成功或业务失败，按响应体 code 判断}
         '403': {description: 需要 platform:order:submit 权限}
   /api/platform/v1/orders/first-leg/{id}:
     put:
-      summary: 平台编辑指定订单草稿
+      summary: 平台版本化幂等编辑订单
+      description: 仅DRAFT/REJECTED/SUBMITTED可编辑；SUBMITTED保持不回退。原键同载荷先返回首次成功，不重写明细历史或重复准备入仓。缺版本/旧平铺体拒绝，首次版本冲突或同键异载荷为A0409。
       parameters:
         - $ref: '#/components/parameters/OrderId'
         - $ref: '#/components/parameters/TenantId'
+        - $ref: '#/components/parameters/IdempotencyKey'
       requestBody:
         required: true
         content:
           application/json:
-            schema: {$ref: '#/components/schemas/FirstLegOrderDraft'}
+            schema: {$ref: '#/components/schemas/PlatformOrderUpdateRequest'}
       responses:
         '200': {description: 成功或业务失败，按响应体 code 判断}
         '403': {description: 需要 platform:order:edit 权限}
+  /api/platform/v1/orders/first-leg/{id}/cancel:
+    post:
+      summary: 平台版本化幂等取消订单
+      description: 复用客户取消命令的版本、原因和幂等规则；原键同载荷成功重放不重复根聚合/历史/事件，同键异载荷或新命令重复取消为A0409。
+      parameters:
+        - $ref: '#/components/parameters/OrderId'
+        - $ref: '#/components/parameters/TenantId'
+        - $ref: '#/components/parameters/IdempotencyKey'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: {$ref: '#/components/schemas/MerchantOrderCancelRequest'}
+      responses:
+        '200': {description: 成功或业务失败，按响应体 code 判断；无业务返回数据}
+        '403': {description: 需要platform:order:cancel权限和平台身份}
+
   /internal/order/v1/fulfillment-splits:
     post:
       summary: 创建父订单装柜拆分（Firstleg 内部）
@@ -1279,6 +1308,17 @@ components:
       type: string
       enum: [TAX_INCLUDED, TAX_EXCLUDED]
       description: 报价包税维度；独立于订单 taxMode 的买单/退税语义
+    PlatformOrderUpdateRequest:
+      type: object
+      required: [expectedVersion, draft]
+      properties:
+        expectedVersion: {type: integer, minimum: 0}
+        draft: {$ref: '#/components/schemas/FirstLegOrderDraft'}
+    OrderSubmitRequest:
+      type: object
+      required: [expectedVersion]
+      properties:
+        expectedVersion: {type: integer, minimum: 0}
     MerchantDraftUpdateRequest:
       type: object
       required: [expectedVersion, draft]