feat(lastleg): harden container receiving contract

2026-08-24 17:37:15 +08:00
parent be1eb4f45c
commit bb74a05562
8 changed files with 288 additions and 7 deletions
@@ -3,6 +3,82 @@ info:
  title: Lastleg Overseas Business API
  version: 1.0.0
 paths:
+  /api/pda/v1/last-leg/receiving-containers/candidates:
+    get:
+      summary: 查询当前客户待签收柜号
+      description: 权限 lastleg:pda:operate；客户与操作账号均从 PDA Token 获取，不接收 customerId。
+      security: [{ bearerAuth: [] }]
+      responses: { '200': { description: 柜号候选及箱数进度 }, '403': { description: 缺少 PDA 操作权限 } }
+  /api/pda/v1/last-leg/receiving-containers/{containerNo}:
+    get:
+      summary: 查询待签收柜号详情
+      description: 权限 lastleg:pda:operate；返回柜内全部入仓码、目的类型、目的仓、托数和实收进度。
+      security: [{ bearerAuth: [] }]
+      parameters: [{ name: containerNo, in: path, required: true, schema: { type: string } }]
+      responses: { '200': { description: 柜号详情 }, '409': { description: 当前账号已锁定其他柜号 } }
+  /api/pda/v1/last-leg/receiving-containers/{containerNo}/prepare:
+    post:
+      summary: 选择当前待签收柜号
+      description: 权限 lastleg:pda:operate；建立 WAIT_SIGN 会话并以账号、柜号双唯一键防止切柜或多人同时处理。
+      security: [{ bearerAuth: [] }]
+      parameters: [{ name: containerNo, in: path, required: true, schema: { type: string } }]
+      requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/ReceivingAction' } } } }
+      responses: { '200': { description: 当前柜会话 }, '409': { description: 账号或柜号已有未完成会话 } }
+  /api/pda/v1/last-leg/receiving-containers/current/unload-photos/files:
+    post:
+      summary: 上传当前柜签收照片
+      description: 权限 lastleg:pda:operate；multipart 文件归属当前 WAIT_SIGN 会话。
+      security: [{ bearerAuth: [] }]
+      requestBody: { required: true, content: { multipart/form-data: { schema: { type: object, required: [file], properties: { file: { type: string, format: binary } } } } } }
+      responses: { '200': { description: 文件标识 }, '409': { description: 当前柜已签收 } }
+  /api/pda/v1/last-leg/receiving-containers/current/sign:
+    post:
+      summary: 签收当前柜
+      description: 权限 lastleg:pda:operate；校验非空照片归属后由 WAIT_SIGN 推进 SIGNED。
+      security: [{ bearerAuth: [] }]
+      requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/ReceivingSign' } } } }
+      responses: { '200': { description: 已签收会话 }, '409': { description: 状态或照片校验失败 } }
+  /api/pda/v1/last-leg/receiving-containers/current:
+    get:
+      summary: 恢复当前账号已签柜
+      description: 权限 lastleg:pda:operate；返回 SIGNED 或 RECEIVING 当前柜，不依赖 planNo。
+      security: [{ bearerAuth: [] }]
+      responses: { '200': { description: 当前柜完整进度 }, '404': { description: 无当前柜 } }
+  /api/pda/v1/last-leg/receiving-containers/current/cartons/resolve:
+    post:
+      summary: 解析当前柜箱唛
+      description: 权限 lastleg:pda:operate；仅 OVERSEAS 目的类型可逐箱收货，返回该箱所属入仓码完整信息。
+      security: [{ bearerAuth: [] }]
+      requestBody: { required: true, content: { application/json: { schema: { type: object, required: [cartonMark], properties: { cartonMark: { type: string } } } } } }
+      responses: { '200': { description: 箱唛与入仓码信息 }, '409': { description: 跨柜、重复箱或目的类型不符 } }
+  /api/pda/v1/last-leg/receiving-containers/current/pallets/resolve:
+    post:
+      summary: 解析当前柜实物托盘码
+      description: 权限 lastleg:pda:operate；托盘固定从 Warehouse Overseas 公共资源作用域解析并校验实际仓与目的仓。
+      security: [{ bearerAuth: [] }]
+      requestBody: { required: true, content: { application/json: { schema: { type: object, required: [palletCode, inboundCode], properties: { palletCode: { type: string }, inboundCode: { type: string } } } } } }
+      responses: { '200': { description: 可用托盘与目的匹配结果 }, '409': { description: 仓库、目的仓或托盘状态不符 } }
+  /api/pda/v1/last-leg/receiving-containers/current/receipts/bulk:
+    post:
+      summary: FBA 入仓码按箱数收货
+      description: 权限 lastleg:pda:operate；只允许 destinationType=FBA，OVERSEAS 在服务端硬拒绝；不接收 customerId、planNo、allocationId、warehouseId、locationId。
+      security: [{ bearerAuth: [] }]
+      requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/ReceivingBulk' } } } }
+      responses: { '200': { description: 本次与累计实收进度 }, '409': { description: 海外仓批量、超收或托盘不匹配 } }
+  /api/pda/v1/last-leg/receiving-containers/current/receipts/carton:
+    post:
+      summary: 海外仓入仓码逐箱收货
+      description: 权限 lastleg:pda:operate；只允许 destinationType=OVERSEAS，拒绝跨柜、重复箱和不匹配托盘。
+      security: [{ bearerAuth: [] }]
+      requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/ReceivingCarton' } } } }
+      responses: { '200': { description: 本次与累计实收进度 }, '409': { description: FBA逐箱、跨柜、重复箱或托盘不匹配 } }
+  /api/pda/v1/last-leg/receiving-containers/current/complete:
+    post:
+      summary: 完成当前柜收货并入库存
+      description: 权限 lastleg:pda:operate；仅柜内每个入仓码实收总数精确相等后完成，库存、计划、尾程状态与卸柜 Outbox 同事务落地。
+      security: [{ bearerAuth: [] }]
+      requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/ReceivingAction' } } } }
+      responses: { '200': { description: COMPLETED 柜号会话 }, '409': { description: 数量未核平或状态冲突 } }
  /api/platform/v1/last-leg/orders:
    get:
      summary: 分页查询尾程订单
@@ -340,6 +416,31 @@ paths:
      responses: { '200': { description: 统一 ApiResponse 包装的换标单详情 }, '409': { description: 非法状态迁移或关联尾程单缺失 } }
 components:
  schemas:
+    ReceivingAction:
+      type: object
+      required: [idempotencyKey]
+      properties: { idempotencyKey: { type: string, minLength: 1, maxLength: 255 } }
+    ReceivingSign:
+      type: object
+      required: [photoFileIds, idempotencyKey]
+      properties:
+        photoFileIds: { type: array, minItems: 1, uniqueItems: true, items: { type: integer, format: int64 } }
+        idempotencyKey: { type: string, minLength: 1, maxLength: 255 }
+    ReceivingBulk:
+      type: object
+      required: [inboundCode, palletCode, packageCount, idempotencyKey]
+      properties:
+        inboundCode: { type: string, minLength: 1 }
+        palletCode: { type: string, minLength: 1 }
+        packageCount: { type: integer, minimum: 1 }
+        idempotencyKey: { type: string, minLength: 1, maxLength: 255 }
+    ReceivingCarton:
+      type: object
+      required: [cartonMark, palletCode, idempotencyKey]
+      properties:
+        cartonMark: { type: string, minLength: 1 }
+        palletCode: { type: string, minLength: 1 }
+        idempotencyKey: { type: string, minLength: 1, maxLength: 255 }
    SmartDispatchCandidate:
      type: object
      properties: