Unify dispatch operations with matched published transfer fixture

lastleg-service/src/main/resources/openapi/fleet-preparation-v1.yaml

@@ -1,32 +1,10 @@
 openapi: 3.0.3
 info:
-  title: 共用车次准备与拼车连续处理
+  title: 外接登记与整车履约衔接
   version: 1.0.0
 security:
   - bearerAuth: []
 paths:
-  /api/platform/v1/last-leg/fleet/trips/prepare:
-    post:
-      summary: 原子新建或加入车次并关联所选排车单
-      description: '权限：platform:fleet:trip:edit；新建另需platform:fleet:trip:create和platform:fleet:trip:assign。新建、资源分配和全部关联在同一事务，失败回滚；幂等键同载荷重放原结果，异载荷拒绝。同仓、未执行、未绑定其他车次；不确认容量、不审批、不发车。'
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema: {$ref: '#/components/schemas/Prepare'}
-      responses:
-        '200': {description: '统一ApiResponse，data为FleetTripModels.Detail；code=200才成功'}
-  /api/platform/v1/last-leg/fleet/trips/{tripNo}/dispatch-candidates:
-    parameters: [{$ref: './fleet-trips-v1.yaml#/components/parameters/TripNo'}]
-    get:
-      summary: 本仓未关联且未开始执行的排车候选
-      description: '权限：platform:fleet:trip:list。数据库筛选后分页，绑定时重新锁定校验。候选不代表预约、装载或审核已完成。'
-      parameters:
-        - {name: keyword, in: query, schema: {type: string}}
-        - {name: page, in: query, schema: {type: integer, minimum: 1, default: 1}}
-        - {name: size, in: query, schema: {type: integer, minimum: 1, maximum: 100, default: 20}}
-      responses:
-        '200': {description: '统一分页data：records含dispatchNo、customerId、warehouseId、packageCount、route及total/page/size/pages；内部身份不作为用户业务编号'}
   /api/platform/v1/last-leg/fleet/capacity-offers/inquiries/{bookingNo}/save-and-confirm:
     parameters: [{$ref: './fleet-trips-v1.yaml#/components/parameters/BookingNo'}]
     post:
@@ -74,7 +52,7 @@ paths:
     parameters: [{$ref: './fleet-trips-v1.yaml#/components/parameters/BookingNo'}]
     post:
       summary: 实收后复用或生成排车并原子排入本车
-      description: '权限：platform:fleet:capacity-offer:manage、platform:fleet:trip:booking-edit、platform:fleet:trip:edit和platform:overseas-warehouse:inbound-order:smart-dispatch。锁原车次和本票来货，先校验实收快照、车辆、有效容量；来源有多张排车或不完整时拒绝，不另建。无排车时复用真实预排命令；任何校验或绑定失败整体回滚。同键重放不重复建单。成功将预留替换为BOUND，旧计划失效待核对，仍需审核和现场作业。'
+      description: '权限：platform:fleet:capacity-offer:manage、platform:fleet:trip:booking-edit、platform:fleet:trip:edit和platform:overseas-warehouse:dispatch:create。核对本车唯一排车主单与本票真实客户来货，校验实收快照、车辆及有效容量；货物加入该唯一主单，不能另建或挂入第二张客户排车。校验或整车加货失败整体回滚。同键重放不重复建单。成功将预留替换为BOUND，旧计划失效待核对，仍需审核和现场作业。'
       requestBody:
         required: true
         content:
@@ -85,19 +63,3 @@ paths:
 components:
   securitySchemes:
     bearerAuth: {type: http, scheme: bearer, bearerFormat: JWT}
-  schemas:
-    Prepare:
-      type: object
-      required: [dispatchNos, idempotencyKey]
-      properties:
-        tripNo: {type: string, nullable: true, maxLength: 64}
-        recordVersion: {type: integer, format: int64, nullable: true, minimum: 0}
-        plan:
-          allOf:
-            - {$ref: './fleet-trips-v1.yaml#/components/schemas/Create'}
-          nullable: true
-          description: 仅新建提交，实际创建幂等键使用外层idempotencyKey。
-        vehicleId: {type: string, nullable: true}
-        driverId: {type: string, nullable: true}
-        dispatchNos: {type: array, minItems: 1, maxItems: 100, uniqueItems: true, items: {type: string, maxLength: 64}}
-        idempotencyKey: {type: string, minLength: 8, maxLength: 128}

