# 质检配货页分页

> 配货列表改分页 + 早班/待补/子货位标记与筛选；含 need/prepared 语义变化与分页破坏性变更说明

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

配货列表接口改为轻表分页（全部分区由 7-8s 降至毫秒级），并新增早班货位、待补货位标记与对应筛选。本页覆盖接口的分页方式、新增字段与渲染规则。

供应商端 · 质检配货页

### POST /zone/info/new · 配货货位列表（分页）

状态：已上测试环境（`supplier/test`）。**有 2 处破坏性变更**：接口改为分页、`need`/ `prepared` 语义变化，见「破坏性变更」。

## 破坏性变更 —— 先读这两条

> [!NOTE]
> **① 接口改为分页，不再一次返回全部货位**
>
> 请求需传 `pageNo`（从 1 开始）、`pageSize`（默认 20）；响应新增 `total`（当前筛选条件下的货位总数）。`shelfSnList` 现在只返回 **当前页**，翻页请自行按 `total` 计算页数。
>
> 不传 `pageNo/pageSize` 时后端按第 1 页、每页 20 条兜底 —— 老前端不改会只看到前 20 个货位，务必接入分页。

> [!NOTE]
> **② `need` / `prepared` 语义由「扎数」改为「货位数」**
>
> `need` = 当前筛选条件下 **可配货货位数**（status=0），`prepared` = **配货完成货位数**（status=1）。用于两个 tab 的角标计数。若原来按扎数展示汇总，需改按货位数。

## 货位卡片视觉状态

列表 **一行一个货位号**（不再拆子货位）。同一张卡片可叠加多种状态，配色与打包页统一，前端直接取用。

| 状态 | 驱动字段 | 视觉 |
|----|----|----|
| 普通货位 | `restockStatus` 为 0 / 2 | 默认卡片 |
| 待补 | `restockStatus === 1` | 卡片正上方居中「待补」橙色徽标 |
| 早班 | `earlyShiftFlag === true` | 整卡红底 |
| 有子货位 | `hasSubShelf === 1` | 右上角「子」徽标 |
| 叠加 | 以上任意组合 | 早班红底 + 待补 + 子 可同时出现 |

> [!NOTE]
> **颜色值（与打包页一致，请勿改）**
>
> **待补徽标**：底色 `#FF6A00`，字体 `#FFFFFF`，卡片正上方居中，`restockStatus === 1` 时显示。
>
> **早班背景**：整卡背景 `#FF000F` 透明度 **70%**（`rgba(255,0,15,.7)`），`earlyShiftFlag === true` 时染红。
>
> **子货位徽标**：`hasSubShelf === 1` 时右上角展示「子」标；点货位进详情看子货位（见「货位级列表 + 子货位详情」）。

## 响应结构（PrepareShelfSnVo）

顶层计数 + 当前页货位列表。

| 字段                | 类型  | 说明                                           |
|---------------------|-------|------------------------------------------------|
| `total` **新增**      | long  | 当前筛选条件下货位总数，用于分页。             |
| `need` **语义变更**     | int   | 可配货货位数（status=0）。原为扎数。           |
| `prepared` **语义变更** | int   | 配货完成货位数（status=1）。原为扎数。         |
| `shelfSnList`       | array | 当前页货位列表，元素为 ShelfSnStatus（下表）。 |

列表元素 `ShelfSnStatus`（一行一货位）：

