优化

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

@@ -2,10 +2,74 @@ openapi: 3.0.3
 info:
   title: 柏悦头程订单 API
   description: 业务成功和失败均使用 HTTP 200；仅响应体 code 为字符串 "200" 时表示成功，其他 code 表示失败。
-  version: 1.1.0
+  version: 1.2.0
 security:
   - bearerAuth: []
 paths:
+  /api/platform/v1/orders:
+    get:
+      summary: 平台统一订单列表
+      description: >-
+        统一返回七态产品主状态、下一步动作及测量/预装/装柜/派送摘要，需要 platform:order:list。
+        有入库单时同时返回 inboundId、inboundVersion、loadingVersion、pickingVersion；inboundVersion
+        才是 C04 loading/complete 的 expectedVersion，loadingVersion 当前等于 pickingVersion（兼容别名）。
+        tenantId 省略时跨全部客户；mainStatus 省略时按订单创建时间分页，指定 PENDING_REVIEW 时由 Order 查询，
+        指定其他主状态时由 Firstleg 精确分页。旧 /orders/first-leg 接口保持兼容。
+      parameters:
+        - {name: tenantId, in: query, required: false, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
+        - $ref: '#/components/parameters/UnifiedKeyword'
+        - $ref: '#/components/parameters/UnifiedOrderNo'
+        - $ref: '#/components/parameters/UnifiedMainStatus'
+        - {name: customerId, in: query, required: false, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
+        - {name: receivingWarehouseId, in: query, required: false, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
+        - {name: destinationWarehouseId, in: query, required: false, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
+        - $ref: '#/components/parameters/UnifiedCreatedFrom'
+        - $ref: '#/components/parameters/UnifiedCreatedTo'
+        - $ref: '#/components/parameters/UnifiedPage'
+        - $ref: '#/components/parameters/UnifiedSize'
+      responses:
+        '200': {description: 成功或业务失败，响应体 code 为字符串 200 时成功}
+        '403': {description: 需要平台身份和 platform:order:list 权限}
+  /api/platform/v1/orders/{orderId}:
+    get:
+      summary: 平台统一订单详情
+      description: 合并 Order 与 Firstleg 时间线并按发生时间升序返回；平台可见内部备注。
+      parameters:
+        - $ref: '#/components/parameters/UnifiedOrderId'
+        - $ref: '#/components/parameters/UnifiedTenantId'
+      responses:
+        '200': {description: 成功或业务失败，按响应体 code 判断}
+        '403': {description: 需要平台身份和 platform:order:list 权限}
+  /api/merchant/v1/orders:
+    get:
+      summary: 客户统一订单列表
+      description: >-
+        只按登录态客户隔离查询，需要 merchant:order:list；不接受目标客户参数。
+        有入库单时同时返回 inboundId、inboundVersion、loadingVersion、pickingVersion；inboundVersion
+        才是 C04 loading/complete 的 expectedVersion，loadingVersion 当前等于 pickingVersion（兼容别名）。
+      parameters:
+        - $ref: '#/components/parameters/UnifiedKeyword'
+        - $ref: '#/components/parameters/UnifiedOrderNo'
+        - $ref: '#/components/parameters/UnifiedMainStatus'
+        - {name: customerId, in: query, required: false, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
+        - {name: receivingWarehouseId, in: query, required: false, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
+        - {name: destinationWarehouseId, in: query, required: false, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
+        - $ref: '#/components/parameters/UnifiedCreatedFrom'
+        - $ref: '#/components/parameters/UnifiedCreatedTo'
+        - $ref: '#/components/parameters/UnifiedPage'
+        - $ref: '#/components/parameters/UnifiedSize'
+      responses:
+        '200': {description: 成功或业务失败，按响应体 code 判断}
+        '403': {description: 需要 merchant:order:list 权限}
+  /api/merchant/v1/orders/{orderId}:
+    get:
+      summary: 客户统一订单详情
+      description: 仅返回登录客户所属订单及客户可见时间线，不返回平台内部备注。
+      parameters:
+        - $ref: '#/components/parameters/UnifiedOrderId'
+      responses:
+        '200': {description: 成功或业务失败，按响应体 code 判断}
+        '403': {description: 需要 merchant:order:view 权限}
   /api/merchant/v1/orders/first-leg:
     get:
       summary: 客户端入库订单聚合列表
@@ -119,6 +183,55 @@ components:
       scheme: bearer
       bearerFormat: JWT
   parameters:
+    UnifiedKeyword:
+      name: keyword
+      in: query
+      required: false
+      schema: {type: string, maxLength: 64}
+    UnifiedOrderNo:
+      name: orderNo
+      in: query
+      required: false
+      schema: {type: string, maxLength: 64}
+    UnifiedMainStatus:
+      name: mainStatus
+      in: query
+      required: false
+      schema:
+        type: string
+        enum: [PENDING_REVIEW, WAIT_MEASURE, INBOUNDED, WAIT_SPLIT, LOADING, LOADED, DELIVERED]
+    UnifiedCreatedFrom:
+      name: createdFrom
+      in: query
+      required: false
+      description: 无主状态或待审核筛选按订单创建时间；其他主状态按履约快照创建时间
+      schema: {type: string, format: date-time}
+    UnifiedCreatedTo:
+      name: createdTo
+      in: query
+      required: false
+      description: 无主状态或待审核筛选按订单创建时间；其他主状态按履约快照创建时间
+      schema: {type: string, format: date-time}
+    UnifiedPage:
+      name: page
+      in: query
+      required: false
+      schema: {type: integer, minimum: 1, default: 1}
+    UnifiedSize:
+      name: size
+      in: query
+      required: false
+      schema: {type: integer, minimum: 1, maximum: 200, default: 20}
+    UnifiedOrderId:
+      name: orderId
+      in: path
+      required: true
+      schema: {type: string, pattern: '^[1-9][0-9]*$'}
+    UnifiedTenantId:
+      name: tenantId
+      in: query
+      required: true
+      schema: {type: string, pattern: '^[1-9][0-9]*$'}
     TenantId:
       name: tenantId
       in: query