simon/wecom_it_smart_desk
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
a4a9c3b260112bca24137edfd16cd1383565ce55
wecom_it_smart_desk/docs/01-产品文档/00-产品规划/PRD-REQ-通用-001-前端设计系统-v1.1.archive.md
T
Simon facc04aa65 chore: docs 结构整改 + compose 双目录对齐（合并重建提交） 
本提交为 .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-*/
2026-08-07 22:31:32 +08:00

10 KiB
Raw Blame History

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 层，否则白底白字。

/* 主体单元格（普通 + 固定列）—— 必须在 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
Reference in New Issue View Git Blame Copy Permalink