lastleg-service/src/main/resources/openapi/fleet-trips-v1.yaml

@@ -3,27 +3,16 @@ info:
   title: 平台运输车次与资源分配
   version: 1.0.0
   description: >-
-    车次是一次实际运输的稳定业务编号，客户排车、库存和派送单继续保留各自客户归属。
-    本文件定义计划、资源分配及客户排车单关联命令；分配或关联不会扣库存或标记发车。
-    创建可暂不指定车与司机，幂等键按创建人隔离；相同键相同内容返回同一车次，不同内容拒绝。
-    正式分配要求在役海外车辆及已确认的托位/载重/容积，以及海外司机；司机按预计任务结束时间重新核验且验证证照文件。
-    发车预览与实际发车重新核对司机当前海外区域和身份；分配后档案变更不能沿用原分配时的资格结果。
-    一个车辆或司机同时只能占用一个未释放车次；当前不提供多个未来时段的并行预约。
-    改派先取得新资源，成功后释放旧资源；整次写入与历史处于同一事务。
-    司机预计结束包含承担的返程/转场；修改预计结束须重新核验司机，所有写命令使用recordVersion。
-    普通计划接口不提供修改发车或签收状态的入口；PDA统一发车，结案检查所有客户派送终态及实发数量。
-    货物结案不释放车辆或司机；结束各资源任务独立提交实际结束时间、地点和原因，车辆另确认可用/维修/停用/已归还状态。
-    结案和结束任务命令携带版本及幂等键；结束司机任务不要求其证照仍有效，也不自动恢复其派车资格。
-    关联要求已分配车和司机，客户排车单同起运仓且未开始拣货；可跨客户关联但不改变客户数据归属。
-    同一排车单唯一关联一个车次；关联、改派、解除及尚未执行的派送单车/司机快照同步使用同一事务。
-    关联后子排车不能独立编辑、取消或单独发车；取消车次前须解除关联，已开工不允许直接解除或变更路线。
-    发车前允许在车次统一换车、换司机或调整时间，保留全部拣货事实与客户归属；已确认装载须能容纳于替换车辆。
-    改派或调整计划使原装载确认失效，发车前须重新确认；不支持用计划接口处理在途换车或撤销已执行货物。
-    关联只建立执行单据关系，不代表实际装载量、容量核验或审核已完成。
-    每张客户排车单调度审核通过后允许新拣货；整车确认实际装载并通过理货审核后允许发车。
-    审核仅通过或打回，通过意见选填、打回原因必填；无需额外提交或不同审核人。
-    换车换司机、修改路线或时间使调度与理货审核待审；仅修改备注保留审核及装载。
-    关联变更、重新确认装载或重新审核客户排车单使理货审核待审；保留全部拣货事实及历史审核快照。
+    排车列表是一趟整车作业的唯一主入口，一张排车单对应唯一车次资源记录；同一起运仓允许多个客户和目的地。
+    整车主单与任务不属于单一客户，货物明细、扫码归属、出库和派送单分别保留真实客户边界。
+    本文件保留资源占用查询、历史详情、计划容量、外接预订、结案及车辆/司机任务结束等附加能力。
+    不提供独立派送车次创建、多排车单手工绑定、旧调度/理货审核或装车写入口；审核和装发使用排车主单接口。
+    已绑定排车主单的资源与路线调整由排车主单执行；零真实扫码时显式退回装车前，修改后重新两级审核。
+    车辆和司机资格、容量与实际占用由服务端复验；候选可用不表示已预留，临时外配证据依排车主单规则核验。
+    调度审核后经理货审核才可真实扫码；PDA拣货核平后，平台和PDA均可确认装车完成及实际发车。
+    发车前整车派送安排须完整，正常签收汇总推进排车派送完成；既有异常业务和附加资源能力保留。
+    货物结案不自动释放车辆或司机；各资源任务分别提交实际结束时间、地点和原因，车辆另确认结束状态。
+    版本、幂等、客户隔离及事务要求以各实际端点及排车公共契约为准；历史数量不授权当前分配。
 security:
   - bearerAuth: []
 paths:
