# 配置中心易用性与视觉优化 实施计划 > **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. **Goal:** 按spec（docs/superpowers/specs/2026-10-14-config-center-ux-visual-design.md）将配置中心重组为分层双模式并统一视觉基线——体验度（结构/引导/保护）与美观度（排版/层级/一致性）双线优化，纯前端零后端改动。 **Architecture:** admin/ SPA 内改造 config/center：新增共享基线组件（ConfigCard 卡壳 / SecretField 密钥四件套 / KeyValueEditor 键值行编辑），WallPane 拆场景卡+高级折叠，JsonGroupPane 退役为三份表单 pane；全部视图逻辑沉淀 model.ts 纯函数（vitest 直测、无组件挂载测试——项目铁律）；PUT 整组替换、`__SET__` 哨兵、试金石预演、未接管键透传四契约不动。 **Tech Stack:** Vue 3.4 + TypeScript + Element Plus（auto-import：ref/computed/ElMessage 等无需 import）+ vitest；样式用 `var(--art-*)`/`var(--el-*)` 语义色（暗色模式两态验收）；图标用 ArtSvgIcon（模板已有，禁 emoji）。 **执行环境注意（Windows）：** - 所有命令在仓库根 `D:\refactor\all-kefu` 下执行；前端命令先 `cd admin` - 单测：`cd admin && pnpm exec vitest run src/views/config/center/__tests__/model.test.ts`（全量：`pnpm test`） - 构建：`cd admin && pnpm build`（vue-tsc --noEmit && vite build）；build 后若 `components.d.ts`/`auto-imports.d.ts` 出现行尾漂移：`git diff --ignore-cr-at-eol` 为空则 `git checkout -- admin/src/types/import/components.d.ts admin/src/types/import/auto-imports.d.ts` 还原（入库版优先纪律） - **新组件须显式 import**：view 内新组件（ConfigCard/SecretField/KeyValueEditor/ContactFormPane/EngineFormPane/MiscFormPane/wall/ScenarioCard/wall/WallAdvanced）不被 unplugin-vue-components 自动注册（它只扫 src/components）——消费方 SFC 必须 `import ConfigCard from './ConfigCard.vue'` 等（与 index.vue 显式 import 既有 panes 同款）；漏 import 构建不报错但渲染空白，dev 走查必看 - **ElMessageBox 非 auto-import**（auto-imports 只有 ElMessage）：用到 `ElMessageBox.confirm` 的文件顶部 `import { ElMessageBox } from 'element-plus'`（reset.ts 同款） - 本地验收环境：Docker 容器 all-kefu-app-1（8018，`/admin/`）跑的是**构建产物**——前端改动本地验收用 dev server：`cd admin && pnpm dev`（默认 3006，代理已配好）；超管 admin / 密码 12345678（本机测试值）；登录滑块为纯前端校验可直接拖 - 每个任务收尾 `git status --short` 应只剩本任务相关文件；截图等临时产物放 `.superpowers/`（已 gitignore），收尾删净 --- ## Batch 1：视觉基线 + SecretField + 导航分层 + brand/creds（✅ 2026-10-14 完成——commits 0a41352/6881ccc/2e00db1+46dfbef/712c5f9/06e28e4/680c4ba；全任务过双审；视觉走查通过；遗留打磨项记 Task 15：色列宽度平衡/预览卡文案去重/头像提示样式） ### Task 1: model.ts 新增 secretFieldState 纯函数（TDD） **Files:** - Modify: `admin/src/views/config/center/model.ts`（import 行 + 新增区块） - Test: `admin/src/views/config/center/__tests__/model.test.ts`（追加） - [ ] **Step 1: 写失败测试**——在 model.test.ts 追加： ```ts import { secretFieldState } from '../model' describe('secretFieldState（密钥四件套展示态）', () => { it('未配置：input 空 + 无掩码', () => { const s = secretFieldState('', '', false) expect(s).toMatchObject({ badge: 'unset', badgeType: 'info', badgeLabel: '未配置' }) expect(s.placeholder).toContain('未设置') }) it('已配置：掩码哨兵且未动', () => { const s = secretFieldState('', '__SET__', false) expect(s).toMatchObject({ badge: 'configured', badgeType: 'success', badgeLabel: '已配置' }) expect(s.placeholder).toContain('留空保持不变') }) it('pending-new：输入了新值（优先级最高）', () => { const s = secretFieldState('new-secret', '__SET__', true) expect(s).toMatchObject({ badge: 'pending-new', badgeType: 'warning', badgeLabel: '已输入新值 · 未保存' }) }) it('pending-clear：清除了已配置值', () => { const s = secretFieldState('', '__SET__', true) expect(s).toMatchObject({ badge: 'pending-clear', badgeType: 'warning', badgeLabel: '将清除 · 未保存' }) }) }) ``` - [ ] **Step 2: 跑测试确认失败**——`cd admin && pnpm exec vitest run src/views/config/center/__tests__/model.test.ts`，预期 FAIL：secretFieldState 未导出 - [ ] **Step 3: 实现**——model.ts 顶部 import 行改为 `import { MASKED_SENTINEL, isMaskedSentinel, secretToSubmit } from '@/api/mask'`；在「凭据三组」区块（`normalizeAiCredsGroup` 之后）插入： ```ts // ---- SecretField 展示态（视觉基线 §4.2；提交值仍走 secretToSubmit） ----------------- /** 密钥字段徽章四态：已配置 / 未配置 / 已输入新值(未保存) / 将清除(未保存) */ export type SecretFieldBadge = 'configured' | 'unset' | 'pending-new' | 'pending-clear' export interface SecretFieldState { badge: SecretFieldBadge /** ElTag type 映射（configured=success / unset=info / pending-*=warning） */ badgeType: 'success' | 'info' | 'warning' badgeLabel: string placeholder: string } /** 输入值 + GET 掩码态 + 清除开关 → 徽章/占位文案（纯展示；优先级 新值 > 清除 > 已配置 > 未配置） */ export function secretFieldState( input: string, masked: string, cleared: boolean ): SecretFieldState { if (input !== '') { return { badge: 'pending-new', badgeType: 'warning', badgeLabel: '已输入新值 · 未保存', placeholder: '' } } if (cleared) { return { badge: 'pending-clear', badgeType: 'warning', badgeLabel: '将清除 · 未保存', placeholder: '' } } if (isMaskedSentinel(masked)) { return { badge: 'configured', badgeType: 'success', badgeLabel: '已配置', placeholder: '已设置，输入新值可更换（留空保持不变）' } } return { badge: 'unset', badgeType: 'info', badgeLabel: '未配置', placeholder: '未设置，输入新值' } } ``` - [ ] **Step 4: 跑测试确认通过**——同 Step 2 命令，预期 4 个新用例 PASS - [ ] **Step 5: Commit**——`git add admin/src/views/config/center/model.ts admin/src/views/config/center/__tests__/model.test.ts && git commit -m "feat(admin): secretFieldState 密钥四态展示纯函数"` ### Task 2: SecretField.vue 组件 **Files:** - Create: `admin/src/views/config/center/SecretField.vue` - [ ] **Step 1: 创建组件**（全量代码）： ```vue ``` - [ ] **Step 2: 构建验证**——`cd admin && pnpm build`，预期零错误（vue-tsc 通过） - [ ] **Step 3: Commit**——`git add admin/src/views/config/center/SecretField.vue && git commit -m "feat(admin): SecretField 密钥四件套组件"` ### Task 3: ConfigCard.vue 基线卡壳 + 共享样式 **Files:** - Create: `admin/src/views/config/center/ConfigCard.vue` - [ ] **Step 1: 创建组件**（全量代码）： ```vue ``` - [ ] **Step 2: 构建验证**——`cd admin && pnpm build`，零错误 - [ ] **Step 3: Commit**——`git add admin/src/views/config/center/ConfigCard.vue && git commit -m "feat(admin): ConfigCard 视觉基线卡壳"` ### Task 4: index.vue 导航分层 **Files:** - Modify: `admin/src/views/config/center/index.vue:519-562`（GROUP_NAV/IMPLEMENTED_GROUPS/activeGroupLabel 区）、`index.vue:46-47`（页副标题）、`index.vue:87-95`（导航模板）、`index.vue:543`（JSON_GROUPS） - [ ] **Step 1: 替换导航数据结构**——`GROUP_NAV`/`IMPLEMENTED_GROUPS` 区块改为： ```ts /** 导航项：任务名 + 副标题（导航与卡头共用文案源） */ interface NavItem { key: GroupKey label: string sub: string } /** 分层双模式（spec §3）：常用 = 日常自助；高级 = 引擎级参数 */ const NAV_SECTIONS: Array<{ title: string; icon: string; items: NavItem[] }> = [ { title: '常用配置', icon: 'solar:star-line-duotone', items: [ { key: 'brand', label: '品牌与外观', sub: '聊天窗标题/颜色/头像/欢迎语' }, { key: 'wall', label: 'AI 话术', sub: '问价格/要联系方式时 AI 怎么回' }, { key: 'prompts', label: '公司资料', sub: 'AI 介绍你公司时依据的内容' }, { key: 'contact', label: '联系方式', sub: '要 WhatsApp/邮箱的行为开关' }, { key: 'creds', label: '凭据与通知', sub: '邮件/推送/AI 密钥 + 连通测试' } ] }, { title: '高级配置', icon: 'solar:settings-minimalistic-line-duotone', items: [ { key: 'engine', label: '聊天限流', sub: '每 IP 发言/连接上限' }, { key: 'misc', label: '国家区号映射', sub: '国名 → 区号补全规则' } ] } ] /** 版本历史：独立于两层之外的救援入口（spec §3） */ const VERSIONS_NAV: NavItem = { key: 'versions', label: '版本历史', sub: '改坏了？这里一键回滚' } /** 全部导航项扁平表（activeGroupLabel / 查找用） */ const ALL_NAV_ITEMS: NavItem[] = [ ...NAV_SECTIONS.flatMap((s) => s.items), VERSIONS_NAV ] ``` `activeGroupLabel` 改为 `ALL_NAV_ITEMS.find((i) => i.key === activeGroup.value)?.label ?? ''`；删除 `IMPLEMENTED_GROUPS`。**GroupKey 类型重定义**（原 `typeof GROUP_NAV` 已删）——用显式联合字面量（**不可**写 `(typeof ALL_NAV_ITEMS)[number]['key']`：NavItem.key 标注为 GroupKey 会构成循环类型别名，tsc 报 TS2456/TS2502）： ```ts type GroupKey = | 'brand' | 'wall' | 'prompts' | 'contact' | 'creds' | 'engine' | 'misc' | 'versions' ``` - [ ] **Step 2: 重写导航模板**——`` 内的 ElMenu 区改为： ```html
救援
{{ VERSIONS_NAV.label }} {{ VERSIONS_NAV.sub }}
``` 同步新增 scoped 样式（.nav-section-title 小节标题 12px 大写字距、.nav-item-text 两行布局 .nav-sub 11px 灰）；页副标题（index.vue:47）改为 `按左侧分组编辑——保存后立即生效并产生新版本，历史可随时回滚`。 - [ ] **Step 3: 验证**——`cd admin && pnpm build` 零错误；`pnpm dev` 打开配置中心，导航呈两层 + 版本独立、无「已实装」徽标、各组 pane 正常切换（暂用旧 pane 不影响） - [ ] **Step 4: Commit**——`git add admin/src/views/config/center/index.vue && git commit -m "feat(admin): 配置中心导航分层双模式（常用/高级/版本独立）"` ### Task 5: CredsPane 套基线 + SecretField 接入 **Files:** - Modify: `admin/src/views/config/center/CredsPane.vue`（三卡模板重排，脚本层函数全部保留） - [ ] **Step 1: 邮件卡改造**——`` 换 ``；表单区改双列 grid（`
` 包 ElFormItem：服务器/端口同排、账号/发件人同排、密码独占、通知邮箱独占——样式 `.form-grid { display:grid; grid-template-columns:1fr 1fr; gap:0 16px; .span-2 { grid-column:span 2 } }`）；SMTP 密码整块换 ``（**masked 传原始掩码值**——SecretField 内部 v-if 按 masked===哨兵 渲染清除按钮，传 `cleared ? '' : masked` 会让按钮在清除态消失、恢复保持不可达；徽章优先级 secretFieldState 已处理 cleared>masked）。原 secret-row/清除按钮/field-warn 模板删除。**提交路径不动**：onSaveEmail 里 buildEmailCredsPayload(form, emailPasswordCleared ? '' : emailPasswordMasked) 维持现状（脚本层三元，与模板 prop 无关）；底部操作条： ```html ``` emits 声明追加 `(e: 'navigate', group: string): void`。 - [ ] **Step 2: 推送/AI 两卡同款改造**——推送 ConfigCard `icon="solar:upload-square-line-duotone" title="线索推送" subtitle="新线索实时推送到你的业务系统（UniService）"`，pushApiKey 换 SecretField；AI 卡 `icon="solar:cpu-bolt-line-duotone" title="AI 服务" subtitle="对话引擎调用的大模型服务凭据"`，aiApiKey 换 SecretField；各自 footer/danger 同款 - [ ] **Step 3: 连通测试小节归置**——两处测试区（`ElDivider` 连通性验证）保持卡内底部，邮件测试按钮文案改「发送测试邮件（真发一封）」、hint 首词「后端用」改「系统用」；确认 429 响应走既有 error 内联路径（后端 detail 已是白话「测试端点调用过于频繁(每租户 15 分钟 5 次)」，无需前端翻译——onTestEmail 的 catch 已内联展示，验证即可） - [ ] **Step 4: 验证 + Commit**——`pnpm build` 零错误；`pnpm dev` 走查：密码徽章四态（未配置/已配置/输入新值/清除）、清除后保存提交空串行为不变（既有 vitest 契约不回归）；`git commit -m "feat(admin): 凭据页套视觉基线+SecretField 四件套"` ### Task 6: 品牌卡套基线 **Files:** - Modify: `admin/src/views/config/center/index.vue`（brand pane 模板区，约 99-260 行；另两处小修） - Modify: `admin/src/views/config/center/CredsPane.vue`（三处 info 文案去「带 • 的」前缀） - [ ] **Step 1: 表单卡换 ConfigCard**——`icon="solar:palette-round-line-duotone" title="品牌与外观" subtitle="客户看到的聊天窗口长什么样" info="整组保存 · 立即生效；图片与链接留空 = 不展示"`；短字段（标题/主色/WhatsApp/邮箱/占位提示）双列 grid、话题标签与隐私链接独占；footer/danger 同 Task 5 模式（footer-left 回滚、footer-right 备注+保存、danger 重置出厂）。brand 是 index.vue 内联块——回滚按钮直接 `@click="onGroupSelect('versions')"`（无需 emit） - [ ] **Step 2: 预览与嵌入代码卡理顺**——预览卡与嵌入代码卡紧随表单卡，预览卡头部加副标题「本地简化预览（真机效果以嵌入站点为准）」 - [ ] **Step 2b: （Task 5 评审折入）navigate 接线 + 文案清理 + 死分支剪除**——① index.vue 的 `` 挂载处补 `@navigate="onGroupSelect"`；② CredsPane 三卡 info 文案的「带 • 的字段留空 = 沿用平台默认」改为「字段留空 = 沿用平台默认」（• 标记约定未实装到 label，删引用防误导）；③ 剪除 pane 条件链尾部不可达的 v-else 占位卡（「后续任务实装」——8 组全实装后为死分支） - [ ] **Step 3: 验证 + Commit**——`pnpm build` + dev 走查（改标题/颜色预览即时反映；凭据页点「出问题？回滚 →」能跳版本历史）；`git commit -m "feat(admin): 品牌卡套视觉基线（Batch 1 收口）"` --- ## Batch 2：wall 重组（场景卡 + 高级折叠）（✅ 2026-10-14 完成——commits 2e6811a+36fe534/ab0cf9f/0553ccc/12b8dab；全任务过双审；视觉+交互走查通过：场景卡语言切换/试金石预演实测；遗留：试金石异步窗口内编辑被旧 payload 覆盖（既有性状，可选加固）） ### Task 7: model.ts wall 辅助纯函数（TDD） **Files:** - Modify: `admin/src/views/config/center/model.ts`（wall 区块追加） - Test: `admin/src/views/config/center/__tests__/model.test.ts`（追加） - [ ] **Step 1: 写失败测试**： ```ts import { poolLanguages, templateVariables, removedTemplateVariables, collectRemovedWallVariables, WALL_SCENARIOS, SCENARIO_WHEN_LABELS } from '../model' describe('poolLanguages（场景卡语言 tabs）', () => { it('多池语言并集，必留语言在前、附加语言按序', () => { expect(poolLanguages({ deflections: { en: ['a'], zh: ['b'], es: ['c'] }, deflections_contact: { en: ['a'], pt: ['d'] } })).toEqual(['en', 'zh', 'es', 'pt']) }) it('空池 → 空数组', () => { expect(poolLanguages({ deflections: {}, deflections_contact: {} })).toEqual([]) }) }) describe('模板变量保护', () => { it('提取 {var} 变量', () => { expect(templateVariables('到 {intl} 联系您，{shown} 已留')).toEqual(['intl', 'shown']) }) it('删除快照出现过的变量被检出', () => { expect(removedTemplateVariables('发到 {intl} 联系', '发到手机联系')).toEqual(['intl']) expect(removedTemplateVariables('发到 {intl}', '发到 {intl}')).toEqual([]) }) it('wall 整组递归检出（池+模板+提醒），同变量去重（全域消失才报）', () => { const before = { deflections: { en: ['call {intl}'] }, cc_templates: { echo: { en: 'at {intl}' } }, reminders: { cc_guide: { echo: '补全为 {intl}' } } } const after = { deflections: { en: ['call me'] }, cc_templates: { echo: { en: 'at email' } }, reminders: { cc_guide: { echo: '补全为手机号' } } } expect(collectRemovedWallVariables(before, after)).toEqual(['intl']) }) it('快照缺键不误报', () => { expect(collectRemovedWallVariables({}, { deflections: { en: ['x'] } })).toEqual([]) }) it('删除含变量的尾行/整语言键同样检出（位置无关）', () => { const before = { deflections: { en: ['plain', 'call {intl}'] } } expect(collectRemovedWallVariables(before, { deflections: { en: ['plain'] } })).toEqual(['intl']) const before2 = { cc_templates: { echo: { en: 'at {intl}' } } } expect(collectRemovedWallVariables(before2, { cc_templates: { echo: {} } })).toEqual(['intl']) }) }) describe('WALL_SCENARIOS（场景卡定义）', () => { it('两池场景卡：同场景 × 未留资/已留资（boundary_filter has_contact 语义）', () => { const price = WALL_SCENARIOS.find((s) => s.key === 'price') expect(price?.pools.map((p) => p.field)).toEqual(['deflections', 'deflections_contact']) expect(price?.pools.map((p) => p.when)).toEqual(['not_given', 'given']) }) it('状态标签契约（ScenarioCard 消费）', () => { expect(SCENARIO_WHEN_LABELS).toEqual({ not_given: '客户还没留联系方式时', given: '客户已经留过之后' }) }) }) ``` - [ ] **Step 2: 跑测试确认失败**——预期 4 组 FAIL（函数未导出） - [ ] **Step 3: 实现**——model.ts wall 区块（`buildWallPayload` 之后）插入： ```ts // ---- wall 重组辅助（场景卡 / 语言 tabs / 模板变量保护——spec §5.2） ------------------ /** 池语言并集（场景卡 tabs 数据源；必留语言在前、附加语言按字母序——排序稳定） */ export function poolLanguages( pools: Record> ): string[] { const set = new Set() for (const pool of Object.values(pools)) { for (const lang of Object.keys(pool)) set.add(lang) } const required = POOL_REQUIRED_LANGS.filter((l) => set.has(l)) const extra = [...set] .filter((l) => !(POOL_REQUIRED_LANGS as readonly string[]).includes(l)) .sort() return [...required, ...extra] } /** 场景卡池位：field = wall 组键；when = 客户联系方式状态（boundary_filter has_contact） */ export interface ScenarioPool { field: PoolField when: 'not_given' | 'given' } export interface ScenarioDef { key: 'price' | 'pivot' title: string note: string pools: readonly ScenarioPool[] } /** 两张双状态场景卡（no_contact / cc_templates 结构非池，模板层直接渲染不走本表） */ export const WALL_SCENARIOS: readonly ScenarioDef[] = [ { key: 'price', title: '问价格等敏感话题怎么回', note: '客户问到价格/优惠/交付等不便直接回答的话题时，AI 用这些话术引导留联系方式', pools: [ { field: 'deflections', when: 'not_given' }, { field: 'deflections_contact', when: 'given' } ] }, { key: 'pivot', title: '怎么把话题引到要联系方式', note: 'AI 主动转向时用的话术——先回应客户话题，再顺势要 WhatsApp 或邮箱', pools: [ { field: 'pivots', when: 'not_given' }, { field: 'pivots_contact', when: 'given' } ] } ] /** 池位状态 → 卡内小节标题 */ export const SCENARIO_WHEN_LABELS: Record = { not_given: '客户还没留联系方式时', given: '客户已经留过之后' } // ---- 模板变量保护（{intl}/{shown}/{no_contact_web} 等运行期回填占位符） --------------- /** 文本中的 {var} 占位符提取（字母/下划线开头，去重保序） */ export function templateVariables(text: string): string[] { return [...new Set([...text.matchAll(/\{([a-z_][a-z0-9_]*)\}/gi)].map((m) => m[1]))] } /** before 出现过且 after 不再出现的变量（保存前警告清单） */ export function removedTemplateVariables(before: string, after: string): string[] { const afterSet = new Set(templateVariables(after)) return templateVariables(before).filter((v) => !afterSet.has(v)) } function collectVariables(value: unknown, out: string[]): void { if (typeof value === 'string') { out.push(...templateVariables(value)) } else if (value !== null && typeof value === 'object') { // typeof 收窄只到 object（无索引签名）——断言收形 const record = value as Record for (const key of Object.keys(record)) collectVariables(record[key], out) } } /** wall 整组文本区（池/no_contact/cc_templates/reminders）变量集差—— * before 出现过且 after 全域不再出现的变量（位置无关：删除尾行/整键同样检出） */ export function collectRemovedWallVariables( before: Record | null | undefined, after: Record | null | undefined ): string[] { const beforeVars: string[] = [] const afterVars: string[] = [] for (const key of [...POOL_FIELDS, 'no_contact', 'cc_templates', 'reminders']) { collectVariables((before ?? {})[key], beforeVars) collectVariables((after ?? {})[key], afterVars) } const afterSet = new Set(afterVars) return [...new Set(beforeVars.filter((v) => !afterSet.has(v)))] } ``` **注意：上面 WALL_SCENARIOS 的 pivot 卡第二个池位是笔误检查点——必须是 `{ field: 'pivots_contact', when: 'given' }`**（实现时以测试断言为准：`price.pools = [deflections, deflections_contact]`、`pivot.pools = [pivots, pivots_contact]`）。 - [ ] **Step 4: 跑测试确认通过**；**Step 5: Commit**——`git commit -m "feat(admin): wall 重组辅助纯函数（场景卡/语言并集/模板变量保护）"` ### Task 8: ScenarioCard.vue 场景卡 **Files:** - Create: `admin/src/views/config/center/wall/ScenarioCard.vue` - [ ] **Step 1: 创建组件**（要点全量）： ```vue ``` 样式（scoped scss）：场景卡 `border:1px solid var(--el-border-color-lighter); border-radius:8px; padding:14px 16px`；sc-title 600 14px、sc-note 12px 灰、sc-pool-label 12px `var(--art-gray-500)` 带左侧 4px 色条（`border-left:3px solid var(--el-color-primary-light-5); padding-left:8px`）、sc-row flex（输入框 flex:1 + 删除钮）、sc-input 一行一句。 （auto-import：ref/computed/watch/ElMessage/ElTabs 等无需 import。） - [ ] **Step 2: 构建验证**——`pnpm build` 零错误 - [ ] **Step 3: Commit**——`git commit -m "feat(admin): WallScenarioCard 双状态场景卡组件"` ### Task 9: WallAdvanced.vue 高级折叠区 **Files:** - Create: `admin/src/views/config/center/wall/WallAdvanced.vue` - 参考：`admin/src/views/config/center/WallPane.vue` 现状 53-210 行（正则区/池区模板迁出源） - [ ] **Step 1: 创建组件**——把 WallPane 现状的 price_patterns/reask_patterns 正则行编辑器、triggers/zero_number 单正则区、reminders 六类区**原样迁入**（模板与逻辑不动，仅搬家），外包： ```vue ``` props `{ model: WallEditModel }`；迁移块内的 section-note 保留但首行加白话短句（如「识别客户在谈价格的句式」）。 - [ ] **Step 2: 构建验证**；**Step 3: Commit**——`git commit -m "feat(admin): WallAdvanced 高级折叠区（正则/提醒迁移）"` ### Task 10: WallPane 重组收口 **Files:** - Modify: `admin/src/views/config/center/WallPane.vue`（大改：主体模板换结构） - Modify: `admin/src/views/config/center/index.vue`（wall pane 挂载处加 `@navigate`） - [ ] **Step 1: 主体重排**——外层换 `ConfigCard icon="solar:chat-round-line-duotone" title="AI 话术" subtitle="AI 回复客户时用的标准句与引擎规则——改动保存后立即对线上对话生效" info="保存前自动跑试金石预演；正则与 AI 指令在下方「高级」区"`；主面顺序：`` → no_contact 卡（三键行编辑，NO_CONTACT_KEYS 白话标签：web=网页会话（有按钮）/ app=App 会话（无按钮）/ already=客户已留过）→ cc_templates 卡（四组 × CC_TEMPLATE_VARIANTS 封闭语言直接渲染，标注 `{intl}` 为运行期回填变量、不可删除）→ 试金石面板（现状保留）→ ``（默认折叠）。旧模板的池区/正则区/提醒区删除（已迁移）。**Task 8 评审折入三件**：① ScenarioCard 的 requiredMissing 收紧为「语言缺失或两池全部行皆空白」——`.some((p) => !(model.pools[p.field][l]?.some((t) => t.trim() !== '')))`（空白行保留但全空也预警，与 cleanPool 序列化语义对齐）；② 场景卡 × 删除钮补键盘可达：`role="button" tabindex="0" aria-label="删除此语言" @keydown.enter.prevent="removeLang(lang)" @keydown.space.prevent="removeLang(lang)"`；③ 添加语言正则保持严格 `^[a-z]{2,3}$`（WallPane 旧池编辑器的宽正则随 Task 10 退役；异常存量码可显示可删不可重加——注释注记即可） - [ ] **Step 2: 保存路径加变量保护**——onSave 组装 payload 后（ElMessageBox 须在 WallPane 顶部 `import { ElMessageBox } from 'element-plus'`——非 auto-import）： ```ts const removed = collectRemovedWallVariables(props.group, payload) if (removed.length) { const ok = await ElMessageBox.confirm( `以下运行期变量在编辑中被删除：{${removed.join('}} {')}}——删除后 AI 无法回填对应内容，确定继续？`, '模板变量被删除', { type: 'warning', confirmButtonText: '仍要保存', cancelButtonText: '回去检查' } ).catch(() => false) if (!ok) return } ``` （后续保持既有试金石预演 → PUT 流程不变。） - [ ] **Step 3: 验证**——`pnpm build` 零错误；`pnpm dev` 走查：两场景卡语言切换/添加语言、必留语言 en/zh **无删除按钮**（其行可被逐条清空——此时卡头「缺必留语言」警示标签出现、后端 400 兜底，这是设计而非硬拦截）、no_contact/cc 卡可编辑、高级区默认折叠、试金石可用、保存一个改动走通试金石流程。注：spec §5.2「编辑器内变量高亮」有意裁剪为「保存时 collectRemovedWallVariables 确认 + cc 卡静态标注」——记为本计划终态，非遗漏 - [ ] **Step 4: 既有 wall 相关 vitest 全量**——`pnpm exec vitest run src/views/config/center/__tests__/model.test.ts` 全绿（initWallEdit/buildWallPayload 契约不回归） - [ ] **Step 5: Commit**——`git commit -m "feat(admin): WallPane 重组为场景卡+高级折叠（Batch 2 收口）"` --- ## Batch 3：prompts 重组 + 三组表单化 + 脏保护（✅ 2026-10-14 完成——commits 8b43056/4dd74d6/250ffdf/edf58ce+e2aa166+26dc93b；全任务过双审；三拦截路径+头像双场景实测通过；挂账 Batch 4：CredsPane 单卡保存联动重置兄弟卡（BASE 起既有性状，修复形态=单卡保存只回写该卡 form+baseline）） ### Task 11: PromptsPane 重组 **Files:** - Modify: `admin/src/views/config/center/PromptsPane.vue`（360 行，模板重排） - [ ] **Step 1: 主面/折叠重排**——外层换 `ConfigCard icon="solar:building-line-duotone" title="公司资料" subtitle="AI 向客户介绍你公司/产品时依据的内容——保持事实准确、精炼" info="AI 行为源头：改动必须填保存备注；每轮对话整段注入，超 50KB 禁存"`；主面 = company_facts 编辑器（PROMPTS_META 取 key==='company_facts' 项，字节计数保留）；折叠区 ElCollapse「AI 引擎级提示词（高级——改错直接影响 AI 行为）」内 v-for 其余三件（system/extractor/evaluator，各自字节计数与 hint 保留） - [ ] **Step 2: 验证**——`pnpm build`；dev 走查：折叠区未展开时保存，payload 仍含三件原值（读-改-写不丢——normalizePromptsGroup 从快照取全四键，保存必填备注逻辑不变） - [ ] **Step 3: Commit**——`git commit -m "feat(admin): PromptsPane 重组（company_facts 主面+引擎级折叠）"` ### Task 12: model.ts 三组表单映射纯函数（TDD） **Files:** - Modify: `admin/src/views/config/center/model.ts`（文件末尾追加新区块；旧 JSON 组区块**暂留**——Task 13 接线后才退役，保证本任务收尾时仓库可构建） - Test: `admin/src/views/config/center/__tests__/model.test.ts`（追加新用例；旧 JSON 组用例不动） - [ ] **Step 1: 写失败测试**（model.test.ts 追加，import 行并入既有 from '../model' 名单）： ```ts import { contactToForm, contactToPayload, engineToForm, engineToPayload, validateEngineForm, miscToForm, miscToPayload, validateKeyValueRows } from '../model' describe('contact 表单化', () => { it('快照 → 表单（bool 缺省 false / 语言数组）', () => { expect(contactToForm({ cc_completion: true, email_light_ask: false, template_languages: ['en', 'zh'] })) .toEqual({ ccCompletion: true, emailLightAsk: false, templateLanguages: ['en', 'zh'] }) expect(contactToForm(null)).toEqual({ ccCompletion: false, emailLightAsk: false, templateLanguages: [] }) }) it('表单 → payload：接管键覆写 + 未知键透传', () => { const snapshot = { cc_completion: false, email_light_ask: false, template_languages: [], _meta: 'keep' } expect(contactToPayload({ ccCompletion: true, emailLightAsk: true, templateLanguages: ['en', ' '] }, snapshot)) .toEqual({ _meta: 'keep', cc_completion: true, email_light_ask: true, template_languages: ['en'] }) }) }) describe('engine 表单化', () => { it('快照 → 表单（数值转串 / seed 映射转行）', () => { expect(engineToForm({ rate_limit_per_hour: 120, ws_conn_limit: 5, context_seed_keys: { a: 'b' } })) .toEqual({ rateLimit: '120', wsConnLimit: '5', seedRows: [{ key: 'a', value: 'b' }] }) expect(engineToForm(null)).toEqual({ rateLimit: '', wsConnLimit: '', seedRows: [] }) }) it('payload：空数值槽保快照原值（快照也无 → 键省略）；未知键透传；seed 恒重建', () => { const snapshot = { rate_limit_per_hour: 120, ws_conn_limit: 5, other: 1 } expect(engineToPayload({ rateLimit: '', wsConnLimit: '9', seedRows: [] }, snapshot)) .toEqual({ other: 1, rate_limit_per_hour: 120, ws_conn_limit: 9, context_seed_keys: {} }) expect(engineToPayload({ rateLimit: '60', wsConnLimit: '', seedRows: [] }, null)) .toEqual({ rate_limit_per_hour: 60, context_seed_keys: {} }) }) it('payload：seed 行空键值剔除、重建映射', () => { expect(engineToPayload( { rateLimit: '1', wsConnLimit: '1', seedRows: [{ key: 'product_name', value: 'app_product_name' }, { key: '', value: 'x' }] }, {} ).context_seed_keys).toEqual({ product_name: 'app_product_name' }) }) it('校验：非正整数报错', () => { expect(validateEngineForm({ rateLimit: '0', wsConnLimit: '', seedRows: [] })) .toEqual(['每 IP 每小时发言上限：须为正整数']) expect(validateEngineForm({ rateLimit: '30', wsConnLimit: '2', seedRows: [] })).toEqual([]) }) }) describe('misc 表单化', () => { it('往返：快照 → 表单 → payload 保未知键', () => { const snapshot = { name_to_region_extras: { 'saudi arabia': '966' }, keep: true } const form = miscToForm(snapshot) expect(form.extrasRows).toEqual([{ key: 'saudi arabia', value: '966' }]) expect(miscToPayload({ extrasRows: [{ key: 'saudi arabia', value: '966' }, { key: 'uae', value: '971' }] }, snapshot)) .toEqual({ keep: true, name_to_region_extras: { 'saudi arabia': '966', uae: '971' } }) }) }) describe('KeyValue 行校验（engine seed / misc extras 共用）', () => { it('重复键与空键报错', () => { expect(validateKeyValueRows([{ key: 'a', value: '1' }, { key: 'a', value: '2' }], '映射')) .toEqual(['映射：键 a 重复']) expect(validateKeyValueRows([{ key: '', value: '1' }], '映射')).toEqual([]) }) }) ``` - [ ] **Step 2: 跑测试确认失败**——新函数未定义 FAIL - [ ] **Step 3: 实现**——model.ts 文件末尾（`JSON_GROUP_FIELDS` 区块之后）追加新区块： ```ts // ---- contact / engine / misc 表单化（spec §5.4-5.7；JsonGroupPane 退役） -------------- export interface KeyValueRow { key: string value: string } /** 键值行校验（空行整行忽略；非空键重复报错；value 空允许——由后端校验语义） */ export function validateKeyValueRows(rows: KeyValueRow[], label: string): string[] { const seen = new Set() const errors: string[] = [] for (const row of rows) { if (row.key.trim() === '' && row.value.trim() === '') continue const key = row.key.trim() if (key === '') continue // 半行（有 value 无 key）序列化时整行剔除，不报错 if (seen.has(key)) errors.push(`${label}：键 ${key} 重复`) seen.add(key) } return errors } function rowsToRecord(rows: KeyValueRow[]): Record { const out: Record = {} for (const row of rows) { const key = row.key.trim() if (key !== '') out[key] = row.value } return out } function recordToRows(value: unknown): KeyValueRow[] { const src = asRecord(value) ?? {} return Object.entries(src) .filter(([, v]) => typeof v === 'string') .map(([key, v]) => ({ key, value: v as string })) } // ---- contact ------------------------------------------------------------------------ export interface ContactForm { ccCompletion: boolean emailLightAsk: boolean templateLanguages: string[] } export function contactToForm( group: Record | null | undefined ): ContactForm { const src = group ?? {} return { ccCompletion: src.cc_completion === true, emailLightAsk: src.email_light_ask === true, templateLanguages: strList(src.template_languages) } } export function contactToPayload( form: ContactForm, group: Record | null | undefined ): Record { return { ...(group ?? {}), cc_completion: form.ccCompletion, email_light_ask: form.emailLightAsk, template_languages: form.templateLanguages.map((s) => s.trim()).filter(Boolean) } } ``` ```ts // ---- engine ------------------------------------------------------------------------- export interface EngineForm { /** 正整数串；'' = 未填（payload 保快照原值/省略键——绝不提交非法值） */ rateLimit: string wsConnLimit: string seedRows: KeyValueRow[] } function intToForm(value: unknown): string { return typeof value === 'number' && Number.isInteger(value) ? String(value) : '' } export function engineToForm( group: Record | null | undefined ): EngineForm { const src = group ?? {} return { rateLimit: intToForm(src.rate_limit_per_hour), wsConnLimit: intToForm(src.ws_conn_limit), seedRows: recordToRows(src.context_seed_keys) } } /** * 表单 → payload：空数值槽 = 保快照原值（spread 已带上；快照无值则不带键 * ——resolver 出厂回退），非空槽覆写；context_seed_keys 行编辑重建（空行 * 剔除）；其余未知键透传。 */ export function engineToPayload( form: EngineForm, group: Record | null | undefined ): Record { const out: Record = { ...(group ?? {}) } const rate = form.rateLimit.trim() if (rate !== '') out.rate_limit_per_hour = Number(rate) const ws = form.wsConnLimit.trim() if (ws !== '') out.ws_conn_limit = Number(ws) out.context_seed_keys = rowsToRecord(form.seedRows) return out } ``` ```ts export function validateEngineForm(form: EngineForm): string[] { const errors: string[] = [] const rate = form.rateLimit.trim() if (rate !== '' && (!/^\d+$/.test(rate) || Number(rate) < 1)) { errors.push('每 IP 每小时发言上限：须为正整数') } const ws = form.wsConnLimit.trim() if (ws !== '' && (!/^\d+$/.test(ws) || Number(ws) < 1)) { errors.push('每 IP WebSocket 连接上限：须为正整数') } return errors } // ---- misc --------------------------------------------------------------------------- export interface MiscForm { extrasRows: KeyValueRow[] } export function miscToForm( group: Record | null | undefined ): MiscForm { return { extrasRows: recordToRows((group ?? {}).name_to_region_extras) } } export function miscToPayload( form: MiscForm, group: Record | null | undefined ): Record { return { ...(group ?? {}), name_to_region_extras: rowsToRecord(form.extrasRows) } } ``` 同时**不删**任何既有导出（`JsonGroupKey`/`jsonGroupDraft`/`parseJsonGroupDraft`/`JSON_GROUP_FIELDS` 与其测试原样保留，Task 13 统一退役——避免「model 删了函数但 index.vue 还在 import」的中间不可构建态）。 - [ ] **Step 4: 跑测试确认通过**——`pnpm exec vitest run src/views/config/center/__tests__/model.test.ts` 新 describe 全绿（旧用例不动仍绿） - [ ] **Step 5: Commit**——`git commit -m "feat(admin): contact/engine/misc 表单映射纯函数"` ### Task 13: 三份表单 pane + KeyValueEditor + JsonGroup 退役 **Files:** - Create: `admin/src/views/config/center/KeyValueEditor.vue` - Create: `admin/src/views/config/center/ContactFormPane.vue` - Create: `admin/src/views/config/center/EngineFormPane.vue` - Create: `admin/src/views/config/center/MiscFormPane.vue` - Delete: `admin/src/views/config/center/JsonGroupPane.vue` - Modify: `admin/src/views/config/center/index.vue`（JSON_GROUPS 分发处换三组件 + 退役清理） - Modify: `admin/src/views/config/center/model.ts`（删旧 JSON 组区块） - Test: `admin/src/views/config/center/__tests__/model.test.ts`（删旧 JSON 组用例与 import 名单中的退役函数） - [ ] **Step 1: KeyValueEditor.vue**——props `{ rows: KeyValueRow[]; keyPlaceholder: string; valuePlaceholder: string }`；模板 = 行循环（两 ElInput mono + 删除钮）＋底部「＋ 添加一行」；emit 无（直接改 reactive rows，与项目模式一致） - [ ] **Step 2: ContactFormPane.vue**——ConfigCard `icon="solar:phone-line-duotone" title="联系方式" subtitle="AI 什么时候向客户要 WhatsApp / 邮箱"`；两个 ElSwitch（label 用 model 注释白话：cc_completion=「号码缺国家代码时自动补全并确认」/ email_light_ask=「留了号码没留邮箱时补要一次」）；template_languages 用 ElSelect multiple allow-create（placeholder「语言代码如 en / zh」）＋`

