打包负责人物资申领

梦花仓管小程序 · 进销存

后端模块 xm-bulky-mall-gallery（与 /supplier/wms/inventory/* 同一服务）。

通用约定

跟 /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 的中文，速查见「报错文案速查」。

角色与状态机

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

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

申领单状态

10 待审核 ──出库(未领满)──▶ 50 部分申领 ──出库(领满)──▶ 60 已完成（completeType=1 自动）
   │   └──出库(一次领满)─────────────────────────────▶ 60 已完成（completeType=1 自动）
   │                       50 部分申领 ──手动完成────▶ 60 已完成（completeType=2 手动）
   ├──拒绝──▶ 30 已拒绝
   └──撤销──▶ 40 已撤销

completeType：0 未完成、1 自动完成、2 手动完成、3 历史完成。

负责人侧

POST/supplier/wms/apply/sku/stock查询物资库房剩余可用库存

调用方：负责人 / 仓管

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

请求参数

响应

响应示例

{
  "skuId": 1012,
  "skuName": "打包纸箱",
  "specification": "60×40×40",
  "unitName": "个",
  "availableStock": 320
}

POST/supplier/wms/apply/create提交物资申领

调用方：仅负责人

请求参数

请求示例

{ "skuId": 1012, "teamId": 3, "quantity": 50, "voucherUrls": "[\"https://oss/a.jpg\",\"https://oss/b.jpg\"]", "remark": "本周加班" }

传 "voucherUrls": ["https://oss/a.jpg"]（数组对象）会报「凭证图片格式错误」。

响应

响应示例

{ "id": 88, "applyNo": "SL20261104001", "skuId": 1012 }

POST/supplier/wms/apply/batchCreate批量提交物资申领

调用方：仅负责人

同一物资类别（skuName 相同）下一次申领多个规格，每个规格各生成一张申领单。整批在一个事务里，任一规格校验失败整批不提交。

请求参数

请求示例

{
  "teamId": 3,
  "items": [
    { "skuId": 1012, "quantity": 50 },
    { "skuId": 1013, "quantity": 20 }
  ],
  "remark": "本周加班"
}

响应

data 为数组，每项字段同「POST /supplier/wms/apply/create」的响应（id / applyNo / skuId），顺序按 skuId 升序。

POST/supplier/wms/apply/cancel撤销物资申领

调用方：仅申领人本人

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

只有 申领人本人、单据处于 待审核且 尚未出库时才能撤销，否则返回 仅申请人可以撤销尚未出库的待审核申领单。并发下状态已被别人改掉时返回 申领单状态已变更，请刷新后重试，收到后刷新列表。

列表与详情

POST/supplier/wms/apply/page申领列表

调用方：负责人 / 仓管

请求参数

列表按申领单 ID 倒序。

响应

records[] 单项：

响应示例

{
  "id": 88,
  "applyNo": "SL20261104001",
  "teamId": 3,
  "teamName": "昆明一区",
  "skuId": 1012,
  "skuName": "打包纸箱",
  "specification": "60×40×40",
  "unitName": "个",
  "applicantName": "李四",
  "applyQuantity": 50,
  "issuedQuantity": 20,
  "remainingQuantity": 30,
  "progressPercent": 40.00,
  "status": 50,
  "statusDesc": "部分申领",
  "rejectReason": "",
  "createTime": "2026-11-04 09:12:33",
  "auditTime": null,
  "completeType": 0,
  "completeTime": null,
  "completeOperatorId": 0,
  "completeOperatorName": "",
  "canCancel": false,
  "canAudit": false,
  "canOutbound": true,
  "canFinish": true
}

POST/supplier/wms/apply/detail申领详情

调用方：仓管 / 本大区负责人

入参 { "id": 申领单ID }。返回列表项的全部字段，另外多出：

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

POST/supplier/wms/apply/item/page出库记录分页

调用方：仓管 / 本大区负责人

请求参数

响应

records[] 单项，按出库时间、明细 ID 升序：

可见范围同详情：非仓管查非自己大区的单返回 申领记录不存在。

仓管操作

POST/supplier/wms/apply/outbound申领出库

调用方：仅仓管

对待审核或部分申领的单出库一次，可多次分批出库。每次出库从库房划拨到申领大区（生成一条大区入库批次和一条库房出库流水），并按累计数量自动流转状态：未领满 → 50 部分申领，领满 → 60 已完成（completeType=1）。

请求参数

请求示例

{ "id": 88, "quantity": 20 }

响应

响应示例

{ "itemId": 501, "quantity": 20, "issuedQuantity": 20, "remainingQuantity": 30, "progressPercent": 40.00, "status": 50 }

出库弹窗建议把数量默认填成 remainingQuantity，上限取 remainingQuantity 与 /apply/sku/stock 的 availableStock 的较小值。

POST/supplier/wms/apply/approve申领出库（兼容入口）

调用方：仅仓管

与「POST /supplier/wms/apply/outbound」逻辑完全相同，只是数量字段名不同，响应也相同。新页面直接用 /outbound。

POST/supplier/wms/apply/finish手动完成

调用方：仅仓管

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

只有 部分申领（已出库且未领满）的单可以手动完成，否则返回 仅部分申领单可以手动完成。完成后状态 60、completeType=2，记录完成时间和完成人；数量和库存都不变。对已完成的单重复调用直接返回成功。

POST/supplier/wms/apply/reject拒绝申领

调用方：仅仓管

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

只有 待审核且未出库的单能拒绝；已出库（部分申领）的单不能拒绝，只能手动完成。

进销存出入库权限与库存口径

申领链路依赖下面三个进销存接口的规则，前端出入库页、库存页要按此渲染。

POST/supplier/wms/inventory/inbound/create新增入库

仅仓库管理员可调用，非仓管返回 非仓库管理员，无进销存操作权限。仓管可以选库房或任意大区入库，入口按角色隐藏即可。

POST/supplier/wms/inventory/outbound/create新增出库

打包负责人可以登记本大区的物资消耗，但不能从库房直接出货（库房物资通过申领出库发到大区）。出库页的团队选择器按角色渲染：仓管给全量，负责人只给 /supplier/wms/inventory/team/list 传 roleName="打包负责人" 后返回的大区。

POST/supplier/wms/inventory/stock/page库存页

teamId = 0 那一行的 teamStock 是「库房剩余可用」：

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

大区行的 teamStock 是该大区剩余。每行都带 availableStock，值同库房剩余可用；欠库时两者都允许为负数。全局实物库存字段不在手机端返回。

搭页面时会用到的进销存接口

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

推荐的提交页交互顺序

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

报错文案速查

联调注意

• 测试账号要准备两个：一个是某大区的 leader_id（负责人），一个命中仓管角色。同一个账号两种身份都有时，很多分支测不出来。
• 时间字段格式与进销存接口一致，auditTime / completeTime / cancelTime 都可能为 null，渲染前判空。
• voucherInfo 进出不对称：提交传字符串，详情返回数组。复用同一个表单模型时注意转换。
• 分批出库要看出库记录：每次出库一条明细，详情的 outboundRecords 或 /apply/item/page 都能取到；累计数量以 issuedQuantity 为准。
• 先看库存页再对申领：联调时先确认 stock/page 库房行的数和你预期的「剩余可用」一致，再测申领链路，否则数字对不上会误判成申领的 bug。