# 统一图片缓存方案设计文档

## 文档信息

- **创建日期**: 2026-01-07
- **版本**: 1.0
- **状态**: 实现中

## 背景

当前项目中存在三个独立的缓存系统：
1. Service Worker 的 Cache API（`drawnix-images`）
2. 应用层的 Media Cache Service（`drawnix-media-cache` IndexedDB）
3. 应用层的 URL Cache Service（`aitu-url-cache` IndexedDB）

这种分散的缓存架构导致了以下问题：
- 缓存逻辑不统一，维护困难
- Service Worker 缓存没有任务元数据（模型、提示词、参数）
- 无法根据缓存时间智能决策传 URL 还是 base64
- 缺少缓存满时的用户友好提示

## 设计目标

1. **统一缓存管理**：一个服务协调 SW 和应用层缓存
2. **完整元数据存储**：记录缓存时间、生成参数、模型信息
3. **智能图片传递**：调用 AI 接口时，1天内用 URL，超过1天用 base64
4. **用户可控清理**：缓存满时提示打开素材库手动删除
5. **向下兼容**：从旧数据库迁移数据

## 架构设计

### 整体架构

```
┌─────────────────────────────────────────────────────────────┐
│                      浏览器主线程                              │
│                                                               │
│  ┌──────────────────────────────────────────────────────┐   │
│  │  Unified Cache Manager (统一缓存管理器)                │   │
│  │                                                        │   │
│  │  - 协调 SW 和 IndexedDB                               │   │
│  │  - 处理元数据存储                                      │   │
│  │  - 智能图片传递逻辑                                    │   │
│  │  - 缓存满检测和提示                                    │   │
│  └──────────────────────────────────────────────────────┘   │
│                          ↕ (postMessage)                      │
│  ┌──────────────────────────────────────────────────────┐   │
│  │         IndexedDB: drawnix-unified-cache              │   │
│  │                                                        │   │
│  │  存储结构：                                             │   │
│  │  - url (主键)                                          │   │
│  │  - type, mimeType, size                               │   │
│  │  - cachedAt, lastUsed                                 │   │
│  │  - metadata: { taskId, prompt, model, params }        │   │
│  └──────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────┘
                             ↕ (fetch intercept)
┌─────────────────────────────────────────────────────────────┐
│                    Service Worker 线程                        │
│                                                               │
│  ┌──────────────────────────────────────────────────────┐   │
│  │  图片请求拦截器                                         │   │
│  │                                                        │   │
│  │  1. 拦截图片请求                                        │   │
│  │  2. 检查 Cache API                                     │   │
│  │     ↓ 命中 → 直接返回                                  │   │
│  │     ↓ 未命中 → 从网络获取                              │   │
│  │  3. 存入 Cache API                                     │   │
│  │  4. 通知主线程更新 IndexedDB 元数据                    │   │
│  └──────────────────────────────────────────────────────┘   │
│                                                               │
│  ┌──────────────────────────────────────────────────────┐   │
│  │         Cache API: drawnix-images                      │   │
│  │  (快速响应，不存元数据)                                 │   │
│  └──────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────┘
```

### 数据库结构

#### IndexedDB: `drawnix-unified-cache`

```typescript
interface CachedMedia {
  url: string;              // 主键
  type: 'image' | 'video';
  mimeType: string;
  size: number;             // 字节数
  cachedAt: number;         // 缓存时间戳
  lastUsed: number;         // 最后使用时间戳
  metadata: {
    taskId?: string;        // 任务ID
    prompt?: string;        // 生成提示词
    model?: string;         // 使用的模型
    params?: any;           // 生成参数
    [key: string]: any;     // 扩展字段
  };
}
```

**索引**：
- `url` (主键)
- `cachedAt` (用于按时间排序)
- `lastUsed` (用于 LRU 清理)

### 核心流程

#### 1. 图片生成并插入画布

