zhangwenrui/material_manage_system
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
b75696f44a
material_manage_system/docs/superpowers/specs/2026-09-22-bom-management-design.md
文睿 张 b75696f44a docs: add initial BOM management design
2026-09-22 18:25:38 +08:00

15 KiB
Raw Blame History

BOM 管理第一版设计与初始规划

日期： 2026-09-22

状态： 初稿，待评审

适用范围： warehouse-mms 第一版 BOM 管理

1. 目标

为成品和半成品提供可追溯的多层 BOM 手工维护能力。第一版重点完成 BOM 的创建、草稿编辑、版本保留、生效与停用、结构合法性校验，以及单个 BOM 按指定数量递归展开的基础能力。

第一版不延伸到制造执行和库存业务，BOM 操作不会生成领料申请、扣减库存或创建出入库单据。

2. 第一版范围

2.1 包含

  • 通过树形界面手工维护 BOM。
  • 为成品或半成品建立多个 BOM 版本。
  • 创建首个 BOM 草稿。
  • 查看 BOM 列表、结构和历史版本。
  • 基于指定历史版本完整复制明细，生成新草稿。
  • 编辑、保存和删除草稿。
  • 生效草稿或停用当前生效版本。
  • 自动校验重复子项、自引用、循环引用、无效数量和最大层级。
  • 按指定产品数量递归展开 BOM，并汇总最底层物料需求。
  • 记录生效、自动停用和手工停用等关键状态变化的审计信息。
  • 第一版页面和接口仅允许超级管理员访问。

2.2 不包含

  • CSV 或 Excel 批量导入。
  • BOM 审批、驳回和申请流程。
  • 替代料。
  • 多 BOM 需求试算。
  • 制造订单。
  • 领料、退料和完工入库。
  • 库存预留、库存扣减和短缺计算。
  • 面向技术人员等其他角色的细分权限。

3. 核心业务规则

3.1 版本与状态

BOM 版本仅使用以下三个状态：

状态 含义 允许操作
draft 草稿 查看、编辑、保存、生效、删除
effective 已生效 查看、停用、基于该版本新建草稿
obsolete 已停用 查看、基于该版本新建草稿

规则如下：

  1. 同一父物料的版本号必须唯一。
  2. 同一父物料最多只能有一个已生效版本。
  3. 已生效版本不可直接修改。
  4. 修改已生效或已停用版本时，必须先完整复制所选版本，生成新的草稿版本。
  5. 新版本生效时，同一父物料原有的已生效版本自动转为已停用。
  6. 已停用版本不能恢复为已生效，但可以作为新版本的复制来源。
  7. 草稿可删除；已生效和已停用版本只保留、不物理删除。

3.2 父子关系

  • 每个 BOM 版本只保存该父物料的直接子物料。
  • 一个子物料可以被多个不同父物料引用。
  • 同一 BOM 版本、同一直接父节点下，相同子物料只能出现一行。
  • 同一物料可出现在整棵 BOM 树的不同父节点下。
  • 同一父节点下不同安装位置的相同物料合并数量，位置和用途写入备注。
  • 子项使用物料的基础单位，第一版不允许在 BOM 中选择其他单位或进行单位换算。

每个 BOM 子项至少记录：

  • 子物料。
  • 单位用量。
  • 基础单位。
  • 损耗率，默认 0%。
  • 备注。
  • 锁定的下层 BOM 版本，可为空。
  • 排序序号。

3.3 下层版本锁定

当子物料存在已生效 BOM 时，上层版本生效时锁定该子物料当时使用的下层 BOM 版本。下层 BOM 以后产生新版本，不改变已经生效的上层版本。

例如：

整机 A V3
  ├─ 外壳组件 V2
  └─ 电机组件 V1

即使电机组件 V2 后续生效，整机 A V3 仍按电机组件 V1 展开。整机需要采用新的电机组件版本时，应创建整机 A 的新草稿版本。

3.4 层级与循环保护

  • BOM 最多支持 20 层。
  • 父物料不能直接引用自身。
  • 禁止任意深度的循环引用，例如 A → B → C → A。
  • 添加子物料时，前端立即检查直接重复和自引用。
  • 保存草稿时，后端检查数量、重复、自引用、循环引用和最大层级。
  • 生效时，后端在同一事务中再次执行完整校验。
  • 递归展开时再次执行循环和最大深度保护，不能仅依赖保存时的校验。
  • 检测失败时返回完整问题路径，并让前端定位对应节点。

3.5 数量与损耗

  • 单位用量必须大于零。
  • 损耗率不得小于零。
  • 每层需求量按以下规则计算：
子项需求量 = 上层需求量 × 单位用量 ×（1 + 损耗率）
  • 递归计算过程中保留足够精度，最终结果按物料基础单位的精度规则向上取整。
  • 汇总结果按物料和基础单位合并相同的最底层物料。

4. 前端信息架构

左侧导航在“物料主数据”和“公司组织”之间增加独立大类：

物料主数据
  ├─ 物料
  └─ 基础配置

