docs: refine BOM version and audit design

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` | 已生效 | 查看、停用、基于该版本新建草稿 |
+| `effective` | 可用 | 查看、被新 BOM 选择、停用、基于该版本新建草稿 |
-| `obsolete` | 已停用 | 查看、基于该版本新建草稿 |
+| `obsolete` | 已停用 | 查看历史、基于该版本新建草稿；不能用于新 BOM |
 
 规则如下：
 
 1. 同一父物料的版本号必须唯一。
-2. 同一父物料最多只能有一个已生效版本。
+2. 同一父物料可以同时存在多个 `effective`（可用）版本。
-3. 已生效版本不可直接修改。
+3. 默认版本是尚未停用且最近一次生效的版本，按生效时间排序；同一时间时按版本 ID 确定唯一结果。停用默认版本后，剩余可用版本中最近生效的版本成为默认版本；全部停用时无默认版本。
-4. 修改已生效或已停用版本时，必须先完整复制所选版本，生成新的草稿版本。
+4. 新版本生效不改变其他可用版本的状态。非默认的可用版本仍可被新建的上层 BOM 明确选择。
-5. 新版本生效时，同一父物料原有的已生效版本自动转为已停用。
+5. 可用版本不可直接修改。修改可用或已停用版本时，必须先完整复制所选版本，生成新的草稿版本。
-6. 已停用版本不能恢复为已生效，但可以作为新版本的复制来源。
+6. 已停用版本不能恢复为可用，但可以作为新版本的复制来源；它不能被新建的上层 BOM 选用。
-7. 草稿可删除；已生效和已停用版本只保留、不物理删除。
+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         查看结构｜编辑草稿｜历史版本
+整机 A     V2         2            V3         查看结构｜编辑草稿｜历史版本
-电机组件   V1         已生效   无         查看结构｜新建版本｜历史版本
+电机组件   V1         1            无         查看结构｜新建版本｜历史版本
 ```
 
 历史版本在展开区域或抽屉中显示：
@@ -175,14 +181,14 @@ BOM 列表
 ```text
 整机 A
   ├─ V3  草稿
-  ├─ V2  已生效
+  ├─ V2  可用·默认
-  └─ V1  已停用
+  └─ 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. 后续阶段