```
任务完成 → 获得图片 URL
  ↓
插入画布（使用原始 URL，不变更现有逻辑）
  ↓
浏览器发起图片请求
  ↓
SW 拦截请求
  ↓
检查 Cache API
  ├─ 命中 → 立即返回缓存
  └─ 未命中
     ↓
     从网络获取图片
     ↓
     存入 Cache API
     ↓
     postMessage 通知主线程
     {
       type: 'IMAGE_CACHED',
       url: '...',
       size: 12345,
       mimeType: 'image/png'
     }
     ↓
主线程收到消息
  ↓
存入 IndexedDB (包含元数据)
```

#### 2. 调用 AI 接口传递图片

```
需要传图片给 AI 接口
  ↓
调用 UnifiedCacheManager.getImageForAI(url)
  ↓
查询 IndexedDB 获取 cachedAt
  ↓
计算 age = Date.now() - cachedAt
  ↓
age < 24小时？
  ├─ 是 → 返回 { type: 'url', value: originalUrl }
  └─ 否
     ↓
     从 Cache API 获取 blob（通过 fetch）
     ↓
     压缩图片（如果需要）
     ↓
     转换为 base64
     ↓
     返回 { type: 'base64', value: base64Data }
```

#### 3. 缓存满处理

```
Cache API 或 IndexedDB 写入失败
  ↓
捕获 QuotaExceededError
  ↓
触发 onQuotaExceeded 回调
  ↓
显示 TDesign Dialog:
"缓存空间已满，是否打开素材库清理缓存？"
[取消] [打开素材库]
  ↓
用户点击"打开素材库"
  ↓
打开媒体库面板（显示所有缓存项）
  ↓
用户选择并删除缓存项
  ↓
删除流程：
  1. 从 IndexedDB 删除记录
  2. postMessage 通知 SW 删除 Cache API 条目
  3. 刷新缓存列表
```

## API 设计

### UnifiedCacheService

```typescript
class UnifiedCacheService {
  /**
   * 注册图片元数据（任务完成时调用）
   */
  async registerImageMetadata(
    url: string,
    metadata: {
      taskId: string;
      prompt?: string;
      model?: string;
      params?: any;
    }
  ): Promise<void>;

  /**
   * 获取适合传给 AI 的图片数据
   * 自动决策返回 URL 或 base64
   */
  async getImageForAI(
    url: string,
    options?: {
      maxAge?: number;        // 默认 24 小时
      maxSize?: number;       // 最大文件大小（超过则压缩）
      quality?: number;       // 压缩质量 0-1
    }
  ): Promise<{
    type: 'url' | 'base64';
    value: string;
  }>;

  /**
   * 获取缓存信息
   */
  async getCacheInfo(url: string): Promise<{
    isCached: boolean;
    cachedAt?: number;
    age?: number;
    size?: number;
    metadata?: any;
  }>;

  /**
   * 手动缓存图片
   */
  async cacheImage(
    url: string,
    metadata?: any
  ): Promise<boolean>;

  /**
   * 删除缓存
   */
  async deleteCache(url: string): Promise<void>;

  /**
   * 批量删除缓存
   */
  async deleteCacheBatch(urls: string[]): Promise<number>;

  /**
   * 获取所有缓存项元数据
   */
  async getAllCacheMetadata(): Promise<CachedMedia[]>;

  /**
   * 获取存储使用情况
   */
  async getStorageUsage(): Promise<{
    used: number;
    quota: number;
    percentage: number;
  }>;

  /**
   * 清空所有缓存
   */
  async clearAllCache(): Promise<void>;

  /**
   * 监听缓存满事件
   */
  onQuotaExceeded(callback: () => void): () => void;

  /**
   * 订阅缓存变化
   */
  subscribe(callback: () => void): () => void;
}
```

### Service Worker 消息协议

#### 主线程 → SW

```typescript
// 删除缓存请求
{
  type: 'DELETE_CACHE',
  url: string
}

// 批量删除缓存请求
{
  type: 'DELETE_CACHE_BATCH',
  urls: string[]
}

// 清空所有缓存
{
  type: 'CLEAR_ALL_CACHE'
}
```

#### SW → 主线程

```typescript
// 图片已缓存通知
{
  type: 'IMAGE_CACHED',
  url: string,
  size: number,
  mimeType: string,
  timestamp: number
}

// 缓存已删除通知
{
  type: 'CACHE_DELETED',
  url: string
}

// 缓存空间不足警告
{
  type: 'QUOTA_WARNING',
  usage: number,
  quota: number
}
```

