zhangwenrui/material_manage_system

Fork 0

文睿张 6ac9f2cb3c 新增伙伴业务分类，优化物料编辑并整理数据库脚本

2026-10-08 11:54:51 +08:00

27 KiB

Raw Permalink Blame History

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

日期： 2026-09-22

状态： 初稿，待评审

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

1. 目标

为成品和半成品提供可追溯的多层 BOM 手工维护能力。第一版重点完成 BOM 的创建、草稿编辑、版本保留、生效与停用、结构合法性校验，以及按父项数量 1 查看单个 BOM 版本的完整层级。

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

2. 第一版范围

2.1 包含

通过树形界面手工维护 BOM。
为成品或半成品建立多个 BOM 版本。
创建首个 BOM 草稿。
从物料列表进入指定物料的 BOM 页面，查看结构和历史版本。
新建后续版本时，可基于指定历史版本完整复制明细，或创建空白草稿。
编辑、保存和删除草稿。
生效草稿或停用指定的生效版本。
自动校验重复子项、自引用、循环引用、无效数量和最大层级。
按父项数量 1 查看单个 BOM 版本的完整层级和各层用量。
记录生效和停用等关键状态变化的审计信息。
第一版页面和接口仅允许超级管理员访问。

2.2 不包含

CSV 或 Excel 批量导入。
BOM 审批、驳回和申请流程。
替代料。
多 BOM 需求试算。
修改查看数量、按计划数量计算需求，以及汇总最底层物料需求。
制造订单。
领料、退料和完工入库。
库存预留、库存扣减和短缺计算。
面向技术人员等其他角色的细分权限。

3. 核心业务规则

3.1 版本与状态

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

状态	含义	允许操作
`draft`	草稿	查看、编辑、保存、生效、删除
`effective`	可用	查看、被新 BOM 选择、停用、基于该版本新建草稿
`obsolete`	已停用	查看历史、基于该版本新建草稿；不能用于新 BOM

规则如下：

同一父物料的版本号必须唯一。
同一父物料可以同时存在多个 effective（可用）版本。
默认版本是尚未停用且最近一次生效的版本，按生效时间排序；同一时间时按版本 ID 确定唯一结果。停用默认版本后，剩余可用版本中最近生效的版本成为默认版本；全部停用时无默认版本。
新版本生效不改变其他可用版本的状态。非默认的可用版本仍可被新建的上层 BOM 明确选择。
可用版本不可直接修改。变更结构时应创建新的草稿版本，可复制指定旧版，也可从空白开始。
已停用版本不能恢复为可用，但可以作为新版本的复制来源；它不能被新建的上层 BOM 选用。
草稿可删除；可用和已停用版本只保留、不物理删除。

3.2 父子关系

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

每个 BOM 子项至少记录：

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

3.3 下层版本锁定

当子物料存在可用 BOM 时，编辑上层草稿可选择其任意可用版本；页面默认预选最近一次生效的版本。上层版本生效时，锁定用户确认的下层 BOM 版本。下层 BOM 以后产生新版本，不改变已经生效的上层版本。

例如：

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

即使电机组件 V2 后续生效，整机 A V3 仍按电机组件 V1 展开。电机组件 V1 即使后来停用，整机 A V3 的历史结构仍可查看和展开；但新建上层版本时不能再选择已停用的电机组件 V1。整机需要采用其他下层版本时，应创建整机 A 的新草稿版本。

3.4 层级与循环保护

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

3.5 数量与损耗

单位用量必须大于零。
损耗率不得小于零。
每层需求量按以下规则计算：

子项需求量 = 上层需求量 × 单位用量 ×（1 + 损耗率）

查看结构时，父项数量固定为 1，按上述公式逐层显示用量，计算过程中保留足够精度。
第一版不输入计划数量，也不汇总不同分支中的最底层物料；相关计算留给后续“多 BOM 需求试算”。

4. 前端信息架构

左侧导航沿用“物料主数据”入口。BOM 维护由物料列表逐行进入，不增加独立的“BOM 管理”菜单：

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

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

日志记录
  ├─ 物料变更日志
  └─ BOM 记录

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

现有独立菜单“日志记录”改为左侧导航大类。现有物料日志页面归入“物料变更日志”，BOM 事件展示在新建的“BOM 记录”子页面。原有 /logs 地址应保持可访问，并跳转到物料变更日志页面，避免旧链接失效。