@@ -116,11 +105,6 @@ paths:
                           size: {type: integer}
                           total: {type: integer}
                           pages: {type: integer}
-    post:
-      summary: 幂等创建车次计划
-      description: '权限：platform:fleet:trip:create；起运仓使用公共有效海外仓目录；不推断GPS路线。'
-      requestBody: {required: true, content: {application/json: {schema: {$ref: '#/components/schemas/Create'}}}}
-      responses: {'200': {$ref: '#/components/responses/Detail'}}
   /api/platform/v1/last-leg/fleet/trips/customer-options:
     get:
       summary: 查询有效委托客户候选
@@ -221,22 +205,6 @@ paths:
       summary: 查询车次详情和当前司机资格
       description: '权限：platform:fleet:trip:list；司机资格仅是详情预览，实际命令必须重新核验。'
       responses: {'200': {$ref: '#/components/responses/Detail'}}
-  /api/platform/v1/last-leg/fleet/trips/{tripNo}/dispatches/{dispatchNo}/review:
-    parameters:
-      - {$ref: '#/components/parameters/TripNo'}
-      - {name: dispatchNo, in: path, required: true, schema: {type: string}}
-    post:
-      summary: 通过或打回单张客户排车调度审核
-      description: '权限：platform:fleet:trip:dispatch-review；仅PLANNED；审核所属车次内的排车单，成功后理货审核待审；审批不扣库存。'
-      requestBody: {required: true, content: {application/json: {schema: {$ref: '#/components/schemas/Review'}}}}
-      responses: {'200': {$ref: '#/components/responses/Detail'}, '409': {description: 版本、关联或资格冲突}}
-  /api/platform/v1/last-leg/fleet/trips/{tripNo}/loading-review:
-    parameters: [{$ref: '#/components/parameters/TripNo'}]
-    post:
-      summary: 通过或打回整车理货审核
-      description: '权限：platform:fleet:trip:loading-review；仅PLANNED；通过要求全部调度审核、拣货和实际装载确认已完成，当前司机资格有效。'
-      requestBody: {required: true, content: {application/json: {schema: {$ref: '#/components/schemas/Review'}}}}
-      responses: {'200': {$ref: '#/components/responses/Detail'}, '409': {description: 版本、调度审核、装载或资格冲突}}
   /api/platform/v1/last-leg/fleet/trips/{tripNo}/plan:
     parameters: [{$ref: '#/components/parameters/TripNo'}]
     put:
@@ -278,20 +246,6 @@ paths:
                 recordVersion: {type: integer, format: int64, minimum: 0}
                 reason: {type: string, minLength: 1, maxLength: 1000}
       responses: {'200': {$ref: '#/components/responses/Detail'}}
-  /api/platform/v1/last-leg/fleet/trips/{tripNo}/dispatches/bind:
-    parameters: [{$ref: '#/components/parameters/TripNo'}]
-    post:
-      summary: 将客户排车单关联到车次
-      description: '权限：platform:fleet:trip:edit；按业务单号解析客户归属，同仓且未开工；关联、车/司机快照同步及按真实货物目的地标识补齐卸货站原子提交；目的地缺失拒绝关联，已有有效站点顺序与索引保留，初始默认占位站替换为真实目的地。'
-      requestBody: {required: true, content: {application/json: {schema: {$ref: '#/components/schemas/BindingCommand'}}}}
-      responses: {'200': {$ref: '#/components/responses/Detail'}}
-  /api/platform/v1/last-leg/fleet/trips/{tripNo}/dispatches/unbind:
-    parameters: [{$ref: '#/components/parameters/TripNo'}]
-    post:
-      summary: 解除尚未执行的客户排车单关联
-      description: '权限：platform:fleet:trip:edit；清除排车及派送单当前车辆司机快照，历史保留；已拣货禁止直接解除。'
-      requestBody: {required: true, content: {application/json: {schema: {$ref: '#/components/schemas/BindingCommand'}}}}
-      responses: {'200': {$ref: '#/components/responses/Detail'}}
   /api/platform/v1/last-leg/fleet/trips/{tripNo}/history:
     parameters: [{$ref: '#/components/parameters/TripNo'}]
     get:
