feat(order): add customer order foundations
This commit is contained in:
@@ -6,6 +6,76 @@ info:
|
||||
security:
|
||||
- bearerAuth: []
|
||||
paths:
|
||||
/api/merchant/v1/order-addresses:
|
||||
get:
|
||||
summary: 查询当前客户下单地址簿
|
||||
parameters:
|
||||
- name: addressType
|
||||
in: query
|
||||
required: false
|
||||
schema: {type: string, enum: [PICKUP, PRIVATE_DESTINATION]}
|
||||
responses:
|
||||
'200': {description: 只返回登录客户可用地址}
|
||||
'403': {description: 需要订单查看、创建或编辑权限}
|
||||
post:
|
||||
summary: 保存当前客户下单地址
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema: {$ref: '#/components/schemas/CustomerOrderAddressSaveRequest'}
|
||||
responses:
|
||||
'200': {description: 返回地址内部 ID，Long 按字符串序列化}
|
||||
'403': {description: 需要 merchant:order:create 权限}
|
||||
/api/merchant/v1/order-addresses/{id}:
|
||||
put:
|
||||
summary: 修改当前客户下单地址
|
||||
description: 已创建订单保存独立快照，本操作不会修改历史订单。
|
||||
parameters:
|
||||
- {name: id, in: path, required: true, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema: {$ref: '#/components/schemas/CustomerOrderAddressSaveRequest'}
|
||||
responses: {'200': {description: 成功}, '403': {description: 需要 merchant:order:edit 权限}}
|
||||
delete:
|
||||
summary: 停用当前客户下单地址
|
||||
description: 停用后不能用于新订单，历史订单快照不受影响。
|
||||
parameters:
|
||||
- {name: id, in: path, required: true, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
|
||||
responses: {'200': {description: 成功}, '403': {description: 需要 merchant:order:edit 权限}}
|
||||
/api/merchant/v1/orders/first-leg/batch-imports/template:
|
||||
get:
|
||||
summary: 下载 Excel 批量下单模板
|
||||
responses:
|
||||
'200': {description: xlsx 模板}
|
||||
'403': {description: 需要 merchant:order:create 权限}
|
||||
/api/merchant/v1/orders/first-leg/batch-imports:
|
||||
post:
|
||||
summary: 上传 Excel 批量创建订单草稿
|
||||
description: >-
|
||||
ATOMIC 在任一行失败时整批回滚；PARTIAL 每行独立事务，错误行不影响成功行。
|
||||
同一操作者重试必须复用 Idempotency-Key，每行再以 clientRowId 派生稳定幂等键。
|
||||
原文件和错误报告分别通过 File 的 ORDER_BATCH_IMPORT_SOURCE、ORDER_BATCH_IMPORT_ERROR_REPORT 契约保存。
|
||||
parameters:
|
||||
- $ref: '#/components/parameters/IdempotencyKey'
|
||||
- name: mode
|
||||
in: query
|
||||
required: true
|
||||
schema: {type: string, enum: [ATOMIC, PARTIAL]}
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
multipart/form-data:
|
||||
schema:
|
||||
type: object
|
||||
required: [file]
|
||||
properties:
|
||||
file: {type: string, format: binary, description: 最大 5MB，仅 xlsx；最多 50 行}
|
||||
responses:
|
||||
'200': {description: 返回逐行结果、原文件 ID 及可选错误报告文件 ID}
|
||||
'403': {description: 需要 merchant:order:create 权限}
|
||||
/api/platform/v1/orders/first-leg/inbound-code-policy:
|
||||
get:
|
||||
summary: 平台端查询全系统入仓码模式
|
||||
@@ -686,7 +756,7 @@ components:
|
||||
description: 报价包税维度；独立于订单 taxMode 的买单/退税语义
|
||||
FirstLegOrderDraft:
|
||||
type: object
|
||||
required: [pricingTaxMode, cargoes]
|
||||
required: [customerName, transportMode, cargoes, pickupMethod, receivingWarehouseId, receivingWarehouseName, channelCode, channelName, taxMode, pricingTaxMode, destinationType]
|
||||
properties:
|
||||
fulfillmentType:
|
||||
type: string
|
||||
@@ -699,6 +769,9 @@ components:
|
||||
pattern: '^[A-Za-z0-9._:-]+$'
|
||||
description: 仅 LEGACY_MANUAL 模式填写的旧系统入仓码；AUTO 模式必须省略
|
||||
pricingTaxMode: {$ref: '#/components/schemas/PricingTaxMode'}
|
||||
senderAddressId: {type: string, pattern: '^[1-9][0-9]*$', description: PICKUP 时必填；必须是本客户 PICKUP 地址}
|
||||
privateDestinationAddressId: {type: string, pattern: '^[1-9][0-9]*$', description: PRIVATE 时必填；必须是本客户 PRIVATE_DESTINATION 地址}
|
||||
customsInspection: {type: boolean, nullable: true, description: 非木制品可空；任一货物 woodenProduct=true 时必须为 true}
|
||||
cargoes:
|
||||
type: array
|
||||
minItems: 1
|
||||
@@ -707,7 +780,25 @@ components:
|
||||
订单保存请求中的完整字段以服务端 FirstLegOrderSaveRequest 为准；fulfillmentType
|
||||
省略时固定为 STANDARD，一键代发必须显式传 ONE_CLICK_DROPSHIP，且不复用计费 businessType；pricingTaxMode
|
||||
是新建和编辑订单的必填报价维度；customerId 不接受客户端指定，服务端始终使用认证企业 ID；
|
||||
发货单位和收货单位仅通过 sender/receiver 保存业务快照。历史存量订单的响应字段仍允许为空。
|
||||
发货与私人目的仓只接受客户地址 ID，服务端在订单参与方表冻结快照；地址簿后续修改不回写历史订单。
|
||||
私人目的仓不得写入或伪装为 Warehouse 平台仓主档。历史存量订单的响应字段仍允许为空。
|
||||
CustomerOrderAddressSaveRequest:
|
||||
type: object
|
||||
required: [addressType, addressName, companyName, contactName, phone, countryCode, city, addressLine, defaultAddress]
|
||||
properties:
|
||||
addressType: {type: string, enum: [PICKUP, PRIVATE_DESTINATION]}
|
||||
addressName: {type: string, maxLength: 64}
|
||||
companyName: {type: string, maxLength: 128}
|
||||
contactName: {type: string, maxLength: 64}
|
||||
phone: {type: string, maxLength: 32}
|
||||
email: {type: string, format: email, maxLength: 128, nullable: true}
|
||||
countryCode: {type: string, minLength: 2, maxLength: 2}
|
||||
province: {type: string, maxLength: 64, nullable: true}
|
||||
city: {type: string, maxLength: 64}
|
||||
district: {type: string, maxLength: 64, nullable: true}
|
||||
addressLine: {type: string, maxLength: 255}
|
||||
postalCode: {type: string, maxLength: 20, nullable: true}
|
||||
defaultAddress: {type: boolean}
|
||||
InboundCodePolicy:
|
||||
type: object
|
||||
required: [mode, manualEntryRequired]
|
||||
@@ -769,7 +860,7 @@ components:
|
||||
errorMessage: {type: string}
|
||||
FirstLegOrderCargo:
|
||||
type: object
|
||||
required: [skuNo, packageCount]
|
||||
required: [packageCount, woodenProduct]
|
||||
properties:
|
||||
skuNo: {type: string, maxLength: 64}
|
||||
cargoName: {type: string, maxLength: 128}
|
||||
@@ -801,6 +892,7 @@ components:
|
||||
cargoRemark: {type: string, maxLength: 500}
|
||||
packageType: {type: string, maxLength: 32}
|
||||
dangerousGoods: {type: boolean}
|
||||
woodenProduct: {type: boolean, description: 木制品权威判定快照；为 true 时订单 customsInspection 必须为 true}
|
||||
description: >-
|
||||
原型货物明细字段。FBA 货物的 skuNo、upcNo、shipmentId、referenceId 由服务端按每条货物校验；
|
||||
productImageFileId 必须属于当前登录客户。
|
||||
|
||||
Reference in New Issue
Block a user