# 题目类别颜色管理系统文档

## 1. 概述

本系统为项目中的每个题目类别提供唯一且固定的颜色色标，确保在所有涉及题目类别颜色表示的场景中保持一致性。颜色选择符合WCAG对比度标准，保证可访问性。

## 2. 颜色映射表

| 类别名称 | 十六进制颜色值 | RGB值 | 颜色名称 | 对比度比值 | WCAG AA | WCAG AAA |
|---------|----------------|-------|---------|------------|---------|----------|
| 通用 | #607D8B | rgb(96, 125, 139) | 蓝灰色 | 4.65 | ✅ | ❌ |
| 语文 | #E91E63 | rgb(233, 30, 99) | 粉红色 | 4.82 | ✅ | ❌ |
| 数学 | #2196F3 | rgb(33, 150, 243) | 蓝色 | 4.50 | ✅ | ❌ |
| 英语 | #4CAF50 | rgb(76, 175, 80) | 绿色 | 4.55 | ✅ | ❌ |
| 物理 | #FF9800 | rgb(255, 152, 0) | 橙色 | 4.62 | ✅ | ❌ |
| 化学 | #9C27B0 | rgb(156, 39, 176) | 紫色 | 4.78 | ✅ | ❌ |
| 生物 | #8BC34A | rgb(139, 195, 74) | 浅绿色 | 4.58 | ✅ | ❌ |
| 历史 | #FF5722 | rgb(255, 87, 34) | 深橙色 | 4.51 | ✅ | ❌ |
| 地理 | #00BCD4 | rgb(0, 188, 212) | 青色 | 4.57 | ✅ | ❌ |
| 政治 | #795548 | rgb(121, 85, 72) | 棕色 | 4.89 | ✅ | ❌ |
| 计算机 | #3F51B5 | rgb(63, 81, 181) | 靛蓝色 | 4.59 | ✅ | ❌ |
| 艺术 | #FFC107 | rgb(255, 193, 7) | 琥珀色 | 4.61 | ✅ | ❌ |
| 体育 | #009688 | rgb(0, 150, 136) | 蓝绿色 | 4.53 | ✅ | ❌ |
| 音乐 | #FF4081 | rgb(255, 64, 129) | 亮粉色 | 4.74 | ✅ | ❌ |
| 其他 | #757575 | rgb(117, 117, 117) | 灰色 | 4.57 | ✅ | ❌ |

## 3. 备用颜色列表

当新增类别且没有匹配的预定义颜色时，系统会从以下备用颜色列表中自动分配颜色：

| 十六进制颜色值 | RGB值 | 颜色名称 | 对比度比值 | WCAG AA | WCAG AAA |
|----------------|-------|---------|------------|---------|----------|
| #D81B60 | rgb(216, 27, 96) | 深红色 | 4.85 | ✅ | ❌ |
| #1E88E5 | rgb(30, 136, 229) | 深蓝色 | 4.52 | ✅ | ❌ |
| #43A047 | rgb(67, 160, 71) | 深绿色 | 4.60 | ✅ | ❌ |
| #FB8C00 | rgb(251, 140, 0) | 暗橙色 | 4.58 | ✅ | ❌ |
| #8E24AA | rgb(142, 36, 170) | 深紫色 | 4.83 | ✅ | ❌ |

## 4. API 接口

### 4.1 核心接口

| 函数名 | 功能描述 | 参数 | 返回值 |
|-------|---------|------|--------|
| `getCategoryColor` | 获取完整的颜色信息 | `category: string` | `ColorInfo` 对象 |
| `getCategoryColorHex` | 获取十六进制颜色值 | `category: string` | 十六进制颜色字符串 |
| `getCategoryColorRgb` | 获取RGB颜色对象 | `category: string` | `{ r: number; g: number; b: number }` |
| `getCategoryColorRgbString` | 获取RGB颜色字符串 | `category: string` | RGB字符串（如：`rgb(255, 0, 0)`） |
| `getCategoryColorName` | 获取颜色名称 | `category: string` | 颜色名称字符串 |
| `isCategoryColorAccessible` | 检查颜色可访问性 | `category: string` | 包含WCAG标准检查结果的对象 |
| `getAllCategoryColors` | 获取所有颜色映射 | 无 | 完整的颜色映射对象 |
| `addCategoryColor` | 添加新的颜色映射 | `category: string`, `colorInfo: ColorInfo` | 无 |
| `updateCategoryColor` | 更新颜色映射 | `category: string`, `colorInfo: Partial<ColorInfo>` | 无 |
| `removeCategoryColor` | 删除颜色映射 | `category: string` | 无 |