邮件通知使用的语言（暂未生效——引擎接线排期中）

`；保存走 contactToPayload、错误内联；footer/danger 同 Task 5 模式；emit saved/navigate - [ ] **Step 3: EngineFormPane.vue**——ConfigCard `icon="solar:widget-5-line-duotone" title="聊天限流" subtitle="防刷与并发的引擎级参数（一般不用改）" info="留空 = 保持当前已存值；出厂档案缺省时省略该键回退平台默认"`；rate/ws 两 ElInput（placeholder「如 120（正整数）」/「如 5」）＋推荐值提示；ElCollapse「会话上下文映射（context_seed_keys）」内 KeyValueEditor；保存 = validateEngineForm → engineToPayload → PUT engine - [ ] **Step 4: MiscFormPane.vue**——ConfigCard `icon="solar:earth-line-duotone" title="国家区号映射" subtitle="客户用国名留言时，系统补全电话区号的额外规则"`；KeyValueEditor（key placeholder「国名（如 saudi arabia）」value「区号（如 966）」）；validateKeyValueRows → miscToPayload → PUT misc - [ ] **Step 5: index.vue 接线 + 退役清理**——`` 分发（index.vue:543 附近的 `v-if JSON_GROUPS.has(activeGroup)` 块）替换为三组件：`` + EngineFormPane/MiscFormPane 同款三份（**必须 v-else-if**——该块处于 pane 条件链中段（brand v-if → … → v-else 占位卡），用 v-if 会让尾部 v-else 占位卡错挂；saved 接既有 handler 名 onPaneSaved——index.vue:630；新组件显式 import）；同步删除 `JSON_GROUPS` 常量、`activeJsonGroup`、`JsonGroupPane` import 与 `JsonGroupKey` 相关 import；onPaneSaved 现有回写逻辑复用 - [ ] **Step 6: 退役删除**——`git rm admin/src/views/config/center/JsonGroupPane.vue`；model.ts 删「通用 JSON 组编辑」整段（`JsonGroupKey`/`jsonGroupDraft`/`parseJsonGroupDraft`/`JSON_GROUP_FIELDS`；`RESET_GROUP_LABELS` 保留不动）；model.test.ts 删旧 JSON 组 describe 块与 import 名单中三个退役函数；`grep -rn "JsonGroupPane\|jsonGroupDraft\|parseJsonGroupDraft\|JSON_GROUP_FIELDS" admin/src` 零残留 - [ ] **Step 7: 验证**——`pnpm build`；`pnpm test` 全绿（总数 = 基线 − 旧 JSON 组用例数 + Task 12 新增数）；dev 走查三组表单（含未知键透传：后台给某租户 contact 组塞 `_custom: 1` 再 GET → 表单保存 → `_custom` 仍在——可用平台 API 或直接 sqlite 验证） - [ ] **Step 8: Commit**——`git commit -m "feat(admin): contact/engine/misc 表单 pane + JsonGroup 退役"` ### Task 14: 未保存离开保护（脏检测 + 三处拦截） **Files:** - Modify: `admin/src/views/config/center/index.vue`（dirty 汇聚 + 三处拦截） - Modify: `admin/src/views/config/center/WallPane.vue` / `PromptsPane.vue` / `CredsPane.vue`（emit dirty） - Modify: `admin/src/views/config/center/ContactFormPane.vue` / `EngineFormPane.vue` / `MiscFormPane.vue`（emit dirty） - [ ] **Step 1: 各 pane 上报 dirty**——七个编辑面（brand 在 index.vue 内联）各加 `const dirty = computed(() => ...)`（判定 = 当前编辑态 JSON.stringify ≠ 初始归一态 JSON.stringify：brand 对比表单初值、prompts 对比 normalizePromptsGroup、wall 对比 initWallEdit 克隆、creds 对比三组 normalize 态、三表单对比 ToForm 初值），`watch(dirty, (v) => emit('dirty', v), { immediate: true })`；emits 增加 `(e: 'dirty', value: boolean): void`；index.vue 记录 `const paneDirty = ref(false)`，各 pane `@dirty="paneDirty = $event"` - [ ] **Step 2: 三处拦截**——index.vue（ElMessageBox 顶部显式 import）： ```ts async function confirmDiscard(): Promise { if (!paneDirty.value) return true try { await ElMessageBox.confirm('有未保存的修改，离开将丢失。确定离开？', '未保存的修改', { type: 'warning', confirmButtonText: '丢弃修改', cancelButtonText: '留下' }) return true } catch { return false } } async function onGroupSelect(index: string): Promise { if (index === activeGroup.value) return if (!(await confirmDiscard())) return activeGroup.value = index as GroupKey } watch(activeSlug, async () => { if (!(await confirmDiscard())) { // 还原租户选择：nextTick 后把 ElSelect 绑定值恢复——实现时用「旧值快照」回写 } // 原有重载逻辑 }) ``` 租户切换的还原实现：watch(activeSlug) 先比对模式（实现时以 ElSelect change 事件前置确认代替 watch 更稳：改用 `@change` 处理器承载确认+回滚，确认失败则 `activeSlug.value = 旧值`）。路由离开：`onBeforeRouteLeave(async () => await confirmDiscard())` - [ ] **Step 3: 验证**——`pnpm build`；dev 走查：brand 改标题不保存 → 切导航组弹确认；wall 改句子 → 切租户弹确认、取消后租户选择还原、草稿还在；保存后切换不弹 - [ ] **Step 4: Commit**——`git commit -m "feat(admin): 未保存离开保护（Batch 3 收口）"` --- ## Batch 4：轻量打磨 + 全局回归（✅ 2026-10-14 完成——commits f92a4be/c6bd542/1df1fc7；终审 Merge-ready（0C/0I/4M）；182 vitest 全绿 + build 零错误 + 暗色两态验收 + 跨租户泄漏缝实测关闭。Minor 处置：#1 试金石异步窗口旧 payload=既有性状挂账（可选加固：确认链后重建 payload 或保存中遮罩）；#2 WallAdvanced 陈旧注释已修；#3 标签宽度逐卡一致但跨卡不统一=接受现状（cosmetic）；#4 三表单 pane configLoaded 门控不对称=补注记归后续。色列宽度/头像提示样式两打磨项经暗色+走查目检视觉可接受，结项） ### Task 15: 其他页面文案/空态轻量打磨 **Files:** - Modify: `admin/src/views/dashboard/console/index.vue`、`admin/src/views/conversations/list/index.vue`、`admin/src/views/stats/overview/index.vue`、`admin/src/views/settings/platform/index.vue`、`admin/src/views/tenants/list/index.vue` - [ ] **Step 1: 定位**——`grep -rn "ElEmpty\|empty-description\|description=" admin/src/views/{dashboard,conversations,stats,settings,tenants}` 列出全部空态点 - [ ] **Step 2: 逐页轻改**——原则（spec §7）：空态从「暂无数据」改具体动作指引（会话页「暂无会话——客户开始聊天后会出现在这里」/统计页「暂无数据——产生会话后展示分析」/平台设置存储表空「暂无设置项——从上方推荐键开始」）；提示文案去术语（「线索」统一、错误 toast 主语明确）。**只改文案与空态，不动布局/逻辑**；每页改完 dev 目检 - [ ] **Step 3: Commit**——`git commit -m "polish(admin): 各页文案与空态轻量打磨"` > 处置注记（Task 15 收尾）：色列宽度与头像提示样式打磨经 Task 16 走查目检后定夺（视觉可接受则结项，否则列入后续）。 ### Task 16: 全局回归 + 验收 - [ ] **Step 1: 前端全量测试**——`cd admin && pnpm test`，预期全绿且总数 ≥ 改造前（既有用例随退役迁移、新增只增不减；当前基线 164） - [ ] **Step 2: 构建 + 行尾纪律**——`pnpm build` 零错误；`git diff --ignore-cr-at-eol --stat` 若仅 components.d.ts/auto-imports.d.ts → `git checkout --` 还原 - [ ] **Step 3: 手动走查（spec §10.3 任务流）**——dev server + 8018 后端：改品牌→改话术（含添加语言 pt）→填 SMTP→测试按钮→开关号码补全→版本历史回滚；明/暗主题切换检查全 pane（顶栏切换钮）；未保存离开保护三路径复验 - [ ] **Step 4: 后端不动确认**——`git status` 应零 app/ 改动；pytest 无需跑（后端零改动，非 seed_profiles 变更） - [ ] **Step 5: 收尾**——临时产物（截图/probe）删除，`git status --short` 干净；`git commit -m "chore: 配置中心优化收尾"`（如有残余杂项） --- ## 附：任务依赖与并行性 - Task 1→2→3 顺序；Task 4 独立（可与 2/3 并行）；Task 5 依赖 2+3；Task 6 依赖 3 - Batch 2 内 7→8、7→9（8/9 可并行）→10 依赖 8+9 - Batch 3 内 11 独立；12→13→14 顺序（14 依赖 13 的三 pane 存在） - Batch 4 顺序收口