Simon
facc04aa65
本提交为 .git 对象库损坏后的重建提交，内容等价于原先三个本地提交 （5e2fd4c2 / 57a53c98 / 5d7e1873）的累积结果，未做任何额外改动。 一、docs 结构整改（整改 #14） 根因：重构时新结构为 untracked 文件，执行 git stash（未带 -u）未纳入， 随后 git reset 拉回 HEAD 旧 tracked 树，导致旧树复活、新旧两棵目录 树并存于 docs/，共 791 文件、双分类体系冲突。 修复动作： - b2 同名异主题文件改名迁移保全 9 个 - C 类 39 个孤立文件按主题正确归类 - A/B1 类 222 个重复文件删除（新结构已有内容副本） - 9 个旧独有空目录删除 - 270 处内部引用按 verified 映射改写 - 整改记录 #14 登记于 04-运维文档/部署运维 结果：docs 791 → 569 文件，顶层仅规范 8 类 + 治理文件，单树恢复。 残留：约 20 处指向从未存在文件的陈旧死链，归入独立文档卫生任务。 二、compose 双目录对齐（消除踩坑 A） - docker-compose.yml：nginx 前端挂载全部由根目录 frontend-*/dist 改为 src/frontend-*/dist（h5 / agent / admin / terminal） - docker-compose.dev.yml：dev 服务 build context 与卷同步改 src/ - 效果：本地 docker compose up 不再把根目录 stale dist 挂回， 与线上一致，分叉隐患消除（已 docker compose config 校验通过） 防复发铁律： - 重构须提交；仓库修复须 git stash -u 或先 commit - 新结构须 git add 并提交，避免再次 untracked 复活 - H5 改动只动 src/frontend-h5/，禁改根目录遗留 frontend-*/
541 lines
26 KiB
Markdown
541 lines
26 KiB
Markdown
# PRD - 前端设计系统
|
||
|
||
> **REQ编号**: REQ-通用-001
|
||
> **版本**: v1.2
|
||
> **状态**: [待评审]
|
||
> **优先级**: P1
|
||
> **阶段**: 中期（3-4个月）
|
||
> **作者**: 宋献
|
||
> **日期**: 2026-08-06
|
||
> **变更类型**: 视觉主题重定义（UI优化）
|
||
|
||
---
|
||
|
||
## 一、问题陈述
|
||
|
||
**用户问题**：
|
||
- H5、坐席、管理后台三端缺乏统一的基础设计语言
|
||
- 三端角色不同，但当前主题色和视觉表达未充分体现角色差异
|
||
- 员工端绿色同时承担品牌色、成功色、在线色和交互强调色，存在语义过载
|
||
- 缺乏分层 Design Tokens，组件容易直接写死颜色值
|
||
- 玻璃拟态、高光和多层阴影在部分场景中可能压过内容，并带来低端设备性能风险
|
||
|
||
**业务目标**：
|
||
- 建立统一的 IT 智能服务台设计系统
|
||
- 统一字体、间距、圆角、图标、交互状态和语义色
|
||
- 通过角色主题区分员工端、坐席端和管理端的使用心理与任务重点
|
||
- 员工端由企微绿调整为服务蓝主题；绿色回归成功、在线、已解决语义
|
||
- 提升三端可访问性、对比度、可维护性和品牌辨识度
|
||
|
||
**设计原则**：
|
||
1. **同源而不雷同**：三端共享基础设计语言，但允许角色主题不同。
|
||
2. **语义优先**：成功、警告、危险、信息等语义色跨三端保持一致，不被角色主题覆盖。
|
||
3. **内容优先**：装饰性玻璃、渐变和阴影不得降低文字、状态和主要操作的可见性。
|
||
4. **Token 优先**：组件只引用语义 Token，不直接写死品牌色值。
|
||
5. **降级可用**：关闭 `backdrop-filter` 或使用低端设备时，布局、对比度和交互仍必须成立。
|
||
|
||
---
|
||
|
||
## 二、需求范围
|
||
|
||
### 2.1 核心功能
|
||
|
||
| 功能 | 描述 |
|
||
|------|------|
|
||
| 基础 Design Tokens | 统一字体、字号、间距、圆角、阴影、动效和中性色 |
|
||
| 角色主题 Tokens | 员工端、坐席端、管理端分别注入角色主题色 |
|
||
| 语义色 Tokens | 成功、警告、危险、信息、AI 能力等语义跨三端固定 |
|
||
| 组件规范 | 按钮、输入框、卡片、弹窗、表格、标签、消息气泡等组件规范 |
|
||
| 图标库 | 统一使用 Lucide 图标库，业务图标不得混用 Emoji |
|
||
| 明暗主题 | 坐席端和管理端完整适配；员工端根据容器与企微环境适配 |
|
||
| 可访问性 | 颜色对比度、键盘焦点、非颜色区分和减少动态效果 |
|
||
| 渐进降级 | 玻璃、模糊和复杂阴影在不支持或低性能设备上可降级 |
|
||
|
||
### 2.2 非目标
|
||
|
||
- 不包含完整的设计系统文档网站
|
||
- 不包含组件库的实现（仅定义规范）
|
||
|
||
---
|
||
|
||
## 三、用户故事
|
||
|
||
| 角色 | 用户故事 | 验收标准 |
|
||
|------|----------|---------|
|
||
| 员工 | 我希望快速获得帮助，不需要学习复杂系统 | 员工端呈现可信、清晰、低压力的服务蓝主题；主要操作易识别 |
|
||
| 坐席 | 我需要同时处理多个会话并快速判断下一步 | 状态、优先级和当前任务层级清晰；装饰颜色不干扰处置判断 |
|
||
| 管理员 | 我需要监控、配置、审计并控制风险 | 管理端保持稳定、权威、可追溯；告警色只用于真实状态 |
|
||
| 前端开发 | 我需要可复用且含义稳定的 Design Tokens | 三端组件不直接写死角色品牌色；主题切换无需修改组件结构 |
|
||
| 产品/设计 | 我需要三端看起来属于同一产品，又能区分角色 | 字体、间距、圆角、图标和交互一致；主题色按角色有明确区分 |
|
||
| 无障碍用户 | 我不能只依赖颜色理解状态 | 关键状态同时具备文字、图标、形状或位置提示 |
|
||
|
||
---
|
||
|
||
## 四、功能详情
|
||
|
||
### 4.1 Design Tokens 定义
|
||
|
||
#### 4.1.1 Token 分层模型
|
||
|
||
Design Tokens 必须分为三层，禁止继续用一个 `--color-primary` 同时承担品牌、角色和状态语义。
|
||
|
||
| 层级 | 作用 | 示例 | 变更频率 |
|
||
|------|------|------|----------|
|
||
| 基础色板层 | 提供稳定、无业务语义的颜色阶梯 | `--palette-blue-600` | 低 |
|
||
| 角色主题层 | 表达员工、坐席、管理员的角色特点 | `--theme-accent` | 中 |
|
||
| 语义用途层 | 组件实际消费的操作和状态含义 | `--color-action-primary` | 低 |
|
||
|
||
```css
|
||
/* 基础色板层 */
|
||
--palette-blue-600: #1769E0;
|
||
--palette-cyan-600: #0E9FBA;
|
||
--palette-green-700: #15803D;
|
||
--palette-amber-700: #B45309;
|
||
--palette-red-700: #B42318;
|
||
|
||
/* 角色主题层：由各端根容器注入 */
|
||
--theme-accent: var(--palette-blue-600);
|
||
--theme-secondary: var(--palette-cyan-600);
|
||
--theme-accent-soft: #E7F0FF;
|
||
|
||
/* 语义用途层：业务组件只引用这一层 */
|
||
--color-action-primary: var(--theme-accent);
|
||
--color-focus-ring: var(--theme-accent);
|
||
--color-status-success: var(--palette-green-700);
|
||
--color-status-warning: var(--palette-amber-700);
|
||
--color-status-danger: var(--palette-red-700);
|
||
```
|
||
|
||
#### 4.1.2 三端角色主题
|
||
|
||
| 端 | 角色心理 | 设计关键词 | 主色 | 辅助色 | 页面基底 |
|
||
|----|----------|------------|------|--------|----------|
|
||
| 员工端 | 快速得到帮助，不想学习复杂系统 | 可信、亲和、清晰、低压力 | 服务蓝 `#1769E0` | 青蓝 `#0E9FBA` | `#F4F8FD` |
|
||
| 坐席端 | 同时处理多个会话并快速决策 | 专注、实时、效率、协同 | 深海蓝 `#155E75` | 冷青 `#22A6B3` | `#F2F7F8` |
|
||
| 管理端 | 监控、配置、审计和风险控制 | 权威、稳定、克制、可追溯 | 靛蓝 `#4F72D8` | 冷紫蓝 `#7889D8` | `#0B1220` |
|
||
|
||
**角色主题约束**：
|
||
- 三端可以使用不同 `--theme-accent`，但字体、间距、圆角、图标、交互状态和语义色必须一致。
|
||
- 绿色不得继续作为员工端品牌主色，只表示成功、在线、已解决、恢复正常。
|
||
- 紫色仅用于 AI 能力或管理端辅助强调，不承担告警、成功或普通导航分组语义。
|
||
- 红、黄、绿只用于真实业务状态，不用于装饰性渐变和导航分组标题。
|
||
|
||
#### 4.1.3 员工端服务蓝主题
|
||
|
||
```css
|
||
[data-product="employee"] {
|
||
--theme-accent: #1769E0;
|
||
--theme-accent-hover: #1258BC;
|
||
--theme-accent-soft: #E7F0FF;
|
||
--theme-secondary: #0E9FBA;
|
||
--surface-page: #F4F8FD;
|
||
--surface-chat: #FFFFFF;
|
||
--surface-ai: #F3F8FF;
|
||
--border-subtle: #D8E6F7;
|
||
--text-primary: #172B4D;
|
||
--text-secondary: #5B6B82;
|
||
}
|
||
```
|
||
|
||
**员工端工具栏决策**：
|
||
- 生产默认采用**扁平蓝色服务舱**：稳定对比度、较低性能成本、清晰操作优先。
|
||
- 蓝色水晶玻璃可作为增强效果；必须提供不使用 `backdrop-filter` 的降级样式。
|
||
- 禁止使用多色发光、紫粉渐变或超过两层的装饰性外阴影。
|
||
- 人工坐席头像使用蓝色主题描边；在线状态小圆点继续使用成功绿。
|
||
|
||
#### 4.1.4 坐席端深海蓝主题
|
||
|
||
```css
|
||
[data-product="agent"] {
|
||
--theme-accent: #155E75;
|
||
--theme-accent-hover: #0E7490;
|
||
--theme-accent-soft: #E5F5F7;
|
||
--theme-secondary: #22A6B3;
|
||
--surface-page: #F2F7F8;
|
||
--surface-panel: #FFFFFF;
|
||
--border-subtle: #D7E5E8;
|
||
}
|
||
```
|
||
|
||
- 当前会话使用主题浅底与左侧指示条，不仅依赖文字颜色。
|
||
- AI 推荐使用青色图标或标签；紫色不得扩散到 logo、版本标签和普通按钮。
|
||
- 完成节点用绿色、当前节点用主题蓝、判断节点用琥珀色。
|
||
- 会话优先级颜色不得同时承担头像、分类和品牌装饰用途。
|
||
|
||
#### 4.1.5 管理端海军蓝主题
|
||
|
||
```css
|
||
[data-product="admin"] {
|
||
--surface-page: #0B1220;
|
||
--surface-sidebar: #101A2C;
|
||
--surface-card: #152238;
|
||
--surface-hover: #1C2E49;
|
||
--theme-accent: #4F72D8;
|
||
--theme-accent-soft: rgba(79, 114, 216, 0.16);
|
||
--text-primary: #E8EEF8;
|
||
--text-secondary: #9AAAC0;
|
||
--border-subtle: rgba(154, 170, 192, 0.16);
|
||
}
|
||
```
|
||
|
||
- 默认维持深色控制台方向。
|
||
- 导航分组标题统一使用灰阶，禁止每个分组使用不同颜色。
|
||
- KPI 卡片不使用彩色渐变；语义色仅出现在数据、状态点或告警标签。
|
||
- 外部系统品牌色只出现在集成图标，不扩散至整张卡片。
|
||
|
||
#### 4.1.6 语义色系统
|
||
|
||
| Token | 浅色主题 | 深色主题 | 用途 |
|
||
|-------|----------|----------|------|
|
||
| `--color-status-success` | `#15803D` | `#4ADE80` | 成功、在线、已解决 |
|
||
| `--color-status-warning` | `#B45309` | `#FBBF24` | 警告、等待、待审核 |
|
||
| `--color-status-danger` | `#B42318` | `#F87171` | 故障、失败、阻断 |
|
||
| `--color-status-info` | `#1769E0` | `#60A5FA` | 信息、说明 |
|
||
| `--color-ai` | `#0E7490` | `#67E8F9` | AI 推荐、智能能力 |
|
||
|
||
**使用规则**：状态不能只通过颜色表达，必须同时提供文字、图标、形状或位置中的至少一种辅助信号。
|
||
|
||
#### 4.1.7 中性色与表面色
|
||
|
||
角色主题不能替代中性色阶。中性色用于文字、背景、边框和组件层级，在三端保持同一明度逻辑。
|
||
|
||
| Token | 浅色值 | 深色值 | 用途 |
|
||
|------|--------|--------|------|
|
||
| `--palette-gray-50` | `#F9FAFB` | `#0B1220` | 页面最浅背景/深色页面基底 |
|
||
| `--palette-gray-100` | `#F3F4F6` | `#101A2C` | 次级背景/侧边栏 |
|
||
| `--palette-gray-200` | `#E5E7EB` | `#152238` | 卡片、面板分层 |
|
||
| `--palette-gray-400` | `#9CA3AF` | `#64748B` | 辅助边框、禁用态 |
|
||
| `--palette-gray-600` | `#4B5563` | `#9AAAC0` | 辅助文字 |
|
||
| `--palette-gray-800` | `#1F2937` | `#E8EEF8` | 标题、正文 |
|
||
| `--palette-gray-900` | `#111827` | `#F3F6FA` | 强调文字/深色高对比文字 |
|
||
|
||
| Token | 浅色主题 | 深色主题 | 用途 |
|
||
|-------|----------|----------|------|
|
||
| `--surface-page` | `#F6F8FB` | `#0B1220` | 页面背景 |
|
||
| `--surface-panel` | `#FFFFFF` | `#152238` | 主面板、卡片 |
|
||
| `--surface-subtle` | `#F1F4F8` | `#1C2E49` | 次级区域、悬停 |
|
||
| `--text-primary` | `#172B4D` | `#E8EEF8` | 标题、正文 |
|
||
| `--text-secondary` | `#5B6B82` | `#9AAAC0` | 辅助文字 |
|
||
| `--border-subtle` | `#DCE3EC` | `rgba(154,170,192,0.16)` | 边框、分隔 |
|
||
|
||
#### 4.1.8 旧 Token 兼容映射
|
||
|
||
为避免三端主题迁移过程中出现未定义变量或样式瞬间失效，迁移期允许保留以下兼容别名。新组件不得继续使用旧别名；兼容别名在三端完成迁移并通过回归验收后移除。
|
||
|
||
| 旧 Token | 迁移映射 | 说明 |
|
||
|----------|----------|------|
|
||
| `--color-primary` | `var(--theme-accent)` | 角色主题主操作色 |
|
||
| `--color-primary-light` | `var(--theme-accent-soft)` | 主题浅背景 |
|
||
| `--color-primary-dark` | `var(--theme-accent-hover)` | 深色/悬停状态 |
|
||
| `--color-secondary` | `var(--theme-secondary)` | 辅助主题色 |
|
||
| `--color-success` | `var(--color-status-success)` | 成功/在线/已解决 |
|
||
| `--color-warning` | `var(--color-status-warning)` | 警告/等待 |
|
||
| `--color-danger` | `var(--color-status-danger)` | 危险/失败 |
|
||
| `--color-info` | `var(--color-status-info)` | 信息/说明 |
|
||
| `--bg-primary` | `var(--surface-page)` | 页面背景 |
|
||
| `--bg-secondary` | `var(--surface-panel)` | 面板/卡片 |
|
||
| `--bg-tertiary` | `var(--surface-subtle)` | 次级表面 |
|
||
|
||
**迁移纪律**：兼容映射只允许放在全局 Token 文件，不得在各个页面重复声明；每次删除旧别名前，必须完成全仓库检索和视觉回归。
|
||
|
||
**排版系统**：
|
||
| Token | 值 | 用途 |
|
||
|-------|-----|------|
|
||
| --font-family | PingFang SC, Microsoft YaHei | 字体 |
|
||
| --font-size-xs | 12px | 辅助文字 |
|
||
| --font-size-sm | 13px | 标签 |
|
||
| --font-size-base | 14px | 正文 |
|
||
| --font-size-lg | 16px | 小标题 |
|
||
| --font-size-xl | 20px | 页面标题 |
|
||
| --font-size-2xl | 24px | 大标题 |
|
||
|
||
**间距系统**（4px 基准）：
|
||
- 4, 8, 12, 16, 20, 24, 32, 48, 64
|
||
|
||
**圆角系统**：
|
||
| Token | 值 | 用途 |
|
||
|-------|-----|------|
|
||
| --radius-sm | 4px | 标签 |
|
||
| --radius-md | 6px | 按钮 |
|
||
| --radius-lg | 8px | 卡片 |
|
||
| --radius-xl | 12px | 大组件 |
|
||
| --radius-full | 999px | 圆形 |
|
||
|
||
**阴影系统**：
|
||
| Token | 值 | 用途 |
|
||
|-------|-----|------|
|
||
| --shadow-sm | 0 1px 2px rgba(0,0,0,0.04) | 悬浮态 |
|
||
| --shadow-md | 0 2px 8px rgba(0,0,0,0.06) | 卡片 |
|
||
| --shadow-lg | 0 4px 16px rgba(0,0,0,0.08) | 弹窗 |
|
||
|
||
**动效系统**：
|
||
| Token | 值 | 用途 |
|
||
|-------|-----|------|
|
||
| --duration-fast | 150ms | hover/press |
|
||
| --duration-normal | 200ms | 展开/收起 |
|
||
| --duration-slow | 300ms | 弹窗/过渡 |
|
||
|
||
### 4.2 组件规范
|
||
|
||
#### 4.2.1 通用要求
|
||
|
||
- 组件只能消费语义用途层 Token，不得直接引用具体颜色值。
|
||
- 正常、悬停、按下、聚焦、禁用、处理中、成功、失败状态必须完整定义。
|
||
- 关键状态不得只依赖颜色，需同时提供文字、图标、形状或位置提示。
|
||
- 主要按钮、危险按钮和普通按钮必须有明确层级；同一区域原则上仅保留一个主要按钮。
|
||
|
||
#### 4.2.2 按钮
|
||
|
||
- 主按钮：`--color-action-primary` 填充，使用通过对比度校验的前景色，6px 圆角。
|
||
- 次按钮：中性边框；悬停后使用 `--theme-accent-soft`，避免大面积主色描边。
|
||
- 文字按钮：无背景、无边框，仅用于低风险辅助操作。
|
||
- 危险按钮：只有执行删除、停用、强制中断等不可逆操作时使用危险色。
|
||
- 处理中：保留按钮宽度，显示加载状态并禁止重复提交。
|
||
|
||
#### 4.2.3 输入框
|
||
|
||
- 默认：中性边框，8px 圆角；不使用 14px 以上的过度圆角。
|
||
- 聚焦：使用 `--color-focus-ring`，外环不得造成布局抖动。
|
||
- 错误：危险色边框 + 错误图标 + 明确错误文字。
|
||
- 禁用：降低表面和文字对比，但仍须保持文字可读。
|
||
|
||
#### 4.2.4 卡片与面板
|
||
|
||
- 优先使用边框和表面明度建立层级，阴影只用于浮层、弹窗和拖拽态。
|
||
- 避免“卡片套卡片”；同一页面主要容器层级不超过三层。
|
||
- 员工端可适量使用半透明表面；坐席端和管理端优先使用稳定实色表面。
|
||
|
||
#### 4.2.5 弹窗、抽屉与下拉层
|
||
|
||
- 弹窗用于需要用户确认或集中完成的任务，不用于承载可直接展示在页面上的普通信息。
|
||
- 弹窗、抽屉和下拉层必须具有明确的层级、关闭方式和焦点管理；打开后焦点进入容器，关闭后回到触发控件。
|
||
- 危险确认弹窗必须明确描述影响范围，并区分取消和确认按钮；确认按钮不得使用模糊文案。
|
||
- 下拉层优先使用实色表面和边框，不使用高透明度玻璃导致选项与背景混淆。
|
||
- 弹窗遮罩仅用于阻断背景交互，颜色和透明度不得降低弹窗正文对比度。
|
||
|
||
#### 4.2.6 消息气泡
|
||
|
||
- 用户消息使用员工端主题主色；AI/坐席消息使用浅表面和清晰边框。
|
||
- 用户、AI、人工坐席除颜色外，还必须通过对齐方向、角色名称或头像进行区分。
|
||
- 成功、失败和系统提示不得伪装成普通聊天消息。
|
||
|
||
#### 4.2.7 表格和数据列表
|
||
|
||
- 管理端、坐席端的表格优先保证密度、对齐和扫描效率。
|
||
- 表格斑马纹、悬停、选中和固定列必须使用统一表面 Token。
|
||
- 状态标签不得以整行高饱和底色表达，优先使用轻底标签和文字。
|
||
|
||
### 4.3 图标规范
|
||
|
||
- 统一使用 Lucide 图标库，线框风格（outline）。
|
||
- 尺寸：16px（辅助）、20px（常规）、24px（强调）。
|
||
- 图标颜色引用语义 Token 或角色主题 Token，不直接写十六进制值。
|
||
- 业务功能图标不得混用 Emoji；Emoji 仅允许作为用户主动输入的内容展示。
|
||
- 图标按钮必须同时提供可见 tooltip 或 `aria-label`。
|
||
- 装饰性 SVG 必须使用 `aria-hidden="true"`，不得进入辅助阅读顺序。
|
||
- 人工坐席头像属于品牌/角色资产，不作为状态图标使用；在线状态必须独立显示。
|
||
|
||
---
|
||
|
||
### 4.4 用户交互反馈规范（2026-07-24 补充）
|
||
|
||
> **补充日期**: 2026-07-24
|
||
> **补充原因**: 2026-07-24 H5选项交互消息重复Bug反思——产品设计文档中缺失「用户交互反馈」定义
|
||
|
||
#### 4.4.1 交互反馈设计原则
|
||
|
||
**核心原则**：所有涉及后端异步响应的用户操作，前端应优先通过**UI状态变化**反馈结果，而非**临时消息**。
|
||
|
||
| 场景 | 不推荐做法 | 推荐做法 |
|
||
|------|-----------|---------|
|
||
| 用户点击AI选项 | 立即显示一条"待确认"消息，等后端返回后删除或保留 | 按钮立即禁用 + 高亮选中态，静默发WS，等后端返回后再添加正式消息 |
|
||
| 用户发送消息 | 本地先添加消息，等后端返回确认后再决定是否显示 | 按钮禁用 + 发送中状态，后端返回后添加正式消息 |
|
||
| 用户上传文件 | 先显示"上传中..."的临时消息 | 进度条 + 按钮禁用，上传完成后显示正式消息 |
|
||
|
||
#### 4.4.2 交互状态定义
|
||
|
||
每一种用户操作都应定义以下状态：
|
||
|
||
| 状态 | 视觉表现 | 说明 |
|
||
|------|---------|------|
|
||
| **正常态** | 按钮可点击，无特殊样式 | 用户可以执行操作 |
|
||
| **处理中态** | 按钮禁用 + 加载指示器 | 后端正在处理，不允许重复点击 |
|
||
| **成功态** | 恢复正常，可能有短暂高亮反馈 | 操作成功完成 |
|
||
| **失败态** | 按钮恢复可用 + 错误提示 | 操作失败，需要用户重试 |
|
||
|
||
#### 4.4.3 消息添加时机原则
|
||
|
||
**技术设计原则**：前端不应在收到后端确认前添加消息到消息列表。
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────────┐
|
||
│ 推荐的消息添加流程 │
|
||
├─────────────────────────────────────────────────────────────────┤
|
||
│ 1. 用户触发操作（如点击选项） │
|
||
│ 2. 前端：UI状态变为「处理中」（按钮禁用） │
|
||
│ 3. 前端：发送请求到后端（WS或HTTP） │
|
||
│ 4. 后端：处理完成，返回确认消息 │
|
||
│ 5. 前端：收到后端确认后，添加到消息列表 │
|
||
│ 6. 前端：UI状态恢复「正常」或变为「成功」 │
|
||
└─────────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
**为什么这样设计**：
|
||
1. 避免消息ID不一致导致的重复显示问题
|
||
2. 用户通过UI状态变化就能感知操作已被接收，不需要"假消息"来确认
|
||
3. 后端失败时，前端只需要恢复UI状态，不需要处理消息的"撤回"
|
||
|
||
### 4.5 Element Plus 深色主题适配规范（v1.1 补充 2026-07-27）
|
||
|
||
> **补充原因**：BUG-通用-001（管理后台 el-table 白底白字）暴露了设计系统在 Element Plus 落地时的具体应用规则缺失。本节明确设计 Tokens 在 Element Plus 组件上的覆盖要求。
|
||
|
||
#### 4.5.1 适用范围
|
||
|
||
- 所有使用 `<el-table>` 的视图（管理后台核心列表页）
|
||
- 后续扩展到 `<el-dialog>` / `<el-tag>` / `<el-form>` / `<el-pagination>` 等深色主题相关组件
|
||
|
||
#### 4.5.2 el-table 三层覆盖规则
|
||
|
||
Element Plus 的 `<el-table>` 在 DOM 上有三层结构：
|
||
|
||
```
|
||
<td> ← td 层（外层）
|
||
<div class="el-table__cell"> ← cell 层（内层 div）
|
||
<!-- 文字 --> ← 内容
|
||
</div>
|
||
</td>
|
||
```
|
||
|
||
**核心规则**：必须覆盖到 **cell 层 + fixed-column 层**，否则白底白字。
|
||
|
||
```css
|
||
/* 主体单元格（普通 + 固定列）—— 必须在 cell 层覆盖 */
|
||
.el-table .el-table__body td,
|
||
.el-table .el-table__body td.el-table__cell,
|
||
.el-table .el-table__body td.el-table-fixed-column--left,
|
||
.el-table .el-table__body td.el-table-fixed-column--right {
|
||
background-color: var(--surface-panel) !important; /* ⚠️ 必须 !important */
|
||
color: var(--text-primary);
|
||
}
|
||
|
||
/* 斑马纹行（偶数行） */
|
||
.el-table .el-table__row--striped td, ... {
|
||
background-color: var(--surface-subtle) !important;
|
||
}
|
||
|
||
/* hover 状态 */
|
||
.el-table .el-table__body tr:hover > td, ... {
|
||
background-color: var(--theme-accent-soft) !important;
|
||
}
|
||
```
|
||
|
||
#### 4.5.3 实施原则
|
||
|
||
| 原则 | 说明 |
|
||
|------|------|
|
||
| **全局覆盖** | 在 `src/<前端项目>/src/styles/global.css` 统一配置，不在每个视图写 scoped 样式 |
|
||
| **必须 !important** | Element Plus 固定列选择器优先级高，不加 !important 无法胜出 |
|
||
| **覆盖完整 3 层** | td / td.el-table__cell / td.el-table-fixed-column--left/--right，缺一不可 |
|
||
| **覆盖完整状态** | 普通 / 斑马纹 / hover，缺一就有半清半不清 |
|
||
|
||
#### 4.5.4 验收清单（每个 el-table 视图必须通过）
|
||
|
||
- [ ] 普通行（无 striped）背景深、文字浅 → 清晰
|
||
- [ ] 偶数行（striped）背景更深一档、文字浅 → 清晰
|
||
- [ ] 固定列（`fixed="left"` 或 `fixed="right"`）与同行普通列颜色一致
|
||
- [ ] hover 时整行变蓝透 → 文字仍可读
|
||
- [ ] 表格头（thead）背景与全站风格一致
|
||
- [ ] WCAG 对比度 ≥ 4.5:1
|
||
|
||
#### 4.5.5 教训（来自 BUG-通用-001）
|
||
|
||
1. **不要在视图里加 scoped `:deep()`**：治标，每个表都得改；scoped 选择器优先级也不够
|
||
2. **必须用 !important**：Element Plus 的 `.el-table-fixed-column--left/--right` 优先级很高
|
||
3. **3 层都要覆盖**：第 1 次只覆盖 td（用户反馈"半清半不清"），第 2 次加 cell（用户反馈"偶数行不清"），第 3 次加 !important + fixed-column 才彻底修复
|
||
4. **完整 Skill 沉淀**：`~/.workbuddy/skills/element-plus-dark-table/SKILL.md`（下次遇到可直接调用）
|
||
|
||
#### 4.5.6 关联文档
|
||
|
||
- 缺陷单：`03-测试文档/05-缺陷单/BUG-通用-用户角色分配表格看不清-001.md`
|
||
- 故障案例：`04-运维文档/部署运维/00-标准故障排查手册.md` CASE-20260727-02
|
||
- Skill：`~/.workbuddy/skills/element-plus-dark-table/SKILL.md`
|
||
|
||
---
|
||
|
||
## 五、指标设计
|
||
|
||
| 指标 | 目标 | 测量方式 |
|
||
|------|------|---------|
|
||
| 设计系统覆盖率 | ≥ 95% | 三端组件使用语义 Design Tokens 的比例；直接写死品牌色的组件数为 0 |
|
||
| 三端基础一致性 | ≥ 90% | 字体、间距、圆角、图标、交互状态抽样评审通过率 |
|
||
| 角色主题识别度 | ≥ 85% | 员工、坐席、管理员用户盲测端角色识别正确率 |
|
||
| WCAG 对比度 | 普通文字 ≥ 4.5:1；大文字 ≥ 3:1 | 自动化扫描 + 真实页面人工复核 |
|
||
| 员工端主要操作可发现性 | ≥ 90% | 首次使用者在 10 秒内找到发送、转人工、上传等主要入口的比例 |
|
||
| 玻璃效果降级成功率 | 100% | 关闭 `backdrop-filter` 或低端设备模拟后，布局、对比度和操作仍可用 |
|
||
| 设计主题迁移回归缺陷 | 0 个 P0/P1 | 三端视觉回归与关键路径测试 |
|
||
|
||
---
|
||
|
||
## 六、技术方案
|
||
|
||
- 使用 CSS Custom Properties 实现基础色板、角色主题和语义用途三层 Design Tokens。
|
||
- 抽离为共享 CSS Token 文件，三端通过根容器属性（如 `[data-product="employee"]`）注入角色主题。
|
||
- 组件只引用语义用途层变量，例如 `--color-action-primary`、`--color-status-success`，禁止直接写死品牌色。
|
||
- 深色模式通过 CSS 变量覆盖实现；员工端需兼容企微容器和窄屏环境。
|
||
- 员工端玻璃效果必须提供 `@supports not (backdrop-filter: blur(1px))` 降级规则，并保留实色表面和可读边框。
|
||
- 颜色对比度纳入 CI 或视觉回归检查；普通文字最低 4.5:1，大文字最低 3:1。
|
||
- Element Plus 组件继续采用全局样式覆盖，表格必须覆盖普通、斑马纹、hover 和 fixed-column 状态。
|
||
- 迁移顺序：Token 层 → 员工端核心会话 → 坐席工作台 → 管理后台 → 三端回归验收。
|
||
|
||
---
|
||
|
||
## 七、实施范围与验收标准
|
||
|
||
### 7.1 第一阶段：Token 重构
|
||
|
||
- [ ] 完成基础色板、角色主题、语义用途三层变量定义。
|
||
- [ ] 三端能够通过根容器切换主题，不修改组件结构。
|
||
- [ ] 全仓库检索，核心组件不再直接写死角色品牌色。
|
||
|
||
### 7.2 第二阶段：员工端主题迁移
|
||
|
||
- [ ] 员工端主色切换为服务蓝，绿色仅保留成功/在线/已解决语义。
|
||
- [ ] 消息气泡、输入区、工具栏、人工坐席描边、焦点环完成迁移。
|
||
- [ ] 蓝色服务舱在关闭 `backdrop-filter` 后仍保持布局、对比度和可操作性。
|
||
- [ ] ≤480px 窄屏、深色环境或低性能设备完成降级验证。
|
||
|
||
### 7.3 第三阶段：坐席端与管理端迁移
|
||
|
||
- [ ] 坐席端完成深海蓝 + 冷青主题收敛，AI 推荐与优先级颜色职责分离。
|
||
- [ ] 管理端完成海军蓝 + 靛蓝主题收敛，导航分组不再使用装饰性多色。
|
||
- [ ] 管理端 el-table 普通、斑马纹、hover、fixed-column 状态清晰一致。
|
||
|
||
### 7.4 体验与无障碍验收
|
||
|
||
- [ ] 普通正文对比度 ≥ 4.5:1，大文字对比度 ≥ 3:1。
|
||
- [ ] 键盘可以访问所有主要操作，并显示可见焦点环。
|
||
- [ ] 关键状态不只依赖颜色表达。
|
||
- [ ] `prefers-reduced-motion: reduce` 下关闭非必要动效。
|
||
- [ ] 视觉回归无 P0/P1 主题迁移缺陷。
|
||
|
||
---
|
||
|
||
## 八、关联文档
|
||
|
||
- 评审提案：`deliverables/视觉设计系统重定义提案-v1.0.md`
|
||
- 员工端原型：`01-产品文档/02-会话管理/原型-REQ-会话-001-工具栏统一设计v1.9.2-员工端主绿水晶玻璃版.html`（待按主题拍板结果更新）
|
||
- 坐席端原型：`01-产品文档/04-坐席工作台/原型-REQ-坐席-000-坐席工作台-v1.6.html`（待按主题拍板结果更新）
|
||
- 管理端原型：`01-产品文档/08-集成生态/原型-REQ-集成-000-管理后台-v1.1.html`（待按主题拍板结果更新）
|
||
- 技术文档：`02-技术文档/前端改造/前端改造建议-v1.1.md`
|
||
|
||
---
|
||
|
||
## 变更记录
|
||
|
||
| 日期 | 版本 | 变更内容 | 变更人 | 变更原因 |
|
||
|------|------|----------|--------|----------|
|
||
| 2026-07-19 | v1.0 | 初版建立前端设计系统 PRD | 宋献 | 统一三端视觉与组件规范 |
|
||
| 2026-07-24 | v1.1 | 补充异步交互反馈与消息添加时机原则 | 宋献 | 修复 H5 选项交互消息重复问题 |
|
||
| 2026-07-27 | v1.1 | 补充 Element Plus 深色主题表格三层覆盖规则 | 宋献 | 修复管理后台 el-table 可读性问题 |
|
||
| 2026-08-06 | v1.2 | 补充归档过程文档中遗漏的中性色阶、弹窗/抽屉/下拉层规范、旧 Token 兼容映射，并统一 Element Plus 表格示例变量 | 宋献 | 对比 v1.1.archive 过程文档后发现的实施完整性补充 |
|