docs: 配置中心易用性与视觉优化设计 spec
Co-Authored-By: Claude Code <noreply@anthropic.com>
This commit is contained in:
浅念
@@ -0,0 +1,145 @@
|
||||
# 配置中心易用性与视觉优化设计（UX + 美观双线）
|
||||
|
||||
- 日期：2026-10-14
|
||||
- 状态：待评审
|
||||
- 范围：admin/ 前端（纯前端改造，后端 API 与校验零改动）
|
||||
- 前置：Phase 3 交付的配置中心（admin/src/views/config/center/，七 pane + 版本历史）
|
||||
|
||||
## 1. 背景与目标
|
||||
|
||||
配置中心现状对**非技术租户管理员**（本次优化的目标用户）不友好，四个已确认痛点：
|
||||
|
||||
1. **裸 JSON 编辑**——contact/engine/misc 三组是整组 JSON textarea，非技术用户无法使用；
|
||||
2. **安全词表太复杂**——967 行 WallPane，技术键名直接当区块标题，无从下手；
|
||||
3. **凭据/密钥交互绕**——哨兵语义（不动=保持 `__SET__`）不直观，无已配置状态反馈；
|
||||
4. **整体缺引导**——不知道每项是干嘛的、改了影响什么、改坏了怎么办。
|
||||
|
||||
同时视觉层欠账（对现状页面截图复盘得出）：全局规则被挤成卡片右上角 11px 灰字、危险操作无隔离、密码字段无状态区分、长表单单列动线过长、「已实装」徽标全绿即噪音。
|
||||
|
||||
**目标**：体验度（结构重组/引导/保护）与美观度（排版/层级/一致性）双线优化，使非技术租户管理员能独立完成日常配置任务且不畏惧。
|
||||
|
||||
**成功判据**：一个不懂 JSON/正则的租户管理员，能独立完成——改品牌与欢迎语、改价格/联系方式话术、填 SMTP 并测试通过、开关号码补全——全程不需要外部解释；任何误操作可经版本历史回滚且离开未保存页有确认保护。
|
||||
|
||||
## 2. 总体方案
|
||||
|
||||
**分层双模式**（信息架构）+ **视觉基线**（统一样式规范）+ **体验补强**（保护与反馈），全部落在 admin/ 内，不动整组替换语义、试金石预演、密钥哨兵契约。
|
||||
|
||||
## 3. 导航重组
|
||||
|
||||
现状 8 项平铺技术组名（品牌/提示词/安全词表/联系方式/凭据/引擎/杂项/版本）。改为：
|
||||
|
||||
**⭐ 常用配置**（日常自助，放心改）：
|
||||
- 品牌与外观（brand）——聊天窗标题/颜色/头像/欢迎语
|
||||
- AI 话术（wall）——问价格/要联系方式时 AI 怎么回
|
||||
- 公司资料（prompts）——AI 介绍你公司时依据的内容
|
||||
- 联系方式（contact）——要 WhatsApp/邮箱的行为开关
|
||||
- 凭据与通知（creds）——邮件/推送/AI 密钥 + 连通测试
|
||||
|
||||
**⚙️ 高级配置**（引擎级参数，改错有影响）：
|
||||
- 聊天限流（engine）——每 IP 发言/连接上限（折叠区含会话上下文映射）
|
||||
- 国家区号映射（misc）——国名 → 区号补全规则
|
||||
|
||||
**🕘 版本历史**——独立于两层之外的第三段（救援入口定位：「改坏了？这里一键回滚」）。
|
||||
|
||||
规则：
|
||||
- 导航组名任务化，副标题只在导航与卡头出现，不再挤页面副标题（页副标题改为一句总述）；
|
||||
- 「已实装」徽标移除（8/8 全实装后为噪音）；
|
||||
- 菜单结构不变仍是组件内 ElMenu（不与全局菜单/角色权限耦合）。
|
||||
|
||||
## 4. 视觉基线（所有 pane 统一）
|
||||
|
||||
1. **卡片头三行结构**：`ArtSvgIcon 图标 + 任务名` → 一句话「这是干嘛的」→ 组级信息条（浅灰底：整组保存 · 立即生效 · 产生新版本可回滚；带 • 字段留空=沿用平台默认）。全局规则一次说清，不再逐字段重复、不再挤标题右侧。
|
||||
2. **密钥字段四件套**（SecretField 组件）：`已配置 ✓ / 未配置` 状态徽章 + `••••••` 掩码态占位 + 👁 显示切换 + 红字「清除」（配确认）；**pending 态**：`已输入新值(未保存)` / `将清除(未保存)` 徽章。提交值计算（保持/新值/清除 → payload，含 `__SET__` 哨兵契约）放 model.ts 纯函数，复用 admin/src/api/mask.ts 既有 helper。
|
||||
3. **双列网格**：短字段（服务器/端口/开关类）并栏；长字段（URL/话术/JSON）独占整行；标签宽度统一，说明文字放字段下方不放标签里。
|
||||
4. **底部操作条**：左「出问题？回滚 →」（链到版本历史）；右「备注（选填）+ 保存主按钮」。**不放版本号/时间戳**——配置版本是租户级整份快照，无组级版本，卡片级展示会误导；版本号只在页头全局展示（现状保留）。
|
||||
5. **危险区隔离**：重置出厂从卡片标题行下沉到卡底单行浅红危险行（红边框浅底 + 红描边按钮），强警示留给确认对话框（明示组名与「恢复出厂档案值」）；多卡 pane（creds 三卡）不叠加红区轰炸。
|
||||
6. **图标与配色**：一律用模板 `ArtSvgIcon` 图标体系（禁 emoji）；新样式一律 `var(--el-*)` / `var(--art-*)` 语义色（禁硬编码色值），验收含暗色模式两态检查。
|
||||
|
||||
## 5. 各 pane 设计
|
||||
|
||||
### 5.1 品牌与外观（brand，轻改）
|
||||
现有表单保留，套视觉基线；预览卡与嵌入代码卡层级理顺（表单主列、预览+嵌入代码右列或紧随其后）；头像上传流程不变。
|
||||
|
||||
### 5.2 AI 话术（wall 重组，同组不拆、一个 pane）
|
||||
**主面 = 4 张场景卡**。分组依据引擎消费点（app/engine/services/boundary_filter.py:104,117——`has_contact` 选池），**同一场景 × 未留资/已留资两状态放同一张卡**：
|
||||
|
||||
| 场景卡 | 内容键 | 时机说明（卡头文案定稿于此） |
|
||||
|---|---|---|
|
||||
| 问价格等敏感话题怎么回 | deflections / deflections_contact | 客户还没留联系方式时 / 已经留过之后 |
|
||||
| 怎么把话题引到要联系方式 | pivots / pivots_contact | 客户还没留联系方式时 / 已经留过之后 |
|
||||
| 客户要我们的联系方式怎么回 | no_contact（web/app/already 三句，单值非语言池） | 网页会话有按钮 / App 会话无按钮 / 客户已留过 |
|
||||
| 号码缺国家代码怎么补要 | cc_templates（ask/wall/note/echo 四变体） | 直接请重发 / 拦截后请重发 / 轻补指引 / 确认回显 |
|
||||
|
||||
- 每卡：场景说明（什么时候触发）+ 语言 tabs + 一行一句行编辑器（增删行）；
|
||||
- **语言 tabs 动态**：取组内各池实际语言键的并集，不硬编码；至少保留 en/zh（wall_schema._REQUIRED_POOLS 约束，删空必留语言时前端拦截）；提供「＋添加语言」；
|
||||
- **模板变量保护**：话术含 `{intl}` `{shown}` `{no_contact_web}` 等占位符——编辑器内高亮显示，保存校验「从快照里出现过的变量被删除」时警告确认；
|
||||
- **折叠警示区**（默认收起 + 警示条「引擎级规则，改错可能导致拦截失灵或 AI 行为异常，不确定就别动」）：拦截规则（price_patterns / zero_number / reask_patterns / triggers，正则双形态行编辑器保留）+ AI 提醒指令（reminders 六类）；
|
||||
- 试金石面板保留主面底部（「试金石 · 话术预演」），保存前自动预演 + 拦截/替换二次确认逻辑不动；
|
||||
- 未接管键透传模式保留。
|
||||
|
||||
### 5.3 公司资料（prompts 重组，同组不拆）
|
||||
主面 = company_facts（公司/产品资料，AI 介绍你公司的依据）；折叠警示区 = system（AI 人格）/ extractor（线索提取）/ evaluator（意向评估）。字节实时计数（50KB/100KB）保留；保存备注必填保留（AI 行为源头）；折叠区未展开的编辑器值从快照原样进 payload（读-改-写整组）。
|
||||
|
||||
### 5.4 联系方式（contact 表单化）
|
||||
- `cc_completion` 开关：「客户号码缺国家代码时，自动按 IP 补全并跟客户确认」；
|
||||
- `email_light_ask` 开关：「客户留了号码没留邮箱时，礼貌补要一次邮箱」；
|
||||
- `template_languages` 标签输入：「邮件通知使用的语言」+ **诚实标注「暂未生效（引擎接线排期中）」**（Phase 3 清理单 #8 未结）；
|
||||
- 未知键透传保留；后端 400 字段路径错误内联展示保留。
|
||||
|
||||
### 5.5 凭据与通知（creds）
|
||||
- 三卡（邮件/推送/AI）套视觉基线；密钥字段全部换 SecretField；
|
||||
- SMTP 测试与推送探测归入「连通测试」小节，按钮明示真实出站（「发送测试邮件（真发一封到 ×××）」/「推送连通探测（发送空批量）」）；
|
||||
- 限流友好反馈：后端 429（每租户每端点 15 分钟 5 次）翻译为白话「测试太频繁，15 分钟内最多 5 次，稍后再试」；
|
||||
- 数值前端预检 + 后端 400 双层保留。
|
||||
|
||||
### 5.6 聊天限流（engine 表单化）
|
||||
- `rate_limit_per_hour` / `ws_conn_limit` 数字输入（白话说明 + 推荐值提示）；
|
||||
- 折叠区：会话上下文映射 `context_seed_keys` 键值对编辑器（产品字段 → 上下文种子键）；
|
||||
- 未知键透传；0 语义校验沿用（rate_limit 与 ws_conn_limit 的 0 语义已统一）。
|
||||
|
||||
### 5.7 国家区号映射（misc 表单化）
|
||||
`name_to_region_extras` 键值对编辑器（国名 → ISO 区号）；未知键透传。
|
||||
|
||||
### 5.8 版本历史（versions，保留 + 入口强化）
|
||||
现有列表/两版对比/回滚/组级重置保留；被各 pane 底部操作条「出问题？回滚」直达。
|
||||
|
||||
## 6. 体验补强（跨 pane）
|
||||
|
||||
1. **未保存离开保护（现状缺陷，最高价值）**：切导航组 / 切租户 / 离开路由时，若有未保存草稿，ElMessageBox 确认（「有未保存的修改，离开将丢失」）。实现：各 pane 向父层上报 dirty 状态（provide/inject 或 emit），index.vue 统一拦截 onGroupSelect / activeSlug watch / onBeforeRouteLeave。
|
||||
2. **密钥 pending 态**：见视觉基线 §4.2。
|
||||
3. **测试端点限流反馈**：见 §5.5。
|
||||
4. **模板变量保护**：见 §5.2。
|
||||
5. **保存反馈一致性**：成功 toast + 页头版本号刷新（现状保留），不引入卡片级版本展示。
|
||||
|
||||
## 7. 其他页面轻量打磨（不动布局）
|
||||
|
||||
仪表盘/会话列表/统计/平台设置/租户管理：文案口语化、空态描述具体化（「暂无会话——客户开始聊天后在这里出现」式）、错误提示白话化。逐页小清单在实施计划里列。
|
||||
|
||||
## 8. 技术约定
|
||||
|
||||
- **JsonGroupPane 退役**，contact/engine/misc 三份表单 pane 取代；字段映射进 model.ts 纯函数：`snapshotToForm(group)` / `formToPayload(form, snapshot)`（未知键从 snapshot 合并）。
|
||||
- **SecretField.vue 新组件**（密钥四件套）；提交值计算纯函数进 model.ts；**不引入组件挂载测试**——沿用「视图逻辑沉淀 model.ts 纯函数 + vitest 直测」的既有约定。
|
||||
- **WallPane 拆分**：场景卡子组件（如 ScenarioCard.vue，四实例）+ 高级折叠子组件；文件聚焦，单文件不再膨胀。
|
||||
- **契约不动**：PUT config 整组替换（前端读-改-写）、`__SET__` 哨兵（mask.ts）、试金石预演、未接管键透传、语言池 en/zh 必留（wall_schema）。
|
||||
- **样式**：语义色 var()；暗色模式两态验收；components.d.ts 行尾漂移纪律照旧（build 后 `git diff --ignore-cr-at-eol` 为空即 checkout 还原）。
|
||||
- **测试策略**：model.ts 新增纯函数全覆盖（表单映射/未知键合并/密钥三态提交值/语言池动态计算/模板变量 diff 检测/dirty 判定）；既有 164 vitest 不回归；`pnpm build`（vue-tsc + vite）零错误。
|
||||
- **分批交付**（每批独立可验收）：
|
||||
1. 视觉基线 + SecretField + 导航分层 + brand/creds 改造；
|
||||
2. wall 重组（场景卡 + 折叠区 + 语言 tabs + 变量保护）；
|
||||
3. prompts 重组 + contact/engine/misc 表单化 + 脏保护；
|
||||
4. 其他页面轻量打磨 + 全局回归。
|
||||
|
||||
## 9. 非目标
|
||||
|
||||
- 不动后端 API/校验/限流（含 400 detail 格式）；
|
||||
- 不动整组替换语义与哨兵契约；
|
||||
- 不做按角色的差异化导航（两层对超管/租户管理员一致）；
|
||||
- 不做 admin i18n（中文单语，目标用户为中文运营者）；
|
||||
- 不做提示词沙箱试聊、推送告警等已列入演进方向的功能。
|
||||
|
||||
## 10. 验收标准
|
||||
|
||||
1. vitest 全绿（新增纯函数测试含上述边界）+ `pnpm build` 零错误 + 后端 pytest 不动仍 632+2skip；
|
||||
2. 明/暗两主题下配置中心全 pane 无硬编码色值穿帮；
|
||||
3. 非技术任务流走查：改品牌→改话术（含加语言）→填 SMTP→测试通过→开关补全→故意改坏→版本回滚，全程无 JSON 暴露、无未保存静默丢失；
|
||||
4. 词表保存仍过试金石预演；密钥 GET 掩码/PUT 哨兵行为与改造前一致（契约测试不破）。
|
||||
Reference in New Issue
Block a user