openapi: 3.0.3
info:
  title: 外接销售报价候选与来源快照
  version: 1.0.0
  description: >-
    候选只读取有效销售报价，不创建承运、库存或费用。客户、起运城市、目的仓码、币种、计价单位和日期明确匹配；
    空价排除，零价保留，重叠有效期不自动选价。PALLET展示LOOSE_DELIVERY，ORDER展示FULL_DELIVERY价项；
    返回整车派送价项不表示已作为拼载成交价采用，必须明确选择报价号、版本及价项。
    日期由调用方根据真实车次计划起运时间和明确业务时区产生，不猜测机器或浏览器时区。
security:
  - bearerAuth: []
paths:
  /api/platform/v1/last-leg/fleet/quotes/sale-candidates:
    get:
      description: platform:fleet:quote:list；同路线原始候选超过5000条明确拒绝，不能截断后声称无报价。
      parameters:
        - { name: customerId, in: query, required: true, schema: { type: integer, format: int64, minimum: 1 } }
        - { name: originCity, in: query, required: true, schema: { type: string, minLength: 1, maxLength: 128 } }
        - { name: destinationCode, in: query, required: true, schema: { type: string, minLength: 1, maxLength: 64 } }
        - { name: currency, in: query, required: true, schema: { type: string, enum: [CNY, USD] } }
        - { name: effectiveOn, in: query, required: true, schema: { type: string, format: date } }
        - { name: priceBasis, in: query, required: true, schema: { type: string, enum: [ORDER, PALLET] } }
        - { 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: 成功业务码为200；失败保留业务码及requestId/traceId，不以空页冒充目录可用。
          content:
            application/json:
              schema:
                type: object
                properties:
                  code: { type: string }
                  message: { type: string }
                  requestId: { type: string }
                  traceId: { type: string }
                  data:
                    type: object
                    required: [records, page, size, total, pages]
                    properties:
                      records: { type: array, items: { $ref: '#/components/schemas/SourceSnapshot' } }
                      page: { type: integer, minimum: 1 }
                      size: { type: integer, minimum: 1 }
                      total: { type: integer, minimum: 0 }
                      pages: { type: integer, minimum: 0 }
components:
  securitySchemes:
    bearerAuth: { type: http, scheme: bearer, bearerFormat: JWT }
  schemas:
    QuoteRef:
      type: object
      required: [quoteNo, recordVersion, priceItem]
      properties:
        quoteNo: { type: string, minLength: 1, maxLength: 64 }
        recordVersion: { type: integer, format: int64, minimum: 0 }
        priceItem: { type: string, enum: [FULL_DELIVERY, LOOSE_DELIVERY] }
    SourceSnapshot:
      type: object
      required: [quoteNo, recordVersion, priceItem, customerId, customerName, originCity, destinationCode, distanceMiles, currency, priceBasis, quotedUnitPrice, validFrom, validTo, effectiveOn]
      properties:
        quoteNo: { type: string }
        recordVersion: { type: integer, format: int64, minimum: 0 }
        priceItem: { type: string, enum: [FULL_DELIVERY, LOOSE_DELIVERY] }
        customerId: { type: string }
        customerName: { type: string, description: 报价版本中的客户名称快照 }
        originCity: { type: string }
        destinationCode: { type: string }
        distanceMiles: { type: number, minimum: 0 }
        currency: { type: string, enum: [CNY, USD] }
        priceBasis: { type: string, enum: [ORDER, PALLET] }
        quotedUnitPrice: { type: number, minimum: 0, description: 正式报价单价；不是承运方最终成交单价或实际应收 }
        validFrom: { type: string, format: date }
        validTo: { type: string, format: date, description: 包含当天 }
        effectiveOn: { type: string, format: date }
x-booking-integration:
  method: FleetQuoteCandidateService.lockAndResolve(Context requested, QuoteRef reference)
  transaction: MANDATORY；由承运写事务调用。SELECT FOR UPDATE锁住原报价直到外层提交，禁止事务外解析后再单独保存。
  context: customerId/originCity/destinationCode/currency/effectiveOn/priceBasis；必须由承运服务按客户、真实路线、计划起运时间和明确业务时区核验，不能原样信任浏览器条件。
  validation: 重新核对SALE、ACTIVE、精确版本、客户、路线、币种、日期及明确选择的价项。未知价拒绝，零价允许；采购、自提、停用或陈旧报价不能引用。
  snapshot: 保存返回的SourceSnapshot，禁止使用浏览器提交的来源快照。来源单价与承运实际成交单价、计价量、金额分别保存，后续报价改价不覆盖历史。
  manual: 未引用时不调用解析方法，保留手填成交价能力；引用报价不自动生成应收、成本或付款。
  ownership: 提供端不修改FleetBooking、共享UI或SQL；接入方负责写权限、幂等重放优先返回原结果和实际成交快照持久化。