docs: limit first BOM view to one unit

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. 面向技术人员等角色的细分权限。