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 901c1e99..0e00770c 100644 --- a/docs/superpowers/specs/2026-09-22-bom-management-design.md +++ b/docs/superpowers/specs/2026-09-22-bom-management-design.md @@ -22,10 +22,10 @@ - 查看 BOM 列表、结构和历史版本。 - 基于指定历史版本完整复制明细,生成新草稿。 - 编辑、保存和删除草稿。 -- 生效草稿或停用当前生效版本。 +- 生效草稿或停用指定的生效版本。 - 自动校验重复子项、自引用、循环引用、无效数量和最大层级。 - 按指定产品数量递归展开 BOM,并汇总最底层物料需求。 -- 记录生效、自动停用和手工停用等关键状态变化的审计信息。 +- 记录生效和停用等关键状态变化的审计信息。 - 第一版页面和接口仅允许超级管理员访问。 ### 2.2 不包含 @@ -48,18 +48,18 @@ BOM 版本仅使用以下三个状态: | 状态 | 含义 | 允许操作 | | --- | --- | --- | | `draft` | 草稿 | 查看、编辑、保存、生效、删除 | -| `effective` | 已生效 | 查看、停用、基于该版本新建草稿 | -| `obsolete` | 已停用 | 查看、基于该版本新建草稿 | +| `effective` | 可用 | 查看、被新 BOM 选择、停用、基于该版本新建草稿 | +| `obsolete` | 已停用 | 查看历史、基于该版本新建草稿;不能用于新 BOM | 规则如下: 1. 同一父物料的版本号必须唯一。 -2. 同一父物料最多只能有一个已生效版本。 -3. 已生效版本不可直接修改。 -4. 修改已生效或已停用版本时,必须先完整复制所选版本,生成新的草稿版本。 -5. 新版本生效时,同一父物料原有的已生效版本自动转为已停用。 -6. 已停用版本不能恢复为已生效,但可以作为新版本的复制来源。 -7. 草稿可删除;已生效和已停用版本只保留、不物理删除。 +2. 同一父物料可以同时存在多个 `effective`(可用)版本。 +3. 默认版本是尚未停用且最近一次生效的版本,按生效时间排序;同一时间时按版本 ID 确定唯一结果。停用默认版本后,剩余可用版本中最近生效的版本成为默认版本;全部停用时无默认版本。 +4. 新版本生效不改变其他可用版本的状态。非默认的可用版本仍可被新建的上层 BOM 明确选择。 +5. 可用版本不可直接修改。修改可用或已停用版本时,必须先完整复制所选版本,生成新的草稿版本。 +6. 已停用版本不能恢复为可用,但可以作为新版本的复制来源;它不能被新建的上层 BOM 选用。 +7. 草稿可删除;可用和已停用版本只保留、不物理删除。 ### 3.2 父子关系 @@ -82,7 +82,7 @@ BOM 版本仅使用以下三个状态: ### 3.3 下层版本锁定 -当子物料存在已生效 BOM 时,上层版本生效时锁定该子物料当时使用的下层 BOM 版本。下层 BOM 以后产生新版本,不改变已经生效的上层版本。 +当子物料存在可用 BOM 时,编辑上层草稿可选择其任意可用版本;页面默认预选最近一次生效的版本。上层版本生效时,锁定用户确认的下层 BOM 版本。下层 BOM 以后产生新版本,不改变已经生效的上层版本。 例如: @@ -92,7 +92,7 @@ BOM 版本仅使用以下三个状态: └─ 电机组件 V1 ``` -即使电机组件 V2 后续生效,整机 A V3 仍按电机组件 V1 展开。整机需要采用新的电机组件版本时,应创建整机 A 的新草稿版本。 +即使电机组件 V2 后续生效,整机 A V3 仍按电机组件 V1 展开。电机组件 V1 即使后来停用,整机 A V3 的历史结构仍可查看和展开;但新建上层版本时不能再选择已停用的电机组件 V1。整机需要采用其他下层版本时,应创建整机 A 的新草稿版本。 ### 3.4 层级与循环保护 @@ -134,10 +134,16 @@ BOM 管理 ├─ 组织管理 ├─ 用户管理 └─ 角色与权限 + +日志记录 + ├─ 物料变更日志 + └─ BOM 记录 ``` “多 BOM 需求试算”属于后续能力,第一版不展示空菜单。 +现有独立菜单“日志记录”改为左侧导航大类。现有物料日志页面归入“物料变更日志”,BOM 事件展示在新建的“BOM 记录”子页面。原有 `/logs` 地址应保持可访问,并跳转到物料变更日志页面,避免旧链接失效。 + ### 4.1 BOM 维护 BOM 维护统一包含以下四类操作: @@ -165,9 +171,9 @@ BOM 列表 列表以父物料为主行,避免历史版本过多导致列表膨胀: ```text -父项物料 当前版本 状态 草稿版本 操作 -整机 A V2 已生效 V3 查看结构|编辑草稿|历史版本 -电机组件 V1 已生效 无 查看结构|新建版本|历史版本 +父项物料 默认版本 可用版本数 草稿版本 操作 +整机 A V2 2 V3 查看结构|编辑草稿|历史版本 +电机组件 V1 1 无 查看结构|新建版本|历史版本 ``` 历史版本在展开区域或抽屉中显示: @@ -175,14 +181,14 @@ BOM 列表 ```text 整机 A ├─ V3 草稿 - ├─ V2 已生效 - └─ V1 已停用 + ├─ V2 可用·默认 + └─ V1 可用 ``` 列表至少支持: - 按父项物料编码或名称查询。 -- 按是否存在草稿、是否存在生效版本筛选。 +- 按是否存在草稿、是否存在可用版本筛选。 - 查看当前或历史版本结构。 - 编辑已有草稿。 - 从指定历史版本复制并发起新版本。 @@ -242,7 +248,7 @@ BOM 列表 - 保存草稿。 - 删除整个草稿。 -对于树中引用的下层 BOM,当前页面只展示其锁定版本和结构,并提供跳转到该物料 BOM 的入口;不在上层 BOM 中直接修改下层 BOM。 +对于树中引用的下层 BOM,草稿编辑页提供可用版本选择器,并默认选择最近一次生效的版本。页面展示所选版本的结构,并提供跳转到该物料 BOM 的入口;不在上层 BOM 中直接修改下层 BOM。可用版本停用后,已锁定它的历史上层版本仍可查看和展开;尚未生效的上层草稿必须改选可用版本后才能生效。 ### 4.5 新建版本 @@ -271,7 +277,7 @@ BOM 列表 ├─ 生效 └─ 删除草稿 -已生效 +可用 ├─ 查看 ├─ 停用 └─ 新建版本 @@ -281,11 +287,11 @@ BOM 列表 └─ 新建版本 ``` -生效和停用都需要二次确认。新版本生效时,应明确提示原生效版本将被自动停用。 +生效和停用都需要二次确认。新版本生效后成为默认版本,其他可用版本保持可用。停用默认版本时,确认提示应说明哪个剩余可用版本会成为新默认版本;没有剩余可用版本时提示该父物料将暂无默认版本。 ## 5. 数据模型建议 -第一版建议使用三个核心表,审计复用系统现有日志能力或补充独立审计记录。 +第一版建议使用三个 BOM 核心表,以及独立的 BOM 操作记录表。现有“物料变更日志”依赖物料 ID 和物料变更字段,不能直接承载 BOM 版本事件。 ### 5.1 `bom_headers` @@ -321,7 +327,7 @@ BOM 列表 约束: - 同一 `bom_header_id` 下版本号唯一。 -- 通过事务和数据库约束保证同一 `bom_header_id` 最多一个 `effective` 版本。 +- 为 `bom_header_id`、`status` 和 `effective_at` 建立查询索引。默认版本由可用版本的生效时间和版本 ID 确定,不单独保存可变的默认标记。 ### 5.3 `bom_items` @@ -344,6 +350,10 @@ BOM 列表 树形层级不直接存成固定层级字段。系统通过各父物料 BOM 版本之间的引用递归组成完整树,因此支持 10 层或 20 层时不需要改变表结构。 +### 5.4 BOM 操作记录 + +独立记录每次 BOM 状态变化,至少保存经营组织、父物料、BOM 版本、操作类型、操作人、操作时间和说明。生效与停用各记录一次;默认版本随这些状态变化而自动重新计算,不生成额外的停用记录。 + ## 6. 后端职责与接口草案 后端延续现有 Go 分层结构: @@ -388,7 +398,7 @@ handler | --- | --- | | 选择子物料 | 当前父节点重复、自引用、物料状态 | | 保存草稿 | 数量、损耗率、基础单位、重复、自引用、循环、20 层限制 | -| 生效 | 完整重复执行保存校验,并验证锁定的下层版本 | +| 生效 | 完整重复执行保存校验,并验证所选下层版本仍可用 | | 递归展开 | 循环保护、20 层限制、版本引用完整性 | 错误信息需要包含: @@ -411,7 +421,21 @@ handler - 第一版菜单、页面和全部 BOM 接口仅超级管理员可访问。 - 不能只通过前端隐藏菜单实现权限控制,后端接口必须再次鉴权。 - 预留独立 BOM 权限边界,后续权限系统完善后再拆分查看、维护和状态操作权限。 -- 创建、复制、生效、自动停用、手工停用和删除草稿记录操作者、时间、目标版本和结果。 +- 创建、复制、生效、停用和删除草稿记录操作者、时间、目标版本和结果。 + +### 8.1 日志记录页面 + +左侧“日志记录”展开后显示两个子页面: + +```text +日志记录 + ├─ 物料变更日志 → 现有物料新增、修改、删除记录 + └─ BOM 记录 → BOM 创建、复制、生效、停用、删除草稿 +``` + +“BOM 记录”页面提供父物料编码或名称、版本、操作类型和时间范围筛选。列表显示操作时间、父物料、版本、操作、操作人和说明;点击记录可查看状态变化。停用记录保留操作者及原因;若停用的是默认版本,详情展示停用后接替的默认版本或“暂无默认版本”。 + +建议路由为 `/logs/materials` 和 `/logs/boms`,原 `/logs` 跳转到 `/logs/materials`。两个子页面均仅超级管理员可访问。 ## 9. 测试与验收重点 @@ -425,23 +449,27 @@ handler - 第 20 层允许,第 21 层拒绝。 - 零数量、负数量和负损耗率拒绝。 - 生效版本禁止修改和删除。 -- 新版本生效时旧版本自动停用,且事务保持一致。 +- 多个版本可同时可用,新版本生效后成为默认版本,旧可用版本状态不变。 +- 停用默认版本后,默认版本按最近生效时间回退;无可用版本时默认版本为空。 - 从指定版本完整复制为新草稿。 - 下层版本锁定后不随新版本变化。 - 多层需求数量、损耗率和底层物料汇总正确。 - 非超级管理员访问全部 BOM 接口均被拒绝。 - 不同组织的数据不能相互读取或引用。 +- BOM 状态变化与对应操作记录同时提交。 ### 9.2 前端 - 导航位置、超级管理员可见性和路由保护。 - 列表查询、主行展示和历史版本展开。 - 新建 BOM 时只允许选择尚未建立 BOM 的成品或半成品。 -- 草稿可编辑,已生效和已停用版本只读。 +- 草稿可编辑,可用和已停用版本只读。 - 添加重复子项和自引用时立即提示。 - 后端返回循环或深度错误时定位并标记问题节点。 -- 生效、自动停用、手工停用和删除草稿具有明确确认提示。 +- 生效、停用和删除草稿具有明确确认提示。 - 从指定历史版本创建草稿后,明细完整复制且可继续编辑。 +- “日志记录”展开后显示两个子页面;原 `/logs` 链接仍能打开物料变更日志。 +- “BOM 记录”支持筛选与查看生效和停用的操作详情。 ## 10. 建议实施顺序 @@ -449,11 +477,12 @@ handler 2. 实现草稿创建、查询、编辑和删除。 3. 实现复制新版本及版本列表。 4. 实现结构校验、20 层限制和完整循环路径反馈。 -5. 实现生效、自动停用和手工停用事务。 +5. 实现多版本可用、默认版本推导、生效和停用事务。 6. 实现前端导航、BOM 列表和历史版本展示。 7. 实现新建及草稿树形编辑页面。 8. 实现单 BOM 递归展开及底层物料汇总能力。 -9. 补齐权限、审计、自动化测试和真实数据副本验收。 +9. 将现有日志入口改为双子页面,接入 BOM 操作记录和筛选。 +10. 补齐权限、自动化测试和真实数据副本验收。 ## 11. 后续阶段