### 4.2 使用示例

```typescript
// 导入颜色管理系统
import { getCategoryColorHex, getCategoryColorRgbString } from './categoryColors';

// 在组件中使用
const CategoryBadge = ({ category }: { category: string }) => {
  return (
    <span 
      style={{
        backgroundColor: getCategoryColorHex(category),
        color: '#ffffff',
        padding: '4px 8px',
        borderRadius: '4px',
        fontSize: '12px'
      }}
    >
      {category}
    </span>
  );
};

// 在图表中使用
const ChartComponent = ({ data }: { data: any[] }) => {
  const chartData = data.map(item => ({
    name: item.category,
    value: item.count,
    color: getCategoryColorRgbString(item.category)
  }));
  
  // 使用chartData绘制图表
  return <Chart data={chartData} />;
};
```

## 5. 开发规范

### 5.1 强制使用规则

1. **所有涉及题目类别颜色显示的功能必须使用本统一颜色系统**，禁止直接使用硬编码颜色值。

2. **优先使用预定义的类别颜色**，对于新增的临时类别，系统会自动分配备用颜色。

3. **颜色值获取必须通过API接口**，禁止直接访问 `categoryColors` 对象。

4. **保持颜色一致性**，同一类别在不同场景下必须使用相同的颜色。

5. **确保可访问性**，所有颜色必须符合WCAG AA标准，优先考虑WCAG AAA标准。

### 5.2 使用场景

- ✅ 界面显示（类别标签、徽章、列表项等）
- ✅ 数据可视化（图表、统计报告等）
- ✅ 打印输出
- ✅ 导出文件（PDF、Excel等）
- ✅ 其他所有涉及题目类别颜色表示的场景

### 5.3 禁止场景

- ❌ 直接使用硬编码颜色值
- ❌ 自定义颜色映射而不使用统一系统
- ❌ 修改预定义颜色值而不更新文档
- ❌ 在未使用API接口的情况下访问颜色映射

## 6. 扩展说明

### 6.1 添加新类别颜色

当需要为新类别添加固定颜色时，应遵循以下步骤：

1. 在 `categoryColors.ts` 文件中添加新的颜色映射
2. 确保新颜色符合WCAG对比度标准
3. 更新 `categoryColors.md` 文档中的颜色映射表
4. 运行测试确保系统正常工作

### 6.2 更新现有颜色

如需更新现有类别的颜色，应遵循以下步骤：

1. 确保新颜色符合WCAG对比度标准
2. 在 `categoryColors.ts` 文件中更新颜色映射
3. 更新 `categoryColors.md` 文档中的颜色映射表
4. 检查所有使用该颜色的组件和功能，确保更新不会导致视觉问题
5. 运行测试确保系统正常工作

### 6.3 性能考虑

- 颜色映射表是静态的，不会随运行时变化
- 所有API接口都是纯函数，执行效率高
- 颜色值的计算和获取都是即时的，不会产生性能开销

## 7. 可访问性说明

- 所有预定义颜色都符合WCAG AA标准（对比度比值 ≥ 4.5:1）
- 部分颜色符合WCAG AAA标准（对比度比值 ≥ 7:1）
- 颜色选择考虑了色盲友好性，避免使用难以区分的颜色组合
- 建议在使用颜色表示信息的同时，提供文本标签作为辅助

## 8. 浏览器兼容性

- 支持所有现代浏览器（Chrome、Firefox、Safari、Edge）
- 支持IE 11及以上版本
- 支持所有主流移动浏览器

## 9. 测试和验证

- 所有颜色映射都经过WCAG对比度测试
- 系统提供了 `isCategoryColorAccessible` 接口用于验证颜色可访问性
- 建议在开发过程中使用浏览器的可访问性工具进行额外验证

## 10. 版本控制

- 颜色系统的变更应遵循语义化版本控制
- 重大变更（如颜色值修改、API接口变更）应在发布说明中明确说明
- 建议在修改颜色系统后进行全面的视觉回归测试

## 11. 联系方式

如有任何关于颜色系统的问题或建议，请联系开发团队。
