wecom_it_smart_desk/docs/01-产品文档/00-产品规划/PRD-REQ-通用-003-管理后台表格可读性-v1.0.md

# PRD - 管理后台表格可读性优化

> **需求编号**: REQ-通用-003
> **版本**: v1.0
> **状态**: 草稿
> **作者**: 宋献
> **日期**: 2026-07-27
> **关联文档**: 无
> **优先级**: P2-Medium

---

## 1. 需求描述

### 1.1 背景

管理后台「角色管理 → 用户角色分配」表格的 **"员工账号 / 姓名 / 分配者 / 分配时间"** 四列内容存在严重的可读性问题，影响运营人员日常工作。

经排查，根因为 `Roles.vue:940-943` 强制把表格行背景设为浅色 `#fafafa`，但文字色仍继承深色主题变量 `var(--text-primary) = #f1f5f9`（接近白色），形成 **白底白字** 的视觉灾难，对比度几乎为 0。

### 1.2 目标

1. 修复用户角色分配表的颜色冲突，恢复文字可读性
2. 为长文本列添加 `show-overflow-tooltip`，避免内容被截断
3. 关键标识列（员工账号、姓名）固定左侧，横向滚动时不会丢失上下文
4. 提供简单搜索框，方便运营人员快速定位某个员工/分配者的记录
5. 形成可复用的"管理后台表格可读性"规范，避免类似问题在其他页面复发

### 1.3 范围

| 改动项 | 涉及文件 | 范围 |
|--------|---------|------|
| 修复颜色冲突 | `src/frontend-admin/src/views/Roles.vue` | 仅 `.user-roles-table` 选择器 |
| 添加 tooltip + fixed 列 | `src/frontend-admin/src/views/Roles.vue` | 表格 8 列全部调整 |
| 添加搜索过滤 | `src/frontend-admin/src/views/Roles.vue` | `filteredUserRoles` computed |
| 复用性规范 | `src/frontend-admin/src/styles/global.css` | 注释（无功能改动） |

**不在范围**：
- 不改动后端 API
- 不改动其他表格（如"自动映射规则"表——目前问题不严重）
- 不重做整个表格组件（如换成 vxe-table）

---

## 2. 用户故事

### 2.1 运营人员

| 优先级 | 用户故事 |
|--------|---------|
| P0 | 作为运营人员，我希望表格文字清晰可读，能直接看到员工账号、姓名、分配者、分配时间 |
| P1 | 作为运营人员，我希望长员工姓名/分配者被截断时，鼠标悬停能看到完整内容 |
| P1 | 作为运营人员，我希望横向滚动表格时，左侧的"员工账号/姓名"列不消失 |
| P2 | 作为运营人员，我希望能搜索员工姓名/账号，快速过滤出我关心的记录 |

### 2.2 前端开发

| 优先级 | 用户故事 |
|--------|---------|
| P1 | 作为前端开发，我希望这套样式修复能复用，避免后续其他表格再犯同样错误 |

---

## 3. 功能需求

### 3.1 样式修复（核心）

**当前代码（Roles.vue:940-943）**：

```css
.user-roles-table :deep(.el-table__body td) {
  background-color: #fafafa;          /* 浅灰白背景 */
  color: var(--text-primary);          /* #f1f5f9 白色文字 = 白底白字 */
}
```

**目标代码**：

```css
.user-roles-table :deep(.el-table__body td) {
  background-color: var(--bg-secondary);  /* #1e293b 与全站深色主题一致 */
  color: var(--text-primary);             /* #f1f5f9 浅色文字，深底浅字对比清晰 */
}
.user-roles-table :deep(.el-table__row--striped td) {
  background-color: var(--bg-tertiary);   /* 斑马纹 #334155 */
}
.user-roles-table :deep(.el-table__body tr:hover > td) {
  background-color: rgba(59, 130, 246, 0.15) !important;
}
```

### 3.2 列属性优化

| 列名 | 当前 | 调整后 |
|------|------|--------|
| 员工账号 | `min-width="120"` | `min-width="120" fixed="left" show-overflow-tooltip` |
| 姓名 | `min-width="100"` | `min-width="100" fixed="left" show-overflow-tooltip` |
| 角色 | `min-width="100"` | `min-width="100"` |
| 来源 | `min-width="100"` | `min-width="100" show-overflow-tooltip` |
| 分配者 | `min-width="100"` | `min-width="120" show-overflow-tooltip` |
| 分配时间 | `min-width="160"` | `min-width="160" show-overflow-tooltip` |
| 过期时间 | `min-width="160"` | `min-width="160" show-overflow-tooltip` |
| 操作 | `width="100" fixed="right"` | 保持不变 |

### 3.3 搜索框

在表格上方添加简易搜索输入框，按 `employee_id` / `employee_name` / `assigned_by` 任一字段做模糊匹配（大小写不敏感）。

**实现**：复用 `filteredUserRoles` computed，新增 `searchKeyword` ref + watcher/计算属性。

---

## 4. 验收标准

### 4.1 功能验收

| 编号 | 验收项 | 通过标准 |
|------|--------|----------|
| AC-1 | 文字可读 | 「员工账号/姓名/分配者/分配时间」四列文字清晰可见（对比度 ≥ 4.5:1，WCAG AA） |
| AC-2 | 溢出提示 | 长员工姓名被截断时，鼠标悬停显示完整内容 |
| AC-3 | 固定列 | 横向滚动表格时，"员工账号/姓名"两列保持可见 |
| AC-4 | 搜索 | 输入员工姓名/账号关键词，列表实时过滤 |
| AC-5 | 主题一致 | 表格样式与全站深色科技风一致，无突兀色块 |
| AC-6 | 斑马纹 | 偶数行/奇数行有可辨识的背景区分 |

### 4.2 回归验收

| 编号 | 验收项 | 通过标准 |
|------|--------|----------|
| AC-7 | 现有功能 | 分配角色 / 撤销角色 / 搜索员工对话框 全部正常使用 |
| AC-8 | 其他表格 | 「自动映射规则」表样式不受影响 |
| AC-9 | 其他页面 | 角色概览卡片网格样式不受影响 |
| AC-10 | 移动端响应式 | 视口宽度 < 1280px 时表格仍可用 |

---

## 5. 关联信息

- **关联缺陷**: BUG-通用-001
- **关联代码文件**: `src/frontend-admin/src/views/Roles.vue`
- **关联样式文件**: `src/frontend-admin/src/styles/global.css`
- **关联测试**: 手动验收（详见 `BUG-通用-001` 验证清单）

---

## 6. 变更记录

| 日期 | 版本 | 变更内容 | 变更人 |
|------|------|----------|--------|
| 2026-07-27 | v1.0 | 创建 PRD，记录表格可读性问题与修复方案 | 宋献 / Duckula |