BOM 管理
  └─ BOM 维护

公司组织
  ├─ 组织管理
  ├─ 用户管理
  └─ 角色与权限

“多 BOM 需求试算”属于后续能力，第一版不展示空菜单。

4.1 BOM 维护

BOM 维护统一包含以下四类操作：

BOM 列表
  → 查询、查看结构、查看历史版本、发起新版本

新建 BOM
  → 为尚未建立 BOM 的父物料创建第一个草稿版本

编辑草稿
  → 编辑明细、保存草稿、删除草稿

状态操作
  → 生效或停用

结构校验不作为独立按钮或菜单。系统在添加、保存和生效过程中自动校验。

树形结构维护是编辑页面的交互方式，不作为独立功能入口。

4.2 BOM 列表

列表以父物料为主行，避免历史版本过多导致列表膨胀：

父项物料   当前版本   状态     草稿版本   操作
整机 A     V2         已生效   V3         查看结构｜编辑草稿｜历史版本
电机组件   V1         已生效   无         查看结构｜新建版本｜历史版本

历史版本在展开区域或抽屉中显示：

整机 A
  ├─ V3  草稿
  ├─ V2  已生效
  └─ V1  已停用

列表至少支持：

  • 按父项物料编码或名称查询。
  • 按是否存在草稿、是否存在生效版本筛选。
  • 查看当前或历史版本结构。
  • 编辑已有草稿。
  • 从指定历史版本复制并发起新版本。
  • 执行当前状态允许的状态操作。

“查看结构”页面默认按父物料数量 1 展示完整层级。用户可以临时修改查看数量，页面随即递归计算各层需求，并展示最底层物料汇总。该能力只计算当前一个 BOM 版本，不单独设置菜单，也不保存试算记录。

查看数量：10

[层级结构]
整机 A × 10
  ├─ 外壳组件 × 10
  │  └─ 螺丝 × 80
  └─ 电机组件 × 20
     └─ 螺丝 × 80

[底层物料汇总]
螺丝 × 160

同时选择多个 BOM 并合并需求，属于后续“多 BOM 需求试算”，不在第一版范围内。

4.3 新建 BOM

新建 BOM 只面向尚未建立 BOM 的成品或半成品。页面包含：

  • 父项物料选择。
  • 初始版本号。
  • 直接子物料树或列表。
  • 子项单位用量、基础单位、损耗率和备注。
  • 保存草稿。

已存在 BOM 的父物料不能再次走“新建 BOM”，应从列表或历史版本选择来源并执行“新建版本”。

4.4 编辑草稿

编辑页采用左侧结构树、右侧节点明细的布局：

┌───────────────────────┬──────────────────────────────┐
│ BOM 结构树            │ 当前节点明细                 │
│                       │                              │
│ ▼ 整机 A              │ 子物料：电机组件             │
│   ├─ 外壳组件 × 1     │ 单位用量：2                  │
│   ├─ 电机组件 × 2     │ 基础单位：套                 │
│   └─ 控制箱 × 1       │ 损耗率：0%                   │
│                       │ 备注：安装位置说明           │
│ [+ 添加子物料]        │                              │
└───────────────────────┴──────────────────────────────┘

编辑草稿允许：

  • 添加、修改、删除和排序直接子物料。
  • 修改用量、损耗率和备注。
  • 保存草稿。
  • 删除整个草稿。

对于树中引用的下层 BOM，当前页面只展示其锁定版本和结构，并提供跳转到该物料 BOM 的入口；不在上层 BOM 中直接修改下层 BOM。

4.5 新建版本

“新建版本”从 BOM 列表或历史版本发起，不属于编辑草稿内部操作：

选择一个历史版本
        ↓
完整复制该版本的 BOM 明细
        ↓
生成新的草稿版本
        ↓
进入草稿编辑页

每次只复制一个明确选中的来源版本，不复制该父物料的全部历史版本。

4.6 状态操作

页面根据状态显示操作：

草稿
  ├─ 查看
  ├─ 编辑草稿
  ├─ 生效
  └─ 删除草稿

已生效
  ├─ 查看
  ├─ 停用
  └─ 新建版本

已停用
  ├─ 查看
  └─ 新建版本

生效和停用都需要二次确认。新版本生效时，应明确提示原生效版本将被自动停用。

5. 数据模型建议

第一版建议使用三个核心表，审计复用系统现有日志能力或补充独立审计记录。

5.1 bom_headers

代表某个父物料的 BOM 主体，而不是具体版本。

建议字段：

  • id
  • organization_id
  • parent_material_id
  • created_at
  • updated_at

约束：同一组织下 parent_material_id 唯一。

5.2 bom_versions

建议字段：

  • id
  • organization_id
  • bom_header_id
  • version
  • status
  • source_version_id，记录复制来源，可为空。
  • effective_at
  • obsoleted_at
  • created_by
  • updated_by
  • created_at
  • updated_at

约束：

  • 同一 bom_header_id 下版本号唯一。
  • 通过事务和数据库约束保证同一 bom_header_id 最多一个 effective 版本。