## 数据迁移方案

### 迁移步骤

1. **检测旧数据库**
   - 检查 `aitu-media-cache` 是否存在
   - 检查 `aitu-url-cache` 是否存在

2. **创建新数据库**
   - 打开 `drawnix-unified-cache`
   - 创建 object store 和索引

3. **迁移 Media Cache 数据**
   ```typescript
   // 从 aitu-media-cache.media 读取
   oldRecord = {
     url, originalUrl, taskId, prompt,
     blob, type, mimeType, size, cachedAt
   }

   // 转换为新格式
   newRecord = {
     url: oldRecord.originalUrl || oldRecord.url,
     type: oldRecord.type,
     mimeType: oldRecord.mimeType,
     size: oldRecord.size,
     cachedAt: oldRecord.cachedAt || Date.now(),
     lastUsed: Date.now(),
     metadata: {
       taskId: oldRecord.taskId,
       prompt: oldRecord.prompt
     }
   }
   ```

4. **迁移 URL Cache 数据**
   ```typescript
   // 从 aitu-url-cache.media-cache 读取
   oldRecord = {
     url, type, data (base64), blob, mimeType, size, cachedAt
   }

   // 转换为新格式（不迁移 blob，让 SW 重新缓存）
   newRecord = {
     url: oldRecord.url,
     type: oldRecord.type,
     mimeType: oldRecord.mimeType,
     size: oldRecord.size,
     cachedAt: oldRecord.cachedAt || Date.now(),
     lastUsed: Date.now(),
     metadata: {}
   }
   ```

5. **删除旧数据库**
   ```typescript
   indexedDB.deleteDatabase('aitu-media-cache');
   indexedDB.deleteDatabase('aitu-url-cache');
   ```

6. **记录迁移状态**
   - localStorage 设置标记：`drawnix_cache_migrated: 'true'`

### 迁移触发时机

- 应用启动时自动检测并迁移
- 迁移过程显示进度提示（可选）
- 迁移完成后发送通知

## 实现计划

### Phase 1: 基础服务实现（核心）

- [x] 创建设计文档
- [ ] 实现 `UnifiedCacheService` 类
- [ ] 实现 IndexedDB 操作
- [ ] 实现与 SW 的通信协议
- [ ] 实现数据迁移逻辑

### Phase 2: Service Worker 集成

- [ ] 修改 SW 图片缓存逻辑
- [ ] 添加缓存通知消息
- [ ] 实现 SW 端的缓存删除响应

### Phase 3: 智能传递逻辑

- [ ] 实现 `getImageForAI()` 方法
- [ ] 添加图片压缩功能
- [ ] 添加缓存时间检测

### Phase 4: UI 集成

- [ ] 更新 TaskItem 使用新服务
- [ ] 实现缓存满提示 Dialog
- [ ] 更新媒体库显示缓存信息
- [ ] 添加缓存管理 UI

### Phase 5: 测试与优化

- [ ] 单元测试
- [ ] 集成测试
- [ ] 性能优化
- [ ] 文档完善

## 注意事项

1. **缓存策略**
   - Service Worker 的 Cache API 用于快速响应（不存元数据）
   - IndexedDB 用于元数据管理和查询
   - 不在 IndexedDB 中存储 blob，避免双重存储

2. **性能考虑**
   - SW 缓存命中后立即返回，不阻塞
   - 元数据更新使用异步消息，不影响图片加载速度
   - 批量操作使用事务优化

3. **兼容性**
   - 保持现有插入画布逻辑不变
   - 渐进式迁移，旧代码依然可用
   - 提供降级方案（如 SW 不可用）

4. **安全性**
   - 验证 URL 来源
   - 限制缓存大小
   - 清理过期缓存

## 参考资料

- [Service Worker API - MDN](https://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API)
- [IndexedDB API - MDN](https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API)
- [Cache API - MDN](https://developer.mozilla.org/en-US/docs/Web/API/Cache)
- [Storage API - MDN](https://developer.mozilla.org/en-US/docs/Web/API/Storage_API)

## 更新日志

- 2026-01-07: 初始版本，完成架构设计