docs: add qc material month import design and implementation plan
Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
1 parent
6957952b4c
commit
f7ee984d04
2 files changed
+1045
No files matched your search
@@ -0,0 +1,235 @@
|
||||
# 质检物料库 · 月初固定导入设计
|
||||
|
||||
> 日期: 2026-08-19
|
||||
> 状态: 已实现(待库表执行与联调验收)
|
||||
> 父模块: 质量检测 → 质检物料库
|
||||
> 相关: `docs/superpowers/specs/2026-06-11-qc-material-batch-inbound-design.md`
|
||||
|
||||
## 1. 背景与目标
|
||||
|
||||
### 现状
|
||||
|
||||
质检物料库(`/#/quality-group/quality-base/qc-material`)已支持:
|
||||
|
||||
- 单条入库 / 批量入库(入库批次:编号、日期、货号、批号、厂家、单价、金额、数量、过期日期等)
|
||||
- 批量出库、批量废弃
|
||||
- 批次列表、变动记录、库存盘点等
|
||||
|
||||
业务侧每月初会固定入库一批物品,字段大体相同,目前需反复手工录入,效率低。
|
||||
|
||||
### 目标
|
||||
|
||||
1. 提供租户可维护的 **月初入库模板**(固定那一批物品,用户可自行增删改)
|
||||
2. 提供 **月初导入**:按模板展开预览 → 用户可改 → 确认后走现有批量入库链路,生成入库批次与变动流水
|
||||
3. 预览时按规则 **默认生成入库编号**(可改);物资不存在时可按模板信息 **自动创建**
|
||||
|
||||
### 已确认决策
|
||||
|
||||
| 问题 | 决策 |
|
||||
|------|------|
|
||||
| 导入本质 | 模板驱动的批量入库(非 Excel 文件导入) |
|
||||
| 模板字段完整度 | 尽量带齐现有入库字段;每月主要改入库日期 / 编号,其余可微调 |
|
||||
| 维护入口 | 仍在质检物料库页:工具栏「月初导入」+「维护月初模板」弹窗 |
|
||||
| 同月重复导入 | 允许随时多次执行,系统不拦截 |
|
||||
| 入库编号 | 预览时默认生成 `RK + YYYYMMDD + 3位序号`,用户可改(现网手工录入,本期补生成能力) |
|
||||
| 物资关系 | 可关联已有物资;也可只填物资信息,确认入库时若不存在则自动创建 |
|
||||
| 执行交互 | 两步:打开预览(可改)→ 确认才真正入库 |
|
||||
| 本期范围 | 仅质检物料库 |
|
||||
| 实现路径 | 独立模板表 + 复用现有批量入库 API |
|
||||
|
||||
### 非目标
|
||||
|
||||
- 定时/cron 自动入库
|
||||
- 生产物料库 / 市场物料库同步改造
|
||||
- 同月幂等或「每月只能导一次」
|
||||
- 改造现有单条入库弹窗的编号生成(可后续复用同一生成函数)
|
||||
- Excel 文件上传导入
|
||||
- 模板行携带质检附件 URL
|
||||
|
||||
---
|
||||
|
||||
## 2. 架构与数据流
|
||||
|
||||
```
|
||||
维护月初模板 (CRUD)
|
||||
↓
|
||||
biz_qc_material_month_template(租户级模板行)
|
||||
↓
|
||||
月初导入预览(选入库日期 → 展开 + 生成编号 → 可改可删行)
|
||||
↓
|
||||
现有批量入库 API(必要时同事务 ensure 物资)
|
||||
↓
|
||||
biz_qc_material_stock_batch + biz_qc_material.stock_qty + biz_qc_material_usage
|
||||
```
|
||||
|
||||
原则:
|
||||
|
||||
- **模板不直接改库存**;只有确认入库才写批次与流水
|
||||
- **预览中的增删改不回写模板**(仅影响本次导入)
|
||||
- 库存一致性完全依赖现有 `batch_stock_in` 事务语义(任一行失败整单回滚)
|
||||
|
||||
---
|
||||
|
||||
## 3. 数据模型
|
||||
|
||||
### 3.1 新表 `biz_qc_material_month_template`
|
||||
|
||||
一行 = 模板中的一条固定入库明细。字段对齐入库批次(不含入库编号 / 入库日期)。
|
||||
|
||||
| 字段 | 说明 |
|
||||
|------|------|
|
||||
| `id` | VARCHAR(64) UUID PK |
|
||||
| `material_id` | 可空;关联已有 `biz_qc_material.id` |
|
||||
| `material_code` | 物资编码(关联时冗余;待建物资时必填) |
|
||||
| `material_name` | 物资名称 |
|
||||
| `spec_model` | 规格型号 |
|
||||
| `unit` | 单位 |
|
||||
| `catalog_no` | 货号(必填,与入库一致) |
|
||||
| `batch_no` | 批号(必填) |
|
||||
| `manufacturer` | 厂家(必填) |
|
||||
| `unit_price` | 单价(元,必填) |
|
||||
| `amount` | 金额(元,必填;维护时可按单价×数量默认) |
|
||||
| `in_qty` | 默认入库数量(>0) |
|
||||
| `expire_date` | 默认过期日期(必填,与现网批次一致) |
|
||||
| `remark` | 备注 |
|
||||
| 公共字段 | `tenant_no`, `order_num`, `create_by`, `create_dept_id`, `create_time`, `update_by`, `update_time`, `del_flag` |
|
||||
|
||||
**规则:**
|
||||
|
||||
- 租户隔离:所有读写按当前用户 `tenant_no` 过滤 / 写入
|
||||
- 软删除:`del_flag=1`
|
||||
- 列表默认按 `order_num ASC, create_time ASC`
|
||||
- 若填写 `material_id`:保存时校验物资存在且未删除;建议同步冗余编码/名称/规格/单位(物资主数据变更后,模板冗余可被用户手动刷新或下次编辑覆盖)
|
||||
- 若未填 `material_id`:`material_code`、`material_name` 必填;导入确认时按 `tenant_no + material_code` 查找启用物资,找不到则创建(`stock_qty=0`,`status=1`)
|
||||
|
||||
SQL 脚本落在 `docs/sql/2026-08-19-qc-material-month-template.sql`(实现阶段)。
|
||||
|
||||
---
|
||||
|
||||
## 4. 业务流程
|
||||
|
||||
### 4.1 维护月初模板
|
||||
|
||||
入口:质检物料库 · 批次列表工具栏「维护月初模板」。
|
||||
|
||||
- 弹窗内表格展示当前租户全部模板行
|
||||
- 支持新增一行、编辑、删除(软删)、调整顺序(`order_num`)
|
||||
- 选择已有物资:下拉选启用物资,带出编码/名称/规格/单位
|
||||
- 手填新物资:清空 `material_id`,填编码/名称等;编码在模板内建议唯一(同租户模板行不重复 `material_code`,避免混淆)
|
||||
- 不维护入库编号、入库日期
|
||||
|
||||
### 4.2 月初导入
|
||||
|
||||
1. 用户点击「月初导入」
|
||||
2. 若模板行数为 0:提示先维护模板,并引导打开维护弹窗;不打开空预览
|
||||
3. 打开预览弹窗:
|
||||
- 顶部「本次入库日期」默认今天,可改
|
||||
- 调用 preview:按模板行展开明细,并为每行生成默认 `stock_in_no`
|
||||
- 用户可改任意字段、删除本行(不回写模板);**本期不要求在预览中新增模板外行**(需要额外物资用普通入库/批量入库)
|
||||
4. 确认入库:
|
||||
- 对每行:`ensure_material`(已有 id 则用;否则按编码查/建)
|
||||
- 组装与现有批量入库相同的 payload
|
||||
- 调用现有批量入库逻辑(同一事务)
|
||||
5. 成功:关闭弹窗、刷新批次列表、提示成功条数
|
||||
|
||||
### 4.3 入库编号生成
|
||||
|
||||
格式:`RK` + `YYYYMMDD`(取自本次入库日期)+ **3 位十进制序号**(左补零),例:`RK20260819001`。
|
||||
|
||||
算法(preview 与最终提交前均可调用):
|
||||
|
||||
1. 取租户内当日(按入库日期对应的 `YYYYMMDD`)已存在且匹配 `RK{YYYYMMDD}%` 的 `stock_in_no`,解析最大序号
|
||||
2. 从 `max+1` 起为预览中的 N 行连续分配
|
||||
3. 提交时仍做租户内唯一校验;若冲突(并发入库),返回明确错误,用户改编号后重试
|
||||
|
||||
说明:现网单条/批量入库仍为手工录入;本能力仅服务月初导入预览默认值。生成函数宜放在后端可复用处,便于日后单条入库复用。
|
||||
|
||||
---
|
||||
|
||||
## 5. API 设计
|
||||
|
||||
前缀与现有质检物料一致:`/web/admin/...`,经现有鉴权 / 租户中间件。
|
||||
|
||||
| 方法 | 路径 | 说明 |
|
||||
|------|------|------|
|
||||
| GET | `/qc-material-month-templates` | 当前租户模板列表 |
|
||||
| POST | `/qc-material-month-templates` | 新增一行 |
|
||||
| PUT | `/qc-material-month-templates/{id}` | 更新 |
|
||||
| DELETE | `/qc-material-month-templates/{id}` | 软删 |
|
||||
| POST | `/qc-material-month-templates/preview` | Body: `{ stockInDate }` → 展开行 + 默认编号 |
|
||||
| POST | `/qc-materials/batch-stock-in`(已有) | 确认入库;前端也可走等价 `/qc-material-batches/batch-stock-in` |
|
||||
|
||||
**确认入库包装(推荐实现方式):**
|
||||
|
||||
- 新增薄封装 `POST /qc-material-month-templates/confirm`:接收预览编辑后的明细列表 + `stockInDate`;服务端 `ensure_material` 后调用已有 `batch_stock_in`
|
||||
- 或:前端先调 ensure/创建物资 API 再调批量入库——**不推荐**(非原子)
|
||||
|
||||
本设计采用 **`confirm` 薄封装**,保证「建物资 + 入库」同事务。
|
||||
|
||||
**权限:** 与质检物料库入库相同(能入库即可维护模板与月初导入);不新增独立菜单。按钮可见性跟随现有入库能力。
|
||||
|
||||
---
|
||||
|
||||
## 6. 前端交互
|
||||
|
||||
页面:`web-admin/src/views/quality-inspection/qc-material/index.vue`(批次列表工具栏)。
|
||||
|
||||
- 工具栏顺序建议:已选 N 项 → **入库**(唯一 `type="primary"`)→ 批量出库 / 批量废弃(现有)→ **月初导入** → **维护月初模板**
|
||||
- 两个弹窗:对齐现有批量入库弹窗风格(`label-position="top"` / 表格明细 / 无 backdrop blur)
|
||||
- 维护弹窗:保存单行即时调 API,或底部统一保存——实现阶段优先 **单行保存 + 删除确认**,与现有 CRUD 习惯一致
|
||||
- 预览弹窗:金额随单价×数量联动规则对齐现有入库(未手工改金额则重算)
|
||||
- 按钮须带 Element Plus 图标(工程 UI 约定)
|
||||
|
||||
界面模式:对照批量入库弹窗(P 系列选型在实现计划中引用 `docs/web-admin-ui-pattern-index.md`)。
|
||||
|
||||
---
|
||||
|
||||
## 7. 校验与错误处理
|
||||
|
||||
| 场景 | 行为 |
|
||||
|------|------|
|
||||
| 模板为空点导入 | 警告提示,不打开预览 |
|
||||
| 模板行缺必填 | 保存模板时拦截 |
|
||||
| 关联物资已删除/停用 | 维护保存时警告;预览时标出该行,确认前须改绑或去掉该行 |
|
||||
| 待建物资编码已存在 | `ensure` 时绑定已有物资,不重复创建 |
|
||||
| 待建物资编码冲突名称不同 | 绑定已有物资并以已有主数据为准;备注中可不强制覆盖名称(避免静默改主数据) |
|
||||
| 入库编号重复 | 整单失败回滚,提示冲突编号 |
|
||||
| 数量 ≤ 0 / 缺必填批次字段 | 与现有批量入库一致,整单失败 |
|
||||
| 并发同日多用户预览 | 允许;提交时唯一校验兜底 |
|
||||
|
||||
`source_type`:确认入库产生的流水仍为现有手动入库类型(如 `manual_in`);若需区分「月初导入」,可新增 `month_template_in`——**本期默认仍用 `manual_in`**,避免报表分叉;若产品后续要统计,再加枚举。
|
||||
|
||||
---
|
||||
|
||||
## 8. 测试要点
|
||||
|
||||
- 模板 CRUD 租户隔离与软删
|
||||
- 空模板导入被拦截
|
||||
- 预览编号:同日多行连续;跨日日期切换后编号日期段正确
|
||||
- 关联已有物资导入成功,库存与流水正确
|
||||
- 仅填编码的新物资:首次导入自动创建并入库;第二次导入复用同一物资
|
||||
- 预览删行不影响模板
|
||||
- 人为制造编号冲突时整单回滚、库存不变
|
||||
- 停用物资关联行:确认被拒绝或强制用户处理
|
||||
|
||||
---
|
||||
|
||||
## 9. 组件边界(便于实现拆分)
|
||||
|
||||
| 单元 | 职责 | 依赖 |
|
||||
|------|------|------|
|
||||
| 模板 CRUD API/CRUD | 模板行持久化 | `BizQcMaterialMonthTemplate` |
|
||||
| preview 服务 | 展开 + 编号生成 | 模板表 + 已有 `stock_in_no` |
|
||||
| confirm 服务 | ensure 物资 + 调 `batch_stock_in` | `qc_material` + `qc_material_stock_batch` |
|
||||
| 前端维护弹窗 | 模板编辑 UX | 模板 API |
|
||||
| 前端导入弹窗 | 预览编辑 UX | preview + confirm API |
|
||||
|
||||
---
|
||||
|
||||
## 10. 开放问题(实现前可再定,有默认)
|
||||
|
||||
| 项 | 默认 |
|
||||
|----|------|
|
||||
| 预览是否允许临时加行 | 否(用普通批量入库) |
|
||||
| 流水 `source_type` | 继续 `manual_in` |
|
||||
| 单条入库是否同步默认编号 | 否(仅月初导入) |
|
||||
Reference in new issue
Block a user