4.1 物料列表中的 BOM 入口

现有物料列表继续负责搜索物料、查看详情、编辑和作废。在符合 BOM 父物料条件的成品或半成品行增加明显的“BOM”按钮，放在独立的窄列中，避免挤占现有操作列。点击后进入该物料的独立 BOM 页面。现有“物料详情”弹窗保持原有用途；BOM 页面显示当前物料的编码、名称、规格、基础单位和状态，并提供“返回物料列表”。已作废物料若已有 BOM，仍可进入页面查看历史版本，但不能新建或生效版本。

物料主数据 → 物料列表 → 选择整机 A 所在行的 [BOM]
                         ↓
                    整机 A 的 BOM 页面

新建 BOM
  → 为当前物料创建第一个草稿版本

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

状态操作
  → 生效或停用

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

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

4.2 单个物料的 BOM 页面

页面只管理入口物料的 BOM，不再建立与物料列表重复的 BOM 总列表。顶部始终显示版本选择框：已有版本时列出该物料的全部草稿、可用和已停用版本，并在选项中标明状态和默认版本；选项按创建时间从新到旧排列。首次进入时优先选中默认可用版本，没有可用版本时选中最近创建的版本。没有任何版本时，版本框显示“无”且不可展开，旁边提供“新建 BOM”按钮：

← 返回物料列表      整机 A · A-001      有效

BOM 版本：[V2 · 可用·默认 ▼]   [新建版本]
当前版本状态：可用            [停用]

▼ 整机 A × 1
  ├─ 外壳组件 × 1
  └─ 电机组件 × 2

选择草稿版本时，操作按钮显示在同一状态行的位置：

← 返回物料列表      整机 A · A-001      有效

BOM 版本：[V3 · 草稿 ▼]       [新建版本]
当前版本状态：草稿           [编辑] [生效] [删除草稿]

▼ 整机 A × 1
  ├─ 外壳组件 × 1
  └─ 电机组件 × 2

无版本时沿用相同布局：

← 返回物料列表      整机 A · A-001      有效

BOM 版本：[无]              [新建 BOM]

暂无 BOM 结构

创建首个草稿后，版本选择框自动选中该草稿并显示其结构。

切换版本后，页面直接加载该版本的完整结构和节点明细，不再要求点击“查看结构”。选中草稿时，顶部状态行显示“编辑”“生效”“删除草稿”；点击“编辑”才进入草稿的树形编辑状态。选中可用版本时，该位置显示“停用”；已停用版本只读，不显示编辑、停用或生效按钮。切换前若草稿存在尚未保存的修改，应先提示保存或放弃，避免丢失内容。

物料列表及该物料 BOM 页面共同支持：

在现有物料列表按编码或名称查找父物料，并从该行进入 BOM 页面。
通过版本选择框查看当前或历史版本结构。
编辑已有草稿。
发起新版本，并选择复制旧版或空白创建。
执行当前状态允许的状态操作。

建议页面路由为 /materials/:materialId/bom。从树中的子物料进入其 BOM 时，也使用同一路由并传入该子物料 ID。物料详情弹窗无需承载多层 BOM 编辑。

版本选择框下方的结构区域固定按父物料数量 1 展示所选 BOM 版本的完整层级和各层用量，不提供数量输入或最底层物料汇总。

整机 A × 1
  ├─ 外壳组件 × 1
  │  └─ 螺丝 × 8
  └─ 电机组件 × 2
     └─ 螺丝 × 8

按计划数量计算、同时选择多个 BOM 并合并相同物料需求，属于后续独立页面“多 BOM 需求试算”。

4.3 新建 BOM

新建 BOM 只面向尚未建立 BOM 的成品或半成品。入口物料已由物料列表确定，页面包含：

当前父物料信息，只读展示，不再重复选择。
初始版本号。
直接子物料树或列表。
子项单位用量、基础单位、损耗率和备注。
保存草稿。

已存在 BOM 的父物料不能再次走“新建 BOM”，应从该物料的 BOM 页面点击“新建版本”，再选择复制旧版或空白创建。

4.4 编辑草稿

编辑页采用左侧结构树、右侧节点明细的布局。点击任意物料节点，右侧先以只读方式展示该节点的物料信息、用量、损耗率、备注和下层 BOM 版本：