5.3 bom_items

建议字段：

  • id
  • organization_id
  • bom_version_id
  • child_material_id
  • quantity
  • unit_id
  • loss_rate
  • remark
  • locked_child_version_id
  • sort_order
  • created_at
  • updated_at

约束：同一 bom_version_id 下 child_material_id 唯一。

树形层级不直接存成固定层级字段。系统通过各父物料 BOM 版本之间的引用递归组成完整树，因此支持 10 层或 20 层时不需要改变表结构。

6. 后端职责与接口草案

后端延续现有 Go 分层结构：

model
  → 定义 BOM、版本、子项和展开结果

repository
  → 负责数据库查询、事务和状态更新

service
  → 负责版本规则、复制、校验、生效、停用和递归展开

handler
  → 负责 HTTP 参数、超级管理员鉴权和统一响应

接口草案：

方法 路径 用途
GET /api/boms 查询 BOM 主列表
POST /api/boms 创建首个草稿版本
GET /api/boms/:id 查看 BOM 主体及当前版本摘要
GET /api/boms/:id/versions 查看历史版本
GET /api/bom-versions/:versionId 查看指定版本和结构
PUT /api/bom-versions/:versionId 保存草稿
DELETE /api/bom-versions/:versionId 删除草稿
POST /api/bom-versions/:versionId/copy 从指定版本生成新草稿
POST /api/bom-versions/:versionId/effective 生效草稿
POST /api/bom-versions/:versionId/obsolete 停用生效版本
POST /api/bom-versions/:versionId/explode 按指定数量递归展开单个 BOM

接口命名在实施计划阶段可按现有路由风格进一步统一，但业务边界不应改变。

7. 自动校验与错误反馈

前端校验用于即时反馈，后端校验是最终可信规则。

时机 校验内容
选择子物料 当前父节点重复、自引用、物料状态
保存草稿 数量、损耗率、基础单位、重复、自引用、循环、20 层限制
生效 完整重复执行保存校验，并验证锁定的下层版本
递归展开 循环保护、20 层限制、版本引用完整性

错误信息需要包含：

  • 错误类型。
  • 父物料和子物料编码。
  • 完整问题路径。
  • 用户可执行的修改建议。

示例：

无法保存：检测到循环引用。
问题路径：整机 A → 电机组件 → 控制模块 → 整机 A。
请删除导致循环的子物料关系。

8. 权限与审计

  • 第一版菜单、页面和全部 BOM 接口仅超级管理员可访问。
  • 不能只通过前端隐藏菜单实现权限控制，后端接口必须再次鉴权。
  • 预留独立 BOM 权限边界，后续权限系统完善后再拆分查看、维护和状态操作权限。
  • 创建、复制、生效、自动停用、手工停用和删除草稿记录操作者、时间、目标版本和结果。

9. 测试与验收重点

9.1 后端

  • 创建首个草稿和保存明细。
  • 同一父物料版本号重复。
  • 同一版本直接子项重复。
  • 父项直接引用自身。
  • 三层及更深循环引用，并返回完整路径。
  • 第 20 层允许，第 21 层拒绝。
  • 零数量、负数量和负损耗率拒绝。
  • 生效版本禁止修改和删除。
  • 新版本生效时旧版本自动停用，且事务保持一致。
  • 从指定版本完整复制为新草稿。
  • 下层版本锁定后不随新版本变化。
  • 多层需求数量、损耗率和底层物料汇总正确。
  • 非超级管理员访问全部 BOM 接口均被拒绝。
  • 不同组织的数据不能相互读取或引用。

9.2 前端

  • 导航位置、超级管理员可见性和路由保护。
  • 列表查询、主行展示和历史版本展开。
  • 新建 BOM 时只允许选择尚未建立 BOM 的成品或半成品。
  • 草稿可编辑，已生效和已停用版本只读。
  • 添加重复子项和自引用时立即提示。
  • 后端返回循环或深度错误时定位并标记问题节点。
  • 生效、自动停用、手工停用和删除草稿具有明确确认提示。
  • 从指定历史版本创建草稿后，明细完整复制且可继续编辑。

10. 建议实施顺序

  1. 建立 BOM 数据表、模型和仓储层。
  2. 实现草稿创建、查询、编辑和删除。
  3. 实现复制新版本及版本列表。
  4. 实现结构校验、20 层限制和完整循环路径反馈。
  5. 实现生效、自动停用和手工停用事务。
  6. 实现前端导航、BOM 列表和历史版本展示。
  7. 实现新建及草稿树形编辑页面。
  8. 实现单 BOM 递归展开及底层物料汇总能力。
  9. 补齐权限、审计、自动化测试和真实数据副本验收。

11. 后续阶段

第一版稳定后再分别设计和实现：

  1. 多 BOM 需求试算，并在 BOM 管理 下增加独立菜单。
  2. CSV 层级导入和错误报告。
  3. 替代料管理。
  4. 面向技术人员等角色的细分权限。
  5. 制造订单、领料、完工和库存联动。