总览 · 通用约定
依据代码提交 43fe351f84 及两段式出库调整整理。出库为两段式:运营端生成待出库任务(可撤销),仓库端 PDA 逐包扫码 / 小程序裸花整单确认后才真正出库(不可撤销)。PDA 和小程序可共用统一入库接口,自动识别包裹码或花材码。三端共 29 个接口,均为 POST + JSON body,无 query / path 参数。
运营端 · 客服后台
/cold (admin)
双端共用 · 统一扫码入库
/cold/inbound (supplier-api)
PDA端 · 物流专员扫码枪
/cold/pda (supplier-api)
小程序端 · 梦花仓管
/cold/mini (supplier-api)
统一返回结构
运营端包裹 R<T>,供应商端包裹 Response<T>,结构一致:
两套分页规则 ⚠ 注意区分
| 端 | 入参字段 | 返回 |
|---|---|---|
| 运营端 | index 页码=1size 页大小=10searchCount=true 全部选填 | PageVO{current,size,total,records[]} |
| 小程序端 | current 当前页size 每页条数 必填 ≥1 | PageVo{current,size,total,records[]} |
鉴权与必需请求头
运营端接口带 @AuthToken(权限点):除登录态外还校验对应权限点(coldStorageView 查看 / coldStorageOperate 客服操作 / coldStorageWarehouse 仓库操作),每个接口所需权限见卡片标签。PDA / 小程序端 userId 由后端从登录态注入,前端无需传(下方标 注入);后端强制走可校验的 Authorization,不再接受历史裸 token 头。PDA 端限 物流专员 / 外部物流专员,小程序端限 质检员 / 区域负责人 / 仓库管理员。
| 请求头 | 端 | 必填 | 说明 |
|---|---|---|---|
| usertokenxm | 运营端 | 必填 | 登录 JWT |
| channel | 运营端 | 必填 | 固定 admin |
枚举字典
下方接口内所有状态字段引用此表。