┌────────────────────────┬─────────────────────────────┐
│ BOM 结构树             │ 当前节点明细                │
│ ▼ 整机 A               │ 电机组件                    │
│   ├─ 外壳组件 × 1      │ 物料编码：DJ-001            │
│   ├─ 电机组件 × 2  ←   │ 单位用量：2 套              │
│   │  └─ 螺丝 × 4       │ 损耗率：0%                  │
│   └─ 控制箱 × 1        │ 下层 BOM：V2               │
│   [+ 添加子物料]       │ 备注：安装位置说明          │
│                        │                       [编辑] │
└────────────────────────┴─────────────────────────────┘

“添加子物料”只显示在根物料的直接子项列表末尾，用来为当前 BOM 添加第二层节点；第三层及更深层节点不显示此按钮。下层子物料应进入对应子 BOM 的草稿页面维护，再由当前 BOM 选择和锁定该子 BOM 版本。

添加子物料时只能搜索并选择当前组织中已存在的物料。如果没有找到目标物料，页面提示先到“物料主数据 → 物料”新增，新增完成后再返回 BOM 草稿继续添加；BOM 页面不自动创建物料主数据。

选中当前 BOM 的直接子项且当前版本为草稿时，右侧显示“编辑”按钮。点击后，右侧明细进入编辑模式，显示可编辑的单位用量、损耗率、备注和下层 BOM 版本，并提供“删除该子物料”“取消”“保存”操作；未点击“编辑”前不修改字段，也不显示删除入口。删除前二次确认，只删除当前草稿中选中的这一条直接子项，不删除物料主数据或子物料自身的 BOM。选中第三层及更深层节点时，右侧只读展示明细，并提供“前往该物料 BOM”入口。可用和已停用版本中的所有节点均只读。

右侧明细：查看模式  [编辑]
                   ↓
右侧明细：编辑模式  [删除该子物料] [取消] [保存]

编辑草稿允许：

添加、修改和排序直接子物料；删除直接子项必须先进入右侧明细的编辑模式。
修改用量、损耗率和备注。
保存草稿。
删除整个草稿。

对于树中引用的下层 BOM，直接子项进入编辑模式后提供可用版本选择器，并默认选择最近一次生效的版本。页面展示所选版本的结构，并提供跳转到该物料 BOM 的入口；不在上层 BOM 中直接修改下层 BOM。可用版本停用后，已锁定它的历史上层版本仍可查看和展开；尚未生效的上层草稿必须改选可用版本后才能生效。

4.5 新建版本

“新建版本”从当前物料的 BOM 页面发起，不属于编辑草稿内部操作。点击后先弹出创建方式选择窗口：

┌─ 新建整机 A 的 BOM 版本 ──────────────────────────┐
│                                                   │
│ [复制旧版]  推荐：沿用现有结构，再修改差异         │
│             选择来源版本：[V2 · 可用 ▼]            │
│                                                   │
│  空白创建   从零开始添加子物料                     │
│                                                   │
│                            [取消] [创建草稿]       │
└───────────────────────────────────────────────────┘

“复制旧版”作为醒目的默认选项，其“来源版本”使用弹窗内的下拉框选择，列出该父物料全部已有版本并标明状态；默认预选当前 BOM 页面正在查看的版本，也允许在下拉框中改选其他版本，不再打开第二个版本选择窗口。创建时完整复制所选版本的明细，并记录来源版本。“空白创建”使用普通样式，不复制明细，来源版本为空。两种方式都生成新的草稿版本并进入草稿编辑页；每次只创建一个版本。

4.6 状态操作

页面根据状态显示操作：

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

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

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

生效和停用都需要二次确认。新版本生效后成为默认版本，其他可用版本保持可用。停用默认版本时，确认提示应说明哪个剩余可用版本会成为新默认版本；没有剩余可用版本时提示该父物料将暂无默认版本。

5. 数据模型建议

第一版使用现有 materials 作为父物料和子物料主数据，新增 bom_versions、bom_items 两个 BOM 核心表，以及独立的 BOM 操作记录表。现有“物料变更日志”依赖物料 ID 和物料变更字段，不能直接承载 BOM 版本事件。

一个父物料由 materials.id 标识，版本表直接引用它。出现在 BOM 中的父物料和所有子物料必须先在 materials 表中存在；如果尚未录入，应先到物料主数据新增物料，再返回 BOM 页面选择。物料名称、编码、类别和基础单位仍由物料主数据维护，BOM 表不重复保存。

