83 lines
5.3 KiB
YAML
83 lines
5.3 KiB
YAML
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；接入方负责写权限、幂等重放优先返回原结果和实际成交快照持久化。
|