baiyue-firstleg/lastleg-service/src/main/resources/openapi/fleet-capacity-offers-v1.yaml

openapi: 3.0.3
info:
  title: 内部拼车车次余位发布与销售意向
  version: 1.0.0
  description: 首版统一我仓上车；Client不开放运力池。来源商业单、库存与费用沿唯一正式履约链，报价与实收款分开。
security:
- bearerAuth: []
paths:
  /api/platform/v1/last-leg/fleet/capacity-offers:
    get:
      summary: 按当前身份分页查询可接运力
      description: 权限：platform:fleet:capacity-offer:list 或 platform:fleet:capacity-offer:manage。普通列表数据库分页，只计算当前页。canConfirm动态筛选候选超过100时要求缩小范围，不返回伪总数。未知余位为null且给出待核对原因。
      responses:
        '200':
          description: 统一业务响应；code=200成功，冲突或资格拒绝不得当成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                  message:
                    type: string
                  data:
                    $ref: '#/components/schemas/OfferPage'
                  requestId:
                    type: string
                    nullable: true
                  traceId:
                    type: string
                    nullable: true
        '401':
          description: 未登录或会话失效
        '403':
          description: 无权限或非本人意向
      parameters:
      - name: page
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          default: 1
      - name: size
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 20
      - name: keyword
        in: query
        required: false
        schema:
          type: string
      - name: origin
        in: query
        required: false
        schema:
          type: string
      - name: destination
        in: query
        required: false
        schema:
          type: string
      - name: tripNo
        in: query
        required: false
        schema:
          type: string
      - name: departureFrom
        in: query
        required: false
        schema:
          type: string
          format: date
      - name: departureTo
        in: query
        required: false
        schema:
          type: string
          format: date
      - name: status
        in: query
        required: false
        schema:
          type: string
          enum:
          - DRAFT
          - OPEN
          - PAUSED
          - CLOSED
      - name: scope
        in: query
        description: 默认AVAILABLE，仅开放且车次仍PLANNED、当前服务端时间早于交货截止且截止不晚于计划发车；数据库分页前筛选，不以容量已知或有余位为条件。ALL包含草稿和历史，仅管理权限可用；车次发布设置读取已有发布须显式传ALL。
        schema: { type: string, enum: [AVAILABLE, ALL], default: AVAILABLE }
      - name: canConfirm
        in: query
        required: false
        schema:
          type: boolean
    post:
      summary: 创建每车次唯一发布草稿
      description: 权限：platform:fleet:capacity-offer:manage。
      responses:
        '200':
          description: 统一业务响应；code=200成功，冲突或资格拒绝不得当成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                  message:
                    type: string
                  data:
                    $ref: '#/components/schemas/OfferResult'
                  requestId:
                    type: string
                    nullable: true
                  traceId:
                    type: string
                    nullable: true
        '401':
          description: 未登录或会话失效
        '403':
          description: 无权限或非本人意向
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OfferWrite'
  /api/platform/v1/last-leg/fleet/capacity-offers/{offerNo}:
    get:
      summary: 读取发布及获准意向首20条
      description: 权限：platform:fleet:capacity-offer:list 或 platform:fleet:capacity-offer:manage。销售非OPEN访问必须已有本人意向；不返回司机或他人客户货物。
      responses:
        '200':
          description: 统一业务响应；code=200成功，冲突或资格拒绝不得当成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                  message:
                    type: string
                  data:
                    $ref: '#/components/schemas/Detail'
                  requestId:
                    type: string
                    nullable: true
                  traceId:
                    type: string
                    nullable: true
        '401':
          description: 未登录或会话失效
        '403':
          description: 无权限或非本人意向
      parameters:
      - name: offerNo
        in: path
        required: true
        schema:
          type: string
          maxLength: 64
    put:
      summary: 维护公开交货信息
      description: 权限：platform:fleet:capacity-offer:manage。
      responses:
        '200':
          description: 统一业务响应；code=200成功，冲突或资格拒绝不得当成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                  message:
                    type: string
                  data:
                    $ref: '#/components/schemas/OfferResult'
                  requestId:
                    type: string
                    nullable: true
                  traceId:
                    type: string
                    nullable: true
        '401':
          description: 未登录或会话失效
        '403':
          description: 无权限或非本人意向
      parameters:
      - name: offerNo
        in: path
        required: true
        schema:
          type: string
          maxLength: 64
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OfferWrite'
  /api/platform/v1/last-leg/fleet/capacity-offers/{offerNo}/publish:
    post:
      summary: 发布运力发布
      description: 权限：platform:fleet:capacity-offer:manage。CLOSED为终态。原成功请求同键同载荷在再次业务资格检查前重放；身份及权限仍校验。
      responses:
        '200':
          description: 统一业务响应；code=200成功，冲突或资格拒绝不得当成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                  message:
                    type: string
                  data:
                    $ref: '#/components/schemas/OfferResult'
                  requestId:
                    type: string
                    nullable: true
                  traceId:
                    type: string
                    nullable: true
        '401':
          description: 未登录或会话失效
        '403':
          description: 无权限或非本人意向
      parameters:
      - name: offerNo
        in: path
        required: true
        schema:
          type: string
          maxLength: 64
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OfferCommand'
  /api/platform/v1/last-leg/fleet/capacity-offers/{offerNo}/pause:
    post:
      summary: 暂停运力发布
      description: 权限：platform:fleet:capacity-offer:manage。CLOSED为终态。原成功请求同键同载荷在再次业务资格检查前重放；身份及权限仍校验。
      responses:
        '200':
          description: 统一业务响应；code=200成功，冲突或资格拒绝不得当成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                  message:
                    type: string
                  data:
                    $ref: '#/components/schemas/OfferResult'
                  requestId:
                    type: string
                    nullable: true
                  traceId:
                    type: string
                    nullable: true
        '401':
          description: 未登录或会话失效
        '403':
          description: 无权限或非本人意向
      parameters:
      - name: offerNo
        in: path
        required: true
        schema:
          type: string
          maxLength: 64
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OfferCommand'
  /api/platform/v1/last-leg/fleet/capacity-offers/{offerNo}/resume:
    post:
      summary: 重新核对并恢复运力发布
      description: 权限：platform:fleet:capacity-offer:manage。CLOSED为终态。原成功请求同键同载荷在再次业务资格检查前重放；身份及权限仍校验。
      responses:
        '200':
          description: 统一业务响应；code=200成功，冲突或资格拒绝不得当成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                  message:
                    type: string
                  data:
                    $ref: '#/components/schemas/OfferResult'
                  requestId:
                    type: string
                    nullable: true
                  traceId:
                    type: string
                    nullable: true
        '401':
          description: 未登录或会话失效
        '403':
          description: 无权限或非本人意向
      parameters:
      - name: offerNo
        in: path
        required: true
        schema:
          type: string
          maxLength: 64
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OfferCommand'
  /api/platform/v1/last-leg/fleet/capacity-offers/{offerNo}/close:
    post:
      summary: 终止运力发布
      description: 权限：platform:fleet:capacity-offer:manage。CLOSED为终态。原成功请求同键同载荷在再次业务资格检查前重放；身份及权限仍校验。
      responses:
        '200':
          description: 统一业务响应；code=200成功，冲突或资格拒绝不得当成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                  message:
                    type: string
                  data:
                    $ref: '#/components/schemas/OfferResult'
                  requestId:
                    type: string
                    nullable: true
                  traceId:
                    type: string
                    nullable: true
        '401':
          description: 未登录或会话失效
        '403':
          description: 无权限或非本人意向
      parameters:
      - name: offerNo
        in: path
        required: true
        schema:
          type: string
          maxLength: 64
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OfferCommand'
  /api/platform/v1/last-leg/fleet/capacity-offers/pending-looseboard-demands:
    get:
      summary: 分页读取客户已提交的待匹配散板原单
      description: 权限：platform:fleet:capacity-offer:manage 或 (platform:fleet:capacity-offer:list 且 platform:fleet:capacity-offer:inquiry-create)。仅返回待接单、没有独立尾程来源且没有生效匹配的原单；取消未确认登记后恢复候选。下单及登记不占位，确认承运才占位。旧独立履约单不回填来源。
      parameters:
      - { name: page, in: query, schema: { type: integer, minimum: 1, default: 1 } }
      - { name: size, in: query, schema: { type: integer, minimum: 1, maximum: 100, default: 20 } }
      - { name: keyword, in: query, schema: { type: string, maxLength: 128 } }
      responses:
        '200':
          description: 统一业务响应
          content:
            application/json:
              schema:
                type: object
                properties:
                  code: { type: string }
                  message: { type: string }
                  data:
                    type: object
                    properties:
                      records:
                        type: array
                        items: { $ref: '#/components/schemas/LooseboardDemand' }
                      page: { type: integer }
                      size: { type: integer }
                      total: { type: integer }
                      pages: { type: integer }
        '401': { description: 未登录 }
        '403': { description: 无需求匹配权限 }
  /api/platform/v1/last-leg/fleet/capacity-offers/inquiries:
    get:
      summary: 分页查询本人或获准的全部意向
      description: 权限：platform:fleet:capacity-offer:list 或 platform:fleet:capacity-offer:manage。ALL和TODO只允许manage；TODO按服务端负责角色筛选调度待办，基础候选超过100条要求按客户或登记号缩小范围，过滤后精确分页，不按当前页伪造总数；销售负责人由登录身份过滤，历史不依赖发布仍OPEN。
      responses:
        '200':
          description: 统一业务响应；code=200成功，冲突或资格拒绝不得当成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                  message:
                    type: string
                  data:
                    $ref: '#/components/schemas/InquiryPage'
                  requestId:
                    type: string
                    nullable: true
                  traceId:
                    type: string
                    nullable: true
        '401':
          description: 未登录或会话失效
        '403':
          description: 无权限或非本人意向
      parameters:
      - name: page
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          default: 1
      - name: size
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 20
      - name: keyword
        in: query
        required: false
        schema:
          type: string
      - name: offerNo
        in: query
        required: false
        schema:
          type: string
      - name: status
        in: query
        required: false
        schema:
          type: string
      - name: scope
        in: query
        required: false
        schema:
          type: string
          enum:
          - MINE
          - ALL
          - TODO
          default: MINE
  /api/platform/v1/last-leg/fleet/capacity-offers/inquiries/{bookingNo}:
    get:
      summary: 读取获准的单条意向
      description: 权限：platform:fleet:capacity-offer:list 或 platform:fleet:capacity-offer:manage。
      responses:
        '200':
          description: 统一业务响应；code=200成功，冲突或资格拒绝不得当成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                  message:
                    type: string
                  data:
                    $ref: '#/components/schemas/Inquiry'
                  requestId:
                    type: string
                    nullable: true
                  traceId:
                    type: string
                    nullable: true
        '401':
          description: 未登录或会话失效
        '403':
          description: 无权限或非本人意向
      parameters:
      - name: bookingNo
        in: path
        required: true
        schema:
          type: string
          maxLength: 64
    put:
      summary: 修改本人询价草稿
      description: 权限：platform:fleet:capacity-offer:manage 或 (platform:fleet:capacity-offer:list 且 platform:fleet:capacity-offer:inquiry-edit)。询价不占位；未知预计箱数可空。确认前补足预报、路线、实托和报价。
      responses:
        '200':
          description: 统一业务响应；code=200成功，冲突或资格拒绝不得当成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                  message:
                    type: string
                  data:
                    $ref: '#/components/schemas/InquiryResult'
                  requestId:
                    type: string
                    nullable: true
                  traceId:
                    type: string
                    nullable: true
        '401':
          description: 未登录或会话失效
        '403':
          description: 无权限或非本人意向
      parameters:
      - name: bookingNo
        in: path
        required: true
        schema:
          type: string
          maxLength: 64
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InquiryWrite'
  /api/platform/v1/last-leg/fleet/capacity-offers/{offerNo}/inquiries:
    post:
      summary: 登记本人询价草稿
      description: 权限：platform:fleet:capacity-offer:manage 或 (platform:fleet:capacity-offer:list 且 platform:fleet:capacity-offer:inquiry-create)。询价不占位；未知预计箱数可空。确认前补足预报、路线、实托和报价。
      responses:
        '200':
          description: 统一业务响应；code=200成功，冲突或资格拒绝不得当成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                  message:
                    type: string
                  data:
                    $ref: '#/components/schemas/InquiryResult'
                  requestId:
                    type: string
                    nullable: true
                  traceId:
                    type: string
                    nullable: true
        '401':
          description: 未登录或会话失效
        '403':
          description: 无权限或非本人意向
      parameters:
      - name: offerNo
        in: path
        required: true
        schema:
          type: string
          maxLength: 64
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InquiryWrite'
  /api/platform/v1/last-leg/fleet/capacity-offers/inquiries/{bookingNo}/confirm:
    post:
      summary: 原子创建商业单并确认承运占位
      description: 权限：platform:fleet:capacity-offer:manage。车次锁内复验最新车辆、计划、发布指纹、时间、三维容量和客户资格；同事务商业单、桥关联与占位，失败全部回滚。
      responses:
        '200':
          description: 统一业务响应；code=200成功，冲突或资格拒绝不得当成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                  message:
                    type: string
                  data:
                    $ref: '#/components/schemas/InquiryResult'
                  requestId:
                    type: string
                    nullable: true
                  traceId:
                    type: string
                    nullable: true
        '401':
          description: 未登录或会话失效
        '403':
          description: 无权限或非本人意向
      parameters:
      - name: bookingNo
        in: path
        required: true
        schema:
          type: string
          maxLength: 64
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InquiryCommand'
  /api/platform/v1/last-leg/fleet/capacity-offers/inquiries/{bookingNo}/cancel:
    post:
      summary: 取消允许范围的意向
      description: 权限：platform:fleet:capacity-offer:manage 或 (platform:fleet:capacity-offer:list 且 platform:fleet:capacity-offer:inquiry-cancel)。销售仅本人DRAFT；CONFIRMED仅调度且无来货时一体取消；已登记来货后拒绝快捷取消，不删除库存。
      responses:
        '200':
          description: 统一业务响应；code=200成功，冲突或资格拒绝不得当成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                  message:
                    type: string
                  data:
                    $ref: '#/components/schemas/InquiryResult'
                  requestId:
                    type: string
                    nullable: true
                  traceId:
                    type: string
                    nullable: true
        '401':
          description: 未登录或会话失效
        '403':
          description: 无权限或非本人意向
      parameters:
      - name: bookingNo
        in: path
        required: true
        schema:
          type: string
          maxLength: 64
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InquiryCommand'
  /api/platform/v1/last-leg/fleet/capacity-offers/customer-options:
    get:
      summary: 选择公司共享有效客户最小目录
      description: 权限：platform:fleet:capacity-offer:manage 或 (platform:fleet:capacity-offer:list 且 platform:fleet:capacity-offer:inquiry-create)。仅id/code/name，不能借此获得客户联系人或财务资料。
      responses:
        '200':
          description: 统一业务响应；code=200成功，冲突或资格拒绝不得当成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                  message:
                    type: string
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/CustomerOption'
                  requestId:
                    type: string
                    nullable: true
                  traceId:
                    type: string
                    nullable: true
        '401':
          description: 未登录或会话失效
        '403':
          description: 无权限或非本人意向
      parameters:
      - name: keyword
        in: query
        required: false
        schema:
          type: string
          maxLength: 128
  /api/platform/v1/last-leg/fleet/capacity-offers/{offerNo}/quote-candidates:
    get:
      summary: 查询本车本客户适用销售报价
      description: 权限：platform:fleet:capacity-offer:list 或 platform:fleet:capacity-offer:manage，并需platform:fleet:quote:list。
      responses:
        '200':
          description: 统一业务响应；code=200成功，冲突或资格拒绝不得当成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                  message:
                    type: string
                  data:
                    type: object
                    properties:
                      records:
                        type: array
                        items:
                          $ref: '#/components/schemas/QuoteSource'
                      page:
                        oneOf:
                        - type: integer
                          format: int64
                          minimum: 0
                        - type: string
                          pattern: ^[0-9]+$
                      size:
                        oneOf:
                        - type: integer
                          format: int64
                          minimum: 0
                        - type: string
                          pattern: ^[0-9]+$
                      total:
                        oneOf:
                        - type: integer
                          format: int64
                          minimum: 0
                        - type: string
                          pattern: ^[0-9]+$
                      pages:
                        oneOf:
                        - type: integer
                          format: int64
                          minimum: 0
                        - type: string
                          pattern: ^[0-9]+$
                  requestId:
                    type: string
                    nullable: true
                  traceId:
                    type: string
                    nullable: true
        '401':
          description: 未登录或会话失效
        '403':
          description: 无权限或非本人意向
      parameters:
      - name: offerNo
        in: path
        required: true
        schema:
          type: string
          maxLength: 64
      - name: page
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          default: 1
      - name: size
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 20
      - name: customerId
        in: query
        required: true
        schema:
          type: string
      - name: destinationKey
        in: query
        required: true
        schema:
          type: string
      - name: currency
        in: query
        required: true
        schema:
          type: string
          enum:
          - CNY
          - USD
      - name: priceBasis
        in: query
        required: true
        schema:
          type: string
          enum:
          - PALLET
          - ORDER
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  schemas:
    Load:
      type: object
      properties:
        palletSpaces:
          type: integer
          minimum: 0
        weightKg:
          type: number
          minimum: 0
        volumeCbm:
          type: number
          minimum: 0
    Cargo:
      $ref: ./fleet-trips-v1.yaml#/components/schemas/BookingCargo
    QuoteRef:
      $ref: ./fleet-trips-v1.yaml#/components/schemas/BookingQuoteRef
    QuoteSource:
      type: object
      description: 已选择的销售报价来源快照；quotedUnitPrice是报价库来源价，不等于意向成交单价或已收金额。
      required: [quoteNo, recordVersion, priceItem, customerId, customerName, originCity, destinationCode, currency, priceBasis, quotedUnitPrice, validFrom, validTo, effectiveOn]
      properties:
        quoteNo:
          type: string
        recordVersion:
          oneOf:
          - type: integer
            format: int64
            minimum: 0
          - type: string
            pattern: ^[0-9]+$
        priceItem:
          type: string
          enum: [FULL_DELIVERY, LOOSE_DELIVERY]
        customerId:
          type: string
        customerName:
          type: string
        originCity:
          type: string
        destinationCode:
          type: string
        distanceMiles:
          type: number
          nullable: true
        currency:
          type: string
          enum: [CNY, USD]
        priceBasis:
          type: string
          enum: [ORDER, PALLET]
        quotedUnitPrice:
          type: number
          minimum: 0
        validFrom:
          type: string
          format: date
        validTo:
          type: string
          format: date
        effectiveOn:
          type: string
          format: date
    OfferActions:
      type: object
      properties:
        canEdit:
          type: boolean
        canPublish:
          type: boolean
        canPause:
          type: boolean
        canResume:
          type: boolean
        canClose:
          type: boolean
    InquiryActions:
      type: object
      properties:
        canEdit:
          type: boolean
        canConfirm:
          type: boolean
        canCancel:
          type: boolean
        blockReason:
          type: string
          nullable: true
    Destination:
      type: object
      properties:
        destinationKey:
          type: string
        name:
          type: string
        deliveryIndex:
          type: integer
          minimum: 1
        remaining:
          $ref: '#/components/schemas/Load'
          nullable: true
    Segment:
      type: object
      properties:
        fromIndex:
          type: integer
        toIndex:
          type: integer
        fromName:
          type: string
        toName:
          type: string
        planned:
          $ref: '#/components/schemas/Load'
        reserved:
          $ref: '#/components/schemas/Load'
        remaining:
          $ref: '#/components/schemas/Load'
    CustomerOption:
      type: object
      properties:
        id:
          type: string
        code:
          type: string
        name:
          type: string
    Offer:
      type: object
      properties:
        offerNo:
          type: string
        tripNo:
          type: string
        warehouseId:
          type: string
        warehouseName:
          type: string
        status:
          type: string
          enum:
          - DRAFT
          - OPEN
          - PAUSED
          - CLOSED
        recordVersion:
          oneOf:
          - type: integer
            format: int64
            minimum: 0
          - type: string
            pattern: ^[0-9]+$
        tripRecordVersion:
          oneOf:
          - type: integer
            format: int64
            minimum: 0
          - type: string
            pattern: ^[0-9]+$
        plannedDepartureAt:
          type: string
          format: date-time
        cutoffAt:
          type: string
          format: date-time
        contactName:
          type: string
          nullable: true
        contactPhone:
          type: string
          nullable: true
        remark:
          type: string
          nullable: true
        destinations:
          type: array
          items:
            $ref: '#/components/schemas/Destination'
        segments:
          type: array
          items:
            $ref: '#/components/schemas/Segment'
        capacityKnown:
          type: boolean
        canCreateInquiry:
          type: boolean
        canConfirm:
          type: boolean
        blockReason:
          type: string
          nullable: true
        actions:
          $ref: '#/components/schemas/OfferActions'
    Inquiry:
      description: 登记返回服务端资料缺项与处理进度；canConfirm同时核对本票完整性和目的地三维余位，最终写命令仍复验。
      type: object
      properties:
        appointmentCoverage:
          type: object
          nullable: true
          description: FBA来源通过AppointmentCoverageService按客户和BOOKING稳定来源批量读取；无订单保留待形成货件资料，私人目的地为null。不把保位当收货预约，不推算未知时区。
          properties:
            status: {type: string}
            sourceVersion: {type: string, nullable: true}
            changeReviewRequired: {type: boolean}
            missingFields: {type: array, items: {type: string}}
            appointments:
              type: array
              items:
                type: object
                properties:
                  appointmentNo: {type: string}
                  confirmationNo: {type: string, nullable: true}
                  status: {type: string}
                  confirmedAt: {type: string, nullable: true}
                  confirmedEndAt: {type: string, nullable: true}
                  timezone: {type: string, nullable: true}
        progress:
          type: object
          description: 只读派生处理提示，不是可写状态；负责人及动作按资料完整性、承运/来货/实收事实返回；保存不保位。
          required: [stage, label, reservation, owner, primaryAction, message, missingFields]
          properties:
            stage: {type: string}
            label: {type: string}
            reservation: {type: string}
            owner: {type: string}
            primaryAction: {type: string, enum: [VIEW, EDIT, CONFIRM, INCOMING, RECEIPT, BIND]}
            message: {type: string}
            missingFields: {type: array, items: {type: string}}
        bookingNo:
          type: string
        offerNo:
          type: string
        tripNo:
          type: string
        salesOwnerUserId:
          type: string
        customerId:
          type: string
        customerCode:
          type: string
        customerName:
          type: string
        destinationLabel:
          type: string
        status:
          type: string
          enum:
          - DRAFT
          - CONFIRMED
          - RECEIVED
          - BOUND
          - CANCELLED
        recordVersion:
          oneOf:
          - type: integer
            format: int64
            minimum: 0
          - type: string
            pattern: ^[0-9]+$
        offerRecordVersion:
          oneOf:
          - type: integer
            format: int64
            minimum: 0
          - type: string
            pattern: ^[0-9]+$
        tripRecordVersion:
          oneOf:
          - type: integer
            format: int64
            minimum: 0
          - type: string
            pattern: ^[0-9]+$
        businessType:
          type: string
          enum:
          - LOCAL_LOOSEBOARD
          - US_TRUCK
        deliveryMode:
          type: string
          enum:
          - SELF_DELIVERY
          - MANUAL_PICKUP_TO_WAREHOUSE
        estimatedArrivalAt:
          type: string
          format: date-time
          nullable: true
        expectedPalletCount:
          type: integer
          minimum: 1
          nullable: true
        cargo:
          $ref: '#/components/schemas/Cargo'
        agreedAmount:
          type: number
          nullable: true
        quoteSource:
          $ref: '#/components/schemas/QuoteSource'
          nullable: true
        businessOrderNo:
          type: string
          nullable: true
        incomingNo:
          type: string
          nullable: true
        dispatchNo:
          type: string
          nullable: true
        updatedAt:
          type: string
          format: date-time
        actions:
          $ref: '#/components/schemas/InquiryActions'
    OfferPage:
      type: object
      properties:
        records:
          type: array
          items:
            $ref: '#/components/schemas/Offer'
        page:
          oneOf:
          - type: integer
            format: int64
            minimum: 0
          - type: string
            pattern: ^[0-9]+$
        size:
          oneOf:
          - type: integer
            format: int64
            minimum: 0
          - type: string
            pattern: ^[0-9]+$
        total:
          oneOf:
          - type: integer
            format: int64
            minimum: 0
          - type: string
            pattern: ^[0-9]+$
        pages:
          oneOf:
          - type: integer
            format: int64
            minimum: 0
          - type: string
            pattern: ^[0-9]+$
    InquiryPage:
      type: object
      properties:
        records:
          type: array
          items:
            $ref: '#/components/schemas/Inquiry'
        page:
          oneOf:
          - type: integer
            format: int64
            minimum: 0
          - type: string
            pattern: ^[0-9]+$
        size:
          oneOf:
          - type: integer
            format: int64
            minimum: 0
          - type: string
            pattern: ^[0-9]+$
        total:
          oneOf:
          - type: integer
            format: int64
            minimum: 0
          - type: string
            pattern: ^[0-9]+$
        pages:
          oneOf:
          - type: integer
            format: int64
            minimum: 0
          - type: string
            pattern: ^[0-9]+$
    Detail:
      type: object
      properties:
        offer:
          $ref: '#/components/schemas/Offer'
        inquiries:
          $ref: '#/components/schemas/InquiryPage'
    OfferResult:
      type: object
      properties:
        offer:
          $ref: '#/components/schemas/Offer'
        replayed:
          type: boolean
    InquiryResult:
      type: object
      properties:
        inquiry:
          $ref: '#/components/schemas/Inquiry'
        offer:
          $ref: '#/components/schemas/Offer'
        replayed:
          type: boolean
    OfferWrite:
      type: object
      required:
      - tripNo
      - tripRecordVersion
      - cutoffAt
      - idempotencyKey
      properties:
        tripNo:
          type: string
          maxLength: 64
        tripRecordVersion:
          oneOf:
          - type: integer
            format: int64
            minimum: 0
          - type: string
            pattern: ^[0-9]+$
        offerRecordVersion:
          oneOf:
          - type: integer
            format: int64
            minimum: 0
          - type: string
            pattern: ^[0-9]+$
          nullable: true
        cutoffAt:
          type: string
          format: date-time
        contactName:
          type: string
          maxLength: 128
          nullable: true
        contactPhone:
          type: string
          maxLength: 128
          nullable: true
        remark:
          type: string
          maxLength: 1000
          nullable: true
        idempotencyKey:
          type: string
          minLength: 8
          maxLength: 128
    OfferCommand:
      type: object
      required:
      - tripRecordVersion
      - offerRecordVersion
      - idempotencyKey
      properties:
        tripRecordVersion:
          oneOf:
          - type: integer
            format: int64
            minimum: 0
          - type: string
            pattern: ^[0-9]+$
        offerRecordVersion:
          oneOf:
          - type: integer
            format: int64
            minimum: 0
          - type: string
            pattern: ^[0-9]+$
        idempotencyKey:
          type: string
          minLength: 8
          maxLength: 128
        reason:
          type: string
          maxLength: 1000
          nullable: true
    InquiryCommand:
      type: object
      required:
      - tripRecordVersion
      - offerRecordVersion
      - recordVersion
      - idempotencyKey
      properties:
        tripRecordVersion:
          oneOf:
          - type: integer
            format: int64
            minimum: 0
          - type: string
            pattern: ^[0-9]+$
        offerRecordVersion:
          oneOf:
          - type: integer
            format: int64
            minimum: 0
          - type: string
            pattern: ^[0-9]+$
        idempotencyKey:
          type: string
          minLength: 8
          maxLength: 128
        reason:
          type: string
          maxLength: 1000
          nullable: true
        recordVersion:
          oneOf:
          - type: integer
            format: int64
            minimum: 0
          - type: string
            pattern: ^[0-9]+$
    LooseboardDemand:
      type: object
      description: 原单待匹配投影；不含创建幂等键、请求哈希和操作人技术身份。
      properties:
        orderNo: { type: string }
        customerId: { type: string }
        version: { type: integer, format: int64 }
        origin: { type: string }
        destination: { type: string }
        productName: { type: string, nullable: true }
        estimatedPalletCount: { type: integer, nullable: true }
        packageCount: { type: integer, nullable: true }
        totalWeightKg: { type: number, nullable: true }
        totalVolumeCbm: { type: number, nullable: true }
        currency: { type: string }
        originContactName: { type: string, nullable: true }
        originContactPhone: { type: string, nullable: true }
        remark: { type: string, nullable: true }
    InquiryWrite:
      type: object
      required:
      - tripRecordVersion
      - offerRecordVersion
      - customerId
      - businessType
      - deliveryMode
      - cargo
      - idempotencyKey
      properties:
        sourceOrderNo:
          type: string
          maxLength: 64
          nullable: true
          description: 从待匹配散板选择原商业单；仅LOCAL_LOOSEBOARD支持。确认承运复用原单，不另开商业单。
        sourceOrderVersion:
          type: integer
          format: int64
          minimum: 0
          nullable: true
          description: 创建匹配时与原单号一起提交；已匹配登记不可替换来源。

        tripRecordVersion:
          oneOf:
          - type: integer
            format: int64
            minimum: 0
          - type: string
            pattern: ^[0-9]+$
        offerRecordVersion:
          oneOf:
          - type: integer
            format: int64
            minimum: 0
          - type: string
            pattern: ^[0-9]+$
        recordVersion:
          oneOf:
          - type: integer
            format: int64
            minimum: 0
          - type: string
            pattern: ^[0-9]+$
          nullable: true
        customerId:
          type: string
          pattern: ^[1-9][0-9]*$
        businessType:
          type: string
          enum:
          - LOCAL_LOOSEBOARD
          - US_TRUCK
        deliveryMode:
          type: string
          enum:
          - SELF_DELIVERY
          - MANUAL_PICKUP_TO_WAREHOUSE
        estimatedArrivalAt:
          type: string
          format: date-time
          nullable: true
        expectedPalletCount:
          type: integer
          minimum: 1
          nullable: true
        cargo:
          $ref: '#/components/schemas/Cargo'
        quoteRef:
          $ref: '#/components/schemas/QuoteRef'
          nullable: true
        idempotencyKey:
          type: string
          minLength: 8
          maxLength: 128
    FleetArrangement:
      type: object
      properties:
        sourceType:
          type: string
          nullable: true
        businessType:
          type: string
          nullable: true
        businessOrderNo:
          type: string
          nullable: true
        bookingNo:
          type: string
          nullable: true
        tripNo:
          type: string
          nullable: true
        originWarehouseName:
          type: string
          nullable: true
        destinationLabel:
          type: string
          nullable: true
        deliveryMode:
          type: string
          nullable: true
        deliveryInstructions:
          type: string
          nullable: true
        fulfillmentStage:
          type: string
          nullable: true
        currency:
          type: string
          nullable: true
        incomingNo:
          type: string
          nullable: true
        dispatchNo:
          type: string
          nullable: true
        deliveryNo:
          type: string
          nullable: true
        exceptionSummary:
          type: string
          nullable: true
        readOnlyReason:
          type: string
          nullable: true
        plannedDepartureAt:
          type: string
          format: date-time
          nullable: true
        stageOccurredAt:
          type: string
          format: date-time
          nullable: true
        agreedFreightAmount:
          type: number
          nullable: true
        signedPackages:
          type: integer
          minimum: 0
          nullable: true
        unsignedPackages:
          type: integer
          minimum: 0
          nullable: true
        returnedPackages:
          type: integer
          minimum: 0
          nullable: true
      description: 仅本客户本土单的实际承运摘要；约定金额不是实收，独立来源订单为null；禁止旧手工状态旁路。