zkxw/openspec/changes/configured-production-reagent/design.md

Context

生产物料库（biz_production_material*）已对齐质检物料库：试剂/耗材统一目录、批次、领用（manual_out）、工单 step_save（parent_usage_id）、盘点。用户确认 方案 A：配置试剂配制完成后 先入库存，工单使用前 再领用，步骤登记 不二次扣库。

已废弃的 biz_consumable_pack 仅为耗材模板，无配制实例与子物料领用追溯，不可复用。

Goals / Non-Goals

Goals:

• 第三类物料 material_type=configured_reagent，目录 + BOM（试剂+耗材子项）
• 配制单：记录每次配制实际消耗的子物料领用行；产出配置试剂批次
• 配置试剂走完整 批次 → 领用 → 工单 step_save 链路
• UI 落在【生产物料库】与【生产工单】执行态，风格对齐 Fresh Mint / QC 物料库

Non-Goals:

• 不合并质检物料库
• 不恢复耗材包
• 工艺库/工艺路线步骤引用配置试剂 BOM（二期）
• 配制现场「直用不入库」模式（方案 B/C）
• 盘点首版对配置试剂做特殊调账逻辑（沿用现有 Part A/B，不调账）

Decisions

Decision 1: 扩展 material_type，不另建独立库存域

选择：configured_reagent 作为 biz_production_material.material_type 第三值；批次/领用/盘点 复用 现有表与 CRUD 模式。

理由：与用户已接受的试剂/耗材统一库一致；避免第二套 batch/usage API。

替代：独立 biz_configured_reagent* 表系 — 拒绝，重复建设。

Decision 2: 配方与配制分离

实体	表	含义
配方 BOM	biz_production_material_formula	主数据：标准子物料与标准用量
配制单	biz_production_material_prep + _prep_line	业务单据：某次实际配制

理由：BOM 可版本化维护；配制单保留历史追溯（哪次用了哪些领用记录）。

配制单头关键字段：configured_material_id、prep_no、prep_time、output_qty、output_unit、batch_no、expire_date、stock_in_no（产出批次）、status（draft/completed/cancelled）。

配制行关键字段：component_material_id、component_material_type、component_material_code、requisition_usage_id（parent 领用记录）、actual_qty、usage_unit。

Decision 3: 库存流水 source_type

环节	change_type	source_type	库存影响
子物料配制消耗	use	prep_consume	子物料 不扣 batch；stock_before==stock_after；parent_usage_id 指向领用记录
配置试剂配制入库	in	prep_in	配置试剂 catalog stock_qty ↑；新建/更新 batch remaining_qty
配置试剂领用	use	manual_out	按 batch 扣减（与现网一致）
工单步骤登记	use	step_save	不扣库存；parent_usage_id 指向领用记录

理由：与 production-material-requisition Decision 5 一致；子物料已在领用时扣过 batch。

Decision 4: 配制完成事务边界

单次「确认配制」在一个 DB 事务内：

1. 校验每行 requisition_usage_id 有效、未重复、领用人为当前用户或允许范围
2. 写入 prep + prep_line
3. 对每个 prep_line 写 prep_consume usage
4. 创建配置试剂 stock_batch + prep_in usage
5. 更新配置试剂 stock_qty

失败则整体回滚。

Decision 5: 生产工单步骤 UI

选择：新增 biz_production_task_step_configured_reagent 子表（或等价命名），工单执行态增加 「配置试剂」Tab；领用下拉 GET /production-material-requisition-options?materialType=configured_reagent。

理由：与保留「试剂」「耗材」分列一致；避免塞入 reagent Tab 造成类型混淆。

保存仍调用统一 register_step_usage_from_requisition；目录内配置试剂 有实际用量时必须选领用记录。

Decision 6: 编码唯一性

沿用 租户 + material_type + material_code；允许配置试剂编码与试剂/耗材编码相同（类型不同）。

Decision 7: 偏离 BOM

配制时允许调整 实际用量；子物料行 必须 选领用记录。标准用量自 BOM 带出，仅作参考。

Risks / Trade-offs

风险	缓解
领用余量与子物料配制量不一致	首版仅记录 prep_consume 关联领用，不强制核销领用余额字段；二期可加「领用已配制量」汇总
配置试剂批次过期日规则不清	配制单必填 expire_date
成本单价	首版 unit_price/amount 可按子物料 prep_consume 金额汇总写入产出 batch
步骤子表增多	配置试剂 Tab 独立；工艺模板引用二期再做
与未完成 production-material-requisition 依赖	tasks 注明前置：统一物料库迁移已执行

Migration Plan

1. DDL：formula、prep、prep_line；字典项 configured_reagent；step 子表（若新建）
2. 部署后端 API + 前端
3. 无历史数据迁移（新能力）；旧耗材包保持废弃

回滚：隐藏菜单与 API；新表保留不删（软兼容）。

Open Questions

#	问题	默认
Q1	配制单是否独立菜单 vs 物料库 Tab	物料库第四 Tab「配制单」
Q2	prep_no 生成规则	租户内按日序号，如 PZ-YYYYMMDD-NNN
Q3	取消配制单是否回滚库存	首版仅 draft 可删；completed 不可撤销