From b75696f44af3e95f128b6da3facdb1c38f1026ce Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=96=87=E7=9D=BF=20=E5=BC=A0?= Date: Tue, 22 Sep 2026 18:25:38 +0800 Subject: [PATCH] docs: add initial BOM management design --- .../specs/2026-09-22-bom-management-design.md | 466 ++++++++++++++++++ 1 file changed, 466 insertions(+) create mode 100644 docs/superpowers/specs/2026-09-22-bom-management-design.md diff --git a/docs/superpowers/specs/2026-09-22-bom-management-design.md b/docs/superpowers/specs/2026-09-22-bom-management-design.md new file mode 100644 index 00000000..901c1e99 --- /dev/null +++ b/docs/superpowers/specs/2026-09-22-bom-management-design.md @@ -0,0 +1,466 @@ +# 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 以后产生新版本，不改变已经生效的上层版本。 + +例如： + +```text +整机 A V3 + ├─ 外壳组件 V2 + └─ 电机组件 V1 +``` + +即使电机组件 V2 后续生效，整机 A V3 仍按电机组件 V1 展开。整机需要采用新的电机组件版本时，应创建整机 A 的新草稿版本。 + +### 3.4 层级与循环保护 + +- BOM 最多支持 20 层。 +- 父物料不能直接引用自身。 +- 禁止任意深度的循环引用，例如 `A → B → C → A`。 +- 添加子物料时，前端立即检查直接重复和自引用。 +- 保存草稿时，后端检查数量、重复、自引用、循环引用和最大层级。 +- 生效时，后端在同一事务中再次执行完整校验。 +- 递归展开时再次执行循环和最大深度保护，不能仅依赖保存时的校验。 +- 检测失败时返回完整问题路径，并让前端定位对应节点。 + +### 3.5 数量与损耗 + +- 单位用量必须大于零。 +- 损耗率不得小于零。 +- 每层需求量按以下规则计算： + +```text +子项需求量 = 上层需求量 × 单位用量 ×（1 + 损耗率） +``` + +- 递归计算过程中保留足够精度，最终结果按物料基础单位的精度规则向上取整。 +- 汇总结果按物料和基础单位合并相同的最底层物料。 + +## 4. 前端信息架构 + +左侧导航在“物料主数据”和“公司组织”之间增加独立大类： + +```text +物料主数据 + ├─ 物料 + └─ 基础配置 + +BOM 管理 + └─ BOM 维护 + +公司组织 + ├─ 组织管理 + ├─ 用户管理 + └─ 角色与权限 +``` + +“多 BOM 需求试算”属于后续能力，第一版不展示空菜单。 + +### 4.1 BOM 维护 + +BOM 维护统一包含以下四类操作： + +```text +BOM 列表 + → 查询、查看结构、查看历史版本、发起新版本 + +新建 BOM + → 为尚未建立 BOM 的父物料创建第一个草稿版本 + +编辑草稿 + → 编辑明细、保存草稿、删除草稿 + +状态操作 + → 生效或停用 +``` + +结构校验不作为独立按钮或菜单。系统在添加、保存和生效过程中自动校验。 + +树形结构维护是编辑页面的交互方式，不作为独立功能入口。 + +### 4.2 BOM 列表 + +列表以父物料为主行，避免历史版本过多导致列表膨胀： + +```text +父项物料 当前版本 状态 草稿版本 操作 +整机 A V2 已生效 V3 查看结构｜编辑草稿｜历史版本 +电机组件 V1 已生效 无 查看结构｜新建版本｜历史版本 +``` + +历史版本在展开区域或抽屉中显示： + +```text +整机 A + ├─ V3 草稿 + ├─ V2 已生效 + └─ V1 已停用 +``` + +列表至少支持： + +- 按父项物料编码或名称查询。 +- 按是否存在草稿、是否存在生效版本筛选。 +- 查看当前或历史版本结构。 +- 编辑已有草稿。 +- 从指定历史版本复制并发起新版本。 +- 执行当前状态允许的状态操作。 + +“查看结构”页面默认按父物料数量 `1` 展示完整层级。用户可以临时修改查看数量，页面随即递归计算各层需求，并展示最底层物料汇总。该能力只计算当前一个 BOM 版本，不单独设置菜单，也不保存试算记录。 + +```text +查看数量：10 + +[层级结构] +整机 A × 10 + ├─ 外壳组件 × 10 + │ └─ 螺丝 × 80 + └─ 电机组件 × 20 + └─ 螺丝 × 80 + +[底层物料汇总] +螺丝 × 160 +``` + +同时选择多个 BOM 并合并需求，属于后续“多 BOM 需求试算”，不在第一版范围内。 + +### 4.3 新建 BOM + +新建 BOM 只面向尚未建立 BOM 的成品或半成品。页面包含： + +- 父项物料选择。 +- 初始版本号。 +- 直接子物料树或列表。 +- 子项单位用量、基础单位、损耗率和备注。 +- 保存草稿。 + +已存在 BOM 的父物料不能再次走“新建 BOM”，应从列表或历史版本选择来源并执行“新建版本”。 + +### 4.4 编辑草稿 + +编辑页采用左侧结构树、右侧节点明细的布局： + +```text +┌───────────────────────┬──────────────────────────────┐ +│ BOM 结构树 │ 当前节点明细 │ +│ │ │ +│ ▼ 整机 A │ 子物料：电机组件 │ +│ ├─ 外壳组件 × 1 │ 单位用量：2 │ +│ ├─ 电机组件 × 2 │ 基础单位：套 │ +│ └─ 控制箱 × 1 │ 损耗率：0% │ +│ │ 备注：安装位置说明 │ +│ [+ 添加子物料] │ │ +└───────────────────────┴──────────────────────────────┘ +``` + +编辑草稿允许： + +- 添加、修改、删除和排序直接子物料。 +- 修改用量、损耗率和备注。 +- 保存草稿。 +- 删除整个草稿。 + +对于树中引用的下层 BOM，当前页面只展示其锁定版本和结构，并提供跳转到该物料 BOM 的入口；不在上层 BOM 中直接修改下层 BOM。 + +### 4.5 新建版本 + +“新建版本”从 BOM 列表或历史版本发起，不属于编辑草稿内部操作： + +```text +选择一个历史版本 + ↓ +完整复制该版本的 BOM 明细 + ↓ +生成新的草稿版本 + ↓ +进入草稿编辑页 +``` + +每次只复制一个明确选中的来源版本，不复制该父物料的全部历史版本。 + +### 4.6 状态操作 + +页面根据状态显示操作： + +```text +草稿 + ├─ 查看 + ├─ 编辑草稿 + ├─ 生效 + └─ 删除草稿 + +已生效 + ├─ 查看 + ├─ 停用 + └─ 新建版本 + +已停用 + ├─ 查看 + └─ 新建版本 +``` + +生效和停用都需要二次确认。新版本生效时，应明确提示原生效版本将被自动停用。 + +## 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 分层结构： + +```text +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 层限制、版本引用完整性 | + +错误信息需要包含： + +- 错误类型。 +- 父物料和子物料编码。 +- 完整问题路径。 +- 用户可执行的修改建议。 + +示例： + +```text +无法保存：检测到循环引用。 +问题路径：整机 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. 制造订单、领料、完工和库存联动。