# 质检配货页分页

> 配货列表分页 + 早班/待补/子货位标记与筛选；need/prepared 为货位数；支持发货时间与二级分类筛选

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

配货列表接口为轻表分页，带早班货位、待补货位、子货位标记与对应筛选。本页覆盖接口的分页方式、字段与渲染规则。

供应商端 · 质检配货页

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

## 分页与计数

- **分页**：请求传 `pageNo`（从 1 开始）、`pageSize`（默认 20），不传按第 1 页、每页 20 条；响应 `total` 为当前筛选条件下的货位总数，`shelfSnList` 只返回 **当前页**，翻页按 `total` 计算页数。
- **`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` 不限。 |
| `deliveryStartTime` / `deliveryEndTime` | string | 发货时间段筛选，`HH:mm`，如 `22:00`~`01:00`；结束早于开始视为跨零点。与打包列表口径一致。 |
| `secondId` | long | 二级分类 id，不传 = 全部二级分类。 |
| `deliveryType` | int | 配送方式筛选：`1` 物流 · `2` 自提（自提 tab/筛选）。 |
| `zone` / `zoneShelf` | string | 分区 / 货架号筛选。全部分区即不传 zone。 |
| `segmentNameList` | array | 分段筛选，传分段时必须同时传 `zone`。 |
| `cityFlag` | int | 是否城配区。 |
| `roleName` | string | 当前角色名称。 |

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

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

### POST /subShelfSn/info · 子货位明细

入参 `shelfSn`（货位号，必填）、`date`（场次，必填），可选 `subShelfSn`、`mobileEnd`（手机尾号）；返回该货位的子货位明细。

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

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

> [!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` · 供应商端。字段口径以后端返回为准；`earlyShiftFlag`/ `restockStatus`/ `hasSubShelf` 均已由服务端算好，前端直接取用。