优化
This commit is contained in:
@@ -0,0 +1,312 @@
|
||||
openapi: 3.0.3
|
||||
info:
|
||||
title: Lastleg Overseas Business API
|
||||
version: 1.0.0
|
||||
paths:
|
||||
/api/platform/v1/last-leg/overseas-procurements:
|
||||
get:
|
||||
summary: 分页查询海外采购订单
|
||||
description: 权限 platform:overseas-business:purchase:list；customerId 为空时查询全部客户。
|
||||
security: [{ bearerAuth: [] }]
|
||||
parameters:
|
||||
- { name: customerId, in: query, schema: { type: string } }
|
||||
- { name: page, in: query, required: true, schema: { type: integer, minimum: 1 } }
|
||||
- { name: size, in: query, required: true, schema: { type: integer, minimum: 1, maximum: 200 } }
|
||||
- { name: orderNo, in: query, schema: { type: string } }
|
||||
- { name: customerKeyword, in: query, schema: { type: string } }
|
||||
- { name: purchaseCategory, in: query, schema: { type: string } }
|
||||
- { name: productName, in: query, schema: { type: string } }
|
||||
- { name: status, in: query, schema: { $ref: '#/components/schemas/ProcurementStatus' } }
|
||||
- { name: purchaseWarehouseId, in: query, schema: { type: string } }
|
||||
responses: { '200': { description: 统一 ApiResponse 包装的采购订单分页 } }
|
||||
/api/platform/v1/last-leg/overseas-procurements/customer-options:
|
||||
get:
|
||||
summary: 查询已有采购订单的客户候选
|
||||
description: 权限 platform:overseas-business:purchase:list；候选来自尾程库采购订单客户快照，不跨库查询 IAM。
|
||||
security: [{ bearerAuth: [] }]
|
||||
parameters:
|
||||
- { name: keyword, in: query, schema: { type: string } }
|
||||
- { name: limit, in: query, schema: { type: integer, minimum: 1, maximum: 200, default: 50 } }
|
||||
responses:
|
||||
'200':
|
||||
description: 客户候选
|
||||
content: { application/json: { schema: { $ref: '#/components/schemas/CustomerOptionResponse' } } }
|
||||
/api/platform/v1/last-leg/overseas-procurements/warehouse-options:
|
||||
get:
|
||||
summary: 查询启用的海外合作采购仓候选
|
||||
description: 权限 platform:overseas-business:purchase:list；复用服务端缓存目录，浏览器不访问国内内部 API。
|
||||
security: [{ bearerAuth: [] }]
|
||||
responses:
|
||||
'200':
|
||||
description: 采购仓候选
|
||||
content: { application/json: { schema: { $ref: '#/components/schemas/WarehouseOptionResponse' } } }
|
||||
/api/platform/v1/last-leg/overseas-procurements/{orderNo}:
|
||||
parameters:
|
||||
- { name: orderNo, in: path, required: true, schema: { type: string } }
|
||||
- { name: customerId, in: query, required: true, schema: { type: string, pattern: '^[1-9][0-9]*$' } }
|
||||
get:
|
||||
summary: 查询海外采购订单详情及操作流水
|
||||
description: 权限 platform:overseas-business:purchase:list。
|
||||
security: [{ bearerAuth: [] }]
|
||||
responses: { '200': { description: 统一 ApiResponse 包装的采购订单详情 } }
|
||||
patch:
|
||||
summary: 编辑海外采购订单
|
||||
description: 权限 platform:overseas-business:purchase:edit；可选字段缺失表示不修改，显式 null 或空串表示清空。采购仓名称由 warehouse ID 对应候选快照决定。采购出库不属于本 API。
|
||||
security: [{ bearerAuth: [] }]
|
||||
requestBody:
|
||||
required: true
|
||||
content: { application/json: { schema: { $ref: '#/components/schemas/ProcurementUpdate' } } }
|
||||
responses: { '200': { description: 统一 ApiResponse 包装的采购订单详情 }, '409': { description: 乐观锁冲突或状态不允许 } }
|
||||
/api/platform/v1/last-leg/overseas-procurements/{orderNo}/review:
|
||||
post:
|
||||
summary: 审核海外采购订单
|
||||
description: 权限 platform:overseas-business:purchase:review。
|
||||
security: [{ bearerAuth: [] }]
|
||||
parameters:
|
||||
- { name: orderNo, in: path, required: true, schema: { type: string } }
|
||||
- { name: customerId, in: query, required: true, schema: { type: string, pattern: '^[1-9][0-9]*$' } }
|
||||
requestBody:
|
||||
required: true
|
||||
content: { application/json: { schema: { type: object, required: [decision], properties: { decision: { type: string, enum: [APPROVE, REJECT] }, remark: { type: string, nullable: true, maxLength: 1000 } } } } }
|
||||
responses: { '200': { description: 统一 ApiResponse 包装的采购订单详情 } }
|
||||
/api/merchant/v1/last-leg/overseas-procurements:
|
||||
post:
|
||||
summary: 客户创建海外采购订单
|
||||
description: 客户 ID 只取认证身份；新单固定进入 PENDING_REVIEW。
|
||||
security: [{ bearerAuth: [] }]
|
||||
requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/ProcurementCreate' } } } }
|
||||
responses: { '200': { description: 统一 ApiResponse 包装的采购订单详情 } }
|
||||
get:
|
||||
summary: 客户分页查询自己的海外采购订单
|
||||
security: [{ bearerAuth: [] }]
|
||||
responses: { '200': { description: 统一 ApiResponse 包装的采购订单分页 } }
|
||||
/api/merchant/v1/last-leg/overseas-procurements/{orderNo}:
|
||||
get:
|
||||
summary: 客户查询自己的海外采购订单详情及流水
|
||||
security: [{ bearerAuth: [] }]
|
||||
parameters: [{ name: orderNo, in: path, required: true, schema: { type: string } }]
|
||||
responses: { '200': { description: 统一 ApiResponse 包装的采购订单详情 } }
|
||||
/api/platform/v1/last-leg/us-truck-orders:
|
||||
get:
|
||||
summary: 分页查询本土卡车订单
|
||||
description: 权限 platform:overseas-business:truck:list。
|
||||
security: [{ bearerAuth: [] }]
|
||||
responses: { '200': { description: 统一 ApiResponse 包装的卡车订单分页 } }
|
||||
post:
|
||||
summary: 平台为指定客户创建本土卡车订单
|
||||
description: 权限 platform:overseas-business:truck:create；customerId 必填且只作为可信服务端隔离键。
|
||||
security: [{ bearerAuth: [] }]
|
||||
parameters: [{ name: customerId, in: query, required: true, schema: { type: string, pattern: '^[1-9][0-9]*$' } }]
|
||||
requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/TruckCreate' } } } }
|
||||
responses: { '200': { description: 统一 ApiResponse 包装的卡车订单详情 } }
|
||||
/api/platform/v1/last-leg/us-truck-orders/{orderNo}:
|
||||
parameters:
|
||||
- { name: orderNo, in: path, required: true, schema: { type: string } }
|
||||
- { name: customerId, in: query, required: true, schema: { type: string, pattern: '^[1-9][0-9]*$' } }
|
||||
get:
|
||||
summary: 查询本土卡车订单详情
|
||||
description: 权限 platform:overseas-business:truck:list。
|
||||
security: [{ bearerAuth: [] }]
|
||||
responses: { '200': { description: 统一 ApiResponse 包装的卡车订单详情 } }
|
||||
patch:
|
||||
summary: 平台普通编辑本土卡车订单
|
||||
description: 权限 platform:overseas-business:truck:edit；仅待审核订单可编辑，不能修改状态。
|
||||
security: [{ bearerAuth: [] }]
|
||||
requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/TruckUpdate' } } } }
|
||||
responses: { '200': { description: 统一 ApiResponse 包装的卡车订单详情 } }
|
||||
/api/platform/v1/last-leg/us-truck-orders/{orderNo}/status:
|
||||
patch:
|
||||
summary: 推进本土卡车订单状态
|
||||
description: 权限 platform:overseas-business:truck:status；普通编辑接口不能修改状态。
|
||||
security: [{ bearerAuth: [] }]
|
||||
parameters:
|
||||
- { name: orderNo, in: path, required: true, schema: { type: string } }
|
||||
- { name: customerId, in: query, required: true, schema: { type: string, pattern: '^[1-9][0-9]*$' } }
|
||||
requestBody: { required: true, content: { application/json: { schema: { type: object, required: [version, status], properties: { version: { type: integer, format: int64, minimum: 0 }, status: { $ref: '#/components/schemas/TruckStatus' }, remark: { type: string, nullable: true, maxLength: 1000 } } } } } }
|
||||
responses: { '200': { description: 统一 ApiResponse 包装的卡车订单详情 }, '409': { description: 非法状态迁移 } }
|
||||
/api/platform/v1/last-leg/us-truck-orders/{orderNo}/receive-pallets:
|
||||
post:
|
||||
summary: 记录本土卡车订单实收托盘
|
||||
description: 权限 platform:overseas-business:truck:status；幂等记录实收，不创建海外仓出库或派送单。
|
||||
security: [{ bearerAuth: [] }]
|
||||
parameters:
|
||||
- { name: orderNo, in: path, required: true, schema: { type: string } }
|
||||
- { name: customerId, in: query, required: true, schema: { type: string, pattern: '^[1-9][0-9]*$' } }
|
||||
responses: { '200': { description: 统一 ApiResponse 包装的卡车订单详情 } }
|
||||
/api/platform/v1/last-leg/local-looseboard-orders:
|
||||
get:
|
||||
summary: 分页查询本土散板订单
|
||||
description: 权限 platform:overseas-business:looseboard:list。
|
||||
security: [{ bearerAuth: [] }]
|
||||
responses: { '200': { description: 统一 ApiResponse 包装的散板订单分页 } }
|
||||
post:
|
||||
summary: 创建本土散板订单
|
||||
description: 权限 platform:overseas-business:looseboard:create；独立稳定子域，不复用卡车端点。
|
||||
security: [{ bearerAuth: [] }]
|
||||
parameters: [{ name: customerId, in: query, required: true, schema: { type: string, pattern: '^[1-9][0-9]*$' } }]
|
||||
requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/LooseboardCreate' } } } }
|
||||
responses: { '200': { description: 统一 ApiResponse 包装的散板订单详情 } }
|
||||
/api/platform/v1/last-leg/local-looseboard-orders/{orderNo}:
|
||||
parameters:
|
||||
- { name: orderNo, in: path, required: true, schema: { type: string } }
|
||||
- { name: customerId, in: query, required: true, schema: { type: string, pattern: '^[1-9][0-9]*$' } }
|
||||
get:
|
||||
summary: 查询本土散板订单详情及操作流水
|
||||
description: 权限 platform:overseas-business:looseboard:list。
|
||||
security: [{ bearerAuth: [] }]
|
||||
responses: { '200': { description: 统一 ApiResponse 包装的散板订单详情 } }
|
||||
put:
|
||||
summary: 全量更新待接单的本土散板订单
|
||||
description: 权限 platform:overseas-business:looseboard:edit；可空字段传 null 或空串即清空；状态由独立端点推进。
|
||||
security: [{ bearerAuth: [] }]
|
||||
requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/LooseboardUpdate' } } } }
|
||||
responses: { '200': { description: 统一 ApiResponse 包装的散板订单详情 }, '409': { description: 版本或状态冲突 } }
|
||||
/api/platform/v1/last-leg/local-looseboard-orders/{orderNo}/status:
|
||||
patch:
|
||||
summary: 推进或取消本土散板订单
|
||||
description: 权限 platform:overseas-business:looseboard:status；只允许 PENDING_ACCEPTANCE→DISPATCHED→IN_TRANSIT→COMPLETED，未完成节点按规则取消。
|
||||
security: [{ bearerAuth: [] }]
|
||||
parameters:
|
||||
- { name: orderNo, in: path, required: true, schema: { type: string } }
|
||||
- { name: customerId, in: query, required: true, schema: { type: string, pattern: '^[1-9][0-9]*$' } }
|
||||
requestBody: { required: true, content: { application/json: { schema: { type: object, required: [version, status], properties: { version: { type: integer, format: int64, minimum: 0 }, status: { $ref: '#/components/schemas/LooseboardStatus' }, remark: { type: string, nullable: true, maxLength: 1000 } } } } } }
|
||||
responses: { '200': { description: 统一 ApiResponse 包装的散板订单详情 }, '409': { description: 非法状态迁移 } }
|
||||
components:
|
||||
schemas:
|
||||
ProcurementStatus: { type: string, enum: [PENDING_REVIEW, APPROVED, REJECTED] }
|
||||
ProcurementCreate:
|
||||
type: object
|
||||
required: [purchaseCategory, productName, purchaseQuantity, contactName, contactPhone, idempotencyKey]
|
||||
properties:
|
||||
customerName: { type: string, nullable: true, maxLength: 255 }
|
||||
purchaseCategory: { type: string, maxLength: 128 }
|
||||
productName: { type: string, maxLength: 255 }
|
||||
productSpecification: { type: string, nullable: true, maxLength: 500 }
|
||||
productUrl: { type: string, nullable: true, maxLength: 2000 }
|
||||
purchaseQuantity: { type: integer, format: int64, minimum: 1 }
|
||||
budgetUnitPrice: { type: number, nullable: true, minimum: 0 }
|
||||
currency: { type: string, minLength: 3, maxLength: 3, default: USD }
|
||||
receivingAddress: { type: string, nullable: true, maxLength: 1000 }
|
||||
contactName: { type: string, maxLength: 128 }
|
||||
contactPhone: { type: string, maxLength: 64 }
|
||||
remark: { type: string, nullable: true, maxLength: 1000 }
|
||||
idempotencyKey: { type: string, maxLength: 255 }
|
||||
NullableTextPatch: { type: string, nullable: true, description: 缺失不修改；null 或空串清空 }
|
||||
ProcurementUpdate:
|
||||
type: object
|
||||
required: [version]
|
||||
properties:
|
||||
version: { type: integer, format: int64, minimum: 0 }
|
||||
purchaseCategory: { type: string, maxLength: 128 }
|
||||
productName: { type: string, maxLength: 255 }
|
||||
productSpecification: { $ref: '#/components/schemas/NullableTextPatch' }
|
||||
productUrl: { $ref: '#/components/schemas/NullableTextPatch' }
|
||||
inboundQuantity: { type: integer, format: int64, minimum: 0 }
|
||||
purchaseWarehouseId: { $ref: '#/components/schemas/NullableTextPatch' }
|
||||
purchaseWarehouseName: { $ref: '#/components/schemas/NullableTextPatch' }
|
||||
domesticCarrier: { $ref: '#/components/schemas/NullableTextPatch' }
|
||||
domesticTrackingNo: { $ref: '#/components/schemas/NullableTextPatch' }
|
||||
overseasCarrier: { $ref: '#/components/schemas/NullableTextPatch' }
|
||||
overseasTrackingNo: { $ref: '#/components/schemas/NullableTextPatch' }
|
||||
estimatedArrivalAt: { type: string, format: date-time, nullable: true, description: 缺失不修改；null 或空串清空 }
|
||||
remark: { $ref: '#/components/schemas/NullableTextPatch' }
|
||||
CustomerOptionResponse:
|
||||
type: object
|
||||
properties:
|
||||
code: { type: string, enum: ['200'] }
|
||||
data: { type: array, items: { type: object, properties: { customerId: { type: string }, customerName: { type: string } } } }
|
||||
WarehouseOptionResponse:
|
||||
type: object
|
||||
properties:
|
||||
code: { type: string, enum: ['200'] }
|
||||
data: { type: array, items: { type: object, properties: { warehouseId: { type: string }, warehouseCode: { type: string }, warehouseName: { type: string }, countryCode: { type: string } } } }
|
||||
TruckStatus: { type: string, enum: [PENDING_REVIEW, WAITING_INBOUND, RECEIVING, WAITING_CONSOLIDATION, PALLET_OVERAGE_REVIEW, PARTIALLY_ALLOCATED, ALLOCATED, PENDING_DISPATCH, DISPATCHED, IN_TRANSIT, COMPLETED, REJECTED, CANCELLED] }
|
||||
TruckCreate:
|
||||
type: object
|
||||
required: [origin, destination, palletCount, totalWeightKg, totalVolumeCbm, contactName, contactInfo, requestedDate, idempotencyKey]
|
||||
properties:
|
||||
transportType: { type: string, enum: [PORT_PICKUP, WAREHOUSE_TO_WAREHOUSE, WAREHOUSE_TO_DOOR] }
|
||||
origin: { type: string, maxLength: 255 }
|
||||
originAddress: { type: string, nullable: true, maxLength: 500 }
|
||||
destination: { type: string, maxLength: 255 }
|
||||
destinationAddress: { type: string, nullable: true, maxLength: 500 }
|
||||
containerType: { type: string, nullable: true, maxLength: 32 }
|
||||
palletCount: { type: integer, minimum: 1 }
|
||||
packageCount: { type: integer, nullable: true, minimum: 0 }
|
||||
totalWeightKg: { type: number, minimum: 0 }
|
||||
totalVolumeCbm: { type: number, minimum: 0 }
|
||||
budgetAmount: { type: number, nullable: true, minimum: 0 }
|
||||
currency: { type: string, minLength: 3, maxLength: 3, default: USD }
|
||||
contactName: { type: string, maxLength: 128 }
|
||||
contactInfo: { type: string, maxLength: 128 }
|
||||
requestedDate: { type: string, format: date }
|
||||
remark: { type: string, nullable: true, maxLength: 1000 }
|
||||
idempotencyKey: { type: string, maxLength: 255 }
|
||||
TruckUpdate:
|
||||
type: object
|
||||
required: [version]
|
||||
properties:
|
||||
version: { type: integer, format: int64, minimum: 0 }
|
||||
transportType: { type: string, enum: [PORT_PICKUP, WAREHOUSE_TO_WAREHOUSE, WAREHOUSE_TO_DOOR] }
|
||||
origin: { type: string, maxLength: 255 }
|
||||
originAddress: { type: string, nullable: true, maxLength: 500 }
|
||||
destination: { type: string, maxLength: 255 }
|
||||
destinationAddress: { type: string, nullable: true, maxLength: 500 }
|
||||
containerType: { type: string, nullable: true, maxLength: 32 }
|
||||
palletCount: { type: integer, minimum: 1 }
|
||||
packageCount: { type: integer, minimum: 0 }
|
||||
totalWeightKg: { type: number, minimum: 0 }
|
||||
totalVolumeCbm: { type: number, minimum: 0 }
|
||||
budgetAmount: { type: number, nullable: true, minimum: 0 }
|
||||
currency: { type: string, minLength: 3, maxLength: 3 }
|
||||
contactName: { type: string, maxLength: 128 }
|
||||
contactInfo: { type: string, maxLength: 128 }
|
||||
requestedDate: { type: string, format: date }
|
||||
remark: { type: string, nullable: true, maxLength: 1000 }
|
||||
LooseboardStatus: { type: string, enum: [PENDING_ACCEPTANCE, DISPATCHED, IN_TRANSIT, COMPLETED, CANCELLED] }
|
||||
LooseboardCreate:
|
||||
type: object
|
||||
required: [transportMode, palletRequired, transportType, origin, destination, packageCount, totalWeightKg, totalVolumeCbm, idempotencyKey]
|
||||
properties:
|
||||
transportMode: { type: string, enum: [SHARED_TRUCK, PRIORITY_CONSOLIDATION] }
|
||||
palletRequired: { type: string, enum: [YES, NO] }
|
||||
transportType: { type: string, enum: [PORT_PICKUP, WAREHOUSE_TO_WAREHOUSE, WAREHOUSE_TO_DOOR] }
|
||||
origin: { type: string, maxLength: 255 }
|
||||
originAddress: { type: string, nullable: true, maxLength: 500 }
|
||||
destination: { type: string, maxLength: 255 }
|
||||
destinationAddress: { type: string, nullable: true, maxLength: 500 }
|
||||
containerType: { type: string, nullable: true, maxLength: 32 }
|
||||
packageCount: { type: integer, minimum: 0 }
|
||||
totalWeightKg: { type: number, minimum: 0 }
|
||||
totalVolumeCbm: { type: number, minimum: 0 }
|
||||
budgetAmount: { type: number, nullable: true, minimum: 0 }
|
||||
currency: { type: string, minLength: 3, maxLength: 3, default: USD }
|
||||
contactName: { type: string, nullable: true, maxLength: 128 }
|
||||
contactInfo: { type: string, nullable: true, maxLength: 128 }
|
||||
requestedDate: { type: string, format: date, nullable: true }
|
||||
remark: { type: string, nullable: true, maxLength: 1000 }
|
||||
idempotencyKey: { type: string, maxLength: 255 }
|
||||
LooseboardUpdate:
|
||||
type: object
|
||||
required: [version, transportMode, palletRequired, transportType, origin, destination, packageCount, totalWeightKg, totalVolumeCbm]
|
||||
properties:
|
||||
version: { type: integer, format: int64, minimum: 0 }
|
||||
transportMode: { type: string, enum: [SHARED_TRUCK, PRIORITY_CONSOLIDATION] }
|
||||
palletRequired: { type: string, enum: [YES, NO] }
|
||||
transportType: { type: string, enum: [PORT_PICKUP, WAREHOUSE_TO_WAREHOUSE, WAREHOUSE_TO_DOOR] }
|
||||
origin: { type: string, maxLength: 255 }
|
||||
originAddress: { type: string, nullable: true, maxLength: 500 }
|
||||
destination: { type: string, maxLength: 255 }
|
||||
destinationAddress: { type: string, nullable: true, maxLength: 500 }
|
||||
containerType: { type: string, nullable: true, maxLength: 32 }
|
||||
packageCount: { type: integer, minimum: 0 }
|
||||
totalWeightKg: { type: number, minimum: 0 }
|
||||
totalVolumeCbm: { type: number, minimum: 0 }
|
||||
budgetAmount: { type: number, nullable: true, minimum: 0 }
|
||||
currency: { type: string, minLength: 3, maxLength: 3, default: USD }
|
||||
contactName: { type: string, nullable: true, maxLength: 128 }
|
||||
contactInfo: { type: string, nullable: true, maxLength: 128 }
|
||||
requestedDate: { type: string, format: date, nullable: true }
|
||||
remark: { type: string, nullable: true, maxLength: 1000 }
|
||||
securitySchemes:
|
||||
bearerAuth: { type: http, scheme: bearer, bearerFormat: JWT }
|
||||
Reference in New Issue
Block a user