# 设计文档

## 概述

本设计为测试流程列表页面添加颜色图例功能。图例将显示在表格上方，展示所有测试分类及其对应的颜色，帮助用户快速理解表格中彩色标签的含义。

## 架构

### 前端组件架构

```
test_flow/index.vue
├── 查询表单区域
├── 操作按钮区域
├── 颜色图例组件 (新增)
│   └── 分类颜色映射显示
├── 数据表格
│   └── 测试项列（使用彩色标签）
└── 分页组件
```

### 颜色分配策略

使用一致的颜色分配算法，确保同一测试分类在所有地方都显示相同的颜色：
- 基于分类ID的哈希值来分配颜色索引
- 使用模运算确保颜色索引在可用颜色范围内
- 颜色数组：`['#409EFF', '#67C23A', '#909399', '#E6A23C', '#F56C6C', '#8E44AD', '#FF7F50']`

## 组件和接口

### 1. 颜色图例组件

**位置**: 在操作按钮行和数据表格之间

**数据源**: 
- `categoryOptions`: 从后端API获取的所有测试分类列表
- `tagColors`: 预定义的颜色数组

**显示逻辑**:
```javascript
// 为每个分类计算一致的颜色索引
getCategoryColor(categoryId) {
  const colorIndex = categoryId % this.tagColors.length;
  return this.tagColors[colorIndex];
}
```

### 2. 表格标签渲染更新

**当前实现问题**: 
- 使用数组索引 `index % tagColors.length` 分配颜色
- 同一分类在不同行可能显示不同颜色

**改进方案**:
- 改用分类ID来计算颜色索引
- 确保同一分类始终显示相同颜色

```javascript
// 修改前
:style="{backgroundColor: tagColors[index % tagColors.length]}"

// 修改后
:style="{backgroundColor: getCategoryColor(tag.test_category_id)}"
```

## 数据模型

### 测试分类数据结构

```javascript
{
  id: Number,           // 分类ID
  name: String,         // 分类名称
  // ... 其他字段
}
```

### 图例项数据结构

```javascript
{
  categoryId: Number,   // 分类ID
  categoryName: String, // 分类名称
  color: String        // 十六进制颜色值
}
```

## 正确性属性

*属性是指在系统所有有效执行中都应该成立的特征或行为——本质上是关于系统应该做什么的正式声明。属性作为人类可读规范和机器可验证正确性保证之间的桥梁。*

### 属性 1: 颜色一致性

*对于任何* 测试分类ID，无论在图例中还是在表格标签中，多次调用颜色计算函数都应该返回相同的颜色值
**验证: 需求 1.2, 2.1, 3.1, 3.2, 3.4**

### 属性 2: 图例完整性

*对于任何* 分类列表，图例中显示的分类数量应该等于输入的分类数量
**验证: 需求 1.4**

### 属性 3: 图例项结构完整性

*对于任何* 图例项，渲染后的DOM元素应该同时包含颜色方块和分类名称文本
**验证: 需求 1.3**

### 属性 4: 颜色来源有效性

*对于任何* 分类ID，分配的颜色应该存在于预定义的tagColors数组中
**验证: 需求 3.3**

### 属性 5: 图例项间距一致性

*对于任何* 相邻的图例项对，它们之间的间距应该相等
**验证: 需求 2.4**

## 错误处理

### 1. 分类数据加载失败
- **场景**: API请求失败或返回空数据
- **处理**: 显示空图例或提示信息，不影响表格正常显示

### 2. 颜色数组未定义
- **场景**: tagColors数组为空或未初始化
- **处理**: 使用默认颜色或灰色作为后备方案

### 3. 分类ID无效
- **场景**: 分类ID为null、undefined或非数字
- **处理**: 使用默认颜色索引0

## 测试策略

### 单元测试

1. **颜色计算函数测试**
   - 测试相同ID返回相同颜色
   - 测试不同ID可能返回不同颜色
   - 测试边界情况（ID为0、负数、很大的数）

2. **图例渲染测试**
   - 测试空分类列表的渲染
   - 测试单个分类的渲染
   - 测试多个分类的渲染

### 集成测试

1. **端到端显示测试**
   - 验证图例和表格标签颜色一致
   - 验证页面加载后图例正确显示
   - 验证响应式布局在不同屏幕尺寸下的表现

### 视觉回归测试

1. 截图对比测试，确保UI变更不影响现有布局
2. 验证颜色对比度满足可访问性标准

## UI设计规范

### 图例布局

```
┌─────────────────────────────────────────────────┐
│ 测试项图例：                                      │
│ ■ 分类1  ■ 分类2  ■ 分类3  ■ 分类4  ■ 分类5      │
└─────────────────────────────────────────────────┘
```

### 样式规范

- **图例容器**: 
  - 背景色: `#f5f7fa`
  - 内边距: `10px 15px`
  - 边框圆角: `4px`
  - 外边距: `10px 0`

- **图例项**:
  - 颜色方块: `12px × 12px`
  - 方块圆角: `2px`
  - 文字大小: `14px`
  - 项间距: `15px`

- **响应式**:
  - 小屏幕: 垂直堆叠
  - 大屏幕: 水平排列，自动换行