fix(order): complete root fulfillment only after effective remainders

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

@@ -9,10 +9,13 @@ paths:
   /internal/order/v1/fulfillment-completions:
     post:
       security: []
-      summary: Firstleg 回传海外派送完成并结束对应订单
+      summary: Firstleg 回传来源实装签收并聚合履约根订单完成
       description: >-
         仅接受内部服务令牌。请求必须携带海外事件已验证的来源订单 ID、订单号、入仓码、
-        FBA 派送单号和完成时间；只推进该派送单关联的订单，COMPLETED 重放返回成功。
+        FBA 派送单号和完成时间。来源根订单先持久化自身实装签收事实，只有全部有效余量子单
+        已完成才完成根订单；来源子单独立完成并在根锁下重新评估聚合。明确 CANCELLED 子单
+        不参与完成门禁，其他未完成状态均阻断。重复事实不得重复写历史。响应明确返回来源状态
+        status 和履约根 rootOrderId/rootStatus；根尚未聚合完成时允许保留其原状态。
       parameters:
         - name: X-Internal-Service-Token
           in: header
@@ -24,18 +27,36 @@ paths:
           application/json:
             schema:
               type: object
-              required: [tenantId, orderId, orderNo, inboundCode, deliveryNo, completedAt, eventId, payloadHash]
+              required: [tenantId, orderId, orderNo, inboundCode, rootOrderId, deliveryNo, completedAt, eventId, payloadHash]
               properties:
                 tenantId: {type: string, pattern: '^[1-9][0-9]*$'}
                 orderId: {type: string, pattern: '^[1-9][0-9]*$'}
                 orderNo: {type: string}
                 inboundCode: {type: string}
+                rootOrderId: {type: string, pattern: '^[1-9][0-9]*$'}
                 deliveryNo: {type: string}
                 completedAt: {type: string, format: date-time}
                 eventId: {type: string, format: uuid}
                 payloadHash: {type: string, pattern: '^[0-9a-fA-F]{64}$'}
       responses:
-        '200': {description: 对应订单已完成或幂等重放成功}
+        '200':
+          description: 来源实装签收事实已保存，返回来源和履约根各自状态
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [code, data]
+                properties:
+                  code: {type: string}
+                  data:
+                    type: object
+                    required: [orderId, status, replayed, rootOrderId, rootStatus]
+                    properties:
+                      orderId: {type: integer, format: int64}
+                      status: {type: string, enum: [APPROVED, ACCEPTED, PROCESSING, COMPLETED]}
+                      replayed: {type: boolean}
+                      rootOrderId: {type: integer, format: int64}
+                      rootStatus: {type: string, enum: [APPROVED, ACCEPTED, PROCESSING, COMPLETED]}
         '403': {description: 内部服务令牌无效}
   /internal/order/v1/cargoes/{tenantId}/{orderId}:
     get: