docs: 记录知识库管理闭环修复结果

ai_knowledge_base_v2/development_records/2026-07-12-知识库管理操作闭环修复记录.md

@@ -0,0 +1,60 @@
+# 知识库管理操作闭环修复记录
+
+日期：2026-07-12
+
+## 一、已修复问题
+
+1. 知识库详情“基本信息”增加编辑入口，可修改后台名称、知识库类型和审核方式。
+2. 增加专用元数据接口，修改时不再携带或覆盖飞书定位、开放状态和版本字段。
+3. 知识库列表增加多选和批量修改类型/审核方式，提交前二次确认，返回成功和失败数量。
+4. “更多”菜单改为 Element Plus `command` 事件，现有查看详情、Agent 预览、查看版本、归档/恢复和删除均有真实处理。
+5. Agent 预览入口会跳转到 Agent 管理页并自动选中当前知识库。
+6. 列表和详情的 `status` 字段口径已统一，详情页不再把已开放状态误显示为已关闭。
+7. 版本操作按状态展示：待审核只显示审核，已通过才显示发布，已拒绝显示飞书修改指引。
+8. 同步提示区分“无变化、待审核、已自动发布”，不再统一误报为已生成待审核版本。
+9. 后端异常的 `detail` 已在前端展示，取消确认弹窗不再产生未处理 Promise 异常。
+
+## 二、主动发现并修复的漏洞
+
+1. **权限绕过**：新增、飞书导入、旧更新和删除接口原先没有超级管理员校验，现已统一补齐。
+2. **无版本直接开放**：新增和飞书导入原先可以直接创建为开放状态，现强制以关闭状态创建，必须完成同步、审核和发布后才能开放。
+3. **旧 PUT 绕过专用状态校验**：原接口可以同时改写 `space_id/node_id/status`，现已禁止通过该接口改动这些受保护字段。
+4. **重复飞书文章**：原先可并发创建多个指向同一 `space_id + node_id` 的知识库，现已增加接口预检和数据库唯一约束。
+5. **回滚版本状态错乱**：原回滚只修改知识库指针，不更新新旧版本的 `published/superseded` 状态，现已同步切换。
+6. **跨知识库版本误操作**：审核、说明卡确认和发布现在必须针对当前待发布版本，不能对历史版本重复操作。
+7. **归档/源异常后开放**：发布和回滚现在不能绕过归档状态和源异常校验强制开放。
+8. **自动审核未生效**：`automatic` 原先仅保存字段，同步仍全部进入人工审核。现在只有“质检通过、非高风险、说明卡可从已确认版本安全继承”时自动审核发布；首次版本、说明卡大变更和高风险内容仍需人工审核。
+9. **物理删除过于宽松**：现在必须先关闭并归档，才能物理删除；列表对非归档数据禁用删除项。
+
+## 三、数据库变更
+
+- 新增 Alembic 迁移 `0008_unique_kb_node`。
+- 在 `sys_knowledge(feishu_space_id, feishu_node_id)` 上增加唯一约束 `uq_knowledge_feishu_node`。
+- 迁移支持在“约束已创建但 Alembic 版本未写入”的中间状态下重试。
+- 业务元数据字段已在上一轮建立，本次不需要新增名称、类型或审核方式列。
+
+## 四、缓存与 Agent 一致性
+
+- KnowledgeList 仍在每次回答时直接读取 MySQL，没有使用可能返回旧名称/旧类型的长驻目录缓存。
+- 新增 `KnowledgeCatalogCacheService`，所有元数据、发布、回滚、开放、关闭、归档、恢复和删除操作后都会更新 Redis 目录版本号。
+- Redis 不可用时不会导致已提交的 MySQL 更新误报失败，Agent 仍直接读取 MySQL 新值。
+
+## 五、验证结果
+
+- 后端自动化测试：17 项全部通过。
+- 管理端 `vue-tsc` 和 Vite 生产构建通过。
+- `0008` 迁移升级、回退到 `0007`、再升级全部通过。
+- 后端健康检查通过。
+- 单个元数据 PATCH 返回 200，数据库、详情和 Agent 目录名称一致。
+- 批量 PATCH 实测 2 项成功、0 项失败，验证后已恢复原数据。
+- 元数据修改前后的 `space_id/node_id`、正式版本、待发布版本和开放状态保持不变。
+- 重复 `space_id + node_id` 写入被数据库唯一约束拒绝。
+- 关闭知识库后，正式 Agent 目录立即排除；后台 Agent 预览仍返回 200 并生成检索轨迹。
+- 归档后开放返回 409；恢复并重新开放后再次进入正式 Agent 目录。
+- 真实验证结束后，被测知识库已恢复为原来的活动、开放状态。
+
+## 六、仍存在的风险
+
+- 目前历史迁移的 6 个知识库类型仍保留为“通用知识库”，系统不能在没有业务确认的情况下自动猜测类型；超级管理员现可在列表批量修改。
+- 物理删除会删除知识库生成数据，历史检索日志仍保留快照和 ID，但无法再打开被删除的原版本详情；因此已强制“先关闭并归档”。
+- 自动发布依赖质检规则和 Manifest 相似度判定，高风险主题和说明卡大变更已强制回到人工审核，但仍需在后续运营中关注质检误判率。