@@ -324,12 +278,6 @@ paths:
       description: '权限：platform:fleet:trip:list；返回各客户货物组成、manifestHash和当前装载确认，实际重量不得使用计费材积重。'
       responses:
         '200': {description: 统一响应data为Loading, content: {application/json: {schema: {$ref: '#/components/schemas/LoadingEnvelope'}}}}
-    post:
-      summary: 确认整车实际装载及逐段容量
-      description: '权限：platform:fleet:trip:edit；全部客户拣货核平且转派送后确认；同一实物托盘只计量一次。货物hash或车次版本变化拒绝，托盘卸货站须匹配原货物目的地。'
-      requestBody: {required: true, content: {application/json: {schema: {$ref: '#/components/schemas/ConfirmLoad'}}}}
-      responses:
-        '200': {description: 已确认装载快照，统一响应data为Loading, content: {application/json: {schema: {$ref: '#/components/schemas/LoadingEnvelope'}}}}
   /api/platform/v1/last-leg/fleet/trips/{tripNo}/completion:
     parameters: [{$ref: '#/components/parameters/TripNo'}]
     get:
@@ -391,7 +339,7 @@ components:
                       dispatches: {type: array, items: {$ref: '#/components/schemas/DispatchBinding'}}
                       previousDispatches:
                         type: array
-                        description: 原绑定历史中已不在当前绑定的批次、客户及来源引用，按最新有效证据去重；历史数量不作为当前装载或可分配数量
+                        description: 原绑定历史中已不在当前绑定的批次及其客户、来源引用，按最新有效证据去重；历史数量不作为当前装载或可分配数量
                         items: {$ref: '#/components/schemas/PreviousDispatch'}
                       appointmentHistoryUnavailableReason:
                         type: string
@@ -697,20 +645,6 @@ components:
         manifestHash: {type: string, pattern: '^[0-9a-f]{64}$'}
         pallets: {type: array, minItems: 1, maxItems: 1000, items: {$ref: '#/components/schemas/Measurement'}}
         reason: {type: string, minLength: 1, maxLength: 1000}
-    BindingCommand:
-      type: object
-      required: [recordVersion, dispatchNo, reason]
-      properties:
-        recordVersion: {type: integer, format: int64, minimum: 0}
-        dispatchNo: {type: string, minLength: 1, maxLength: 64}
-        reason: {type: string, minLength: 1, maxLength: 1000}
-    Review:
-      type: object
-      required: [recordVersion, decision]
-      properties:
-        recordVersion: {type: integer, format: int64, minimum: 0}
-        decision: {type: string, enum: [APPROVED, REJECTED]}
-        reason: {type: string, nullable: true, maxLength: 1000, description: 通过选填；打回必填}
     ReviewState:
       type: object
       required: [status]
@@ -726,17 +660,15 @@ components:
       properties:
         appointmentBatches: {type: array, items: {$ref: 'overseas-business-v1.yaml#/components/schemas/DispatchBatchReference'}}
         dispatchNo: {type: string}
-        customerId: {type: string, description: 排车单自身客户归属，由服务端解析}
         packageCount: {type: integer, description: 关联时待发运箱数，不是实物托位数}
         boundBy: {type: string}
         boundAt: {type: string, format: date-time}
         review: {$ref: '#/components/schemas/ReviewState'}
     PreviousDispatch:
       type: object
-      required: [dispatchNo, customerId, recordVersion, recordedAt, appointmentBatches]
+      required: [dispatchNo, recordVersion, recordedAt, appointmentBatches]
       properties:
         dispatchNo: {type: string}
-        customerId: {type: string}
         recordVersion: {type: integer, format: int64, description: 原绑定历史的车次版本}
         recordedAt: {type: string, format: date-time}
         appointmentBatches: {type: array, items: {$ref: 'overseas-business-v1.yaml#/components/schemas/DispatchBatchReference'}}
