219 lines
8.6 KiB
Markdown
219 lines
8.6 KiB
Markdown
# 质检物料库 · 编辑弹窗数量修正设计
|
||
|
||
> 日期: 2026-07-07
|
||
> 状态: 已实现
|
||
> 父模块: 质量检测 → 质检物料库(`/#/quality-group/quality-base/qc-material`)
|
||
> 关联文档: `2026-06-11-qc-material-batch-inbound-design.md`
|
||
|
||
## 1. 背景与目标
|
||
|
||
### 问题
|
||
|
||
编辑入库批次弹窗中,**入库数量**(`in_qty`)与**剩余数量**(`remaining_qty`)为只读,入库时若填错数量无法事后修正,导致批次余额与物资汇总库存(`stock_qty`)不准确。
|
||
|
||
### 目标(用户确认:场景 C — 两种都要支持)
|
||
|
||
| 场景 | 说明 | 典型操作 |
|
||
|------|------|----------|
|
||
| **A. 入库录入错误** | 初始入库量填错,出库/废弃/任务扣减记录本身正确 | 修正 `in_qty`,剩余按公式联动 |
|
||
| **B. 账实不符** | 入库量无误,实物盘点或发现剩余与账面不一致 | 直接修正 `remaining_qty`,写库存调整流水 |
|
||
|
||
### 非目标
|
||
|
||
- 修改历史出库 / 废弃 / 任务扣减流水(审计记录不可篡改)
|
||
- 回溯修改已完成盘点单中的快照行
|
||
- 同步改造生产物料库、细胞存储物料库(本 spec 仅覆盖质检物料库;后续可复用模式)
|
||
|
||
---
|
||
|
||
## 2. 数据不变量
|
||
|
||
### 2.1 批次级
|
||
|
||
```
|
||
已出库总量(out_total) = Σ |change_qty|
|
||
WHERE batch_id = 当前批次
|
||
AND del_flag = 0
|
||
AND change_type IN ('use', 'discard')
|
||
|
||
理论剩余(theoretical_remaining) = in_qty − out_total
|
||
```
|
||
|
||
恒等式(正常状态下):
|
||
|
||
- `0 ≤ remaining_qty ≤ in_qty`
|
||
- `remaining_qty = theoretical_remaining`(无独立调整时)
|
||
|
||
### 2.2 物资汇总
|
||
|
||
```
|
||
material.stock_qty = Σ batch.remaining_qty(同 material_id、del_flag=0)
|
||
```
|
||
|
||
### 2.3 流水职责
|
||
|
||
| 类型 | change_type | source_type | 是否随编辑修改 |
|
||
|------|-------------|-------------|----------------|
|
||
| 入库 | `in` | `manual_in` | **是** — 同步 `change_qty`、`amount` 快照 |
|
||
| 出库 | `use` | `manual_out` 等 | **否** |
|
||
| 废弃 | `discard` | `manual_discard` | **否** |
|
||
| 库存调整(新增) | `adjust` | `batch_qty_edit` | **新增** — 仅当剩余与理论值不一致时 |
|
||
|
||
---
|
||
|
||
## 3. 业务规则
|
||
|
||
### 3.1 编辑弹窗字段
|
||
|
||
| 字段 | 可编辑 | 说明 |
|
||
|------|--------|------|
|
||
| 入库数量 `inQty` | ✅ | `el-input-number`,min > 0,精度与入库一致(4 位小数) |
|
||
| 剩余数量 `remainingQty` | ✅ | 同上;可与理论值不同(场景 B) |
|
||
| 已出库总量 | 只读展示 | 打开弹窗时由后端返回或前端根据查看数据展示 |
|
||
| 理论剩余 | 只读展示 | `inQty − outTotal`;用户改 `inQty` 时前端实时重算 |
|
||
|
||
**UI 提示(有出库时):**
|
||
|
||
> 该批次已出库/废弃共 **{outTotal}** {unit}。修改入库数量后,若剩余数量未手工改动,将自动调整为 **{theoreticalRemaining}**。
|
||
|
||
**UI 提示(剩余与理论值不一致时):**
|
||
|
||
> 剩余数量与「入库数量 − 已出库」不一致,保存后将写入一条**库存调整**记录。
|
||
|
||
### 3.2 前端联动逻辑
|
||
|
||
1. 打开编辑弹窗:请求批次详情(含 `outTotal`),或列表行扩展字段 `outTotal`。
|
||
2. 用户修改 `inQty`:
|
||
- 若用户**未**手工改过 `remainingQty`(`remainingQtyTouched = false`)→ `remainingQty = inQty − outTotal`
|
||
- 若 `remainingQtyTouched = true` → 不自动覆盖剩余(支持场景 B)
|
||
3. 用户修改 `remainingQty` → 设 `remainingQtyTouched = true`
|
||
4. 改 `inQty` 且未锁定金额时 → 重算 `amount = unitPrice × inQty`(与入库弹窗一致)
|
||
5. 提交前校验:
|
||
- `inQty > 0`
|
||
- `remainingQty ≥ 0`
|
||
- `remainingQty ≤ inQty`
|
||
- `inQty ≥ outTotal`(入库量不能小于已出库总量)
|
||
|
||
### 3.3 后端 `update_batch` 扩展(已实现:保留原入库 + adjust 流水)
|
||
|
||
- **原入库流水**(`change_type=in`):**不修改** `change_qty`、`amount`,仅同步编号/批号等元数据快照。
|
||
- **入库数量变化**:写入 `adjust` 流水,`change_qty = 新入库量 − 旧入库量`,备注 `编辑修正入库数量(旧 → 新)`。
|
||
- **剩余数量在入库修正之外另有差异**:再写入一条 `adjust`,`change_qty = 新剩余 − (旧剩余 + 入库量差)`,备注 `编辑修正剩余数量`。
|
||
- **出库/废弃/任务流水**:仍不修改。
|
||
|
||
### 3.4 出库流水 — 明确不改
|
||
|
||
以下记录 **只读、不 UPDATE**:
|
||
|
||
- `change_type = use`(含 `manual_out`、`task_complete`、`outbound_handover`)
|
||
- `change_type = discard`
|
||
|
||
理由:反映真实领用/废弃/任务消耗,修正入库错误不应篡改历史操作。
|
||
|
||
### 3.5 边界情况
|
||
|
||
| 情况 | 处理 |
|
||
|------|------|
|
||
| 无出库记录(`out_total = 0`) | 改 `in_qty` 时默认 `remaining = in_qty`;两字段可联动 |
|
||
| 有出库,`in_qty` 从 100 改为 1000,剩余未手工改 | `remaining` 自动 970(已出 30) |
|
||
| 有出库,仅改 `remaining`(`in_qty` 不变) | 写 adjust 流水,差值进 `material.stock_qty` |
|
||
| `in_qty` 改小到小于 `out_total` | 拒绝,400:「入库数量不能小于已出库量 {out_total}」 |
|
||
| `remaining` 改负或大于 `in_qty` | 拒绝,400 |
|
||
| 批次已删除 / 物资已停用 | 沿用现网校验 |
|
||
|
||
---
|
||
|
||
## 4. API 变更
|
||
|
||
### 4.1 批次详情(可选,推荐)
|
||
|
||
```
|
||
GET /api/admin/web/admin/qc-material-batches/{batchId}
|
||
Response 在现有字段上增加:
|
||
outTotal: number // 已出库+废弃总量
|
||
outCount: number // 出库/废弃流水条数(用于 UI 提示)
|
||
```
|
||
|
||
若暂不增详情接口,可在 `list_batches` 每行附带 `outTotal`(编辑时从列表行读取);有性能顾虑时优先详情接口。
|
||
|
||
### 4.2 更新批次
|
||
|
||
```
|
||
PUT /api/admin/web/admin/qc-material-batches/{batchId}
|
||
Body 新增可选字段:
|
||
inQty: number
|
||
remainingQty: number
|
||
```
|
||
|
||
`QcMaterialBatchUpdateBody` 增加上述两字段。
|
||
|
||
### 4.3 变动记录列表
|
||
|
||
- `change_type=adjust` 纳入筛选(变动类型下拉新增「库存调整」,`value=adjust`)
|
||
- `_row_to_dict` / 前端展示:`adjust` → Tag `warning`,文案「库存调整」;`source_type=batch_qty_edit` → 「批次数量修正」
|
||
|
||
---
|
||
|
||
## 5. 前端改造
|
||
|
||
### 5.1 文件
|
||
|
||
| 文件 | 改动 |
|
||
|------|------|
|
||
| `web-admin/src/views/quality-inspection/qc-material/index.vue` | 编辑弹窗:`inQty`/`remainingQty` 可编辑;只读展示已出库/理论剩余;联动与校验;提交 payload |
|
||
| `web-admin/src/api/qc-material.ts` | 类型与 update 入参增加字段;可选 fetchBatchDetail |
|
||
| `web-admin/src/views/quality-inspection/qc-material/QcMaterialUsageTab.vue` | 变动类型筛选项 + 展示文案 |
|
||
|
||
### 5.2 编辑弹窗布局(在现有 `form-grid-3` 内)
|
||
|
||
```
|
||
入库数量 [input-number] 剩余数量 [input-number] 已出库总量 [只读]
|
||
理论剩余 [只读,inQty−outTotal] (有差异时 el-alert 提示将写调整流水)
|
||
```
|
||
|
||
- 数量控件样式与入库弹窗 `input-number` 一致
|
||
- `form-label-tip`:「已出库总量含手动出库、废弃及任务扣减(若启用)」
|
||
|
||
### 5.3 查看弹窗
|
||
|
||
- 批次基础信息仍展示修正后的 `inQty` / `remainingQty`
|
||
- 出库明细列表不变;若存在 adjust 流水,可在「变动记录」Tab 中查看
|
||
|
||
---
|
||
|
||
## 6. 后端改造
|
||
|
||
| 文件 | 改动 |
|
||
|------|------|
|
||
| `backend/app/crud/qc_material_stock_batch.py` | `update_batch` 数量修正逻辑;`_sum_batch_out_total()` helper |
|
||
| `backend/app/api/qc.py` | `QcMaterialBatchUpdateBody` 增字段;可选 GET batch detail |
|
||
| `backend/app/crud/qc_material_usage.py` | `list_usages` 支持 `change_type=adjust` 筛选;`_row_to_dict` 展示 |
|
||
|
||
无需新增数据库表;`change_type` / `source_type` 为 varchar,新枚举值直接写入。
|
||
|
||
---
|
||
|
||
## 7. 测试要点
|
||
|
||
1. **场景 A**:入库 100,无出库 → 改 in 为 1000 → remaining=1000,stock_qty +900,入库流水 change_qty=1000,无 adjust 流水
|
||
2. **场景 A+出库**:入库 100,出库 30 → 改 in 为 1000 → remaining=970,stock_qty +900,出库 3 条不变
|
||
3. **场景 B**:in 保持 100,出库 30,remaining 从 70 改为 65 → stock_qty −5,新增 adjust 流水 change_qty=−5
|
||
4. **校验**:in 改为 20(已出 30)→ 失败
|
||
5. **校验**:remaining 改为 101(in=100)→ 失败
|
||
6. **仅改厂家/批号**:数量不变,无 adjust、无 stock_qty 变化
|
||
7. **变动记录 Tab**:adjust 类型可筛选、Tag 展示正确
|
||
|
||
---
|
||
|
||
## 8. 与盘点的关系
|
||
|
||
- **库存盘点 Tab** 仍用于周期性盘点、登记未用完物料;本能力用于**单批次事后纠错**,二者互补。
|
||
- 已完成盘点单中的 `remaining_qty` 快照**不回溯**修改。
|
||
|
||
---
|
||
|
||
## 9. 后续扩展(本 spec 不做)
|
||
|
||
- 生产物料库 / 细胞存储物料库复用同一模式
|
||
- 数量修正权限细分(如仅库管可改剩余量)
|