# 打包页待补 / 早班 / 设箱

> 货架待补状态徽标、早班红底、设箱不符角标的渲染配色与三 tab 筛选映射，含早班跨午夜判断函数

- 类型：前端对接
- 分类：仓库配货 / 打包
- 端：打包小程序
- 后端服务：supplier
- 更新：2026-08-19
- 网页版：https://doc.xfun.fun/shelf-restock-api

供应商端 · 打包师傅页面

### POST /package/shelf/page · 货架打包状态分页

状态：已上测试环境（`supplier/test`）。改动仅新增字段与筛选，原有字段与行为不变。

## 三种视觉状态一览

同一张货架卡片可叠加多种状态。下面是实际配色的样例，颜色/透明度已按需求锁定，前端直接取用。

| 状态 | 驱动字段 | 视觉 |
|----|----|----|
| 普通货架 | `restockStatus` 为 0 / 2 | 默认卡片 |
| 待补 | `restockStatus === 1` | 卡片正上方居中「待补」橙色徽标 |
| 早班 | `earlyShiftFlag === true`（交货时间 ≥22:00 或 ≤01:00） | 整卡红底 |
| 设箱不符 | `boxMismatchFlag === 1` | 右上角「不符」红徽标 |
| 叠加 | 以上任意组合 | 早班红底 + 待补徽标 + 不符徽标可同时出现 |

> [!NOTE]
> **颜色值（需求锁定，请勿改）**
>
> **待补徽标**：底色 `#FF6A00`，字体 `#FFFFFF`，位于卡片正上方居中。
>
> **早班背景**：整卡背景 `#FF000F` 透明度 **70%**（即 `rgba(255,0,15,.7)`）。
>
> **设箱不符**：沿用现有「不符」红徽标（右上角），由 `boxMismatchFlag` 驱动，本次未改。

## 响应新增字段（ShelfPackageStatusVo）

| 字段 | 类型 | 说明 |
|----|----|----|
| `restockStatus` **新增** | int | **待补状态**。`0` 无待补 · `1` 存在待补货（→ 展示「待补」徽标）· `2` 补货已完成。徽标只在 `=== 1` 时显示。 |
| `earlyShiftFlag` **新增** | boolean | **是否早班**。后端已按口径算好（`deliveryTime >= 22:00` 或 `<= 01:00`），`true` 直接给整卡染红，前端无需自行判断时间，见「早班口径」。 |
| `deliveryTime` | string HH:mm:ss | **交货时间**（HH:mm:ss，已含提前 30 分钟）。仅展示用，早班判断请直接取 `earlyShiftFlag`。 |
| `boxMismatchFlag` | int | 货位下是否存在设箱不符包裹。`0` 否 · `1` 是（→「不符」徽标）。既有字段。 |
| `shelfSn` / `zoneShelf` | int / string | 货架号 / 区-货架，卡片主标题。既有字段。 |
| `selfPickup` | int | 是否自提 `1`/ `0`。自提货架单独 tab。既有字段。 |
| `preparedInfo` | object | 配货进度 `{ total, prepared, progress }`。既有字段。 |

## 请求新增筛选参数（ShelfPackageStatusPageQo）

| 参数 | 类型 | 说明 |
|----|----|----|
| `restockFilter` **新增** | int | **只看待补**。`null`/ `0` 不限 · `1` 只看待补（后端等价 `restockStatus = 1`）。 |
| `onlyEarlyShift` **新增** | boolean | **只看早班**。`true` 只看早班（`deliveryTime >= 22:00` 或 `<= 01:00`）；`null`/ `false` 不限。 |
| `boxMatchFilter` | int | 设箱筛选。`null`/ `0` 全部 · `1` 设箱合规 · `2` 设箱不符。既有参数。 |
| `date` **必填** | string | 场次日期，如 `2026-08-14`。必填。 |
| `status` **必填** | int | tab 状态：`0` 可打包/未打包 · `1` 打包完成 · `2` 出库完成 · `3` 自提。必填。 |
| `userId` / `userName` **必填** | long / string | 操作人。`current` / `size` 分页。必填。 |

## 早班口径 —— 后端已算好

> [!NOTE]
> **前端直接用 `earlyShiftFlag`，不用自己算时间**
>
> 后端口径：**`deliveryTime >= 22:00` 或 `deliveryTime <= 01:00`（跨零点，含边界）**即早班，已在服务端算入 `earlyShiftFlag`，前端 **直接取布尔值染红**即可。与配货页 `/zone/info/new` 的 `earlyShiftFlag` 是同一口径。
>
> 「只看早班」 `onlyEarlyShift` 用的也是同一口径，与卡片染红天然一致；前端不要再按 `deliveryTime` 自行判断，避免阈值分叉。

```text
// 渲染时：
// 早班背景 -> row.earlyShiftFlag === true 背景 rgba(255,0,15,.7)
// 待补徽标 -> row.restockStatus === 1 底 #FF6A00 / 字 #FFFFFF
// 不符徽标 -> row.boxMismatchFlag === 1
```

## 三个 Tab 的筛选项映射（需求第 4 点）

| Tab          | status | 只看待补        | 只看早班       | 设箱合规/不符      |
|--------------|--------|-----------------|----------------|--------------------|
| **可打包**   | 0      | restockFilter=1 | onlyEarlyShift | 无                 |
| **打包完成** | 1      | restockFilter=1 | onlyEarlyShift | boxMatchFilter=1/2 |
| **自提货架** | 3      | restockFilter=1 | 无             | boxMatchFilter=1/2 |

各筛选项可自由组合，后端按 AND 叠加。「只看待补」在所有 tab 都有；「只看早班」仅可打包 / 打包完成两个 tab；「设箱」仅打包完成 / 自提两个 tab（沿用既有 `boxMatchFilter`）。

## 关于「退货已补货显示绿色」（需求第 1 点）

需求第 1 点（标记退货的已补货花材显示为绿色）属于 **质检配货页面的花材级**展示，不在本打包货架接口范围内，其所需字段由该页面自身接口返回，本次 **不涉及**。本页只覆盖打包页面的第 2、3、4 点。

接口 `POST /package/shelf/page` · 供应商端 · 测试分支 `supplier/test`。字段口径以后端返回为准；`earlyShiftFlag`/ `restockStatus` 均已由服务端算好，前端直接取用。