6.3 KiB
国内仓整柜业务前端接口交接单
通用约定
- Base path：
/api/platform/v1/domestic-containers - 浏览器继续使用
/api前缀，不写死 Gateway 地址。 - 所有接口仅允许平台端登录态，公共作用域固定为
tenant_id=0；前端不传客户/租户字段。 - 成功响应统一为
{ code: "200", message, data, requestId, traceId, timestamp }。 - 时间字段使用 ISO-8601
LocalDateTime，例如2026-08-12T09:30:00。 warehouseId必须对应平台公共、启用且warehouseType=DOMESTIC的国内仓；响应同时返回warehouseName快照。- OpenAPI：
warehouse/src/main/resources/openapi/domestic-container-v1.yaml。 - Warehouse 表迁移：
warehouse/src/main/resources/db/domestic-container-business.sql。 - IAM 权限迁移：
iam/src/main/resources/db/domestic-container-permissions.sql，最终权限 ID 固定为5103070、5103071、5103072。 - 测试环境验收模块：
scripts/admin-test-env-modules/domestic-container.mjs；合同测试：同目录domestic-container-contract.test.mjs。
接口清单
| 用途 | 方法 | 路径 | 权限 |
|---|---|---|---|
| 入库单列表 | GET | /inbounds |
platform:domestic-container:list |
| 新建入库单 | POST | /inbounds |
platform:domestic-container:inbound:create |
| 出库单列表 | GET | /outbounds |
platform:domestic-container:list |
| 新建出库单 | POST | /outbounds |
platform:domestic-container:outbound:create |
| 库存列表及汇总 | GET | /inventories |
platform:domestic-container:list |
| 库存详情/交易记录 | GET | /inventories/{inventoryId} |
platform:domestic-container:list |
列表筛选
入库单与出库单使用相同查询参数：page（默认 1）、size（默认 20，最大 200）、warehouseId、orderNo、containerNo、cargoName、status。字符串按包含匹配，status 为精确匹配。
库存列表参数：page、size、warehouseId、containerNo、cargoName、status。库存响应的 summary 是当前全部筛选结果的汇总，不只汇总当前页。
新建入库
请求字段：
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
warehouseId |
int64 | 是 | 平台国内仓 ID |
cargoName |
string | 是 | 货物名称，最长 128 |
containerNo |
string | 是 | 集装箱号，服务端转大写 |
boxCount |
integer | 是 | 入库箱数，大于 0 |
volumeCbm |
decimal | 是 | 入库体积，大于等于 0.0001，最多 4 位小数 |
inboundTime |
datetime | 是 | 入库操作时间 |
status |
enum | 是 | PENDING 或 COMPLETED |
remark |
string | 否 | 最长 500 |
idempotencyKey |
string | 是 | 每次用户提交生成的稳定唯一键，最长 128 |
COMPLETED 会在同一事务内增加库存并写入一条入库交易流水；PENDING 只创建待入库单，不影响库存。当前原型没有待单后续确认动作，本契约不提供确认/取消接口。
新建出库
请求字段：warehouseId、containerNo、boxCount、outboundTime、status、可选 remark、idempotencyKey、可选 inventoryVersion。
- 集装箱必须已在该国内仓形成库存；货物名称由库存快照带出，前端不提交。
COMPLETED会锁定库存、校验版本与可用箱数、原子扣减并写出库流水。PENDING创建待出库单但不扣库存；inventoryVersion可不传。- 已读取库存详情时，
COMPLETED请求应回传其version。版本过期返回A0409，前端刷新库存后由用户重试。 - 出库数量小于可用库存后状态为
PARTIALLY_OUTBOUND；等于可用库存后为OUTBOUND。
响应字段
创建响应 data：id、orderNo、replayed。replayed=true 表示同一幂等键及相同请求已处理，本次返回首次结果。
单据 records[]：id、businessType、orderNo、warehouseId、warehouseName、containerNo、cargoName、boxCount、volumeCbm、operationTime、status、remark、version、createdAt。出库单 volumeCbm 固定为 0，前端可不展示。
库存 records[]：id、warehouseId、warehouseName、containerNo、cargoName、inboundBoxes、outboundBoxes、availableBoxes、inboundVolumeCbm、inventoryStatus、version、updatedAt。
详情 data：inventory、inboundOrderCount、outboundOrderCount、transactions[]。交易字段为 id、businessType、orderNo、quantity、operationTime、remark，按操作时间倒序。
状态映射
| 后端枚举 | 页面文案 |
|---|---|
PENDING |
待入库 / 待出库（按当前页签） |
COMPLETED |
已入库 / 已出库（按当前页签） |
IN_STOCK |
在库 |
PARTIALLY_OUTBOUND |
部分出库 |
OUTBOUND |
已出库 |
INBOUND |
入库（交易类型） |
OUTBOUND |
出库（交易类型） |
幂等与错误处理
idempotencyKey必须在同一操作类型内唯一。相同键、相同请求返回首次结果；相同键、不同请求返回A0409。- 前端在网络超时后必须使用原键重试，不要生成新键；用户主动再次创建时生成新键。
- 业务响应以 body
code判断：200成功；A0403无平台端身份或无权限；A0404国内仓/整柜库存不存在或仓库未启用；A0409幂等键冲突、处理中、库存不足或库存版本已变化；A0422/A0400为字段格式或校验失败；S0500/S0503为服务或基础设施异常。 - 出错时记录
requestId、traceId和服务端message，不要模拟成功或本地扣减库存。
权限与验收接入
Warehouse Controller 强制校验上述三条权限码。独立 IAM 迁移会幂等注册权限并授予 PLATFORM_ADMIN，同时检查权限 ID/编码冲突、权限数量和管理员授权数量。国内整柜保留 5103070..5103072；供应商权限不得复用该区间。
验收模块不会在导入时访问环境，也不包含网关或账号。只有获得测试环境写 API 授权后，由总编排显式调用：
node scripts/admin-test-env-acceptance.mjs --modules domestic-container --output reports/admin-domestic-container.json
模块已安全加入 admin-test-env-acceptance.mjs 的 DEFAULT_MODULES，正式全量验收默认调用；动态模块加载逻辑无需修改。