5.1 `bom_versions`

建议字段：

id
organization_id
parent_material_id，引用 materials.id。
version
status
source_version_id，记录复制来源，可为空。
effective_at
obsoleted_at
created_by
updated_by
created_at
updated_at

约束：

同一组织、同一 parent_material_id 下版本号唯一；父物料必须属于同一组织，且为允许建立 BOM 的成品或半成品。
为 organization_id、parent_material_id、status 和 effective_at 建立查询索引。默认版本由可用版本的生效时间和版本 ID 确定，不单独保存可变的默认标记。

5.2 `bom_items`

建议字段：

id
organization_id
bom_version_id
child_material_id
quantity
unit_id
loss_rate
remark
child_bom_version_id，引用所选子物料本身的 BOM 版本；子物料本身无下层 BOM 时为空。
sort_order
created_at
updated_at

约束：同一 bom_version_id 下 child_material_id 唯一。子物料引用 materials.id，必须与该 BOM 版本属于同一组织；child_bom_version_id 必须指向以该子物料为父物料的 BOM 版本。草稿可选择可用版本，草稿生效后该引用不可修改。

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

查询某个整机 BOM 的结构时，按以下关系逐层查找：

整机 materials.id
  → 按 bom_versions.parent_material_id 查整机的版本，并选择要查看的版本
  → 用该版本的 bom_versions.id 查 bom_items.bom_version_id，取得全部直接子项
  → 用每条 bom_items.child_material_id 查 materials，取得子物料主数据
  → 用该条 bom_items.child_bom_version_id 查已选定的下层 BOM 版本
  → 用下层版本的 bom_versions.id 继续查它的 bom_items

child_bom_version_id 为空时，该子项不再往下展开；有值时按这个固定版本继续查询。新增或编辑草稿时，系统才根据 child_material_id 查询该子物料的可用 BOM 版本，默认预选最近生效的版本，并允许用户选择其他可用版本。保存所选版本 ID 后，查看已保存的 BOM 不再重新选择默认版本，因此下层 BOM 后续推出新版本也不会改变当前 BOM 的结构。查看历史 BOM 时仍按当时保存的版本引用展开。

5.3 BOM 操作记录

独立记录每次 BOM 状态变化，至少保存经营组织、父物料、BOM 版本、操作类型、操作人、操作时间和说明。生效与停用各记录一次；默认版本随这些状态变化而自动重新计算，不生成额外的停用记录。

6. 后端职责与接口草案

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

model
  → 定义 BOM、版本、子项和树形结构结果

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

service
  → 负责版本规则、复制、校验、生效、停用和结构树查询

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

接口草案：

方法	路径	用途
`POST`	`/api/boms`	为指定父物料创建首个草稿版本
`GET`	`/api/boms/:materialId`	按父物料 ID 查看 BOM 及默认版本摘要
`GET`	`/api/boms/:materialId/versions`	按父物料 ID 查看全部版本
`POST`	`/api/boms/:materialId/versions`	为已有 BOM 创建空白草稿版本
`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`	停用生效版本
`GET`	`/api/bom-versions/:versionId/tree`	按父项数量 `1` 查看完整 BOM 结构

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

7. 自动校验与错误反馈

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

时机	校验内容
选择子物料	当前组织物料存在、当前父节点重复、自引用、物料状态
保存草稿	数量、损耗率、基础单位、重复、自引用、循环、20 层限制
生效	完整重复执行保存校验，并验证所选下层版本仍可用
结构树查询	循环保护、20 层限制、版本引用完整性

错误信息需要包含：

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

示例：

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

8. 权限与审计

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

8.1 日志记录页面

左侧“日志记录”展开后显示两个子页面：

日志记录
  ├─ 物料变更日志  → 现有物料新增、修改、删除记录
  └─ BOM 记录     → BOM 创建、复制、生效、停用、删除草稿

“BOM 记录”页面提供父物料编码或名称、版本、操作类型和时间范围筛选。列表显示操作时间、父物料、版本、操作、操作人和说明；点击记录可查看状态变化。停用记录保留操作者及原因；若停用的是默认版本，详情展示停用后接替的默认版本或“暂无默认版本”。

建议路由为 /logs/materials 和 /logs/boms，原 /logs 跳转到 /logs/materials。两个子页面均仅超级管理员可访问。

