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-*/
285 lines
10 KiB
Markdown
285 lines
10 KiB
Markdown
# PRD - 前端设计系统
|
||
|
||
> **REQ编号**: REQ-通用-001
|
||
> **版本**: v1.1
|
||
> **优先级**: P1
|
||
> **阶段**: 中期（3-4个月）
|
||
> **作者**: 宋献
|
||
> **日期**: 2026-07-19（v1.1 补充 2026-07-27）
|
||
|
||
---
|
||
|
||
## 一、问题陈述
|
||
|
||
**用户问题**：
|
||
- H5、坐席、管理后台三端视觉风格割裂
|
||
- 缺乏统一的 Design Tokens
|
||
- 品牌感弱，除绿色外没有独特视觉符号
|
||
|
||
**业务目标**：
|
||
- 建立统一的 IT 智能服务台设计系统
|
||
- 三端视觉风格一致，提升产品辨识度
|
||
- 提升用户体验和品牌感知
|
||
|
||
---
|
||
|
||
## 二、需求范围
|
||
|
||
### 2.1 核心功能
|
||
|
||
| 功能 | 描述 |
|
||
|------|------|
|
||
| Design Tokens | 统一的色彩、字体、间距、圆角、阴影、动效 |
|
||
| 组件规范 | 按钮、输入框、卡片、弹窗等组件规范 |
|
||
| 图标库 | 统一使用 Lucide 图标库 |
|
||
| 深色模式 | 完整的深色模式适配 |
|
||
|
||
### 2.2 非目标
|
||
|
||
- 不包含完整的设计系统文档网站
|
||
- 不包含组件库的实现（仅定义规范）
|
||
|
||
---
|
||
|
||
## 三、用户故事
|
||
|
||
| 角色 | 用户故事 | 验收标准 |
|
||
|------|----------|---------|
|
||
| 前端开发 | 有统一的 Design Tokens 可复用 | 三端使用统一的 CSS 变量 |
|
||
| 设计师 | 有完整的组件规范文档 | 设计产出符合规范 |
|
||
| 员工 | 三端视觉风格一致 | H5、坐席、后台看起来像同一产品 |
|
||
|
||
---
|
||
|
||
## 四、功能详情
|
||
|
||
### 4.1 Design Tokens 定义
|
||
|
||
**色彩系统**：
|
||
| Token | 值 | 用途 |
|
||
|-------|-----|------|
|
||
| --color-primary | #07C160 | 主色（企微绿） |
|
||
| --color-primary-light | #E8F5E9 | 主色浅背景 |
|
||
| --color-primary-dark | #056739 | 主色深色 |
|
||
| --color-secondary | #3b82f6 | 辅助色-蓝 |
|
||
| --color-accent | #FF9800 | 强调色-橙 |
|
||
| --color-success | #10B981 | 成功 |
|
||
| --color-warning | #F59E0B | 警告 |
|
||
| --color-danger | #EF4444 | 危险 |
|
||
| --color-info | #6B7280 | 信息 |
|
||
|
||
**灰阶**：
|
||
| Token | 值 | 用途 |
|
||
|-------|-----|------|
|
||
| --gray-50 | #F9FAFB | 页面背景 |
|
||
| --gray-100 | #F3F4F6 | 卡片背景 |
|
||
| ... | ... | ... |
|
||
| --gray-900 | #111827 | 主标题 |
|
||
|
||
**排版系统**：
|
||
| 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 组件规范
|
||
|
||
**按钮**：
|
||
- 主按钮：主色填充，白色文字，6px 圆角
|
||
- 次按钮：边框主色，主色文字，透明背景
|
||
- 文字按钮：无背景，无边框，主色文字
|
||
|
||
**输入框**：
|
||
- 默认：灰色边框，14px 圆角
|
||
- 聚焦：主色边框，显示阴影
|
||
- 错误：红色边框，显示错误提示
|
||
|
||
**卡片**：
|
||
- 白色背景，8px 圆角，轻微阴影
|
||
- 可选：边框样式（细灰线）
|
||
|
||
### 4.3 图标规范
|
||
|
||
- 统一使用 Lucide 图标库
|
||
- 风格：线框风格（outline）
|
||
- 尺寸：16px（辅助）、20px（常规）、24px（强调）
|
||
|
||
---
|
||
|
||
## 四、用户交互反馈规范（补充）
|
||
|
||
> **补充日期**: 2026-07-24
|
||
> **补充原因**: 2026-07-24 H5选项交互消息重复Bug反思——产品设计文档中缺失「用户交互反馈」定义
|
||
|
||
### 4.4 交互反馈设计原则
|
||
|
||
**核心原则**：所有涉及后端异步响应的用户操作，前端应优先通过**UI状态变化**反馈结果，而非**临时消息**。
|
||
|
||
| 场景 | 不推荐做法 | 推荐做法 |
|
||
|------|-----------|---------|
|
||
| 用户点击AI选项 | 立即显示一条"待确认"消息，等后端返回后删除或保留 | 按钮立即禁用 + 高亮选中态，静默发WS，等后端返回后再添加正式消息 |
|
||
| 用户发送消息 | 本地先添加消息，等后端返回确认后再决定是否显示 | 按钮禁用 + 发送中状态，后端返回后添加正式消息 |
|
||
| 用户上传文件 | 先显示"上传中..."的临时消息 | 进度条 + 按钮禁用，上传完成后显示正式消息 |
|
||
|
||
### 4.5 交互状态定义
|
||
|
||
每一种用户操作都应定义以下状态：
|
||
|
||
| 状态 | 视觉表现 | 说明 |
|
||
|------|---------|------|
|
||
| **正常态** | 按钮可点击，无特殊样式 | 用户可以执行操作 |
|
||
| **处理中态** | 按钮禁用 + 加载指示器 | 后端正在处理，不允许重复点击 |
|
||
| **成功态** | 恢复正常，可能有短暂高亮反馈 | 操作成功完成 |
|
||
| **失败态** | 按钮恢复可用 + 错误提示 | 操作失败，需要用户重试 |
|
||
|
||
### 4.6 消息添加时机原则
|
||
|
||
**技术设计原则**：前端不应在收到后端确认前添加消息到消息列表。
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────────┐
|
||
│ 推荐的消息添加流程 │
|
||
├─────────────────────────────────────────────────────────────────┤
|
||
│ 1. 用户触发操作（如点击选项） │
|
||
│ 2. 前端：UI状态变为「处理中」（按钮禁用） │
|
||
│ 3. 前端：发送请求到后端（WS或HTTP） │
|
||
│ 4. 后端：处理完成，返回确认消息 │
|
||
│ 5. 前端：收到后端确认后，添加到消息列表 │
|
||
│ 6. 前端：UI状态恢复「正常」或变为「成功」 │
|
||
└─────────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
**为什么这样设计**：
|
||
1. 避免消息ID不一致导致的重复显示问题
|
||
2. 用户通过UI状态变化就能感知操作已被接收，不需要"假消息"来确认
|
||
3. 后端失败时，前端只需要恢复UI状态，不需要处理消息的"撤回"
|
||
|
||
### 4.7 Element Plus 深色主题适配规范（v1.1 补充 2026-07-27）
|
||
|
||
> **补充原因**：BUG-通用-001（管理后台 el-table 白底白字）暴露了设计系统在 Element Plus 落地时的具体应用规则缺失。本节明确设计 Tokens 在 Element Plus 组件上的覆盖要求。
|
||
|
||
#### 4.7.1 适用范围
|
||
|
||
- 所有使用 `<el-table>` 的视图（管理后台核心列表页）
|
||
- 后续扩展到 `<el-dialog>` / `<el-tag>` / `<el-form>` / `<el-pagination>` 等深色主题相关组件
|
||
|
||
#### 4.7.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(--bg-secondary) !important; /* ⚠️ 必须 !important */
|
||
color: var(--text-primary);
|
||
}
|
||
|
||
/* 斑马纹行（偶数行） */
|
||
.el-table .el-table__row--striped td, ... {
|
||
background-color: var(--bg-tertiary) !important;
|
||
}
|
||
|
||
/* hover 状态 */
|
||
.el-table .el-table__body tr:hover > td, ... {
|
||
background-color: rgba(59, 130, 246, 0.15) !important;
|
||
}
|
||
```
|
||
|
||
#### 4.7.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.7.4 验收清单（每个 el-table 视图必须通过）
|
||
|
||
- [ ] 普通行（无 striped）背景深、文字浅 → 清晰
|
||
- [ ] 偶数行（striped）背景更深一档、文字浅 → 清晰
|
||
- [ ] 固定列（`fixed="left"` 或 `fixed="right"`）与同行普通列颜色一致
|
||
- [ ] hover 时整行变蓝透 → 文字仍可读
|
||
- [ ] 表格头（thead）背景与全站风格一致
|
||
- [ ] WCAG 对比度 ≥ 4.5:1
|
||
|
||
#### 4.7.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.7.6 关联文档
|
||
|
||
- 缺陷单：`03-测试文档/05-缺陷单/BUG-通用-用户角色分配表格看不清-001.md`
|
||
- 故障案例：`04-运维文档/部署运维/00-标准故障排查手册.md` CASE-20260727-02
|
||
- Skill：`~/.workbuddy/skills/element-plus-dark-table/SKILL.md`
|
||
|
||
---
|
||
|
||
## 五、指标设计
|
||
|
||
| 指标 | 目标 | 测量方式 |
|
||
|------|------|---------|
|
||
| 设计系统覆盖率 | 100% | 三端组件使用 Design Tokens 的比例 |
|
||
| 三端视觉一致性 | ≥ 90% | 用户调研评分 |
|
||
|
||
---
|
||
|
||
## 六、技术方案
|
||
|
||
- 使用 CSS Custom Properties 实现 Design Tokens
|
||
- 抽离为独立 CSS 文件，三端引入
|
||
- 深色模式通过 CSS 变量覆盖实现
|
||
|
||
---
|
||
|
||
## 七、关联文档
|
||
|
||
- 技术文档: `02-技术文档/前端改造/前端改造建议-v1.1.md`
|