feat: complete phase 5 overseas fulfillment contracts

2026-09-01 14:24:59 +08:00
parent ffed9bf898
commit 97168b19d8
46 changed files with 2446 additions and 409 deletions
@@ -2,10 +2,71 @@ openapi: 3.0.3
 info:
  title: Lastleg Overseas PDA Warehouse Operations API
  version: 1.0.0
-  description: 海外仓PDA盘点、同仓整托移库、托盘作业与换标现场作业；全部范围从PDA Token解析。
+  description: 海外仓PDA排车拣货发车、一件代发出库、盘点、同仓整托移库、托盘与换标作业；全部范围从PDA Token解析，派送不进入PDA。
 security:
  - bearerAuth: []
 paths:
+  /api/pda/v1/last-leg/dispatches:
+    get:
+      summary: 查询Token绑定仓的排车PDA任务
+      description: 仅 OVERSEAS_WAREHOUSE_PDA_OPERATOR + lastleg:pda:operate；跨客户读取绑定仓任务，不接收customerId或warehouseId。
+      parameters: [{ name: status, in: query, required: false, schema: { type: string } }]
+      responses: { '200': { description: 排车任务列表 }, '403': { description: 角色、权限或仓库绑定缺失 } }
+  /api/pda/v1/last-leg/dispatches/{dispatchNo}:
+    get:
+      summary: 查询绑定仓排车任务详情
+      parameters: [{ name: dispatchNo, in: path, required: true, schema: { type: string } }]
+      responses: { '200': { description: 排车托盘、目的仓与库存位置详情 }, '404': { description: 当前绑定仓无此排车任务 } }
+  /api/pda/v1/last-leg/dispatches/{dispatchNo}/items/{itemId}/pick:
+    post:
+      summary: 扫码拣取排车托盘包裹
+      parameters:
+        - { name: dispatchNo, in: path, required: true, schema: { type: string } }
+        - { name: itemId, in: path, required: true, schema: { type: string, pattern: '^[0-9]+$' } }
+      requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/DispatchPick' } } } }
+      responses: { '200': { description: 本次及累计拣货结果；同键同请求重放既有结果 }, '409': { description: 跨仓、跨客户、库存、数量或幂等冲突 } }
+  /api/pda/v1/last-leg/dispatches/{dispatchNo}/complete:
+    post:
+      summary: 完成排车拣货
+      description: 每个要求托盘及全部包裹必须精确完成；不允许部分完成。
+      parameters: [{ name: dispatchNo, in: path, required: true, schema: { type: string } }]
+      requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/IdempotentAction' } } } }
+      responses: { '200': { description: READY_TO_DEPART结果 }, '409': { description: 未全部拣货或幂等冲突 } }
+  /api/pda/v1/last-leg/dispatches/{dispatchNo}/depart:
+    post:
+      summary: 排车发车并完成出库门禁
+      description: 仅完整拣货且存在待出库单时发车；同事务推进出库与排车状态、订单归属并释放托盘锁，不重复扣减扫码时已扣库存。
+      parameters: [{ name: dispatchNo, in: path, required: true, schema: { type: string } }]
+      requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/DepartAction' } } } }
+      responses: { '200': { description: DEPARTED结果；同键同请求返回既有结果 }, '409': { description: 拣货、出库或幂等门禁未满足 } }
+  /api/pda/v1/last-leg/outbound-tasks:
+    get:
+      summary: 查询Token绑定仓的一件代发出库任务
+      description: 一件代发复用统一出库任务模型；不接收customerId或warehouseId，派送不进入PDA。
+      parameters: [{ name: status, in: query, required: false, schema: { type: string } }]
+      responses: { '200': { description: 出库任务列表 } }
+  /api/pda/v1/last-leg/outbound-tasks/{taskNo}:
+    get:
+      summary: 查询一件代发出库任务详情
+      parameters: [{ name: taskNo, in: path, required: true, schema: { type: string } }]
+      responses:
+        '200':
+          description: 出库任务、出库项及每条可拣库存位置；inventoryPositionId仅作为pick提交键，不作为用户展示编号
+          content: { application/json: { schema: { $ref: '#/components/schemas/PdaOutboundTaskDetail' } } }
+        '404': { description: 当前绑定仓无此任务 }
+  /api/pda/v1/last-leg/outbound-tasks/{taskNo}/pick:
+    post:
+      summary: 扫码拣取一件代发箱件
+      parameters: [{ name: taskNo, in: path, required: true, schema: { type: string } }]
+      requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/OutboundPick' } } } }
+      responses: { '200': { description: 更新后的统一出库任务 }, '409': { description: 库存、数量或幂等冲突 } }
+  /api/pda/v1/last-leg/outbound-tasks/{taskNo}/complete:
+    post:
+      summary: 完成一件代发出库任务
+      description: 全部托盘及箱件精确拣完后完成；同一完成幂等键返回既有结果，其他键明确冲突。
+      parameters: [{ name: taskNo, in: path, required: true, schema: { type: string } }]
+      requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/IdempotentAction' } } } }
+      responses: { '200': { description: COMPLETED任务 }, '409': { description: 未全部拣货或幂等冲突 } }
  /api/pda/v1/last-leg/stocktakes:
    get:
      summary: 查询Token绑定仓盘点任务