| 字段 | 类型 | 说明 |
|----|----|----|
| `shelfSn` | int | 货位号，卡片主标题。 |
| `status` | int | 配货完成状态：`0` 可配货 · `1` 配货完成（货位级：所有子货位都配完才为 1）。 |
| `restockStatus` **新增** | int | **待补状态**：`0` 无待补 · `1` 存在待补货（→「待补」徽标）· `2` 补货已完成。徽标仅 `=== 1` 显示。 |
| `earlyShiftFlag` **新增** | boolean | **是否早班**。后端已按口径算好，`true` 直接染红，前端无需自行判断时间（口径见「早班口径」）。 |
| `hasSubShelf` **新增** | int | **是否有子货位**：`0` 无 · `1` 有（→「子」徽标）。 |
| `subShelfSn` | string | 列表层 **恒为空串** `""`（列表是货位级）。子货位明细走详情接口，见「货位级列表 + 子货位详情」。 |
| `total` / `prepared` / `notRestock` / `progress` | int / decimal | 该货位进度：应配 / 已配 / 退缺 / 进度（0~1，封顶 1）。跨子货位汇总。 |
| `zone` / `zoneShelf` / `segmentName` | string | 分区 / 区-货架 / 分段。既有字段。 |
| `deliveryType` | int | 配送方式 `1` 物流 · `2` 自提。既有字段。 |
| `limitDistribution` / `wareType` / `wareId` | int | 限制配货标识 / 仓库类型 / 仓库 id。既有字段。 |

## 请求参数（ZoneInfoQo）

| 参数 | 类型 | 说明 |
|----|----|----|
| `date` **必填** | string | 场次日期，如 `2026-08-17`。必填。 |
| `type` | int | tab：`0` 可配货 · `1` 配货完成 · `-1` 全部。默认 0。 |
| `pageNo` **新增** | int | 页码，从 `1` 开始。默认 1。 |
| `pageSize` **新增** | int | 每页条数。默认 20。 |
| `onlyRestock` **新增** | boolean | **只看待补**。`true` 仅展示 `restockStatus=1` 的货位；`null`/ `false` 不限。 |
| `onlyEarlyShift` **新增** | boolean | **只看早班**。`true` 仅展示早班货位；`null`/ `false` 不限。 |
| `deliveryType` | int | 配送方式筛选：`1` 物流 · `2` 自提。既有参数（自提 tab/筛选）。 |
| `zone` / `zoneShelf` | string | 分区 / 货架号筛选。既有参数。全部分区即不传 zone。 |
| `segmentNameList` | array | 分段筛选，传分段时必须同时传 `zone`。既有参数。 |
| `cityFlag` | int | 是否城配区。既有参数。 |

## 货位级列表 + 子货位详情

列表 **一行一个货位号**；一个货位有多个子货位时，只出一张卡片并打「子」标（`hasSubShelf === 1`）。点货位进详情看子货位，走既有详情接口：

### POST /subShelfSn/info · 入参货位号 shelfSn，返回该货位的子货位明细

完成状态是 **货位级**：一个货位只要还有任意子货位没配完，整货位就算未完成（留在「可配货」），全部子货位配完才整体进「配货完成」。

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

> [!NOTE]
> **前端直接用 `earlyShiftFlag`，不用自己算时间**
>
> 后端口径：**`deliveryTime >= 22:00` 或 `deliveryTime <= 01:00`（跨零点）**即早班。此口径与打包页一致，且已在服务端算入 `earlyShiftFlag`，前端 **直接取布尔值染红**即可。
>
> 「只看早班」 `onlyEarlyShift` 用的是同一口径，与卡片染红天然一致。

```text
// 渲染时（字段均由后端返回，前端不再自行判断时间）：
// 早班背景 -> row.earlyShiftFlag === true 背景 rgba(255,0,15,.7)
// 待补徽标 -> row.restockStatus === 1 底 #FF6A00 / 字 #FFFFFF
// 子货位标 -> row.hasSubShelf === 1 右上角「子」
```

## Tab 与筛选映射

| Tab          | type | 只看待补    | 只看早班       | 自提           |
|--------------|------|-------------|----------------|----------------|
| **可配货**   | 0    | onlyRestock | onlyEarlyShift | deliveryType=2 |
| **配货完成** | 1    | onlyRestock | onlyEarlyShift | deliveryType=2 |

筛选项可自由组合，后端 AND 叠加，且两个 tab 均支持。「配货完成」tab 勾「只看待补」返回的是 **已配货完成但仍有待补记录**的货位（待补与完成是两个独立维度）。

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