@@ -753,16 +685,6 @@ components:
         name: {type: string, minLength: 1, maxLength: 128}
         address: {type: string, nullable: true, maxLength: 500}
         destinationKey: {type: string, nullable: true, maxLength: 160, description: 卸货站匹配Loading货物的destinationKey；未配置时可以保存计划但不能确认装载}
-    Create:
-      type: object
-      required: [warehouseId, plannedDepartureAt, expectedDriverEndAt, stops, idempotencyKey]
-      properties:
-        warehouseId: {type: string, pattern: '^[1-9][0-9]*$'}
-        plannedDepartureAt: {type: string, format: date-time}
-        expectedDriverEndAt: {type: string, format: date-time}
-        stops: {type: array, minItems: 2, maxItems: 200, items: {$ref: '#/components/schemas/Stop'}}
-        remark: {type: string, nullable: true, maxLength: 1000}
-        idempotencyKey: {type: string, minLength: 8, maxLength: 128}
     Plan:
       type: object
       required: [recordVersion, plannedDepartureAt, expectedDriverEndAt, stops, reason]

lastleg-service/src/main/resources/openapi/overseas-pda-operations-v1.yaml

@@ -8,39 +8,292 @@ security:
 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: 角色、权限或仓库绑定缺失 } }
+      summary: 读取Token绑定仓五阶段整车任务
+      description: 权限 OVERSEAS_WAREHOUSE_PDA_OPERATOR + lastleg:pda:operate。不接收客户或仓库范围参数；真实客户归属保留在items，整车公共版本及Gate由服务端返回。
+      security:
+      - bearerAuth: []
+      responses:
+        '200':
+          description: 统一ApiResponse；业务失败通过code返回，不能仅凭HTTP200判断成功。
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  code:
+                    type: string
+                  message:
+                    type: string
+                  requestId:
+                    type: string
+                    nullable: true
+                  traceId:
+                    type: string
+                    nullable: true
+                  timestamp:
+                    type: string
+                    format: date-time
+                  data:
+                    allOf:
+                    - type: array
+                      items:
+                        $ref: overseas-business-v1.yaml#/components/schemas/DispatchPdaTask
+                    nullable: true
+      parameters:
+      - name: stage
+        in: query
+        schema:
+          $ref: overseas-business-v1.yaml#/components/schemas/DispatchStage
   /api/pda/v1/last-leg/dispatches/{dispatchNo}:
     get:
-      summary: 查询绑定仓排车任务详情
-      description: 返回 tripNo、tripRecordVersion、tripDispatchCount、driverWarning、canDepart、departBlockReason、canPick 与 pickBlockReason；门禁反映整车所有客户单据、实际装载及当前司机资格，PDA 不得仅按当前子单拣货数量推断。canPick/pickBlockReason仅反映当前客户排车单调度审核，不以其他客户审核结果替代。未关联车次不可拣货或发车；列表按车次复用同次查询的门禁结果。证照30天内到期但覆盖任务时driverWarning提醒且仍允许，预计结束前过期则阻断。
-      parameters: [{ name: dispatchNo, in: path, required: true, schema: { type: string } }]
-      responses: { '200': { description: 排车托盘、目的仓与库存位置详情 }, '404': { description: 当前绑定仓无此排车任务 } }
+      summary: 读取本仓整车任务及真实货物
+      description: 权限 OVERSEAS_WAREHOUSE_PDA_OPERATOR + lastleg:pda:operate。
+      security:
+      - bearerAuth: []
+      responses:
+        '200':
+          description: 统一ApiResponse；业务失败通过code返回，不能仅凭HTTP200判断成功。
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  code:
+                    type: string
+                  message:
+                    type: string
+                  requestId:
+                    type: string
+                    nullable: true
+                  traceId:
+                    type: string
+                    nullable: true
+                  timestamp:
+                    type: string
+                    format: date-time
+                  data:
+                    allOf:
+                    - $ref: overseas-business-v1.yaml#/components/schemas/DispatchPdaTask
+                    nullable: true
+    parameters:
+    - name: dispatchNo
+      in: path
+      required: true
+      schema:
+        type: string
+  /api/pda/v1/last-leg/dispatches/{dispatchNo}/loading:
+    get:
+      summary: 读取本车拣货核平和实际测量依据
+      description: 权限 OVERSEAS_WAREHOUSE_PDA_OPERATOR + lastleg:pda:operate。
+      security:
+      - bearerAuth: []
+      responses:
+        '200':
+          description: 统一ApiResponse；业务失败通过code返回，不能仅凭HTTP200判断成功。
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  code:
+                    type: string
+                  message:
+                    type: string
+                  requestId:
+                    type: string
+                    nullable: true
+                  traceId:
+                    type: string
+                    nullable: true
+                  timestamp:
+                    type: string
+                    format: date-time
+                  data:
+                    allOf:
+                    - $ref: overseas-business-v1.yaml#/components/schemas/DispatchLoadingPreview
+                    nullable: true
+    parameters:
+    - name: dispatchNo
+      in: path
+      required: true
+      schema:
+        type: string
+  /api/pda/v1/last-leg/dispatches/{dispatchNo}/commands/{idempotencyKey}:
+    get:
+      summary: 核对本人本仓原命令结果
+      description: 权限 OVERSEAS_WAREHOUSE_PDA_OPERATOR + lastleg:pda:operate。
+      security:
+      - bearerAuth: []
+      responses:
+        '200':
+          description: 统一ApiResponse；业务失败通过code返回，不能仅凭HTTP200判断成功。
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  code:
+                    type: string
+                  message:
+                    type: string
+                  requestId:
+                    type: string
+                    nullable: true
+                  traceId:
+                    type: string
+                    nullable: true
+                  timestamp:
+                    type: string
+                    format: date-time
+                  data:
+                    allOf:
+                    - $ref: overseas-business-v1.yaml#/components/schemas/DispatchCommandResult
+                    nullable: true
+    parameters:
+    - name: dispatchNo
+      in: path
+      required: true
+      schema:
+        type: string
+    - name: idempotencyKey
+      in: path
+      required: true
+      schema:
+        type: string
   /api/pda/v1/last-leg/dispatches/{dispatchNo}/items/{itemId}/pick:
     post:
-      summary: 扫码拣取排车托盘包裹
-      description: 新请求须当前排车调度审核通过；同键同内容重放已保存结果不重新扣库存。
-      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:
+      summary: 按本车真实货物来源执行扫码拣货
+      description: 权限 OVERSEAS_WAREHOUSE_PDA_OPERATOR + lastleg:pda:operate。只用整车recordVersion和全载荷幂等键；扫码执行真实库存SHIP，装车完成和发车不重复SHIP。错误或结果未知保留原请求核对。
+      security:
+      - bearerAuth: []
+      responses:
+        '200':
+          description: 统一ApiResponse；业务失败通过code返回，不能仅凭HTTP200判断成功。
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  code:
+                    type: string
+                  message:
+                    type: string
+                  requestId:
+                    type: string
+                    nullable: true
+                  traceId:
+                    type: string
+                    nullable: true
+                  timestamp:
+                    type: string
+                    format: date-time
+                  data:
+                    allOf:
+                    - $ref: overseas-business-v1.yaml#/components/schemas/DispatchCommandResult
+                    nullable: true
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: overseas-business-v1.yaml#/components/schemas/DispatchPick
+    parameters:
+    - name: dispatchNo
+      in: path
+      required: true
+      schema:
+        type: string
+    - name: itemId
+      in: path
+      required: true
+      schema:
+        type: string
+  /api/pda/v1/last-leg/dispatches/{dispatchNo}/loading-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: 未全部拣货或幂等冲突 } }
+      summary: 真实拣货核平后显式确认装车完成
+      description: 权限 OVERSEAS_WAREHOUSE_PDA_OPERATOR + lastleg:pda:operate。只用整车recordVersion和全载荷幂等键；扫码执行真实库存SHIP，装车完成和发车不重复SHIP。错误或结果未知保留原请求核对。
+      security:
+      - bearerAuth: []
+      responses:
+        '200':
+          description: 统一ApiResponse；业务失败通过code返回，不能仅凭HTTP200判断成功。
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  code:
+                    type: string
+                  message:
+                    type: string
+                  requestId:
+                    type: string
+                    nullable: true
+                  traceId:
+                    type: string
+                    nullable: true
+                  timestamp:
+                    type: string
+                    format: date-time
+                  data:
+                    allOf:
+                    - $ref: overseas-business-v1.yaml#/components/schemas/DispatchCommandResult
+                    nullable: true
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: overseas-business-v1.yaml#/components/schemas/DispatchLoadingComplete
+    parameters:
+    - name: dispatchNo
+      in: path
+      required: true
+      schema:
+        type: string
   /api/pda/v1/last-leg/dispatches/{dispatchNo}/depart:
     post:
-      summary: 从排车任务确认所属车次整车发车
-      description: 按Token绑定仓锁定车次，校验期望车次版本、车辆占用、全部调度审核、实际装载、整车理货审核及全部客户拣货和待出库单，重新核验司机证照、当前海外区域和身份；区域或身份变化与预览门禁一致阻断。一个事务推进所有子单，任一失败全车回滚。扫码阶段已扣库存不重复扣减；同键同内容重放整车结果，不同内容冲突。DEPARTING仅是同事务内部状态，不对外提交。
-      parameters: [{ name: dispatchNo, in: path, required: true, schema: { type: string } }]
-      requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/DepartAction' } } } }
-      responses: { '200': { description: '统一响应data包含tripNo、status=IN_TRANSIT、departedAt、shippedPackages、dispatches数组（dispatchNo/shippedPackages）和replayed；每张子排车状态均为DEPARTED' }, '409': { description: 车次版本、装载、资格、拣货、出库或幂等门禁未满足 } }
+      summary: 完整安排派送后确认实际发车
+      description: 权限 OVERSEAS_WAREHOUSE_PDA_OPERATOR + lastleg:pda:operate。只用整车recordVersion和全载荷幂等键；扫码执行真实库存SHIP，装车完成和发车不重复SHIP。错误或结果未知保留原请求核对。
+      security:
+      - bearerAuth: []
+      responses:
+        '200':
+          description: 统一ApiResponse；业务失败通过code返回，不能仅凭HTTP200判断成功。
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  code:
+                    type: string
+                  message:
+                    type: string
+                  requestId:
+                    type: string
+                    nullable: true
+                  traceId:
+                    type: string
+                    nullable: true
+                  timestamp:
+                    type: string
+                    format: date-time
+                  data:
+                    allOf:
+                    - $ref: overseas-business-v1.yaml#/components/schemas/DispatchCommandResult
+                    nullable: true
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: overseas-business-v1.yaml#/components/schemas/DispatchDepart
+    parameters:
+    - name: dispatchNo
+      in: path
+      required: true
+      schema:
+        type: string
   /api/pda/v1/last-leg/outbound-tasks:
     get:
       summary: 查询Token绑定仓的一件代发出库任务
@@ -962,24 +1215,6 @@ components:
       type: object
       required: [idempotencyKey]
       properties: { idempotencyKey: { type: string, minLength: 1, maxLength: 255 } }
-    DepartAction:
-      type: object
-      required: [recordVersion, idempotencyKey]
-      properties:
-        recordVersion: { type: integer, format: int64, minimum: 0, description: 当前车次版本，来自tripRecordVersion}
-        idempotencyKey: { type: string, minLength: 8, maxLength: 128 }
-        remark: { type: string, maxLength: 1000, nullable: true }
-    DispatchPick:
-      type: object
-      description: 普通库存提交positionId；原生退货换标箱提交cartonMark、positionId为空、packages=1，productQuantity必须与箱快照一致。两类来源互斥。
-      required: [packages, productQuantity, idempotencyKey]
-      properties:
-        positionId: { type: string, pattern: '^[0-9]+$', nullable: true }
-        cartonMark: { type: string, maxLength: 255, description: 本排车来源的系统箱唛 }
-        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, packages, idempotencyKey]