@@ -128,6 +189,68 @@ components:
      type: object
      required: [idempotencyKey]
      properties: { idempotencyKey: { type: string, minLength: 1, maxLength: 255 } }
+    DepartAction:
+      type: object
+      required: [idempotencyKey]
+      properties:
+        idempotencyKey: { type: string, minLength: 1, maxLength: 255 }
+        remark: { type: string, maxLength: 1000, nullable: true }
+    DispatchPick:
+      type: object
+      required: [positionId, packages, productQuantity, idempotencyKey]
+      properties:
+        positionId: { type: string, pattern: '^[0-9]+$' }
+        packages: { type: integer, format: int64, minimum: 1 }
+        productQuantity: { type: integer, format: int64, minimum: 0 }
+        idempotencyKey: { type: string, minLength: 1, maxLength: 255 }
+        remark: { type: string, maxLength: 1000, nullable: true }
+    OutboundPick:
+      type: object
+      required: [outboundPalletItemId, inventoryPositionId, packages, idempotencyKey]
+      properties:
+        outboundPalletItemId: { type: string, pattern: '^[0-9]+$' }
+        inventoryPositionId: { type: string, pattern: '^[0-9]+$' }
+        packages: { type: integer, format: int64, minimum: 1 }
+        idempotencyKey: { type: string, minLength: 1, maxLength: 255 }
+    PdaOutboundTaskDetail:
+      type: object
+      required: [task, items]
+      properties:
+        task:
+          type: object
+          required: [taskNo, status, outboundNo]
+          properties:
+            taskNo: { type: string }
+            status: { type: string }
+            outboundNo: { type: string }
+            pushedAt: { type: string, format: date-time, nullable: true }
+            completedAt: { type: string, format: date-time, nullable: true }
+        items:
+          type: array
+          items:
+            type: object
+            required: [outboundPalletItemId, palletNo, skuCode, inboundCode, packageCount, pickedPackageCount, status, positions]
+            properties:
+              outboundPalletItemId: { type: string, description: pick请求提交键，不作为用户展示编号 }
+              palletNo: { type: string }
+              skuCode: { type: string }
+              inboundCode: { type: string }
+              packageCount: { type: integer }
+              pickedPackageCount: { type: integer }
+              status: { type: string }
+              positions:
+                type: array
+                items:
+                  type: object
+                  required: [inventoryPositionId, palletNo, cartonMark, skuCode, inboundCode, availablePackages, pickedPackages]
+                  properties:
+                    inventoryPositionId: { type: string, description: pick请求提交键，不作为用户展示编号 }
+                    palletNo: { type: string }
+                    cartonMark: { type: string, nullable: true }
+                    skuCode: { type: string }
+                    inboundCode: { type: string }
+                    availablePackages: { type: integer, format: int64, minimum: 0 }
+                    pickedPackages: { type: integer, format: int64, minimum: 0 }
    StocktakeCreate:
      type: object
      required: [scopeType, scopeCode, idempotencyKey]