9. 测试与验收重点

9.1 后端

创建首个草稿和保存明细。
父物料和子物料必须存在于物料主数据且属于同一组织；不存在的物料 ID 无法创建 BOM。
同一父物料版本号重复。
同一版本直接子项重复。
父项直接引用自身。
三层及更深循环引用，并返回完整路径。
第 20 层允许，第 21 层拒绝。
零数量、负数量和负损耗率拒绝。
生效版本禁止修改和删除。
多个版本可同时可用，新版本生效后成为默认版本，旧可用版本状态不变。
停用默认版本后，默认版本按最近生效时间回退；无可用版本时默认版本为空。
从指定版本完整复制为新草稿。
下层版本锁定后不随新版本变化。
单件多层结构、各层用量和损耗率计算正确，且不返回跨分支物料汇总。
非超级管理员访问全部 BOM 接口均被拒绝。
不同组织的数据不能相互读取或引用。
BOM 状态变化与对应操作记录同时提交。

9.2 前端

物料列表仅对符合条件的父物料显示“BOM”按钮；入口和 BOM 页面仅超级管理员可访问。
从物料列表进入指定物料的独立 BOM 页面；版本选择框列出该物料全部版本并标明状态，切换后直接显示所选版本结构。
没有版本时版本框显示“无”，结构区域显示空状态；创建首个草稿后自动选中该版本。
版本选择框包含全部草稿、可用和已停用版本，约 50 个版本以内可滚动选择；切换后显示该版本结构与对应状态操作。
只有符合条件且尚无版本的成品或半成品，才能从其 BOM 页面创建首个草稿；父物料由入口固定，不再重复选择。
草稿可编辑，可用和已停用版本只读。
选中草稿时，状态行显示“编辑”“生效”“删除草稿”；点击顶部“编辑”后才进入树形编辑状态，选中可用版本时仅显示“停用”。
点击节点先在右侧查看明细；仅草稿的直接子项显示“编辑”按钮，点击后才进入编辑模式。
删除子物料入口只在右侧编辑模式出现，删除前确认，且只影响当前草稿中的该条子项。
“添加子物料”只在根物料的第二层子项列表末尾出现；更深层节点通过对应子 BOM 维护。
添加子物料时只允许选择当前组织已有物料；搜索不到时提示先新增物料主数据，再返回 BOM 草稿继续添加。
添加重复子项和自引用时立即提示。
后端返回循环或深度错误时定位并标记问题节点。
生效、停用和删除草稿具有明确确认提示。
从指定历史版本创建草稿后，明细完整复制且可继续编辑。
点击“新建版本”先弹出方式选择窗口；“复制旧版”醒目且默认选中，来源版本通过弹窗内下拉框选择；“空白创建”可生成无明细草稿。
“日志记录”展开后显示两个子页面；原 /logs 链接仍能打开物料变更日志。
“BOM 记录”支持筛选与查看生效和停用的操作详情。

10. 建议实施顺序

建立 BOM 数据表、模型和仓储层。
实现草稿创建、查询、编辑和删除。
实现复制新版本及版本列表。
实现结构校验、20 层限制和完整循环路径反馈。
实现多版本可用、默认版本推导、生效和停用事务。
在物料列表增加 BOM 入口，实现单个物料的 BOM 页面和完整版本选择框。
实现新建及草稿树形编辑页面。
实现单个 BOM 版本按父项数量 1 的结构树查询和各层用量显示。
将现有日志入口改为双子页面，接入 BOM 操作记录和筛选。
补齐权限、自动化测试和真实数据副本验收。

11. 后续阶段

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

多 BOM 需求试算：在独立页面输入一个或多个 BOM 的计划数量，递归计算并汇总相同底层物料需求，再在“物料主数据”下增加菜单。
CSV 层级导入和错误报告。
替代料管理。
面向技术人员等角色的细分权限。
制造订单、领料、完工和库存联动。
增加结构化的“使用位置明细”：在同一 BOM 子项下分别填写安装位置、用途和用量，系统自动合计该子项的总用量，并在可展开的 BOM 树节点下展示各位置明细。可根据这些明细自动生成备注，且允许人工修改备注；同一直接父节点下仍只保留一条该物料的 BOM 子项。

27 KiB Raw Permalink Blame History Unescape Escape