101 lines
6.3 KiB
Markdown
101 lines
6.3 KiB
Markdown
# 国内仓整柜业务前端接口交接单
|
||
|
||
## 通用约定
|
||
|
||
- 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 授权后，由总编排显式调用：
|
||
|
||
```powershell
|
||
node scripts/admin-test-env-acceptance.mjs --modules domestic-container --output reports/admin-domestic-container.json
|
||
```
|
||
|
||
模块已安全加入 `admin-test-env-acceptance.mjs` 的 `DEFAULT_MODULES`，正式全量验收默认调用；动态模块加载逻辑无需修改。
|