打包负责人物资申领 · 前端对接

01通用约定

跟现有 /supplier/wms/inventory/* 一模一样：base https://api.xunmengvip.cn/xm-bulky-mall-gallery，全部 POST + JSON body，鉴权、{ code, msg, data, success } 包装（success 是布尔，等价于 code === 0；失败时 HTTP 状态码仍是 200，别用状态码判断成败）、index/size 分页都照旧，直接复用现成封装。失败响应的 msg 是可以直接 toast 的中文，速查见 08 节。

02角色与状态机

后端从两处判定当前账号的身份，不需要前端传角色来鉴权：

一个账号可以同时是仓管和负责人，这种情况下列表默认看全部；如果前端提供了「角色切换」，把当前视角作为 roleName 传给 /apply/page 即可（见 04 节）。

申领单状态

03新增接口 · 负责人侧

查询物资库房剩余可用库存 NEW

选好物资后调用，用于在申领数量输入框旁边展示「当前可申领上限」。

// 响应 data
{
  "skuId": 1012,
  "skuName": "打包纸箱",
  "specification": "60×40×40",
  "unitName": "个",
  "availableStock": 320   // 库房剩余可用 = 全局实物 − 各大区已分配剩余
}

提交物资申领 NEW

// ✅ 正确
{ "skuId": 1012, "quantity": 50, "voucherUrls": "[\"https://oss/a.jpg\",\"https://oss/b.jpg\"]" }

// ❌ 会报「凭证图片格式错误」
{ "skuId": 1012, "quantity": 50, "voucherUrls": ["https://oss/a.jpg"] }

响应 data 为 null，成功即可返回列表页刷新。接口不返回新建的申领单 ID，需要跳详情的话得先刷列表拿。

撤销物资申领 NEW

入参 { "id": 申领单ID }，响应 data 为 null。

只有申领人本人且单据处于待审核时才能撤销。不满足条件统一返回 申领单状态已变更，请刷新后重试（不区分「不是你的单」和「已经被审了」，避免泄露他人单据）。收到这个提示应当刷新列表。

04新增接口 · 列表与详情

申领列表 NEW

响应 records 单项：

{
  "id": 88,
  "applyNo": "SL20260825001",     // SL + yyyyMMdd + 3位序列
  "teamName": "昆明一区",
  "skuName": "打包纸箱",           // 即「物资类别」
  "specification": "60×40×40",
  "unitName": "个",
  "applyQuantity": 50,
  "issuedQuantity": 45,          // 仅「已同意」有值，其余状态恒为 null
  "status": 20,
  "statusDesc": "已同意",          // 后端已给中文，直接展示
  "createTime": "2026-08-25 09:12:33",
  "auditTime":  "2026-08-25 10:04:51",
  "canCancel": false,            // 撤销按钮显隐
  "canAudit":  false             // 同意/拒绝按钮显隐
}

申领详情 NEW

入参 { "id": 申领单ID }。返回值是列表项的超集，在上面所有字段之外多出：

非仓管账号查非自己大区的单，返回 申领记录不存在（不是无权限），前端按「记录不存在」处理即可。

05新增接口 · 仓管审核

同意申领 NEW

审批弹窗建议把 issuedQuantity 默认填成 applyQuantity，允许仓管改小。响应 data 为 null。

拒绝申领 NEW

入参 { "id": 申领单ID, "rejectReason": "库存留给昆明二区" }。rejectReason 后端不强制（≤255 字符），如果产品要求必填请前端自己拦。响应 data 为 null。

06既有接口的行为变化 · 必须跟进

这三处不是新接口，是本次一并收口的老接口。前端不跟会出报错或数字对不上。

新增入库补上了仓管校验 CHANGED

该接口此前完全没有角色校验，任何登录账号都能调。现在非仓管调用会返回 非仓库管理员，无进销存操作权限。

团队选择逻辑不变，仓管依旧可以选库房或任意大区入库。打包负责人此前若能进到这个页面，现在会被拦下，入口按角色隐藏即可。

新增出库按来源团队收敛权限 BREAKING

打包负责人登记本大区物资消耗的能力保留，但不能再从库房直接出货。出库页的团队选择器建议按角色渲染：仓管给全量，负责人只给 /supplier/wms/inventory/team/list 传 roleName="打包负责人" 后返回的那几个大区。

库存页「库房」一行的口径变了 BREAKING

teamId = 0 那一行的 teamStock，从「全局实物库存」改成了「库房剩余可用」：

库房剩余可用 = 全局实物库存 − Σ(各大区批次剩余)

大区行的 teamStock 语义不变（该大区剩余）。响应额外带一个 availableStock 字段，值同库房剩余可用，各行都有。

07搭页面时会用到的既有接口

申领相关页面不需要新的下拉数据接口，直接复用现成的两个：

推荐的提交页交互顺序

1. team/list（带 roleName）→ 过滤掉库房 → 大区下拉；只有一个就选中并隐藏
2. sku/list → 物资类别 / 规格下拉，选中拿到 skuId
3. apply/sku/stock（id 传 skuId）→ 展示「库房剩余可用 N 个」，作为数量输入框的 max
4. 上传凭证 → JSON.stringify(urls)，本地先校验张数 ≤5、长度 ≤512
5. apply/create → 成功后回列表页刷新

08报错文案速查

所有失败响应的 msg 都是可以直接 toast 的中文，无需前端翻译。下表用于确认交互分支：

09联调注意

• 测试账号要准备两个：一个是某大区的 leader_id（负责人），一个命中仓管角色。同一个账号两种身份都有时，很多分支测不出来。
• 时间字段格式与现有进销存接口一致，createTime / auditTime / cancelTime 都可能为 null，渲染前判空。
• 提交接口不回 ID：create 的 data 是 null，需要「提交成功后跳详情」的话，得先刷列表取第一条。
• voucherInfo 进出不对称：提交传字符串，详情返回数组。复用同一个表单模型时注意转换。
• 先看库存页再对申领：库房口径变了，联调时先确认 stock/page 库房行的数和你预期的「剩余可用」一致，再测申领链路，否则数字对不上会误判成申领的 bug。