# 推荐箱型 / 设箱校验

> 打包小程序设箱确认弹窗、货架列表合规筛选与角标、包裹详情设箱不符标识；运营后台打包配置预估可装重量

- 类型：前端对接
- 分类：仓库配货 / 打包
- 端：打包小程序 / 运营后台
- 后端服务：supplier / admin
- 更新：2026-08-07
- 网页版：https://doc.xfun.fun/box-suggest-api

包裹单生成时后端会写入系统推荐箱型。打包小程序需要新增三处交互：设箱不符时的确认弹窗、打包完成货架列表的合规筛选与角标、包裹详情的"设箱不符"标识；运营后台需要在打包配置页维护"预估可装花材重量"。本页覆盖全部接口变更与字段口径。

供应商端 · 打包小程序 ＋ 运营后台

服务：**supplier-api**（小程序） / **bulky-admin**（运营后台） 全部 **POST** · JSON Body 更新：**2026-08-07**

## 核心概念：boxMatchStatus

所有包裹对象新增的匹配状态字段，前端展示只认它

每个包裹可能带有推荐箱型（`suggestPackId` / `suggestPackInfo`）。打包员设箱后，实际箱型与推荐箱型的比对结果由后端算好放在 `boxMatchStatus`，前端 **不要自行比对 id**：

| boxMatchStatus | 含义 | 展示 | 说明 |
|----|----|----|----|
| `0` | 无推荐 | 什么都不展示 | 历史包裹、中通普通包裹、未设箱的包裹都是 0，界面与现状一致。特殊花材附加面单**有**推荐（蝴蝶兰/红掌/大花蕙兰→蝴蝶兰箱，蓝色妖姬→蓝妖箱），仅当配置里没有对应箱型时才为 0 |
| `1` | 设箱合规 | 正常态，无强调 | 实际箱型 = 推荐箱型；筛选 chips 里的「设箱合规」对应此态 |
| `2` | 设箱不符 | 红色标识 | 实际箱型 ≠ 推荐箱型（小程序为确认强制使用；PDA 扫码不拦截直接落库）。详情打红标，货架卡片打「不符」角标 |

## 设箱确认弹窗流程

打包完成 / 改箱时，箱型与推荐不符会被后端拦下，需要二次确认

#### 正常调用打包完成接口

扫箱型码后按现有逻辑调 `/package/pack/finish`（或 scan / change），参数不变，`forceFlag` 不传或传 0。

#### 后端返回 code = 6001 时弹确认框

新错误码 `6001`（箱型与推荐不符）。**用 code 判断，不要匹配 msg 文案**。msg 已带推荐箱型名，可直接作为弹窗正文。其余错误码照旧当普通失败 toast。

弹窗示意：正文直接渲染后端 msg，例如「该箱型与系统推荐箱型（110\*60\*60）不符，请确认合理性并强制使用」，按钮为【否】【确认使用】。

#### 按用户选择分支处理

- **点「否」**：关闭弹窗即可，不发任何请求，箱型不变更，包裹仍是待打包状态。
- **点「确认使用」**：用 **完全相同的原参数**重调同一接口，仅追加 `forceFlag: 1`。成功后按现有成功逻辑走，后端自动记录强制使用留痕。

> [!NOTE]
> **注意：** 中通冷链禁用大箱的报错仍是普通错误码 `1`（msg「中通冷链不允许50\*50以上的箱子」），**不能**通过 forceFlag 绕过，不要对它弹确认框。

## 接口变更：打包完成 ×3

三个接口入参与错误码变更完全一致

### POST /package/pack/finish · 打包师傅 · 拍照设箱

同规则适用：`/package/pack/finish/change`（打包完成后改箱）。**扫码枪 `/package/pack/finish/scan`（PDA）除外**：PDA 无弹窗交互，设箱不符 **不拦截、不返回 6001**，直接完成并由后端留痕，PDA 前端无需任何改造。

#### 入参新增 **新增**

