docs: add QC material remaining-stock filter design.

Capture the approved approach for separating used-up and available batches via toolbar capsules and a backend stockStatus query param.

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
zlwuandCursor committed 2026-08-18 09:31:33 +08:00
1 parent 00af72e11b
commit 8e689ee771
1 file changed
+98
@@ -0,0 +1,98 @@
# 质检物料库 · 物料列表按剩余库存分胶囊过滤 — 设计文档
> 日期:2026-08-18
> 状态:待实现
> 范围:【质检物料库】「物料列表」Tab(`/#/quality-group/quality-base/qc-material`)
---
## 1. 背景
「物料列表」实际展示的是质检物料**入库批次**(`QcMaterialBatch`),含剩余数量。已用完(剩余为 0)与未用完的批次混在同一列表,日常查看时已用完记录占屏。用户希望在工具栏用胶囊将二者分开过滤。
## 2. 已确认规则
| 项 | 约定 |
|----|------|
| 页面 / Tab | 仅【质检物料库】「物料列表」 |
| UI 位置 | 工具栏:「已选 N 项」与「入库」按钮之间 |
| 胶囊文案 | **全部** / **未用完** / **已用完** |
| 默认选中 | **未用完** |
| 未用完 | `remaining_qty > 0` |
| 已用完 | `remaining_qty = 0` |
| 全部 | 不按剩余数量限制 |
| 与其它筛选 | 可与关键词、状态下拉叠加 |
| 切换胶囊 | 重置到第 1 页并重新请求列表 |
| 导出 | 尊重当前全部筛选条件(含胶囊) |
| 分页 total | 与当前胶囊过滤结果一致 |
## 3. 方案(方案 A)
后端批次列表增加查询参数,按 `remaining_qty` 过滤;前端工具栏三胶囊驱动该参数。
不采用:仅前端对当前页过滤(分页 / total 不准);拆独立接口。
## 4. 后端
### 4.1 查询参数
在质检物料批次列表接口(`GET /web/admin/qc-material-batches`,对应 `list_batches`)增加可选参数:
| 参数名 | 类型 | 取值 | 默认(API 未传时) |
|--------|------|------|-------------------|
| `stockStatus` | string | `all` \| `available` \| `exhausted` | `all`(兼容旧调用) |
说明:页面默认选中「未用完」时,**前端请求显式传** `stockStatus=available`,不依赖后端默认。
### 4.2 过滤逻辑(`list_batches`)
在现有 `keyword` / `material_id` / `status` / 租户 / 数据权限过滤之后追加:
- `available` → `BizQcMaterialStockBatch.remaining_qty > 0`
- `exhausted` → `BizQcMaterialStockBatch.remaining_qty = 0`
- `all` 或缺省 / 非法值 → 不追加剩余数量条件
排序、分页、返回字段结构不变。
### 4.3 范围外接口
不改:物料主数据列表、批次 options(出库/废弃选批)、变动记录、库存盘点相关接口。
## 5. 前端
### 5.1 工具栏 UI
文件:`web-admin/src/views/quality-inspection/qc-material/index.vue`
在 `list-toolbar-row` 内、「已选 N 项」之后、「入库」之前增加三个小胶囊(segment / pill),样式对齐页面已有 `panel-pill-tabs` 视觉体系或同类工具栏分段控件,保证:
- 同一时刻仅一个选中
- 点击切换即更新过滤并 `loadData`
- 不破坏工具栏「已选在前、主行动在后、禁止 space-between 整组推右」约定
### 5.2 状态与请求
- 新增状态,例如 `stockStatusFilter: 'available' | 'exhausted' | 'all'`,初始值 `'available'`
- `loadData` / 导出拉全量:将 `stockStatus` 一并传给 `fetchQcMaterialBatchList`
- `api/qc-material.ts`:列表请求类型增加可选 `stockStatus`
### 5.3 交互
- 切换胶囊 → `pagination.page = 1` → `loadData`
- 搜索 / 重置:重置时胶囊是否恢复默认「未用完」——**是**(与进入页面一致)
- 关键词、状态下拉与胶囊条件同时生效
## 6. 验收
1. 进入物料列表默认「未用完」,列表仅 `remainingQty > 0` 的批次;total 与之匹配。
2. 点「已用完」仅见 `remainingQty = 0`;点「全部」与改前全量一致(仍受关键词/状态约束)。
3. 关键词 / 状态与胶囊叠加正确;翻页顺序与 total 正确。
4. 导出结果与当前胶囊 + 筛选一致。
5. 「变动记录」「库存盘点」无回归;生产物料 / 细胞存储物料库页面无改动。
## 7. 非目标
- 生产物料库、细胞存储物料库同类改造(可后续对齐)
- 数据库迁移或冗余「是否用完」字段
- 改变入库 / 出库 / 废弃业务逻辑
- 修改物料主数据 CRUD 接口