zkxw/docs/superpowers/specs/2026-06-15-configured-reagent-design.md

配置试剂一次性配制功能设计

1. 需求概述

1.1 背景

• 现有系统中，「生产物料库」包含试剂和耗材两种基础物料类型
• 客户需要在生产过程中使用由试剂和耗材组合而成的配置试剂
• 现有「配置试剂目录」和「配制单」功能过于复杂（配方模板 + 多状态流程），需要简化

1.2 目标

将配置试剂的操作简化为一次性配制流程：

1. 选择已领用但未用完的试剂/耗材作为子物料
2. 输入配置试剂名称和产出数量
3. 提交即完成：子物料扣减 → 配置试剂入库 → 自动出库给当前操作人
4. 历史配制记录保留用于追溯

2. 功能设计

2.1 入口改造

位置：生产物料库 → 配制单 Tab

改造前	改造后
工具栏：新建配制单	工具栏：配置试剂
列表有状态（草稿/已完成/已作废）	列表无状态（仅用于追溯）
有编辑/确认配制等多步操作	一次性完成，无编辑功能
配置试剂目录 按钮	移除

2.2 新建配制弹窗

点击「配置试剂」按钮，弹出配制弹窗：

表单字段： | 字段 | 类型 | 说明 | |------|------|------| | 配置试剂名称 | 文本输入 | 必填，自由命名（如「75% 乙醇溶液」） | | 产出数量 | 数字输入 | 必填，正整数，默认 1 | | 子物料明细 | 物料选择表格 | 必填，至少选择一种子物料 |

子物料选择交互：

1. 点击「添加子物料」按钮，弹出物料选择对话框
2. 物料来源：已领用但未用完的试剂/耗材批次（不限领用人）
3. 选择物料后，自动代入该批次的最大可用数量，用户可手动调整
4. 每种子物料需填写「消耗数量」
5. 支持删除已添加的子物料

子物料表格字段： | 字段 | 说明 | |------|------| | 物料名称 | 只读，从领用批次带入 | | 物料类型 | 只读，试剂/耗材 | | 批次号 | 只读，来自领用记录 | | 可用数量 | 只读，该批次剩余可用数量 | | 消耗数量 | 可编辑，≤ 可用数量 |

2.3 提交逻辑

点击「提交」后，后端执行以下操作：

1. 校验：子物料消耗数量 ≤ 可用数量
2. 扣减子物料库存：
   • 遍历子物料明细，扣减对应领用批次的可用数量
3. 创建配置试剂库存：
   • 在 biz_production_material_stock 中创建 configured_reagent 类型记录
   • 库存数量 = 产出数量
4. 自动出库：
   • 创建出库记录，将配置试剂出库给当前操作人
5. 记录配制历史：
   • 在 biz_production_material_prep 中创建记录（status = 'completed'）
   • 记录配制人、配制时间、子物料明细、产出数量
6. 记录消耗明细：
   • 在「我的领用记录」中关联展示子物料的消耗

2.4 列表改造

列表字段（精简后）： | 字段 | 说明 | |------|------| | 序号 | 序号 | | 配制单号 | 自动生成 | | 配置试剂 | 配置试剂名称 | | 配制时间 | 配制完成时间 | | 产出数量 | 产出数量 | | 操作人 | 配制人姓名 |

操作列：

• 查看：查看配制详情（子物料明细、出库去向等）

移除：

• 状态列（已完成/草稿/已作废）
• 编辑、确认配制、删除操作按钮

2.5 我的物料领用记录

新增关联展示：

在「我的物料领用记录」中，为配置试剂配制场景增加消耗明细：

字段	说明
物料名称	子物料名称
类型	试剂/耗材
消耗数量	用于配制的消耗量
来源批次	领用批次号
消耗时间	配制时间
关联配制单	配制单号（点击可跳转查看）
产出配置试剂	配制产出的配置试剂名称

3. 数据模型

3.1 新增/修改表结构

biz_production_material_prep 表改造：

字段	类型	说明
id	VARCHAR(64)	主键
prep_no	VARCHAR(64)	配制单号
configured_material_name	VARCHAR(128)	配置试剂名称
output_qty	DECIMAL(10,2)	产出数量
status	VARCHAR(32)	固定为 'completed'
prep_time	DATETIME	配制时间
...	...	公共字段

biz_production_material_prep_line 表：

字段	类型	说明
id	VARCHAR(64)	主键
prep_id	VARCHAR(64)	关联配制单
material_id	VARCHAR(64)	子物料ID
material_name	VARCHAR(128)	子物料名称
material_type	VARCHAR(32)	试剂/耗材
batch_no	VARCHAR(64)	领用批次号
consumption_qty	DECIMAL(10,2)	消耗数量
...	...	公共字段

新增：biz_production_material_consumption 表（用于记录消耗明细，关联到领用记录）：

字段	类型	说明
id	VARCHAR(64)	主键
prep_id	VARCHAR(64)	关联配制单
source_receipt_id	VARCHAR(64)	领用记录ID
material_id	VARCHAR(64)	物料ID
consumption_qty	DECIMAL(10,2)	消耗数量
consumption_time	DATETIME	消耗时间
...	...	公共字段

