# 管理后台体验与系统配置需求变更记录

日期：2026-07-07

## 背景

当前管理后台已经具备 Agent 调试、用户管理和系统配置入口，但有三处不满足当前产品要求：

1. Agent 调试预览仍像后台表单结果展示，不像正常聊天产品，调试人员难以判断真实用户端效果。
2. 学员批量导入仍是文本粘贴格式，不适合运营人员批量维护学员名单。
3. 系统配置页面只是裸 Key/Value 占位，无法作为一期正式后台能力交付。

本次变更先更新文档，再进入代码实现。

## 变更一：Agent 调试预览样式

Agent 管理中的右侧预览窗口需要调整为接近 DeepSeek、ChatGPT 等聊天产品的常规对话样式：

- 对话消息按用户和 Agent 区分左右或视觉层级。
- Agent 回复应正常显示多行文本、列表、代码和引用信息，不再像后台小卡片堆叠。
- 输入框固定在预览窗口底部，发送按钮和输入框组合为聊天输入区。
- 调试中需要有明确的“正在思考/生成中”状态。
- 预览窗口用于模拟真实用户端问答体验，发送测试问题不再放在左侧配置区。

## 变更二：学员 Excel 导入

学员批量导入从“CSV 文本粘贴”调整为“Excel 模板导入”。

后台用户管理需要提供：

1. 下载导入模板。
2. 上传 Excel 文件导入学员。
3. 导入后展示新增、更新、失败数量。
4. 导入失败时展示行号、手机号和失败原因。

模板字段暂定为：

| 字段 | 必填 | 说明 |
| --- | --- | --- |
| 手机号 | 是 | 登录准入手机号，必须符合中国大陆手机号格式。 |
| 姓名 | 是 | 学员真实姓名或系统展示名称。 |
| 昵称 | 否 | 可为空。 |
| 每日聊天额度 | 否 | 不填时使用系统配置的默认每日额度。 |
| 状态 | 否 | 支持“启用/禁用”或 `1/0`。 |
| 有效期 | 否 | 不填表示不过期。 |

旧的文本粘贴导入可以作为兼容接口保留，但后台正式入口使用 Excel 导入。

## 变更三：系统设置补齐

系统设置页面不再作为占位页面，需要具备可直接使用的配置管理能力。

一期先做分组配置表单，重点覆盖：

- 用户与登录：默认每日聊天额度、登录 Token 有效期。
- AI 问答：AI 请求超时时间、上下文消息数、是否展示引用来源。
- 外部服务：飞书搜索接口地址、飞书请求超时、飞书检索重试次数；知识库检索不再提供 mock 开关。

配置项保存到 `sys_system_config`，后台展示为中文配置项；页面不再提供“高级配置”或自由 Key/Value 输入。

后续允许管理员配置的项目必须显式登记在系统配置页中，不能只通过输入任意 Key 的方式临时增加。这样可以避免配置项含义不清、交接困难、误填 Key 后功能不生效等问题。

本次实现中，默认每日聊天额度需要接入手动添加和批量导入学员逻辑；其他配置先完成持久化和后台可维护，为后续运行时接入保留明确 Key。

## 验收重点

1. Agent 调试预览像正常聊天窗口，可以连续提问和查看 Agent 回复。
2. 学员管理可以下载 Excel 模板。
3. 按模板上传 Excel 后可以导入学员，并显示导入结果。
4. Excel 中不合法数据不会整体中断导入，失败行有明确原因。
5. 系统设置页面不再是裸输入框，也不展示高级配置入口；管理员可以按分组维护全部允许配置的项目。
6. 修改默认每日聊天额度后，新手动添加或导入且未单独填写额度的学员使用新的默认额度。
