# 知识库管理操作闭环补齐设计

日期：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。
- “更多”的每个菜单项都有可见、可验证的结果。
- 完整生命周期的错误状态和操作日志可追踪。
