ecg-form/docs/examCache-usage.md

# examCache 缓存系统使用指南

## 概述

`examCache` 是一个基于 Pinia 的缓存系统，用于在页面间存储和获取 `examId`、`orgId` 等检查相关信息。该系统支持自动持久化到 localStorage，并具有缓存有效期管理功能。

## 特性

- ✅ 基于 Pinia 状态管理
- ✅ 自动持久化到 localStorage
- ✅ 缓存有效期管理（24小时）
- ✅ 支持从 URL 参数自动更新缓存
- ✅ TypeScript 类型支持
- ✅ 优雅的降级处理

## 安装和配置

### 1. 确保已安装依赖

项目已经安装了必要的依赖：
- `pinia`
- `pinia-plugin-persistedstate`

### 2. 缓存 Store 已配置

缓存 Store 位于 `src/store/modules/examCache.ts`，已在主 Store 中注册。

## 基本使用

### 1. 设置缓存

在页面跳转前设置缓存：

```typescript
import { useExamCacheStore } from '@/store/modules/examCache'

const examCacheStore = useExamCacheStore()

// 设置缓存
examCacheStore.setCache('EXAM001', 'ORG001', 'http://example.com/image.jpg')
```

### 2. 获取缓存

在目标页面获取缓存：

```typescript
import { useExamCacheStore } from '@/store/modules/examCache'

const examCacheStore = useExamCacheStore()

// 获取有效的 examId 和 orgId
const examId = examCacheStore.getValidExamId
const orgId = examCacheStore.getValidOrgId
const imgUrl = examCacheStore.imgUrl

// 检查缓存是否有效
if (examCacheStore.isCacheValid) {
  console.log('缓存有效，可以使用')
} else {
  console.log('缓存已过期或不存在')
}
```

### 3. 从 URL 参数更新缓存

当页面通过 URL 参数传递数据时，可以自动更新缓存：

```typescript
import { useExamCacheStore } from '@/store/modules/examCache'
import { useRoute } from 'vue-router'

const route = useRoute()
const examCacheStore = useExamCacheStore()

// 从路由参数更新缓存
examCacheStore.updateFromRoute(route.query)
```

### 4. 清除缓存

```typescript
import { useExamCacheStore } from '@/store/modules/examCache'

const examCacheStore = useExamCacheStore()

// 清除缓存
examCacheStore.clearCache()
```

## 实际应用场景

### 场景1: ECGForm 页面跳转到 translate 页面

**在 ECGForm.vue 中：**

```typescript
// 在跳转前设置缓存
const examCacheStore = useExamCacheStore()
examCacheStore.setCache(rowinfo.value.examId, rowinfo.value.orgId, imageUrl)

// 跳转到 translate 页面
router.push({
  path: '/translate',
  query: {
    img: imageUrl,
    examId: rowinfo.value.examId,
    orgId: rowinfo.value.orgId
  }
})
```

**在 translate/index.vue 中：**

```typescript
import { onMounted } from 'vue'
import { useRoute } from 'vue-router'
import { useExamCacheStore } from '@/store/modules/examCache'

const route = useRoute()
const examCacheStore = useExamCacheStore()

onMounted(() => {
  // 优先从 URL 参数获取，如果没有则从缓存获取
  const examId = (route.query.examId as string) || examCacheStore.getValidExamId
  const orgId = (route.query.orgId as string) || examCacheStore.getValidOrgId
  const imgUrl = (route.query.img as string) || examCacheStore.imgUrl
  
  // 如果从 URL 参数获取到数据，更新缓存
  if (route.query.examId || route.query.orgId || route.query.img) {
    examCacheStore.updateFromRoute(route.query)
  }
})
```

### 场景2: ukey.ts 中使用缓存

**修改 ukey.ts 中的 uploadPdf 函数：**

