# 字典系统使用指南

## 概述

字典系统是为了解决项目中数据字典不统一、硬编码问题而设计的统一管理方案。系统支持静态字典（本地定义）和动态字典（API获取），并提供了便捷的访问接口。

## 系统架构

字典系统由以下几个部分组成：

1. **工具类** (`src/utils/dict.ts`) - 提供静态字典数据和工具函数
2. **Store** (`src/stores/dict.ts`) - 管理动态字典数据，与现有Pinia架构集成
3. **API服务** (`src/service/api/dict.ts`) - 提供动态字典获取接口
4. **组件示例** - 展示如何在组件中使用字典系统

## 使用方法

### 1. 在组件中使用字典

```typescript
<script setup lang="ts">
import { useDictStore } from '~/stores/dict'
import { getDictLabel, getDictColor } from '~/utils/dict'

const dictStore = useDictStore()

// 获取字典项列表
const professionalCategoryItems = computed(() => dictStore.getDictItems('professionalCategory'))

// 获取字典项标签
const label = dictStore.getDictLabel('professionalCategory', 'science')

// 获取字典项颜色
const color = dictStore.getDictColor('educationalLevel', 'undergraduate')
</script>
```

### 2. 在模板中使用

```vue
<template>
  <select v-model="selectedValue">
    <option 
      v-for="item in dictStore.getDictItems('professionalCategory')" 
      :key="item.value" 
      :value="item.value"
    >
      {{ item.label }}
    </option>
  </select>
  
  <!-- 显示标签 -->
  <span>选中值: {{ dictStore.getDictLabel('professionalCategory', selectedValue) }}</span>
</template>
```

### 3. 静态字典工具函数

```typescript
// 获取字典项列表
const items = getDictItems('professionalCategory')

// 获取字典标签
const label = getDictLabel('professionalCategory', 'science')

// 获取字典值
const value = getDictValue('professionalCategory', '理工类')

// 获取字典颜色
const color = getDictColor('professionalCategory', 'science')

// 获取字典项对象
const item = getDictItem('professionalCategory', 'science')
```

### 4. 动态字典管理

```typescript
// 加载动态字典
await dictStore.loadDynamicDicts()

// 加载特定类型的动态字典
await dictStore.loadDynamicDicts(['dynamic_type1', 'dynamic_type2'])

// 手动设置动态字典
dictStore.setDynamicDict('custom_type', [
  { label: '自定义项1', value: 'custom1' },
  { label: '自定义项2', value: 'custom2' }
])

// 清空动态字典
dictStore.clearDynamicDicts()
```

## 字典数据结构

字典项接口定义：

```typescript
interface DictItem {
  label: string      // 显示标签
  value: string | number  // 实际值
  disabled?: boolean  // 是否禁用
  color?: string     // 颜色值
  order?: number     // 排序
  [key: string]: any // 扩展属性
}
```

## 静态字典类型

目前系统已内置以下静态字典：

- `professionalCategory` - 专业类别
- `educationalLevel` - 学历层次
- `provinces` - 省份
- `subjectList` - 科目列表
- `gender` - 性别
- `status` - 状态
- `type` - 类型

## 动态字典API

动态字典通过API获取，支持以下接口：

- `GET /dict/list` - 获取字典列表
- `GET /dict/type/{type}` - 获取指定类型的字典

## 在现有组件中集成

以ScoreForm.vue为例，展示了如何将现有硬编码的选项替换为字典系统：

1. 导入字典Store
2. 使用computed属性获取字典项
3. 在模板中使用字典数据

## 扩展字典类型

如需添加新的静态字典类型：

1. 在 `src/utils/dict.ts` 中的 `staticDicts` 对象中添加新类型
2. 确保遵循 `DictItem[]` 的数据结构

如需添加新的动态字典类型：

1. 在后端API中提供相应的字典数据接口
2. 在前端调用 `dictStore.loadDynamicDicts()` 时指定类型

## 最佳实践

1. **优先使用字典系统** - 避免在代码中硬编码选项数据
2. **统一管理** - 所有字典数据通过字典系统统一管理
3. **性能优化** - 字典数据通常在应用初始化时加载一次，后续直接使用
4. **扩展性** - 支持静态和动态字典，满足不同业务场景需求
5. **类型安全** - 提供完整的TypeScript类型定义

## 注意事项

1. 动态字典加载失败时，系统会继续使用静态字典数据
2. 字典数据在应用生命周期内会被缓存，避免重复请求
3. 在组件中使用字典前，确保字典数据已加载完成
4. 动态字典会覆盖同名的静态字典数据