Document admin import settings and preview changes

ai_knowledge_base_v2/development_records/2026-07-06-api-priority.md

@@ -48,7 +48,9 @@ P2 用于让管理员能配置和运营系统。
 | `GET /admin/user/list` | 用户列表 |
 | `GET /admin/user/{id}` | 用户详情 |
 | `POST /admin/user` | 手动新增学员 |
-| `POST /admin/user/import` | 批量导入学员 |
+| `GET /admin/user/import/template` | 下载学员 Excel 导入模板 |
+| `POST /admin/user/import/excel` | 上传 Excel 批量导入学员 |
+| `POST /admin/user/import` | 批量导入学员，保留为兼容 JSON 接口 |
 | `PUT /admin/user` | 修改用户 |
 | `DELETE /admin/user/{id}` | 删除用户 |
 | `POST /admin/user/chat-limit` | 批量修改聊天次数 |

ai_knowledge_base_v2/development_records/2026-07-06-decision-register.md

@@ -47,7 +47,10 @@
 | D-022 | 用户-知识库授权先放在用户管理中维护。 | 已废弃 | 2026-07-07 需求调整后，一期不再按人分配知识库，已开放知识库默认所有用户可见。 |
 | D-023 | Agent 调试预览采用接近用户端聊天页的交互形态。 | 默认采用 | 测试问题从配置区移到预览窗口底部，减少调试和真实用户问答体验之间的差异。 |
 | D-024 | 知识库访问范围改为“开放即全员可见”。 | 用户确认 | 知识库不再精确到用户授权；用户端问答只使用已开放、未禁用知识库，用户管理不再承担知识库授权职责。 |
-| D-025 | 学员批量导入一期先支持 CSV 文本粘贴。 | 默认采用 | 避免先引入复杂 Excel 解析和上传组件；后续需要时再扩展 xlsx 上传。 |
+| D-025 | 学员批量导入一期先支持 CSV 文本粘贴。 | 已废弃 | 2026-07-07 需求调整为 Excel 模板导入，CSV 文本粘贴不再作为正式后台入口。 |
+| D-026 | 学员批量导入正式入口改为 Excel 模板上传。 | 用户确认 | 后台提供模板下载和 Excel 上传导入；导入结果展示新增、更新、失败及失败原因。 |
+| D-027 | Agent 调试预览采用接近 DeepSeek 等聊天产品的显示方式。 | 用户确认 | 预览窗口以真实聊天体验为目标，支持连续对话、底部输入和生成中状态。 |
+| D-028 | 系统配置页面从占位 Key/Value 调整为中文分组配置表单。 | 用户确认 | 配置保存到 `sys_system_config`，默认每日额度接入学员新增和导入逻辑；其他配置作为后续运行时读取的统一入口。 |
 
 ## 待确认决策
 

ai_knowledge_base_v2/development_records/2026-07-06-phase1-scope.md

@@ -40,13 +40,13 @@
 | --- | --- | --- |
 | 管理员登录 | 必须 | 用户名 + 密码。 |
 | Dashboard | 必须 | 展示用户、聊天、Token 等核心统计；AI 成功率/失败率一期不展示。 |
-| 用户管理 | 必须 | 查询、详情、手动添加学员、批量导入学员、启用/禁用、删除、设置额度和有效期。 |
+| 用户管理 | 必须 | 查询、详情、手动添加学员、Excel 模板批量导入学员、启用/禁用、删除、设置额度和有效期。 |
 | 管理员管理 | 必须 | 仅超级管理员可维护管理员账号。 |
 | 知识库管理 | 必须 | 新增、编辑、删除、启用/禁用飞书知识库。 |
-| Prompt 管理 | 必须 | 查看、编辑、保存、恢复默认；保存后立即生效。 |
+| Prompt / Agent 管理 | 必须 | 查看、编辑、保存、恢复默认；选择模型和知识库；在聊天式预览窗口中调试 Agent。 |
 | AI 模型管理 | 必须 | 新增、编辑、启用、删除模型；同一时间仅一个模型启用。 |
 | 聊天记录 | 必须 | 查询、详情、导出。 |
