fix: complete phase5 overseas deployment contract

2026-09-01 20:20:25 +08:00
parent d88e5cffce 8e17401f37
commit 974d7b1e43
45 changed files with 810 additions and 638 deletions
@@ -0,0 +1,79 @@
+openapi: 3.0.3
+info:
+  title: Lastleg Internal Dropship API
+  version: 1.0.0
+  description: 国内头程事件落地后向海外 Lastleg 冻结一件代发托盘、SKU 与箱唛快照的内部同步契约。
+paths:
+  /internal/v1/lastleg/dropship/receive:
+    post:
+      summary: 接收一件代发托盘与 SKU 快照
+      description: 仅服务间调用；必须携带内部服务令牌。相同 customerId、orderId 与 idempotencyKey 重放返回既有结果。
+      security:
+        - internalServiceToken: []
+      parameters:
+        - name: X-Internal-Service-Token
+          in: header
+          required: true
+          schema: { type: string, minLength: 1 }
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: '#/components/schemas/DropshipReceiveRequest' }
+      responses:
+        '200':
+          description: 统一 ApiResponse，data 为接收的箱唛数量
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/IntegerApiResponse' }
+        '401': { description: 内部服务令牌缺失或无效 }
+components:
+  securitySchemes:
+    internalServiceToken:
+      type: apiKey
+      in: header
+      name: X-Internal-Service-Token
+  schemas:
+    DropshipReceiveRequest:
+      type: object
+      required: [customerId, orderId, warehouseId, idempotencyKey, pallets]
+      properties:
+        customerId: { type: string, minLength: 1, description: 客户数据隔离键 }
+        orderId: { type: integer, format: int64, description: Lastleg 尾程订单 ID }
+        warehouseId: { type: integer, format: int64, description: 海外仓 ID 快照 }
+        idempotencyKey: { type: string, minLength: 1, description: 跨区域调用幂等键 }
+        pallets:
+          type: array
+          minItems: 1
+          items: { $ref: '#/components/schemas/DropshipPallet' }
+    DropshipPallet:
+      type: object
+      required: [palletNo, skuPackages]
+      properties:
+        palletNo: { type: string, minLength: 1, description: 来源头程托盘号快照 }
+        skuPackages:
+          type: array
+          minItems: 1
+          items: { $ref: '#/components/schemas/DropshipSkuPackages' }
+    DropshipSkuPackages:
+      type: object
+      required: [skuCode, packageCount, productQuantity, cartonMarks]
+      properties:
+        skuCode: { type: string, minLength: 1 }
+        productName: { type: string, nullable: true }
+        packageCount: { type: integer, format: int64, minimum: 1 }
+        productQuantity: { type: integer, format: int64, minimum: 1 }
+        cartonMarks:
+          type: array
+          minItems: 1
+          items: { type: string, minLength: 1 }
+    IntegerApiResponse:
+      type: object
+      required: [code, message, data, timestamp]
+      properties:
+        code: { type: string, example: '200' }
+        message: { type: string }
+        data: { type: integer, format: int32, minimum: 0 }
+        requestId: { type: string, nullable: true }
+        traceId: { type: string, nullable: true }
+        timestamp: { type: string, format: date-time }