```typescript
import { useExamCacheStore } from '@/store/modules/examCache'

const uploadPdf = async (byteArray: number[], filename: string = 'signed.pdf') => {
  try {
    const fileStream = byteArray.join(',')
    
    // 获取缓存 store
    const examCacheStore = useExamCacheStore()
    
    // 优先从缓存获取 examId 和 orgId，如果没有则从 route.query 获取
    const examId = examCacheStore.getValidExamId || (route.query.examId as string) || ''
    const orgId = examCacheStore.getValidOrgId || (route.query.orgId as string) || ''
    
    const formData = new FormData()
    formData.append('examId', examId)
    formData.append('orgId', orgId)
    // ... 其他代码
  } catch (error) {
    console.error('文件上传失败:', error)
    throw error
  }
}
```

## API 参考

### Store 状态

```typescript
interface ExamCacheState {
  examId: string      // 检查编号
  orgId: string       // 机构编号
  imgUrl: string      // 图片地址
  timestamp: number   // 缓存时间戳
}
```

### Getters

- `isCacheValid`: 检查缓存是否有效（24小时内）
- `getValidExamId`: 获取有效的 examId
- `getValidOrgId`: 获取有效的 orgId

### Actions

- `setCache(examId: string, orgId: string, imgUrl?: string)`: 设置缓存
- `clearCache()`: 清除缓存
- `updateFromRoute(query: any)`: 从路由参数更新缓存

## 缓存策略

### 优先级顺序

1. **URL 参数** - 最高优先级
2. **缓存数据** - 次优先级
3. **空值** - 最低优先级

### 有效期管理

- 缓存有效期为 **24 小时**
- 过期后需要重新设置
- 时间戳不持久化，每次页面刷新后重新计算

### 持久化配置

```typescript
persist: {
  key: 'exam-cache',
  storage: localStorage,
  paths: ['examId', 'orgId', 'imgUrl'] // 只持久化这些字段
}
```

## 最佳实践

### 1. 在页面跳转前设置缓存

```typescript
// 推荐：在跳转前设置缓存
const examCacheStore = useExamCacheStore()
examCacheStore.setCache(examId, orgId, imgUrl)
router.push({ path: '/target', query: { examId, orgId, img: imgUrl } })
```

### 2. 在目标页面优先使用 URL 参数

```typescript
// 推荐：优先使用 URL 参数，然后回退到缓存
const examId = (route.query.examId as string) || examCacheStore.getValidExamId
const orgId = (route.query.orgId as string) || examCacheStore.getValidOrgId
```

### 3. 定期清理过期缓存

```typescript
// 在应用启动时检查缓存有效性
const examCacheStore = useExamCacheStore()
if (!examCacheStore.isCacheValid) {
  examCacheStore.clearCache()
}
```

### 4. 错误处理

```typescript
// 添加错误处理
try {
  const examId = examCacheStore.getValidExamId
  if (!examId) {
    throw new Error('未找到有效的检查编号')
  }
  // 使用 examId
} catch (error) {
  console.error('获取缓存失败:', error)
  // 处理错误
}
```

## 注意事项

1. **缓存有效期**: 缓存有效期为 24 小时，过期后需要重新设置
2. **类型安全**: 使用 TypeScript 确保类型安全
3. **降级处理**: 始终提供降级方案，避免因缓存问题导致功能不可用
4. **调试**: 使用浏览器开发者工具查看 localStorage 中的缓存数据
5. **清理**: 在适当的时候清理过期缓存

## 故障排除

### 常见问题

1. **缓存不生效**
   - 检查 Pinia 是否正确配置
   - 检查 localStorage 是否可用
   - 检查缓存是否已过期

2. **类型错误**
   - 确保正确导入类型
   - 检查 TypeScript 配置

3. **缓存数据丢失**
   - 检查 localStorage 存储限制
   - 检查浏览器隐私设置

### 调试方法

```typescript
// 在浏览器控制台中调试
const examCacheStore = useExamCacheStore()
console.log('缓存状态:', {
  examId: examCacheStore.examId,
  orgId: examCacheStore.orgId,
  imgUrl: examCacheStore.imgUrl,
  timestamp: examCacheStore.timestamp,
  isValid: examCacheStore.isCacheValid
})

// 查看 localStorage
console.log('localStorage:', localStorage.getItem('exam-cache'))
```