-| 系统配置 | 必须 | 登录有效期、每日聊天次数、AI 超时、飞书重试次数、上下文长度、是否展示引用来源。 |
+| 系统配置 | 必须 | 以中文分组表单维护登录有效期、每日聊天次数、AI 超时、飞书重试次数、上下文长度、是否展示引用来源；保留原始 Key/Value 排查表。 |
 | 操作日志 | 必须 | 关键后台操作必须写日志；日志不允许删除。 |
 
 ### AI/RAG 能力

ai_knowledge_base_v2/development_records/2026-07-07-admin-experience-settings-import-change.md

@@ -0,0 +1,70 @@
+# 管理后台体验与系统配置需求变更记录
+
+日期：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 检索、是否使用 mock 模型。
+
+配置项保存到 `sys_system_config`，后台展示为中文配置项；高级表格保留原始 Key/Value 便于排查。
+
+本次实现中，默认每日聊天额度需要接入手动添加和批量导入学员逻辑；其他配置先完成持久化和后台可维护，为后续运行时接入保留明确 Key。
+
+## 验收重点
+
+1. Agent 调试预览像正常聊天窗口，可以连续提问和查看 Agent 回复。
+2. 学员管理可以下载 Excel 模板。
+3. 按模板上传 Excel 后可以导入学员，并显示导入结果。
+4. Excel 中不合法数据不会整体中断导入，失败行有明确原因。
+5. 系统设置页面不再是裸输入框，管理员可以按分组维护配置。
+6. 修改默认每日聊天额度后，新手动添加或导入且未单独填写额度的学员使用新的默认额度。

ai_knowledge_base_v2/development_records/2026-07-07-student-roster-login-change.md

@@ -35,19 +35,25 @@
 
 ### 批量导入学员
 
-一期先支持轻量导入格式：
+批量导入从轻量 CSV 文本粘贴调整为 Excel 模板导入。后台需要提供“下载模板”和“上传 Excel 导入”两个入口。
 
-```text
+模板字段：
-手机号,姓名,昵称
+
-13800000001,张三,三三
+| 字段 | 必填 | 说明 |
-13800000002,李四,
+| --- | --- | --- |
-```
+| 手机号 | 是 | 登录准入手机号，必须符合中国大陆手机号格式。 |
+| 姓名 | 是 | 学员姓名。 |
+| 昵称 | 否 | 可为空。 |
+| 每日聊天额度 | 否 | 不填时使用系统配置默认值。 |
+| 状态 | 否 | 支持“启用/禁用”或 `1/0`。 |
+| 有效期 | 否 | 不填表示不过期。 |
 
 导入规则：
 
 - 手机号必填且格式必须正确。
 - 姓名必填。
 - 昵称可为空。
+- 每日聊天额度为空时使用系统配置 `daily_chat_limit`。
 - 已存在手机号不重复创建，按导入内容更新姓名、昵称、状态和额度。
 - 已被软删除的手机号再次导入时恢复为未删除。
 - 导入结果需要返回新增数、更新数、失败数和失败明细。
@@ -71,7 +77,7 @@
 ## 验收重点
 
 1. 管理员可以手动添加学员。
-2. 管理员可以批量导入学员，并看到导入结果。
+2. 管理员可以下载 Excel 模板并批量导入学员，导入后看到结果。
 3. 已导入或手动添加的学员可以通过验证码登录。
 4. 系统中不存在的手机号不能发送验证码，也不能登录。
 5. 禁用或过期学员仍不能登录。

ai_knowledge_base_v2/development_records/README.md

@@ -39,4 +39,5 @@
 | `2026-07-07-admin-operations-completion.md` | 管理后台知识库、用户权限和 Agent 预览补齐记录。 |
 | `2026-07-07-knowledge-open-access-change.md` | 知识库访问范围改为“开放即全员可见”的需求变更记录。 |
 | `2026-07-07-student-roster-login-change.md` | 学员名单准入、手动添加和批量导入需求变更记录。 |
+| `2026-07-07-admin-experience-settings-import-change.md` | Agent 调试预览、学员 Excel 导入和系统配置补齐需求变更记录。 |
 | `../test_records/2026-07-06-phase6-verification.md` | 阶段六验证记录。 |