质检物料库 · 物料列表按剩余库存分胶囊过滤 — 设计文档

日期：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. 验收

进入物料列表默认「未用完」，列表仅 remainingQty > 0 的批次；total 与之匹配。
点「已用完」仅见 remainingQty = 0；点「全部」与改前全量一致（仍受关键词/状态约束）。
关键词 / 状态与胶囊叠加正确；翻页顺序与 total 正确。
导出结果与当前胶囊 + 筛选一致。
「变动记录」「库存盘点」无回归；生产物料 / 细胞存储物料库页面无改动。

7. 非目标

生产物料库、细胞存储物料库同类改造（可后续对齐）
数据库迁移或冗余「是否用完」字段
改变入库 / 出库 / 废弃业务逻辑
修改物料主数据 CRUD 接口

2026-08-18-qc-material-remaining-stock-filter-design.md 4.0 KB Permalink History Raw