diff --git a/docs/superpowers/specs/2026-09-22-bom-management-design.md b/docs/superpowers/specs/2026-09-22-bom-management-design.md index 8b713056..6fdefb02 100644 --- a/docs/superpowers/specs/2026-09-22-bom-management-design.md +++ b/docs/superpowers/specs/2026-09-22-bom-management-design.md @@ -8,7 +8,7 @@ ## 1. 目标 -为成品和半成品提供可追溯的多层 BOM 手工维护能力。第一版重点完成 BOM 的创建、草稿编辑、版本保留、生效与停用、结构合法性校验,以及单个 BOM 按指定数量递归展开的基础能力。 +为成品和半成品提供可追溯的多层 BOM 手工维护能力。第一版重点完成 BOM 的创建、草稿编辑、版本保留、生效与停用、结构合法性校验,以及按父项数量 `1` 查看单个 BOM 版本的完整层级。 第一版不延伸到制造执行和库存业务,BOM 操作不会生成领料申请、扣减库存或创建出入库单据。 @@ -24,7 +24,7 @@ - 编辑、保存和删除草稿。 - 生效草稿或停用指定的生效版本。 - 自动校验重复子项、自引用、循环引用、无效数量和最大层级。 -- 按指定产品数量递归展开 BOM,并汇总最底层物料需求。 +- 按父项数量 `1` 查看单个 BOM 版本的完整层级和各层用量。 - 记录生效和停用等关键状态变化的审计信息。 - 第一版页面和接口仅允许超级管理员访问。 @@ -34,6 +34,7 @@ - BOM 审批、驳回和申请流程。 - 替代料。 - 多 BOM 需求试算。 +- 修改查看数量、按计划数量计算需求,以及汇总最底层物料需求。 - 制造订单。 - 领料、退料和完工入库。 - 库存预留、库存扣减和短缺计算。 @@ -102,7 +103,7 @@ BOM 版本仅使用以下三个状态: - 添加子物料时,前端立即检查直接重复和自引用。 - 保存草稿时,后端检查数量、重复、自引用、循环引用和最大层级。 - 生效时,后端在同一事务中再次执行完整校验。 -- 递归展开时再次执行循环和最大深度保护,不能仅依赖保存时的校验。 +- 查询完整结构树时再次执行循环和最大深度保护,不能仅依赖保存时的校验。 - 检测失败时返回完整问题路径,并让前端定位对应节点。 ### 3.5 数量与损耗 @@ -115,8 +116,8 @@ BOM 版本仅使用以下三个状态: 子项需求量 = 上层需求量 × 单位用量 ×(1 + 损耗率) ``` -- 递归计算过程中保留足够精度,最终结果按物料基础单位的精度规则向上取整。 -- 汇总结果按物料和基础单位合并相同的最底层物料。 +- 查看结构时,父项数量固定为 `1`,按上述公式逐层显示用量,计算过程中保留足够精度。 +- 第一版不输入计划数量,也不汇总不同分支中的最底层物料;相关计算留给后续“多 BOM 需求试算”。 ## 4. 前端信息架构 @@ -196,23 +197,17 @@ BOM 列表 - 从指定历史版本复制并发起新版本。 - 执行当前状态允许的状态操作。 -“查看结构”页面默认按父物料数量 `1` 展示完整层级。用户可以临时修改查看数量,页面随即递归计算各层需求,并展示最底层物料汇总。该能力只计算当前一个 BOM 版本,不单独设置菜单,也不保存试算记录。 +“查看结构”页面固定按父物料数量 `1` 展示当前选定 BOM 版本的完整层级和各层用量,不提供数量输入或最底层物料汇总。 ```text -查看数量:10 - -[层级结构] -整机 A × 10 - ├─ 外壳组件 × 10 - │ └─ 螺丝 × 80 - └─ 电机组件 × 20 - └─ 螺丝 × 80 - -[底层物料汇总] -螺丝 × 160 +整机 A × 1 + ├─ 外壳组件 × 1 + │ └─ 螺丝 × 8 + └─ 电机组件 × 2 + └─ 螺丝 × 8 ``` -同时选择多个 BOM 并合并需求,属于后续“多 BOM 需求试算”,不在第一版范围内。 +按计划数量计算、同时选择多个 BOM 并合并相同物料需求,属于后续独立页面“多 BOM 需求试算”。 ### 4.3 新建 BOM @@ -362,13 +357,13 @@ BOM 列表 ```text model - → 定义 BOM、版本、子项和展开结果 + → 定义 BOM、版本、子项和树形结构结果 repository → 负责数据库查询、事务和状态更新 service - → 负责版本规则、复制、校验、生效、停用和递归展开 + → 负责版本规则、复制、校验、生效、停用和结构树查询 handler → 负责 HTTP 参数、超级管理员鉴权和统一响应 @@ -388,7 +383,7 @@ handler | `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 | +| `GET` | `/api/bom-versions/:versionId/tree` | 按父项数量 `1` 查看完整 BOM 结构 | 接口命名在实施计划阶段可按现有路由风格进一步统一,但业务边界不应改变。 @@ -401,7 +396,7 @@ handler | 选择子物料 | 当前父节点重复、自引用、物料状态 | | 保存草稿 | 数量、损耗率、基础单位、重复、自引用、循环、20 层限制 | | 生效 | 完整重复执行保存校验,并验证所选下层版本仍可用 | -| 递归展开 | 循环保护、20 层限制、版本引用完整性 | +| 结构树查询 | 循环保护、20 层限制、版本引用完整性 | 错误信息需要包含: @@ -455,7 +450,7 @@ handler - 停用默认版本后,默认版本按最近生效时间回退;无可用版本时默认版本为空。 - 从指定版本完整复制为新草稿。 - 下层版本锁定后不随新版本变化。 -- 多层需求数量、损耗率和底层物料汇总正确。 +- 单件多层结构、各层用量和损耗率计算正确,且不返回跨分支物料汇总。 - 非超级管理员访问全部 BOM 接口均被拒绝。 - 不同组织的数据不能相互读取或引用。 - BOM 状态变化与对应操作记录同时提交。 @@ -482,7 +477,7 @@ handler 5. 实现多版本可用、默认版本推导、生效和停用事务。 6. 实现前端导航、BOM 列表和历史版本展示。 7. 实现新建及草稿树形编辑页面。 -8. 实现单 BOM 递归展开及底层物料汇总能力。 +8. 实现单个 BOM 版本按父项数量 `1` 的结构树查询和各层用量显示。 9. 将现有日志入口改为双子页面,接入 BOM 操作记录和筛选。 10. 补齐权限、自动化测试和真实数据副本验收。 @@ -490,7 +485,7 @@ handler 第一版稳定后再分别设计和实现: -1. 多 BOM 需求试算,并在 `BOM 管理` 下增加独立菜单。 +1. 多 BOM 需求试算:在独立页面输入一个或多个 BOM 的计划数量,递归计算并汇总相同底层物料需求,再在 `BOM 管理` 下增加菜单。 2. CSV 层级导入和错误报告。 3. 替代料管理。 4. 面向技术人员等角色的细分权限。