From 8e689ee7715a2840530093b8f36b40423064b2d4 Mon Sep 17 00:00:00 2001 From: zlwu <704541015@qq.com> Date: Tue, 18 Aug 2026 09:31:33 +0800 Subject: [PATCH] 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 --- ...-material-remaining-stock-filter-design.md | 98 +++++++++++++++++++ 1 file changed, 98 insertions(+) create mode 100644 docs/superpowers/specs/2026-08-18-qc-material-remaining-stock-filter-design.md diff --git a/docs/superpowers/specs/2026-08-18-qc-material-remaining-stock-filter-design.md b/docs/superpowers/specs/2026-08-18-qc-material-remaining-stock-filter-design.md new file mode 100644 index 00000000..eafa7d1d --- /dev/null +++ b/docs/superpowers/specs/2026-08-18-qc-material-remaining-stock-filter-design.md @@ -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 接口