提交

2026-11-02 17:14:02 +08:00
parent 035e7e06af
commit 21a9ce7d27
98 changed files with 2558 additions and 104 deletions
@@ -0,0 +1,68 @@
+openapi: 3.0.3
+info:
+  title: 本土散板排车照片履约
+  version: 1.0.0
+  description: >-
+    仅同客户权威关联的本土散板明细进入照片节点。全车为散板且尚无真实扫码时，审核通过后逐票保存取货照片，
+    自动从LOADING进入DELIVERING；不生成库存、PDA拣货或仓库出库事实。逐票保存送达照片后自动DELIVERED并结案释放车辆司机。
+    混排从AFTER_LOADING或DELIVERING可逐票保存取货及送达照片；同票须先取货再送达，不同票不限制取送顺序。
+    装车后保存照片保持原阶段，保留原PDA出库及装车资料齐全后进入派送的链路；全部仓内货签收且散板照片齐全才可整车完结。既有真实扫码不可抹除或倒改。
+    图片只接受10MiB以内JPG或PNG，每票每节点最多20张。保存提交该节点完整保留列表，支持追加和逐张删除；空列表代表删除最后一张。
+    整车已完结的节点及已有送达照片的取货节点至少保留一张凭证，可先追加再删除；修改照片不撤销已执行的取货、发运或送达，不重复累计货量。
+    上传不等于保存，保存用公共版本和幂等键，失败同事务回滚。历史照片列表保留审计，仅最新列表授权预览。
+    本土散板号只用LB原单，不生成入仓码、柜号或虚构派送单号。分车运输按已保存送达照片的明细去重累计箱数，整票送达后才完成原单。
+paths:
+  /api/platform/v1/last-leg/dispatches/{number}/looseboard-execution:
+    parameters:
+      - { name: number, in: path, required: true, schema: { type: string } }
+    get:
+      summary: 读取散板逐票照片与节点资格
+      description: 需要platform:overseas-warehouse:dispatch:list。data包含dispatchNo、recordVersion、stage、direct和items；items包含itemId、customerId、orderNo、destination、packages、pickupPhotos、arrivalPhotos、canPickup、canArrive。
+      responses: { '200': { description: 统一ApiResponse } }
+  /api/platform/v1/last-leg/dispatches/{number}/looseboard-execution/{itemId}/{phase}/uploads:
+    parameters:
+      - { name: number, in: path, required: true, schema: { type: string } }
+      - { name: itemId, in: path, required: true, schema: { type: string, pattern: '^[1-9][0-9]*$' } }
+      - { name: phase, in: path, required: true, schema: { type: string, enum: [PICKUP, ARRIVAL] } }
+    post:
+      summary: 上传本车本节点照片，尚不作为保存或发运事实
+      description: 需要platform:overseas-warehouse:dispatch:edit。文件业务归属为平台、本车ID、独立节点类别。
+      requestBody:
+        required: true
+        content:
+          multipart/form-data:
+            schema:
+              type: object
+              required: [file]
+              properties: { file: { type: string, format: binary } }
+      responses: { '200': { description: data为fileId、fileName、contentType、sizeBytes } }
+  /api/platform/v1/last-leg/dispatches/{number}/looseboard-execution/{itemId}/{phase}:
+    parameters:
+      - { name: number, in: path, required: true, schema: { type: string } }
+      - { name: itemId, in: path, required: true, schema: { type: string } }
+      - { name: phase, in: path, required: true, schema: { type: string, enum: [PICKUP, ARRIVAL] } }
+    put:
+      summary: 保存逐票节点照片并原子核对运输进度
+      description: 需要platform:overseas-warehouse:dispatch:edit；不得跨车、跨节点或在不同票之间重复绑定照片。重审轮次变化后旧照片保留历史但不代替本轮履约。
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [recordVersion, idempotencyKey, fileIds]
+              properties:
+                recordVersion: { type: integer, format: int64, minimum: 0 }
+                idempotencyKey: { type: string, minLength: 8, maxLength: 128 }
+                fileIds: { type: array, maxItems: 20, uniqueItems: true, description: 本节点完整保留照片列表，空列表用于删除最后一张且受已履约凭证约束, items: { type: string, pattern: '^[1-9][0-9]*$' } }
+      responses: { '200': { description: 返回当前整车照片状态；重复原命令不重复推进运输或生成作业事实 } }
+  /api/platform/v1/last-leg/dispatches/{number}/looseboard-execution/{itemId}/{phase}/files/{fileId}/content:
+    parameters:
+      - { name: number, in: path, required: true, schema: { type: string } }
+      - { name: itemId, in: path, required: true, schema: { type: string } }
+      - { name: phase, in: path, required: true, schema: { type: string, enum: [PICKUP, ARRIVAL] } }
+      - { name: fileId, in: path, required: true, schema: { type: string } }
+    get:
+      summary: 读取当前明细节点已保存照片
+      description: 需要platform:overseas-warehouse:dispatch:list；未保存上传和其他票照片不可读取。
+      responses: { '200': { description: JPG或PNG，Cache-Control no-store } }