diff --git a/ai_knowledge_base_v2/development_records/2026-07-06-api-priority.md b/ai_knowledge_base_v2/development_records/2026-07-06-api-priority.md index fd6099c..692aaaa 100644 --- a/ai_knowledge_base_v2/development_records/2026-07-06-api-priority.md +++ b/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` | 批量修改聊天次数 | diff --git a/ai_knowledge_base_v2/development_records/2026-07-06-decision-register.md b/ai_knowledge_base_v2/development_records/2026-07-06-decision-register.md index a9a3328..f59e69f 100644 --- a/ai_knowledge_base_v2/development_records/2026-07-06-decision-register.md +++ b/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`，默认每日额度接入学员新增和导入逻辑；其他配置作为后续运行时读取的统一入口。 | ## 待确认决策 diff --git a/ai_knowledge_base_v2/development_records/2026-07-06-phase1-scope.md b/ai_knowledge_base_v2/development_records/2026-07-06-phase1-scope.md index 6ee03e8..0a23e30 100644 --- a/ai_knowledge_base_v2/development_records/2026-07-06-phase1-scope.md +++ b/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 能力 diff --git a/ai_knowledge_base_v2/development_records/2026-07-07-admin-experience-settings-import-change.md b/ai_knowledge_base_v2/development_records/2026-07-07-admin-experience-settings-import-change.md new file mode 100644 index 0000000..6c3d30d --- /dev/null +++ b/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. 修改默认每日聊天额度后，新手动添加或导入且未单独填写额度的学员使用新的默认额度。 diff --git a/ai_knowledge_base_v2/development_records/2026-07-07-student-roster-login-change.md b/ai_knowledge_base_v2/development_records/2026-07-07-student-roster-login-change.md index 9f203bf..4c7146e 100644 --- a/ai_knowledge_base_v2/development_records/2026-07-07-student-roster-login-change.md +++ b/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. 禁用或过期学员仍不能登录。 diff --git a/ai_knowledge_base_v2/development_records/README.md b/ai_knowledge_base_v2/development_records/README.md index a4266c0..4382629 100644 --- a/ai_knowledge_base_v2/development_records/README.md +++ b/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` | 阶段六验证记录。 |