| 字段 | 类型 | 必填 | 说明 |
|----|----|----|----|
| forceFlag | int | 否 | 默认 0。用户在确认弹窗点「确认使用」后重调时传 **1**，其余参数保持与首次调用一致 |

#### 新增错误码 `6001`

失败响应示例（触发确认弹窗）

```json
{
  "code": 6001,
  "msg": "该箱型与系统推荐箱型（110*60*60）不符，请确认合理性并强制使用",
  "data": null
}
```

确认后重调请求示例（仅多一个 forceFlag）

```json
{
  "codeContent": "88231",
  "packId": 14,
  "packName": "110*50*50箱",
  "url": "https://…/finish.jpg",
  "shelfPackage": 1,
"forceFlag": 1
}
```

## 接口变更：货架列表筛选

打包师傅首页「打包完成」tab 的 chips 筛选与卡片角标

### POST /package/shelf/page · 打包师傅 · 货架分页

#### 入参新增 **新增**

| 字段 | 类型 | 必填 | 说明 |
|----|----|----|----|
| boxMatchFilter | int | 否 | 不传 / 0 = 全部；**1** = 仅设箱合规；**2** = 仅设箱不符。chips 仅在 `status=1`（打包完成）tab 下展示，切 tab 或取消选中时不传 |

#### 出参 records\[\] 新增 **新增**

| 字段 | 类型 | 说明 |
|----|----|----|
| boxMismatchFlag | int | 0 / 1。为 1 时货架卡片右上角展示红色「不符」角标。该货架下任一包裹设箱不符即为 1 |

> [!NOTE]
> 筛选「仅设箱不符」且当日没有任何不符货架时，接口正常返回空列表（total=0），按空态展示即可。

## 接口变更：详情与列表的包裹字段

包裹对象（WmsExpressPackageInfoVo）统一新增三个字段

### POST /package/shelf/detail · 货架打包详情

同字段出现于：`/package/info`（扫码包裹信息）、`/package/page`、`/package/list`（已废弃）。凡返回包裹对象的地方都带。

#### 包裹对象新增字段 **新增**

