# 知识库管理操作闭环修复记录

日期：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 相似度判定，高风险主题和说明卡大变更已强制回到人工审核，但仍需在后续运营中关注质检误判率。
