# Opentu 核心功能流程

本文档详细说明项目的核心功能实现流程，包括 AI 生成、Service Worker 架构、工作流机制等。这是 `CLAUDE.md` 的详细补充，当需要理解具体功能实现时参考本文档。

> **注意**：本文档由 CLAUDE.md 拆分而来，包含详细的架构说明和实现细节。

---

## 目录

- [AI 生成流程](#ai-生成流程service-worker-模式)
- [Service Worker 任务队列架构](#service-worker-任务队列架构)
- [Service Worker 预缓存机制](#service-worker-预缓存机制)
- [工作流提交机制](#工作流提交机制)
- [WorkZone 画布元素](#workzone-画布元素)
- [灵感创意板块](#灵感创意板块)
- [历史提示词功能](#历史提示词功能)
- [图片合并与分割](#图片合并与分割)

---

## 核心功能流程

### AI 生成流程（Service Worker 模式）

项目使用 Service Worker 作为后台任务执行器，实现页面刷新不影响任务执行。

```
用户输入
  ↓
AIInputBar (输入组件)
  ↓
swTaskQueueService.createTask() (应用层)
  ↓ postMessage
Service Worker (后台)
  ├── SWTaskQueue.submitTask() (任务管理)
  ├── ImageHandler / VideoHandler (执行器)
  └── taskQueueStorage (IndexedDB 持久化)
  ↓ broadcastToClients
应用层接收状态更新
  ↓
Canvas 插入 / 媒体库缓存
```

**核心特性**：
- **页面刷新恢复**：任务状态持久化到 IndexedDB，刷新后自动恢复
- **多标签页同步**：通过 `broadcastToClients` 向所有标签页广播状态
- **视频任务恢复**：通过 `remoteId` 恢复轮询，继续等待视频生成完成

### Service Worker 任务队列架构

```
apps/web/src/sw/
├── index.ts                       # SW 主入口
└── task-queue/
    ├── queue.ts                   # 任务队列核心 (SWTaskQueue)
    ├── storage.ts                 # IndexedDB 存储 (TaskQueueStorage)
    ├── types.ts                   # 类型定义
    ├── handlers/                  # 任务处理器
    │   ├── image.ts               # 图片生成处理器
    │   ├── video.ts               # 视频生成处理器
    │   ├── character.ts           # 角色生成处理器
    │   └── chat.ts                # 聊天处理器
    ├── workflow-executor.ts       # 工作流执行器
    ├── workflow-types.ts          # 工作流类型
    ├── chat-workflow/             # 聊天工作流
    │   ├── executor.ts            # 聊天工作流执行器
    │   └── types.ts               # 聊天工作流类型
    ├── mcp/                       # MCP 工具系统
    │   ├── tools.ts               # 工具注册
    │   └── executor.ts            # 工具执行器
    └── utils/
        └── index.ts               # 工具函数导出
```

**应用层服务**：
```
packages/drawnix/src/services/
├── sw-client/
│   ├── client.ts                  # SW 通信客户端 (SWTaskQueueClient)
│   ├── types.ts                   # 消息类型定义
│   └── index.ts                   # 导出
├── sw-task-queue-service.ts       # SW 任务队列服务
├── sw-chat-service.ts             # SW 聊天服务
├── sw-chat-workflow-service.ts    # SW 聊天工作流服务
└── task-queue/
    └── index.ts                   # 任务队列入口（自动选择 SW/传统模式）
```

**通信协议**：
```typescript
// 应用层 → Service Worker
type MainToSWMessage =
  | { type: 'TASK_QUEUE_INIT'; geminiConfig; videoConfig }
  | { type: 'TASK_SUBMIT'; taskId; taskType; params }
  | { type: 'TASK_CANCEL'; taskId }
  | { type: 'TASK_RETRY'; taskId }
  | { type: 'TASK_GET_ALL' }
  | { type: 'CHAT_START'; chatId; params }
  | { type: 'WORKFLOW_SUBMIT'; workflow }
  // ...

// Service Worker → 应用层
type SWToMainMessage =
  | { type: 'TASK_CREATED'; task }
  | { type: 'TASK_STATUS'; taskId; status; progress }
  | { type: 'TASK_COMPLETED'; taskId; result }
  | { type: 'TASK_FAILED'; taskId; error; retryCount }
  | { type: 'WORKFLOW_STEP_STATUS'; workflowId; stepId; status }
  // ...
```

**IndexedDB 存储结构**：
- `tasks` - 任务数据（图片/视频/角色生成）
- `config` - API 配置（apiKey, baseUrl）
- `workflows` - 工作流数据
- `chat-workflows` - 聊天工作流数据
- `pending-tool-requests` - 待处理的主线程工具请求

**任务生命周期**：
```
PENDING → PROCESSING → COMPLETED
                    ↘ FAILED
                    ↘ CANCELLED
```

**使用示例**：
```typescript
import { taskQueueService } from '../services/task-queue';

// 创建任务
const task = taskQueueService.createTask(
  { prompt: '生成一张日落图片', size: '1:1' },
  TaskType.IMAGE
);

// 监听任务更新
taskQueueService.observeTaskUpdates().subscribe((event) => {
  if (event.type === 'taskUpdated' && event.task.status === TaskStatus.COMPLETED) {
    console.log('任务完成:', event.task.result?.url);
  }
});
```

### Service Worker 预缓存机制 (Precache Manifest)

项目使用 **Precache Manifest** 机制确保版本更新时用户能快速加载新版本：

**问题**：如果 SW 只预缓存少量基础文件（如 index.html），版本更新后用户首次访问需要从网络下载所有 JS/CSS，导致加载慢。

**解决方案**：

1. **构建时生成资源清单** (`vite.config.ts`)：
```typescript
// Vite 插件在构建完成后扫描 dist 目录
function precacheManifestPlugin(): Plugin {
  return {
    name: 'precache-manifest',
    closeBundle: {
      async handler() {
        // 扫描所有静态资源，生成 precache-manifest.json
        // 包含 URL 和文件哈希（用于增量更新）
        manifest.push({ url: '/assets/xxx.js', revision: 'a1b2c3d4' });
      }
    }
  };
}
```

2. **SW 安装时预缓存所有资源** (`sw/index.ts`)：
```typescript
sw.addEventListener('install', (event) => {
  event.waitUntil(
    (async () => {
      const files = await loadPrecacheManifest(); // 读取 manifest
      await precacheStaticFiles(cache, files);    // 并发预缓存
    })()
  );
});
```

3. **增量更新**：通过 `x-sw-revision` 头比较文件哈希，跳过未变化的文件

**工作流程**：
```
版本更新发布 → 用户访问 → 新 SW 安装
                           ↓
                    读取 precache-manifest.json
                           ↓
                    并发预缓存所有资源（6个并发）
                           ↓
                    预缓存完成 → 通知用户更新
                           ↓
                    用户确认 → 激活新 SW → 缓存优先秒开
```

**相关文件**：
- `apps/web/vite.config.ts` - `precacheManifestPlugin()` 生成 manifest
- `apps/web/src/sw/index.ts` - `loadPrecacheManifest()` 和 `precacheStaticFiles()`
- `dist/apps/web/precache-manifest.json` - 构建产物

**预缓存不阻塞首次访问**：

这是一个常见误解 —— 很多开发者担心 `event.waitUntil()` 会阻塞页面加载。实际上：

1. **页面加载和 SW 安装是并行的**：用户访问时页面正常从网络加载，SW 在后台安装
2. **SW 在页面 load 后才注册**：`main.tsx` 中 `window.addEventListener('load', () => { navigator.serviceWorker.register(...) })`
3. **`event.waitUntil()` 只影响 SW 生命周期**：它让 SW 等待预缓存完成后才激活，不影响主线程

```
时间 →
[页面加载] ████████████ load 事件
                         ↓
[用户可用] ──────────────●──────────────── 用户已可使用
                         
[SW 注册]                ●────────
[SW 预缓存]                   ████████████████
[SW 激活]                                    ●────────
```

**结论**：首次访问正常加载，SW 在后台默默预缓存，下次访问秒开。

**Service Worker 自动激活策略**：

项目采用 **自动激活** 策略，确保用户总是使用最新版本：

```typescript
// sw/index.ts - install 事件
sw.addEventListener('install', (event) => {
  event.waitUntil(
    (async () => {
      await precacheStaticFiles(cache, files);
      // 预缓存完成后，直接激活新 SW
      sw.skipWaiting();
    })()
  );
});

// activate 事件
sw.addEventListener('activate', (event) => {
  event.waitUntil(
    (async () => {
      await sw.clients.claim(); // 接管所有页面
      // 通知客户端 SW 已更新
      const clients = await sw.clients.matchAll();
      clients.forEach(client => {
        client.postMessage({ type: 'SW_ACTIVATED', version: APP_VERSION });
      });
    })()
  );
});
```

**页面刷新策略**（区分主应用和调试页面）：

| 页面类型 | SW 更新后行为 | 原因 |
|---------|-------------|------|
| 主应用 (React) | 显示更新提示，**不自动刷新** | 避免打断用户操作 |
| sw-debug.html | **自动刷新** | 调试页面需要最新版本 |

```typescript
// main.tsx - 主应用只在用户确认后才刷新
navigator.serviceWorker.addEventListener('controllerchange', () => {
  if (!userConfirmedUpgrade) {
    return; // 用户没确认就不刷新
  }
  window.location.reload();
});

// sw-debug/app.js - 调试页面自动刷新
onControllerChange(() => {
  window.location.reload();
});
```

### 编辑器插件系统
```
Drawnix (主编辑器)
  ├── Plait Board (绘图核心)
  └── Plugins
      ├── withTool (工具系统)
      ├── withFreehand (自由画)
      ├── withMind (思维导图)
      ├── withDraw (基础绘图)
      ├── withHotkey (快捷键)
      ├── withTextLink (文本链接)
      ├── withTextPaste (文本粘贴)
      ├── withImage (图片粘贴)
      ├── withVideo (视频支持)
      ├── withWorkZone (工作流进度)
      └── ...
```

### 工作流提交机制

项目使用统一的工作流提交机制，避免重复创建工作流导致的问题。

**核心文件**：
- `hooks/useWorkflowSubmission.ts` - 工作流提交 Hook
- `components/ai-input-bar/workflow-converter.ts` - 工作流转换器
- `services/workflow-submission-service.ts` - 工作流提交服务

**工作流程**：
```
AIInputBar 创建工作流
  ↓
convertToWorkflow() - 创建 LegacyWorkflowDefinition（唯一 ID）
  ↓
submitWorkflowToSW(parsedParams, referenceImages, retryContext, existingWorkflow)
  ↓
useWorkflowSubmission.submitWorkflow() - 复用已有工作流，避免重复创建
  ↓
workflowSubmissionService.submit() - 提交到 SW
  ↓
SW WorkflowExecutor 执行
```

**关键设计**：
- `submitWorkflow` 接受可选的 `existingWorkflow` 参数
- 如果传入 `existingWorkflow`，直接使用而不重新创建
- 避免因重复调用 `convertToWorkflow` 导致不同 ID 的工作流

**API 签名**：
```typescript
submitWorkflow: (
  parsedInput: ParsedGenerationParams,
  referenceImages: string[],
  retryContext?: WorkflowRetryContext,
  existingWorkflow?: LegacyWorkflowDefinition
) => Promise<{ workflowId: string; usedSW: boolean }>
```

### WorkZone 画布元素

WorkZone 是一个特殊的画布元素，用于在画布上直接显示 AI 生成任务的工作流进度。

**核心文件**：
- `plugins/with-workzone.ts` - Plait 插件，注册 WorkZone 元素类型
- `components/workzone-element/WorkZoneContent.tsx` - React 渲染组件
- `types/workzone.types.ts` - 类型定义

**工作流程**：
```
AIInputBar 提交生成任务
  ↓
创建 WorkZone 元素到画布 (WorkZoneTransforms.insertWorkZone)
  ↓
WorkflowContext 更新工作流状态
  ↓
WorkZoneContent 组件响应更新，显示进度
  ↓
任务完成/失败后可删除 WorkZone
```

**关键 API**：
- `WorkZoneTransforms.insertWorkZone(board, options)` - 创建 WorkZone
- `WorkZoneTransforms.updateWorkflow(board, id, workflow)` - 更新工作流状态
- `WorkZoneTransforms.removeWorkZone(board, id)` - 删除 WorkZone

**AI 生成完成事件**：
当所有工作流步骤完成后，会触发 `ai-generation-complete` 事件：
```typescript
window.dispatchEvent(new CustomEvent('ai-generation-complete', {
  detail: { type: 'image' | 'mind' | 'flowchart', success: boolean, workzoneId: string }
}));
```
- 思维导图/流程图：在 `sw-capabilities/handler.ts` 中触发
- 图片生成：在 `useAutoInsertToCanvas.ts` 的 `updateWorkflowStepForTask` 中触发
- `AIInputBar` 监听此事件来重置 `isSubmitting` 状态

**技术要点**：
- 使用 SVG `foreignObject` 在画布中嵌入 React 组件
- 使用 XHTML 命名空间确保 DOM 元素正确渲染
- 需要在 `pointerdown` 阶段阻止事件冒泡，避免 Plait 拦截点击事件
- WorkZone 元素被选中时不触发 popup-toolbar（在 `popup-toolbar.tsx` 中过滤）
- AIInputBar 发送工作流时不自动展开 ChatDrawer（通过 `autoOpen: false` 参数控制）

**位置策略**（按优先级）：
1. **有选中元素** → 放在选中元素下方（左对齐）
2. **无选中元素** → 放在最底部元素下方（左对齐）
3. **画布为空** → 放在视口中心

**选中框缩放**：
- 选中框大小根据 `zoom` 属性自动调整，与缩放后的内容匹配
- 使用 `activeGenerator` 的 `getRectangle` 计算缩放后的矩形

**自动滚动**：
- 使用 `scrollToPointIfNeeded` 函数智能滚动
- WorkZone 不在视口内时自动滚动到中心位置
- WorkZone 已在视口内时不滚动（避免干扰用户）


### 灵感创意板块 (InspirationBoard)

当画板为空时，在 AI 输入框上方显示灵感创意板块，帮助用户快速开始创作。

**核心文件**：
- `components/inspiration-board/InspirationBoard.tsx` - 主组件
- `components/inspiration-board/InspirationCard.tsx` - 模版卡片组件
- `components/inspiration-board/constants.ts` - 模版数据配置

**功能特点**：
- 画板为空时自动显示，有内容时隐藏
- 3x2 网格布局展示创意模版
- 支持分页浏览更多模版
- 点击模版自动填充提示词到输入框
- 提供"提示词"快捷按钮，可打开香蕉提示词工具

**数据加载状态管理 (`isDataReady`)**：

为了避免在画布数据加载完成前误判画布为空（导致灵感板闪烁），项目使用 `isDataReady` 状态来标识数据是否已准备好。

**数据流**：
```
app.tsx (isDataReady state)
  ↓ setValue 完成后 setIsDataReady(true)
  ↓ prop
drawnix.tsx (isDataReady prop)
  ↓ prop
DrawnixContent (isDataReady prop)
  ↓ prop
AIInputBar (isDataReady prop)
  ↓ prop
SelectionWatcher (isDataReady prop)
  ↓
只有 isDataReady=true 时才检查画布是否为空
```

**关键逻辑**：
- `app.tsx`：初始 `isDataReady = false`，在 `setValue` 完成后（`finally` 块中）设置为 `true`
- `SelectionWatcher`：只有当 `isDataReady` 为 `true` 时才开始检查画布是否为空
- 避免在数据加载前误判画布为空，防止灵感板闪烁

### 历史提示词功能

支持记录和管理用户的历史提示词，方便快速复用。

**核心文件**：
- `services/prompt-storage-service.ts` - 存储服务（localStorage）
- `hooks/usePromptHistory.ts` - React Hook
- `components/ai-input-bar/PromptHistoryPopover.tsx` - UI 组件

**功能特点**：
- 自动保存用户发送的提示词（无数量限制，使用 IndexedDB 存储）
- 支持置顶/取消置顶常用提示词
- 鼠标悬浮三点图标显示历史列表
- 点击历史提示词回填到输入框
- 支持删除单条历史记录

**API 示例**：
```typescript
const { history, addHistory, removeHistory, togglePinHistory } = usePromptHistory();

// 添加历史
addHistory('生成一张日落风景图', hasSelection);

// 置顶/取消置顶
togglePinHistory(itemId);
```

### 文本粘贴功能

支持智能文本粘贴到画布，自动控制文本宽度避免过长。

**核心文件**：
- `plugins/with-text-paste.ts` - 文本粘贴插件
- `plugins/with-common.tsx` - 插件注册（文本粘贴 + 图片粘贴）

**功能特点**：
- 自动换行：超过 50 字符自动换行
- 智能断行：优先在空格处断行，保持单词完整
- 保留格式：保留原文本的换行符
- 不影响现有功能：图片粘贴和 Plait 元素复制粘贴正常工作

**配置参数**：
```typescript
const TEXT_CONFIG = {
  MAX_CHARS_PER_LINE: 50,    // 最大字符数/行
  DEFAULT_WIDTH: 400,         // 默认文本框宽度
  MAX_WIDTH: 600,             // 最大文本框宽度
  CHAR_WIDTH: 8,              // 估算字符宽度
};
```

**使用方法**：
1. 从任何地方复制文本
2. 在画布上按 `Ctrl+V` / `Cmd+V`
3. 文本自动插入并换行

**插件链顺序**：
```typescript
// 在 with-common.tsx 中
return withTextPastePlugin(withImagePlugin(newBoard));
```

详细文档：`/docs/TEXT_PASTE_FEATURE.md`

### 模型健康状态功能

在模型选择下拉菜单中显示实时健康状态，帮助用户了解模型的可用性。

**核心文件**：
- `services/model-health-service.ts` - 健康状态 API 服务
- `hooks/useModelHealth.ts` - React Hook（带缓存和自动刷新）
- `components/shared/ModelHealthBadge.tsx` - 健康状态徽章组件
- `components/shared/model-health-badge.scss` - 样式文件

**功能特点**：
- 仅当 `baseUrl` 为 `api.tu-zi.com` 时才启用
- 每 5 分钟自动刷新健康数据
- 全局缓存避免重复请求
- 彩色方块徽章显示状态，hover 显示状态文字
- API 请求失败时静默处理，不显示健康状态

**API 来源**：
- 端点：`https://apistatus.tu-zi.com/api/history/aggregated`
- 返回字段：`model_name`、`status_label`、`status_color`、`error_rate` 等

**使用示例**：
```typescript
import { useModelHealth } from '../../hooks/useModelHealth';
import { ModelHealthBadge } from '../shared/ModelHealthBadge';

// 在组件中使用 Hook
const { shouldShowHealth, getHealthStatus } = useModelHealth();

// 获取特定模型的健康状态
const status = getHealthStatus('gemini-2.0-flash-exp-image-generation');

// 使用徽章组件
<ModelHealthBadge modelId="gemini-2.0-flash-exp-image-generation" />
```

**显示规则**：
- `shouldShowHealth` 为 `true` 时（baseUrl 包含 `api.tu-zi.com`）才显示徽章
- 没有匹配模型的健康数据时不显示徽章
- 徽章颜色由 API 返回的 `statusColor` 决定（绿/黄/红等）

### 字体管理与缓存

支持 Google Fonts 的自动加载和缓存，通过 Service Worker 实现应用层无感知的字体缓存。

**核心文件**：
- `services/font-manager-service.ts` - 字体管理服务
- `apps/web/src/sw/index.ts` - Service Worker 字体缓存逻辑
- `constants/text-effects.ts` - 字体配置（系统字体 + Google Fonts）

**功能特点**：
- 自动提取画布中使用的字体
- 画布初始化时预加载已使用的字体
- Service Worker 自动缓存字体文件（基于 URL）
- 支持系统字体和 Google Fonts
- 字体预览图管理

**工作流程**：
```
画布加载
  ↓
提取使用的字体（从 text.children 中）
  ↓
fontManagerService.preloadBoardFonts()
  ↓
加载 Google Fonts（link 标签）
  ↓
Service Worker 拦截请求
  ├─ 检查 drawnix-fonts 缓存
  ├─ 缓存命中 → 直接返回
  └─ 缓存未命中 → 下载并缓存
  ↓
字体加载完成 → board.redraw()
```

**缓存策略**：
- 使用 Service Worker Cache API
- Cache-First 策略（优先使用缓存）
- 缓存 CSS 文件和字体文件（woff2）
- 应用层无感知，完全由 Service Worker 管理

**支持的字体**：
- 系统字体：苹方、微软雅黑、黑体、宋体、楷体等
- Google Fonts：Noto Sans SC、ZCOOL 系列、Ma Shan Zheng 等

### 参考图上传组件 (ReferenceImageUpload)

统一的参考图上传组件，用于 AI 图片生成和视频生成弹窗。

**核心文件**：
- `components/ttd-dialog/shared/ReferenceImageUpload.tsx` - 主组件
- `components/ttd-dialog/shared/ReferenceImageUpload.scss` - 样式文件

**功能特点**：
- 本地文件上传：点击"本地"按钮选择文件
- 素材库选择：点击"素材库"按钮从媒体库选择图片
- 拖拽上传：支持将图片拖拽到上传区域
- 粘贴板获取：支持 Ctrl+V / Cmd+V 粘贴图片
- 多种模式：
  - 单图模式 (`multiple=false`)
  - 多图网格模式 (`multiple=true`)
  - 插槽模式 (`slotLabels` 用于视频生成的首帧/尾帧)

**使用示例**：
```tsx
// AI 图片生成中的使用
<ReferenceImageUpload
  images={uploadedImages}
  onImagesChange={setUploadedImages}
  language={language}
  disabled={isGenerating}
  multiple={true}
  label="参考图片 (可选)"
/>

// AI 视频生成中的使用（首帧/尾帧模式）
<ReferenceImageUpload
  images={uploadedImages}
  onImagesChange={handleImagesChange}
  language={language}
  disabled={isGenerating}
  multiple={true}
  maxCount={2}
  slotLabels={['首帧', '尾帧']}
  label="首尾帧图片 (可选)"
/>
```

**类型定义**：
```typescript
interface ReferenceImage {
  url: string;    // Base64 或 URL
  name: string;   // 文件名
  file?: File;    // 原始文件对象
}

interface ReferenceImageUploadProps {
  images: ReferenceImage[];
  onImagesChange: (images: ReferenceImage[]) => void;
  language?: 'zh' | 'en';
  disabled?: boolean;
  multiple?: boolean;
  maxCount?: number;
  label?: string;
  slotLabels?: string[];  // 插槽标签（如 ['首帧', '尾帧']）
  onError?: (error: string | null) => void;
}
```

**样式特点**：
- 虚线边框的上传区域
- 垂直排列的"本地"和"素材库"按钮
- 拖拽时的视觉反馈
- 统一的按钮样式（图标 16px，字体 13px，字重 400）

### 备份恢复功能 (Backup & Restore)

支持将用户数据（提示词、项目、素材）导出为 ZIP 文件，并从 ZIP 文件恢复数据。

**核心文件**：
- `services/backup-restore/` - 备份恢复服务（支持自动分片）
- `components/backup-restore/backup-restore-dialog.tsx` - UI 对话框

**功能特点**：
- 导出提示词历史（图片/视频提示词）
- 导出项目数据（文件夹和画板）
- 导出素材库（本地上传 + AI 生成的缓存媒体）
- 增量导入（自动去重，不覆盖已有数据）
- 支持进度显示

**ZIP 文件结构**：
```
aitu_backup_xxx.zip
├── manifest.json              # 备份元信息
├── prompts.json               # 提示词数据
├── projects/                  # 项目文件
│   ├── 文件夹名/
│   │   └── 画板名.drawnix     # 画板数据
│   └── 画板名.drawnix         # 根目录画板
└── assets/                    # 素材文件
    ├── xxx.meta.json          # 素材元数据
    └── xxx.jpg/.mp4           # 媒体文件
```

**数据来源**：
```
导出素材：
├── 本地素材库 ← localforage (asset-storage-service)
└── AI 生成缓存 ← unified-cache-service (drawnix-unified-cache)

导入素材：
├── 本地素材 → localforage + unified-cache
└── AI 生成素材 (source: 'AI_GENERATED') → 仅 unified-cache
```

**关键 API**：
```typescript
// 导出
const blob = await backupRestoreService.exportToZip({
  includePrompts: true,
  includeProjects: true,
  includeAssets: true,
}, onProgress);
backupRestoreService.downloadZip(blob);

// 导入
const result = await backupRestoreService.importFromZip(file, onProgress);
// result: { success, prompts, projects, assets, errors }
```

**缓存刷新机制**：
导入数据后需要刷新内存缓存才能生效：
- `resetPromptStorageCache()` - 刷新提示词缓存
- `workspaceService.reload()` - 刷新工作区缓存

**技术要点**：
- 使用 JSZip 处理 ZIP 文件
- 媒体文件通过 `unifiedCacheService.getCachedBlob()` 获取
- 虚拟 URL（`/asset-library/`）从 Cache API 获取
- 导入时区分本地素材和 AI 生成素材，存储位置不同

### 分页加载与虚拟滚动

支持任务队列和素材库的分页加载与虚拟滚动，优化大数据量场景下的性能。

**核心文件**：
- `hooks/useInfinitePagination.ts` - 无限滚动分页 Hook
- `hooks/useVirtualList.ts` - 虚拟列表 Hook（封装 @tanstack/react-virtual）
- `hooks/useImageLazyLoad.ts` - 图片懒加载 Hook
- `components/lazy-image/LazyImage.tsx` - 懒加载图片组件
- `components/task-queue/VirtualTaskList.tsx` - 虚拟任务列表组件
- `components/media-library/VirtualAssetGrid.tsx` - 虚拟素材网格组件
- `apps/web/src/sw/task-queue/storage.ts` - IndexedDB 游标分页查询

**功能特点**：
- IndexedDB 游标分页：支持大数据量的高效分页查询
- 无限滚动：滚动到底部自动加载更多数据
- 虚拟滚动：只渲染可见区域的元素，大幅减少 DOM 节点
- 图片懒加载：基于 IntersectionObserver，进入视口才加载图片
- 实时更新：支持 `prependItems`、`updateItem`、`removeItem` 操作

**使用示例**：
```typescript
// 无限滚动分页
const {
  items,
  isLoading,
  isLoadingMore,
  hasMore,
  loadMore,
  reset,
} = useInfinitePagination({
  fetcher: async ({ offset, limit }) => {
    const result = await swTaskQueueClient.requestPaginatedTasks({
      offset,
      limit,
      status: filterStatus,
    });
    return {
      items: result.tasks,
      total: result.total,
      hasMore: result.hasMore,
    };
  },
  pageSize: 50,
  getItemKey: (task) => task.id,
  deps: [filterStatus],
});

// 虚拟列表
const { parentRef, virtualItems, totalSize, getItem } = useVirtualList({
  items: tasks,
  estimateSize: 200,
  overscan: 3,
});
```

**IndexedDB 分页查询**：
```typescript
// Service Worker 中的游标分页实现
async getPaginatedTasks(params: PaginationParams): Promise<PaginatedResult> {
  const { offset = 0, limit = 50, status } = params;
  const db = await this.getDB();
  const tx = db.transaction('tasks', 'readonly');
  const store = tx.objectStore('tasks');
  const index = store.index('by-createdAt');

  let cursor = await index.openCursor(null, 'prev');
  let skipped = 0;
  const items: Task[] = [];

  while (cursor && items.length < limit) {
    if (status && cursor.value.status !== status) {
      cursor = await cursor.continue();
      continue;
    }
    if (skipped < offset) {
      skipped++;
      cursor = await cursor.continue();
      continue;
    }
    items.push(cursor.value);
    cursor = await cursor.continue();
  }

  return { items, total, hasMore: offset + items.length < total };
}
```

**性能优化**：
- 默认每页 50 条数据
- 虚拟列表 overscan 设置为 3-5 个元素
- 图片懒加载 rootMargin 设置为 200px（提前加载）
- 使用 `getItemKey` 进行去重，避免重复数据

---

### Service Worker 版本升级流程

#### 升级时序

```
主线程 5 分钟定时 registration.update()
  → 浏览器检测到新 sw.js
  → 新 SW install（prewarming → 预缓存资源 → markNewVersionReady → upgradeState='ready'）
  → 新 SW 进入 waiting 状态
  → 主线程 statechange='installed' → requestSWVersionState
  → SW 响应 SW_VERSION_STATE（pendingVersion + upgradeState='ready'）
  → 主线程 dispatch 'sw-update-available'
  → VersionUpdatePrompt 显示升级提示
  → 用户点击"立即更新" → COMMIT_UPGRADE → skipWaiting → activate → claim → reload
```

#### 自然激活（所有旧 tab 关闭）

当所有旧 tab 关闭后，waiting SW 自动变为 active。activate 处理器必须无条件将 `committedVersion` 更新为 `APP_VERSION`，否则新 tab 会用旧版本号打开旧缓存、从网络获取新 `index.html`，导致新 hash 资源用旧版本号请求 CDN → 404。

#### 踩坑记录

1. **waiting SW 的 postmessage-duplex 不可靠**：新 SW 处于 waiting 状态时，`channelManager.sendSWNewVersionReady()` 可能无法到达客户端（channel 未与 waiting worker 建立）。必须依赖原生 `postMessage` + `statechange` 事件作为可靠通知路径。

2. **statechange 通知需要重试**：`requestSWVersionState(newWorker)` 只发一次，如果 SW 仍在预缓存（`waitUntil` 未完成），响应可能丢失。需要 5 秒后重试 + `visibilitychange` 时重新检查。

3. **CDN URL 版本重写陷阱**：`cleanResourcePath` 会剥离 CDN 路径中的版本前缀（`npm/aitu-app@x.y.z/`），`buildCDNUrl` 再用 `committedVersion` 重建。如果 `committedVersion` 与请求 URL 中的版本不一致，会构造出错误的 CDN URL。防御措施：`extractVersionFromCDNPath` 优先使用 URL 中已有的版本号。

4. **activate 必须无条件更新 committedVersion**：原设计只在首次安装和用户确认时更新，自然激活时遗漏。SW 一旦激活就是当前版本，`committedVersion` 必须与 `APP_VERSION` 一致。

#### 关键文件

| 文件 | 职责 |
|------|------|
| `apps/web/src/main.tsx` | SW 注册、版本状态监听、升级确认 |
| `apps/web/src/sw/index.ts` | install/activate 处理、版本状态管理、静态资源拦截 |
| `apps/web/src/sw/cdn-fallback.ts` | CDN 回退、版本号提取、健康检查 |
| `packages/drawnix/src/components/version-update/version-update-prompt.tsx` | 升级提示 UI |

---