| 字段 | 类型 | 说明 |
|----|----|----|
| suggestPackId | int | 推荐箱型配置 id，**0 = 无推荐** |
| suggestPackInfo | string | 推荐箱型名称，如 110\*60\*60箱；无推荐时为空串 |
| boxMatchStatus | int | 0 无推荐 / 1 设箱合规 / 2 设箱不符，见[核心概念](#核心概念boxmatchstatus) |

响应片段示例

```json
{
  "id": 88231,
  "packageId": 14,
  "packageInfo": "110*50*50箱",
"suggestPackId": 17,
"suggestPackInfo": "110*60*60箱",
"boxMatchStatus": 2,  // 展示红色「设箱不符」标签
  "expressStatus": 10
}
```

## 接口变更：运营后台（bulky-admin）

打包配置维护预估花材容量 ＋ 发货单列表展示推荐箱型

### POST /system/add/packConfig · 仓库管理 · 打包配置 · 新增/编辑

#### 入参新增 **新增**

| 字段 | 类型 | 必填 | 说明 |
|----|----|----|----|
| flowerWeight | decimal | **是** | 预估可装花材重量（kg），范围 0~1000，最多 2 位小数。**0 表示不参与推荐箱型**（专用箱如蝴蝶兰箱、蓝妖箱就配 0）。不传后端报「预估可装花材重量不能为空」 |

> [!NOTE]
> **必须与后端同步上线：** 字段为必填，旧版配置页不传该字段时，新增/编辑都会保存失败。

### POST /system/packConfigList · 仓库管理 · 打包配置 · 列表

#### 出参新增 **新增**

| 字段 | 类型 | 说明 |
|----|----|----|
| flowerWeight | decimal | 预估可装花材重量（kg）。上线时存量配置会统一清零，由运营逐个补录 |

#### 配置页展示建议

- 列表增加「预估可装花材重量」列；值为 0 的箱型标注「未配置，不参与推荐」，提示运营补全。
- 多个箱型容量相同时推荐取 **排序更靠前**的那个，建议保存时对重复容量给个提醒（不阻断）。

### POST /order/wmsExpressPackage/list · 打单页 · 物流面单列表

#### 出参 records\[\] 新增 **新增**

| 字段 | 类型 | 说明 |
|----|----|----|
| suggestPackId | int | 推荐箱型配置 id，0 = 无推荐 |
| suggestPackInfo | string | 推荐箱型名称 |
| suggestPackFlowerWeight | decimal | 推荐箱型的预估可装花材重量（kg）；无推荐或该箱型未配置容量时为 `null` |

`/order/wmsExpressPackage/listByIds` 同样返回这三个字段。实际箱型仍看 `packageId` / `packageInfo`（设箱后才有值）。

### POST /order/sendOrder/list · 发货单 · 分页列表/导出

#### 出参 records\[\] 新增 **新增**

| 字段 | 类型 | 说明 |
|----|----|----|
| suggestPackList | array | 按序对应每个 **普通面单**的推荐箱型，元素为 `{packId, packName}`。中通或未配置箱型容量时为空数组 |

响应片段示例

```json
{
  "sendNo": "SD20260807001",
  "allTotalWeight": 180.00,
  "expressPackageNum": 3,
"suggestPackList": [
{ "packId": 17, "packName": "110*60*60箱" },
{ "packId": 17, "packName": "110*60*60箱" },
{ "packId": 3, "packName": "小件90*20" }
]
}
```

> [!NOTE]
> **expressPackageNum 口径变化：** 普通物流现在等于推荐箱型个数（不再固定按 60kg 拆）；中通仍按 45kg 拆、航邦 50kg 特殊拆分已取消；所有箱型都未配置容量时回退 60kg 拆分。特殊花材的附加面单不在 `suggestPackList` 里，件数口径不变。

## UI 落点

对照产品图的三个展示位

#### ① 货架列表 · 筛选 chips

设箱合规 设箱不符

仅「打包完成」tab 下展示，单选可取消。选中「设箱不符」传 `boxMatchFilter=2`，合规传 1，取消不传。

#### ② 货架卡片 · 角标

12-197 卡片右上角 不符

`boxMismatchFlag=1` 时展示红色角标，任意 tab 下有数据就展示，不依赖筛选是否开启。

#### ③ 打包详情 · 包裹标签

包裹类型：110\*50\*50箱 `设箱不符`

`boxMatchStatus=2` 时在「包裹类型」旁展示红标；为 1 时不额外展示；为 0 时保持现状。

## 联调注意

容易踩的坑集中在这里

- **错误码判断只认 code=6001**，msg 文案（含推荐箱型名）可能调整，别做字符串匹配。
- **forceFlag=1 重调必须复用首次请求的全部原参数**（codeContent、packId、packName、url 等），只追加 forceFlag，否则会以错误的箱型落库。
- `suggestPackId=0` 的包裹（历史数据、中通普通面单）永远不会返回 6001，也不展示任何标识——测试时别拿存量包裹验证弹窗，需用 **新生成的包裹**。
- **特殊花材附加面单同样有推荐箱型**（蝴蝶兰箱 / 蓝妖箱），设箱不符也会返回 6001、展示不符标识；前提是打包配置里存在同名箱型，测试前先确认配置。
- 弹窗「否」纯前端行为，不发请求；不要把「否」实现成带 forceFlag=0 的重调。
- 扫码枪接口 `/pack/finish/scan`（PDA） **不返回 6001**：设箱不符直接打包成功，后端自动留痕，包裹仍会显示"设箱不符"标识；确认弹窗只需小程序端实现。
- 防重锁与校验顺序已调整：6001 被拦时 **不占用**10 秒扫码频控，确认后立即重调不会报「扫码频繁」。
- 推荐箱型展示（如设箱前提示「推荐：110\*60\*60箱」）可直接用 `/package/info` 返回的 `suggestPackInfo`，为空串就不展示。