285 lines
11 KiB
Markdown
285 lines
11 KiB
Markdown
# 出库放行审核 · 出库物料准备(台账)设计
|
||
|
||
> 日期: 2026-05-27
|
||
> 状态: 待审阅
|
||
> 父模块: 中试服务管理 → 出库放行审核
|
||
> 关联: `openspec/changes/outbound-release-review`、方案 A(独立弹窗 + 子表)
|
||
> **库存策略(已确认)**: **台账模式 — 出库物料准备界面仅记录,不联动库存**
|
||
|
||
## 1. 背景与目标
|
||
|
||
### 现状
|
||
|
||
- 出库放行审核列表/查看/审核已实现,审核记录存于 `biz_outbound_release_review`。
|
||
- 每条输注计划尚无「出库物料准备」维护入口。
|
||
- 细胞产品库、质检物料库已有独立库存/状态管理(生产任务、质检任务等场景会真实扣减)。
|
||
|
||
### 目标
|
||
|
||
针对**每条输注计划**,提供「**出库物料准备**」界面,用于登记拟出库内容(台账),**保存时不改变细胞产品状态、不扣质检物料库存**:
|
||
|
||
| 区块 | 数据来源 | 保存行为 |
|
||
|------|----------|----------|
|
||
| 出库细胞 | 细胞产品库勾选 | 写入关联 ID + 字段快照,**不改** `biz_cell_product` |
|
||
| 使用的物料 | 质检物料库勾选 + 用量 | 写入关联 ID + 用量 + 快照,**不扣** `stock_qty` |
|
||
| 其他纸质材料 | 附件上传 | 仅存 URL |
|
||
|
||
### 非目标
|
||
|
||
- **不在本界面做真实出库**(不改细胞状态、不释库位、不写 `biz_qc_material_usage`)。
|
||
- 不与「交付物料清单」(`biz_pilot_delivery_material`)合并或自动同步。
|
||
- 批量审核弹窗不涉及出库物料(仍按条维护)。
|
||
- 真实出库若后续需要,另开能力/节点实现(本 spec 不覆盖)。
|
||
|
||
## 2. 架构决策
|
||
|
||
| 项 | 决策 |
|
||
|----|------|
|
||
| UI 定位 | 「出库物料**准备**」— 台账登记,非库存事务 |
|
||
| UI | 列表操作列「出库物料」→ `OutboundReleaseMaterialDialog.vue` |
|
||
| 数据 | 1 主表 + 2 子表;纸质附件放主表 |
|
||
| 保存语义 | **全量替换**:软删旧子表行 → 写入新行 + 主数据快照 |
|
||
| 库存 | **零联动**;前端可展示当前库存/状态作参考,保存时不校验库存是否足够 |
|
||
| 复杂度 | 无 revert/apply、无 `qc_material_usage` 扩展、无库位占用变更 |
|
||
|
||
## 3. 数据库设计
|
||
|
||
SQL 文件:`docs/sql/outbound_release_material.sql`
|
||
|
||
### 3.1 `biz_outbound_release_material`(主表,1:1 输注计划)
|
||
|
||
```sql
|
||
CREATE TABLE `biz_outbound_release_material` (
|
||
`id` varchar(64) NOT NULL COMMENT '主键ID',
|
||
`infusion_schedule_id` varchar(64) NOT NULL COMMENT '输注计划ID',
|
||
`paper_attachments` varchar(4000) DEFAULT NULL COMMENT '其他纸质材料附件(逗号分隔URL)',
|
||
`tenant_no` varchar(64) NOT NULL DEFAULT 'zkxw',
|
||
`order_num` int(11) DEFAULT NULL,
|
||
`remark` varchar(512) DEFAULT NULL,
|
||
`create_by` varchar(64) DEFAULT NULL,
|
||
`create_dept_id` varchar(64) NOT NULL DEFAULT '',
|
||
`create_time` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP,
|
||
`update_by` varchar(64) DEFAULT NULL,
|
||
`update_time` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
|
||
`del_flag` tinyint(4) NOT NULL DEFAULT 0,
|
||
PRIMARY KEY (`id`),
|
||
UNIQUE KEY `uk_orm_schedule` (`infusion_schedule_id`, `del_flag`),
|
||
KEY `idx_orm_tenant` (`tenant_no`, `del_flag`)
|
||
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='出库放行-出库物料准备主表';
|
||
```
|
||
|
||
### 3.2 `biz_outbound_release_cell`(出库细胞行)
|
||
|
||
```sql
|
||
CREATE TABLE `biz_outbound_release_cell` (
|
||
`id` varchar(64) NOT NULL,
|
||
`material_id` varchar(64) NOT NULL COMMENT '关联 biz_outbound_release_material.id',
|
||
`infusion_schedule_id` varchar(64) NOT NULL COMMENT '冗余,便于查询',
|
||
`cell_product_id` varchar(64) NOT NULL COMMENT '细胞产品ID',
|
||
`product_code` varchar(128) DEFAULT NULL COMMENT '保存时快照',
|
||
`product_name` varchar(200) DEFAULT NULL,
|
||
`product_type_name` varchar(100) DEFAULT NULL,
|
||
`spec_name` varchar(100) DEFAULT NULL,
|
||
`passage` varchar(32) DEFAULT NULL,
|
||
`batch_no` varchar(64) DEFAULT NULL,
|
||
`storage_slot_name` varchar(200) DEFAULT NULL,
|
||
`product_status` varchar(32) DEFAULT NULL COMMENT '保存时状态快照(只读展示)',
|
||
`tenant_no` varchar(64) NOT NULL DEFAULT 'zkxw',
|
||
`order_num` int(11) DEFAULT NULL,
|
||
`remark` varchar(512) DEFAULT NULL,
|
||
`create_by` varchar(64) DEFAULT NULL,
|
||
`create_dept_id` varchar(64) NOT NULL DEFAULT '',
|
||
`create_time` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP,
|
||
`update_by` varchar(64) DEFAULT NULL,
|
||
`update_time` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
|
||
`del_flag` tinyint(4) NOT NULL DEFAULT 0,
|
||
PRIMARY KEY (`id`),
|
||
UNIQUE KEY `uk_orc_schedule_product` (`infusion_schedule_id`, `cell_product_id`, `del_flag`),
|
||
KEY `idx_orc_product` (`cell_product_id`, `del_flag`),
|
||
KEY `idx_orc_material` (`material_id`, `del_flag`)
|
||
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='出库放行-出库细胞(台账)';
|
||
```
|
||
|
||
> 不需要 `product_status_before` / `storage_slot_id` 回滚字段。
|
||
|
||
### 3.3 `biz_outbound_release_qc_material`(质检物料行)
|
||
|
||
```sql
|
||
CREATE TABLE `biz_outbound_release_qc_material` (
|
||
`id` varchar(64) NOT NULL,
|
||
`material_id` varchar(64) NOT NULL COMMENT '关联 biz_outbound_release_material.id',
|
||
`infusion_schedule_id` varchar(64) NOT NULL,
|
||
`qc_material_id` varchar(64) NOT NULL,
|
||
`qty` decimal(18,4) NOT NULL COMMENT '计划用量(台账)',
|
||
`material_code` varchar(64) DEFAULT NULL,
|
||
`material_name` varchar(200) DEFAULT NULL,
|
||
`spec_model` varchar(200) DEFAULT NULL,
|
||
`unit` varchar(32) DEFAULT NULL,
|
||
`tenant_no` varchar(64) NOT NULL DEFAULT 'zkxw',
|
||
`order_num` int(11) DEFAULT NULL,
|
||
`remark` varchar(512) DEFAULT NULL,
|
||
`create_by` varchar(64) DEFAULT NULL,
|
||
`create_dept_id` varchar(64) NOT NULL DEFAULT '',
|
||
`create_time` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP,
|
||
`update_by` varchar(64) DEFAULT NULL,
|
||
`update_time` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
|
||
`del_flag` tinyint(4) NOT NULL DEFAULT 0,
|
||
PRIMARY KEY (`id`),
|
||
UNIQUE KEY `uk_orqm_schedule_material` (`infusion_schedule_id`, `qc_material_id`, `del_flag`),
|
||
KEY `idx_orqm_material` (`material_id`, `del_flag`)
|
||
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='出库放行-质检物料(台账)';
|
||
```
|
||
|
||
> **不**关联 `biz_qc_material_usage`;**不**扩展 `source_type`。
|
||
|
||
## 4. 核心业务流程
|
||
|
||
### 4.1 保存出库物料准备(单事务)
|
||
|
||
```
|
||
save_outbound_release_material(schedule_id, payload):
|
||
1. 校验输注计划存在 + 租户 + 数据权限
|
||
2. 校验 payload:
|
||
- cells 内 cell_product_id 不重复
|
||
- qcMaterials 内 material_id 不重复
|
||
- qty > 0
|
||
- 关联主数据存在且未软删(产品/物料)
|
||
3. upsert 主表(paper_attachments、remark)
|
||
4. 软删本 schedule 下旧 cell / qc_material 子行
|
||
5. 对每个 cell_product_id:读主数据 → 写快照 → insert 子行
|
||
6. 对每个 qc_material + qty:读主数据 → 写快照 → insert 子行
|
||
7. db.commit()
|
||
```
|
||
|
||
**明确不做:**
|
||
|
||
- 不调用 `cell_product.update` / 不改 `product_status`
|
||
- 不调用 `occupancy_svc.remove_by_item`
|
||
- 不调用 `qc_material_usage.deduct_*`
|
||
- 不校验质检库存是否 ≥ 用量(用量仅作计划登记)
|
||
|
||
### 4.2 编辑
|
||
|
||
- 再次保存 = 全量替换子表(软删旧行 + 插入新行)。
|
||
- 无库存回滚逻辑。
|
||
|
||
### 4.3 业务校验(台账级)
|
||
|
||
| 规则 | 说明 |
|
||
|------|------|
|
||
| 同计划细胞不重复 | 同一 `infusion_schedule_id` 下 `cell_product_id` 唯一 |
|
||
| 同计划物料不重复 | 同一 schedule 下 `qc_material_id` 唯一 |
|
||
| 跨计划可重复引用 | 不同输注计划可登记同一细胞/物料(台账互不排斥) |
|
||
| 主数据存在性 | 保存时产品/物料须存在;已软删的主数据不允许新增引用 |
|
||
| 细胞状态 | **不限制**可选状态;选择器展示状态供人判断,保存时不拦截 |
|
||
|
||
### 4.4 细胞产品选择范围
|
||
|
||
- 从细胞产品库分页/搜索勾选(复用 `TaskInputEnhancedTable` 选择弹窗模式)。
|
||
- 列表展示编码、名称、类型、代次、储物格、**当前状态**(参考信息)。
|
||
- **可选增强(v1.1)**:默认筛选与本计划出库生产工单产出相关的产品,仍允许从全库补选。
|
||
|
||
## 5. API 设计
|
||
|
||
前缀:`/web/admin/pilot-release-reviews`
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| GET | `/{scheduleId}/outbound-materials` | 获取出库物料准备(主表 + 细胞行 + 质检行) |
|
||
| PUT | `/{scheduleId}/outbound-materials` | 全量保存(仅写台账) |
|
||
|
||
**PUT Body:**
|
||
|
||
```json
|
||
{
|
||
"paperAttachments": "url1,url2",
|
||
"remark": "",
|
||
"cells": [{ "cellProductId": "..." }],
|
||
"qcMaterials": [{ "materialId": "...", "qty": 1.5, "remark": "" }]
|
||
}
|
||
```
|
||
|
||
- `cells` / `qcMaterials` 可为空数组。
|
||
- `GET .../detail` 响应增加 `outboundMaterial` 域(查看弹窗只读)。
|
||
|
||
## 6. 前端设计
|
||
|
||
### 6.1 模式
|
||
|
||
- **P22** 审核列表 + 子表编辑弹窗。
|
||
- 弹窗标题建议:**「出库物料准备」**(与「真实出库」区分)。
|
||
- 参考:
|
||
- 细胞选择:`TaskInputEnhancedTable.vue`
|
||
- 质检物料:`qc-task/index.vue` 物料使用区(**去掉库存不足拦截**)
|
||
- 纸质附件:`OutboundReleaseReviewDialog.vue` 卡片上传
|
||
|
||
### 6.2 页面改动
|
||
|
||
| 文件 | 改动 |
|
||
|------|------|
|
||
| `outbound-release-review/index.vue` | 操作列「出库物料」 |
|
||
| `OutboundReleaseMaterialDialog.vue` | **新建** |
|
||
| `OutboundReleaseViewDialog.vue` | Section「出库物料准备」只读 |
|
||
| `api/outbound-release-review.ts` | fetch/save API |
|
||
|
||
### 6.3 交互规则
|
||
|
||
- 保存成功:「出库物料准备已保存」(**不提**库存更新)。
|
||
- 质检物料表可展示「当前库存」列作参考,**不**因库存不足阻止保存。
|
||
- 删除行:前端移除,点保存后生效。
|
||
- 操作列宽度:约 260px(查看 / 审核 / 出库物料)。
|
||
|
||
## 7. 后端模块划分
|
||
|
||
| 文件 | 职责 |
|
||
|------|------|
|
||
| `app/crud/outbound_release_material.py` | 查询、全量 save、主数据快照 |
|
||
| `app/schemas/outbound_release_material.py` | Pydantic |
|
||
| `app/api/outbound_release_review.py` | 两个端点 |
|
||
| `app/models/models.py` | 三个 ORM 模型 |
|
||
|
||
**不修改:** `qc_material_usage.py`、`cell_product.py` 库存/状态逻辑。
|
||
|
||
## 8. 错误处理
|
||
|
||
| 场景 | HTTP | 说明 |
|
||
|------|------|------|
|
||
| 细胞/物料不存在 | 400 | ID 无效或已删除 |
|
||
| 同计划重复勾选 | 400 | 同一产品/物料不可重复 |
|
||
| qty ≤ 0 | 400 | 用量须大于 0 |
|
||
| 输注计划不存在 | 404 | — |
|
||
|
||
## 9. 测试要点
|
||
|
||
1. 保存后:`biz_cell_product` 状态/库位**不变**;`biz_qc_material.stock_qty` **不变**。
|
||
2. 编辑替换细胞/物料行:仅子表与快照更新。
|
||
3. 两计划登记同一细胞:均允许保存(台账)。
|
||
4. 查看弹窗正确展示快照与附件。
|
||
5. 主数据后续变更:已保存台账仍显示保存时快照。
|
||
|
||
## 10. OpenSpec 增量
|
||
|
||
- `outbound-release-material-api`: GET/PUT outbound-materials(台账 CRUD)
|
||
- `outbound-release-material-ui`: 出库物料准备弹窗 + 查看 Section
|
||
|
||
## 11. 工作量估算
|
||
|
||
| 项 | 人天 |
|
||
|----|------|
|
||
| SQL + Model + CRUD | 1.0 |
|
||
| API + 详情聚合 | 0.5 |
|
||
| 前端弹窗 + 查看 | 1.5 |
|
||
| 联调 | 0.5 |
|
||
| **合计** | **~3.5** |
|
||
|
||
---
|
||
|
||
## 附录:策略变更记录
|
||
|
||
| 版本 | 策略 | 说明 |
|
||
|------|------|------|
|
||
| v0(讨论稿) | B 真实出库 | 保存时改状态 + 扣库存 + 回滚 |
|
||
| **v1(当前)** | **台账模式** | 出库物料**准备**界面仅记录;与交付清单类似,不联动库存 |
|
||
|
||
若后续需要在「审核通过」或独立「确认出库」节点做真实出库,应新建 spec,与本台账表通过 `infusion_schedule_id` 衔接,避免在本界面混入库存事务。
|