docs: 补充知识库管理操作闭环设计

ai_knowledge_base_v2/development_records/2026-07-12-知识库管理操作闭环补齐设计.md

@@ -0,0 +1,69 @@
+# 知识库管理操作闭环补齐设计
+
+日期：2026-07-12
+
+## 一、修复目标
+
+在不改变现有飞书源、知识版本和 Agent 检索架构的前提下，补齐知识库元数据编辑、批量修改、列表更多菜单和全生命周期操作闭环。
+
+## 二、业务边界
+
+- 只允许超级管理员修改后台名称、知识库类型和审核方式。
+- 元数据修改不改动 `space_id`、`node_id`、飞书源快照、当前正式版本、待发布版本和开放状态。
+- 后台不增加知识卡或飞书正文编辑能力。
+- 关闭知识库不进入正式 Agent 目录；后台预览仍可选择关闭知识库。
+- 不引入向量数据库、多 Agent 或自动测试题。
+
+## 三、接口设计
+
+### 3.1 单个元数据更新
+
+`PATCH /api/admin/knowledge/{id}/metadata`
+
+请求仅包含：
+
+- `name`
+- `knowledgeType`：`course | qa | general`
+- `reviewMode`：`manual | automatic`
+
+使用独立请求模型，避免编辑元数据时意外覆盖飞书定位、开放状态或版本字段。
+
+### 3.2 批量元数据更新
+
+`PATCH /api/admin/knowledge/batch/metadata`
+
+请求包含知识库 ID 列表，以及可选的知识库类型和审核方式。至少提供一个待更新字段。
+
+返回总数、成功数、失败数和逐项结果。每个成功项写入操作日志，不因单个无效 ID 导致其他合法项失败。
+
+## 四、页面改造
+
+- 知识库详情“基本信息”增加编辑入口和元数据展示。
+- 编辑弹窗只展示后台名称、类型和审核方式。
+- 列表增加多选和批量修改入口，提交前显示确认弹窗。
+- “更多”改为统一 `command` 事件处理，仅保留查看详情、Agent 预览、查看版本、归档和删除。
+- 归档项在已归档状态下禁用，归档后立即关闭知识库。
+- 接口失败不显示成功消息，所有加载和提交状态在 `finally` 中恢复。
+
+## 五、一致性与缓存
+
+- 当前 KnowledgeList 每次回答都从 MySQL 读取，没有长驻知识目录缓存。
+- 更新接口事务提交后，列表、详情和 Agent 下一轮目录查询立即读取新值。
+- 为防止后续增加缓存后遗漏失效，元数据变更统一调用目录失效服务，并更新 Redis 中的目录版本号。
+
+## 六、主动排查范围
+
+对新增、同步、审核、发布、开放、Agent 调用、版本更新、回滚、关闭、归档和删除逐项检查：
+
+- 前后端入口是否成对。
+- 权限、状态前置条件和危险操作确认。
+- 数据库、列表、详情和 Agent 目录的最终一致性。
+- 空数据、异常、重复提交和加载状态。
+
+## 七、验收标准
+
+- 单个和批量元数据修改均能在数据库、列表、详情和 Agent 目录中一致生效。
+- 元数据修改前后的正式版本、待发布版本、开放状态和飞书定位不变。
+- 非超级管理员调用返回 403。
+- “更多”的每个菜单项都有可见、可验证的结果。
+- 完整生命周期的错误状态和操作日志可追踪。