3.2 API 设计

前端 API（web-admin/src/api/production-material.ts）：

方法	路径	说明
GET	/api/admin/production-material/prep	分页查询配制记录
POST	/api/admin/production-material/prep	新建配制（一次性完成）
GET	/api/admin/production-material/prep/{id}	查看配制详情
GET	/api/admin/production-material/prep/available-materials	获取可用子物料（已领用未用完）
GET	/api/admin/production-material/consumption	查询消耗明细（我的领用记录用）

后端路由（backend/app/api/production_material.py）：

方法	路径	说明
GET	/api/admin/production-material/prep	列表
POST	/api/admin/production-material/prep	创建配制
GET	/api/admin/production-material/prep/{prep_id}	详情
GET	/api/admin/production-material/prep/available-materials	可用子物料
GET	/api/admin/production-material/consumption	消耗明细

4. 前端改造

4.1 配制单 Tab 改造

文件：web-admin/src/views/production/production-material/ProductionMaterialPrepTab.vue

改动点：

1. 工具栏按钮：新建配制单 → 配置试剂
2. 列表移除：状态列、编辑/确认配制/删除按钮
3. 列表增加：操作人列
4. 新建弹窗：重构为一次性配制弹窗

4.2 新建配制弹窗设计

文件：新建 ProductionMaterialPrepDialog.vue

布局：弹窗 + 子物料选择表格

交互流程：

1. 输入配置试剂名称和产出数量
2. 点击「添加子物料」→ 弹出物料选择对话框
3. 选择物料 → 自动代入可用数量 → 用户可调整消耗量
4. 点击「提交」→ 调用 API → 成功后关闭弹窗并刷新列表

4.3 子物料选择对话框

文件：新建 MaterialBatchSelectDialog.vue

功能：

1. 列表展示：已领用未用完的物料批次
2. 支持搜索：物料名称、批次号
3. 选择后返回：物料信息 + 批次信息 + 可用数量

4.4 我的物料领用记录改造

文件：web-admin/src/views/production/my-production-task/index.vue

改动点：

1. 增加 Tab 或筛选项，区分「领用记录」和「消耗明细」
2. 消耗明细 Tab：展示子物料消耗记录，包含关联配制单号

5. 后端改造

5.1 新增 Schema

# backend/app/schemas/production_material.py

class PrepCreateBody(BaseModel):
    """一次性配制请求"""
    configured_material_name: str = Field(..., max_length=128, description="配置试剂名称")
    output_qty: Decimal = Field(..., gt=0, description="产出数量")
    lines: List[PrepLineCreate]  # 子物料明细

class PrepLineCreate(BaseModel):
    material_id: str = Field(..., description="物料ID")
    material_type: str = Field(..., description="物料类型")
    batch_no: str = Field(..., description="批次号")
    consumption_qty: Decimal = Field(..., gt=0, description="消耗数量")

class ConsumptionResp(BaseModel):
    """消耗明细响应"""
    id: str
    material_name: str
    material_type: str
    consumption_qty: Decimal
    batch_no: str
    consumption_time: datetime
    prep_no: str
    configured_material_name: str

5.2 CRUD 改造

文件：backend/app/crud/production_material.py

新增：

• create_prep_with_transaction()：一次性创建配制（包含库存扣减、入库、出库）
• get_available_materials()：查询可用子物料
• get_consumptions()：查询消耗明细

5.3 Service 层

文件：backend/app/services/production_material_service.py

新增配制业务逻辑：

1. 校验子物料可用数量
2. 扣减子物料库存（锁定批次）
3. 创建配置试剂库存
4. 创建出库记录
5. 创建配制记录
6. 创建消耗明细记录

6. 改动范围汇总

类别	文件	改动类型
后端模型	backend/app/models/production_material.py	新增消耗明细表
后端 Schema	backend/app/schemas/production_material.py	新增配制请求/响应 schema
后端 CRUD	backend/app/crud/production_material.py	新增配制相关 CRUD
后端 Service	backend/app/services/production_material_service.py	新增配制业务逻辑
后端 API	backend/app/api/production_material.py	新增/改造配制接口
前端 API	web-admin/src/api/production-material.ts	新增 API 方法
前端组件	ProductionMaterialPrepTab.vue	改造列表和工具栏
前端组件	ProductionMaterialPrepDialog.vue	新建配制弹窗
前端组件	MaterialBatchSelectDialog.vue	新建物料批次选择弹窗
前端页面	my-production-task/index.vue	改造领用记录增加消耗明细
路由	web-admin/src/router/modules/sqxp.ts	可能需要调整菜单配置

7. 实现计划

阶段一：后端基础（半天）

1. 新增 biz_production_material_consumption 表
2. 新增 Schema
3. 实现 CRUD 和 Service 层
4. 实现 API 接口

阶段二：前端基础（半天）

1. 新建物料批次选择弹窗
2. 新建配制弹窗
3. 改造配制单 Tab

阶段三：领用记录改造（半天）

1. 改造我的物料领用记录页面
2. 对接消耗明细 API

阶段四：联调测试（半天）

1. 前后端联调
2. 功能测试
3. UI 验收

预计总工期：2 天