openapi: 3.0.3
info:
  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:
      summary: 同窗补齐登记资料并原子确认承运
      description: '权限：platform:fleet:capacity-offer:manage。复用InquiryWrite，更新资料、创建唯一商业订单及占位同事务；任何阶段失败全部回滚，不把保存当成交。同键同载荷返回原结果。'
      requestBody:
        required: true
        content:
          application/json:
            schema: {$ref: './fleet-capacity-offers-v1.yaml#/components/schemas/InquiryWrite'}
      responses:
        '200': {description: '统一ApiResponse，data为InquiryResult'}
  /api/platform/v1/last-leg/fleet/capacity-offers/inquiries/{bookingNo}/fulfillment:
    parameters: [{$ref: './fleet-trips-v1.yaml#/components/parameters/BookingNo'}]
    get:
      summary: 从原登记查看本票履约进度
      description: '权限：platform:fleet:capacity-offer:list或platform:fleet:capacity-offer:manage。销售仅本人；返回本票booking、preview及plannedDepartureAt，不返回整车司机或他人货物。preview含tripRecordVersion、recordVersion、incoming，未安排时incoming为null。'
      responses:
        '200': {description: '统一ApiResponse，data为Fulfillment'}
  /api/platform/v1/last-leg/fleet/capacity-offers/inquiries/{bookingNo}/incoming:
    parameters: [{$ref: './fleet-trips-v1.yaml#/components/parameters/BookingNo'}]
    post:
      summary: 从原登记明确安排来货
      description: '权限：platform:fleet:capacity-offer:manage和platform:fleet:trip:booking-edit。复用版本及幂等门禁，未填时间时沿用登记预计到仓，仍缺失则拒绝，不自动减两小时猜测。承运确认不自动调用此命令。'
      requestBody:
        required: true
        content:
          application/json:
            schema: {$ref: './fleet-trips-v1.yaml#/components/schemas/BookingIncoming'}
      responses:
        '200': {$ref: './fleet-trips-v1.yaml#/components/responses/BookingResult'}
  /api/platform/v1/last-leg/fleet/capacity-offers/inquiries/{bookingNo}/receipt-confirmation:
    parameters: [{$ref: './fleet-trips-v1.yaml#/components/parameters/BookingNo'}]
    post:
      summary: 原登记核对真实实收与约定运费
      description: '权限：platform:fleet:capacity-offer:manage和platform:fleet:trip:booking-confirm。沿实际receiptHash/托盘和三维容量校验；不以预报覆盖实收。'
      requestBody:
        required: true
        content:
          application/json:
            schema: {$ref: './fleet-trips-v1.yaml#/components/schemas/BookingAcceptReceipt'}
      responses:
        '200': {$ref: './fleet-trips-v1.yaml#/components/responses/BookingResult'}
  /api/platform/v1/last-leg/fleet/capacity-offers/inquiries/{bookingNo}/arrange-dispatch:
    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，旧计划失效待核对，仍需审核和现场作业。'
      requestBody:
        required: true
        content:
          application/json:
            schema: {$ref: './fleet-trips-v1.yaml#/components/schemas/BookingCommand'}
      responses:
        '200': {$ref: './fleet-trips-v1.yaml#/components/responses/BookingResult'}
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}