# 管理后台运营能力补齐记录

日期：2026-07-07

## 2026-07-07 需求变更说明

本记录中的“用户知识库权限分配”是当时按旧需求完成的能力。后续底层需求已调整为：知识库不再精确授权到个人，已开放知识库默认所有用户可见。

因此，本记录中涉及“知识库权限分配”“用户-知识库授权”“`/knowledge-permissions` 接口”的内容只作为历史实现记录，不再代表当前一期目标。当前目标以 `2026-07-07-knowledge-open-access-change.md` 为准。

## 背景

用户反馈当前后台仍有三块没有做到产品可用状态：

1. 知识库管理只做到新增和列表，缺少编辑、删除、启停、备注维护。
2. 用户管理只做到查询、启停和额度调整，按当时旧口径缺少删除用户和知识库权限分配。
3. Agent 调试预览不符合用户端聊天体验，测试问题在左侧配置区，预览窗口在右侧，使用时割裂。

本次调整目标是把后台从“可演示”推进到“一期运营人员可使用”的状态。

## 本次完成内容

### 知识库管理

- 新增知识库编辑能力。
- 新增知识库删除能力。
- 支持在列表中直接启用或禁用知识库。
- 表单补充备注字段。
- 删除知识库时按当时旧口径同步清理用户-知识库授权关系，避免外键约束导致删除失败。

### 用户管理（旧口径，后续已调整）

- 用户列表补充 ID、昵称、最近登录时间。
- 支持删除用户。
- 支持打开“知识库权限分配”抽屉。
- 可为用户按知识库开启或关闭权限。
- 可为每个授权设置生效时间和失效时间。
- 后端新增用户知识库权限读取和保存接口。
- 以上权限分配能力已被“开放知识库全员可见”的新口径替代。

### Agent 管理预览

- 移除左侧配置区中的“调试问题”输入。
- 右侧预览窗口改为接近用户端聊天的交互：
  - 上方展示对话消息。
  - 下方固定输入框。
  - 右侧发送按钮。
- 发送后输入框自动清空，消息进入预览对话流。

## 后端接口变化

新增接口（旧口径，后续会移除或废弃）：

- `GET /api/admin/user/{user_id}/knowledge-permissions`
  - 读取指定用户已分配的知识库权限。
- `PUT /api/admin/user/{user_id}/knowledge-permissions`
  - 覆盖保存指定用户的知识库权限列表。

复用接口：

- `GET /api/admin/knowledge/list`
- `POST /api/admin/knowledge`
- `PUT /api/admin/knowledge/{knowledge_id}`
- `DELETE /api/admin/knowledge/{knowledge_id}`
- `GET /api/admin/user/list`
- `PUT /api/admin/user/{user_id}`
- `DELETE /api/admin/user/{user_id}`
- `POST /api/admin/agent/debug`

## 当前边界

- 用户知识库权限已经可以维护，但后续新口径改为用户端问答链路只按知识库开放状态过滤。
- 当前用户删除仍是软删除，聊天记录和审计记录不会被物理删除。
- Agent 管理目前仍是调试态，尚未做正式的 Agent 版本发布、回滚和灰度。
- 权限分配按用户维护是旧口径；新口径不再按人维护。

## 后续建议

1. 在用户端接入真实登录后，问答链路按已开放知识库过滤检索范围，不再按 `sys_user_kb` 过滤。
2. Agent 管理增加“保存草稿 / 发布版本 / 回滚版本”，把提示词、模型、知识库和参数落成版本。
3. 用户管理增加批量启停和导入导出；不再做批量知识库授权。
4. 知识库管理增加同步状态、最后同步时间、文档数量和检索测试入口。
