160 lines
6.9 KiB
YAML
160 lines
6.9 KiB
YAML
openapi: 3.0.3
|
|
info:
|
|
title: Firstleg Coload Group API
|
|
version: 1.0.0
|
|
description: 同柜且不可拆组平台管理契约；允许跨客户及不同目的仓港成组，仅要求国内仓和渠道一致。
|
|
paths:
|
|
/api/platform/v1/first-leg/coload-groups:
|
|
post:
|
|
summary: 创建同柜不可拆组
|
|
description: >-
|
|
需要 platform:firstleg:smart-loading:assign。orderIds 至少2项；服务端解析每个订单处于待审核、
|
|
待测量/测量中、待分柜或装柜中的全部有效入仓片段；待审核订单先经 Order 批量权威核验并幂等准备
|
|
PREPARING 入库投影。全部成员要求国内仓和渠道一致，并冻结全部片段及其满箱数。
|
|
全部成员未进入装柜计划时创建 ACTIVE 组；全部成员已经按满箱数完整进入同一个装柜计划时直接创建并
|
|
锁定为 LOCKED 组。仅部分成员进柜、分散在不同装柜计划、箱数不完整、已属于其他活动组或权威仓库/
|
|
渠道快照缺失时拒绝。跨成员仓库或渠道不一致时返回入仓码及仓库名/渠道名；平台错误不得展示
|
|
orderId、inboundId 或 groupId。
|
|
parameters:
|
|
- $ref: '#/components/parameters/IdempotencyKey'
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema: {$ref: '#/components/schemas/CreateColoadGroupRequest'}
|
|
responses:
|
|
'200': {$ref: '#/components/responses/ColoadGroupResponse'}
|
|
'403': {description: 缺少智能排柜分配权限}
|
|
/api/platform/v1/first-leg/coload-groups/by-inbound-code/{inboundCode}/cancel:
|
|
post:
|
|
summary: 整组取消同柜不可拆组
|
|
description: 使用任一成员入仓码整组取消；仅 ACTIVE 组允许取消，不提供单成员编辑。
|
|
parameters:
|
|
- $ref: '#/components/parameters/IdempotencyKey'
|
|
- {name: inboundCode, in: path, required: true, schema: {type: string, minLength: 1, maxLength: 40}}
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema: {$ref: '#/components/schemas/CancelColoadGroupByInboundCodeRequest'}
|
|
responses:
|
|
'200': {$ref: '#/components/responses/ColoadGroupResponse'}
|
|
'403': {description: 缺少智能排柜分配权限}
|
|
/api/platform/v1/first-leg/coload-groups/by-inbound-code/{inboundCode}:
|
|
get:
|
|
summary: 按入仓码查询同柜组业务摘要
|
|
description: >-
|
|
需要 platform:firstleg:smart-loading:list。使用任一有效成员的全局唯一 inboundCode 查询；
|
|
返回真实业务组号 groupNo、组业务状态、有效成员数和全部唯一成员入仓码。任一冻结成员缺少有效 inboundCode 时失败关闭；
|
|
页面不持有或展示 groupId、orderId，也不得从技术ID或订单号推导入仓码。
|
|
parameters:
|
|
- name: inboundCode
|
|
in: path
|
|
required: true
|
|
schema: {type: string, minLength: 1, maxLength: 40}
|
|
responses:
|
|
'200':
|
|
description: 业务响应
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- {$ref: '#/components/schemas/ApiEnvelope'}
|
|
- type: object
|
|
properties:
|
|
data: {$ref: '#/components/schemas/ColoadGroupBusinessSummary'}
|
|
'403': {description: 缺少智能排柜列表权限}
|
|
components:
|
|
parameters:
|
|
IdempotencyKey:
|
|
name: Idempotency-Key
|
|
in: header
|
|
required: true
|
|
schema: {type: string, minLength: 1, maxLength: 128}
|
|
responses:
|
|
ColoadGroupResponse:
|
|
description: 成功或业务失败，按响应体 code 判断
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- {$ref: '#/components/schemas/ApiEnvelope'}
|
|
- type: object
|
|
properties:
|
|
data: {$ref: '#/components/schemas/ColoadGroup'}
|
|
schemas:
|
|
ApiEnvelope:
|
|
type: object
|
|
required: [code, message, timestamp]
|
|
properties:
|
|
code: {type: string, example: '200'}
|
|
message: {type: string}
|
|
requestId: {type: string, nullable: true}
|
|
traceId: {type: string, nullable: true}
|
|
timestamp: {type: string, format: date-time}
|
|
CreateColoadGroupRequest:
|
|
type: object
|
|
additionalProperties: false
|
|
required: [orderIds]
|
|
properties:
|
|
orderIds:
|
|
type: array
|
|
minItems: 2
|
|
maxItems: 100
|
|
uniqueItems: true
|
|
items: {type: string, pattern: '^[1-9][0-9]*$'}
|
|
CancelColoadGroupByInboundCodeRequest:
|
|
type: object
|
|
additionalProperties: false
|
|
properties:
|
|
reason: {type: string, maxLength: 500, nullable: true}
|
|
ColoadGroupMember:
|
|
type: object
|
|
additionalProperties: false
|
|
required: [tenantId, orderId, inboundId, inboundCode, fullPackageCount]
|
|
properties:
|
|
tenantId: {type: string, pattern: '^[1-9][0-9]*$'}
|
|
orderId: {type: string, pattern: '^[1-9][0-9]*$'}
|
|
inboundId: {type: string, pattern: '^[1-9][0-9]*$'}
|
|
inboundCode: {type: string, minLength: 1, maxLength: 40, description: 冻结成员的全局唯一入仓码，禁止由技术ID推导}
|
|
fullPackageCount: {type: integer, minimum: 1}
|
|
ColoadGroup:
|
|
type: object
|
|
additionalProperties: false
|
|
required: [groupId, groupNo, status, warehouseId, channelCode, version, members,
|
|
fullPackageCount, createdAt, updatedAt]
|
|
properties:
|
|
groupId: {type: string, pattern: '^[1-9][0-9]*$'}
|
|
groupNo: {type: string, pattern: '^CLG-[1-9][0-9]*$'}
|
|
status: {type: string, enum: [ACTIVE, LOCKED, CONSUMED, CANCELLED]}
|
|
warehouseId: {type: string, pattern: '^[1-9][0-9]*$'}
|
|
channelCode: {type: string}
|
|
lockedPlanId: {type: string, nullable: true}
|
|
version: {type: integer, minimum: 0}
|
|
members:
|
|
type: array
|
|
minItems: 2
|
|
items: {$ref: '#/components/schemas/ColoadGroupMember'}
|
|
fullPackageCount: {type: integer, minimum: 2, description: 全部成员满箱数之和}
|
|
createdAt: {type: string, format: date-time}
|
|
updatedAt: {type: string, format: date-time}
|
|
ColoadGroupBusinessMember:
|
|
type: object
|
|
additionalProperties: false
|
|
required: [inboundCode]
|
|
properties:
|
|
inboundCode: {type: string, minLength: 1, maxLength: 40}
|
|
ColoadGroupBusinessSummary:
|
|
type: object
|
|
additionalProperties: false
|
|
required: [groupNo, status, memberCount, members]
|
|
properties:
|
|
groupNo: {type: string, pattern: "^CLG[0-9]{12}$", description: 真实同柜业务组号；与创建及重放结果一致}
|
|
status: {type: string, enum: [ACTIVE, LOCKED, CONSUMED]}
|
|
memberCount: {type: integer, minimum: 1}
|
|
members:
|
|
type: array
|
|
minItems: 1
|
|
uniqueItems: true
|
|
items: {$ref: '#/components/schemas/ColoadGroupBusinessMember'}
|