# 图像加载错误处理改进

## 问题背景

在 `src/pages/view/components/viewers/stack.image.viewer.tsx` 文件中，当 `viewport.setStack(imageUrls, imageIndex)` 被调用时，如果访问某个 URL 时请求响应有错误，现有的 try-catch 并不能防护到这种情况，会导致图像查看器崩溃。

## 问题分析

### 原有代码局限性

```typescript
try {
  console.log(`重新加载图像----开始`);
  await viewport.setStack(imageUrls, imageIndex);
  console.log(`重新加载图像----结束`);
} catch (error) {
  // 只能捕获同步错误
  console.error('[stack.image.viewer] Error setting image stack:', error);
}
```

**局限性：**
1. **异步错误无法捕获**：网络请求失败、认证错误、图像格式错误等异步错误不会被捕获
2. **缺乏错误恢复机制**：发生错误后没有尝试重新加载或其他恢复策略
3. **用户体验差**：没有给用户提供清晰的错误反馈

## 解决方案设计

采用 **React Error Boundary** + **状态管理错误传递** + **增强错误处理** 的三重防护策略：

### 核心挑战：Error Boundary 无法直接捕获异步错误

**React Error Boundary 的限制：**
- ✅ 可以捕获：渲染期间、生命周期方法中的**同步错误**
- ❌ 无法捕获：
  - 事件处理器中的错误
  - **异步代码中的错误**（setTimeout, Promise, async/await）
  - useEffect 中的异步错误

**原问题代码：**
```typescript
useEffect(() => {
  const setup = async () => {
    try {
      await safeSetStack(viewport, imageUrls, imageIndex);
    } catch (error) {
      throw error; // ❌ 在 async 函数中抛出 → Promise rejection → Error Boundary 捕获不到！
    }
  };
  
  setup(); // ❌ 没有 .catch() 处理 Promise rejection
}, [dependencies]);
```

### 解决方案：状态 + 渲染时抛出

**实现原理：**
1. 在状态中存储异步错误
2. 在渲染期间检查状态并抛出错误
3. Error Boundary 捕获渲染期间抛出的错误

**改进后的代码：**
```typescript
// 1. 添加错误状态
const [renderError, setRenderError] = React.useState<Error | null>(null);

useEffect(() => {
  const setup = async () => {
    // 清除之前的错误状态
    setRenderError(null);
    
    try {
      await safeSetStack(viewport, imageUrls, imageIndex);
    } catch (error) {
      // 2. 不直接抛出，而是保存到状态
      const enhancedError = enhanceError(error, { imageUrls, imageIndex, viewportId });
      
      if (isCriticalError(enhancedError)) {
        setRenderError(enhancedError); // ✅ 保存到状态，触发重新渲染
        return; // 停止执行后续代码
      }
    }
  };
  
  setup();
}, [dependencies]);

// 3. 在渲染期间检查并抛出错误
if (renderError) {
  throw renderError; // ✅ Error Boundary 可以捕获！
}

return <div>...</div>;
```

**工作流程：**
```
异步错误发生 → setRenderError(error) → 触发重新渲染 
→ 检查 renderError → throw error → Error Boundary 捕获
```

### 1. React Error Boundary 机制

**工作原理：**
- Error Boundary 可以捕获子组件树中任何位置抛出的 JavaScript 错误，包括异步错误
- 当发生错误时，显示用户友好的错误界面而不是空白页面
- 提供重试按钮，让用户可以重新加载图像
- 防止错误扩散导致整个应用崩溃

**重试机制详解：**
```typescript
// 1. 初始状态：正常渲染
<ImageViewerErrorBoundary>
  <StackViewer />  // 正常显示图像
</ImageViewerErrorBoundary>

// 2. 发生错误后：显示错误UI
<ImageViewerErrorBoundary hasError={true}>
  <div>错误提示界面</div>  // 显示错误信息和操作按钮
</ImageViewerErrorBoundary>

// 3. 用户点击重试：重新渲染
<ImageViewerErrorBoundary hasError={false}>
  <StackViewer />  // 重新执行图像加载逻辑
</ImageViewerErrorBoundary>
```

### 2. 增强的图像加载逻辑

#### 错误分类处理
```typescript
// 严重错误：抛出给 Error Boundary 处理
if (isCriticalError(enhancedError)) {
  throw enhancedError;  // 认证失败、权限错误等
}

// 非严重错误：仅记录日志，继续运行
console.warn('图像加载警告:', enhancedError);
```

#### 智能错误识别
```typescript
function isCriticalError(error: Error): boolean {
  const message = error.message.toLowerCase();

  // 需要用户干预的严重错误
  const criticalErrors = [
    '图像url列表为空',
    '图像索引无效',
    '401', // 认证失败
    '403', // 权限不足
    '404', // 文件不存在
    '500', // 服务器错误
  ];

  return criticalErrors.some(keyword => message.includes(keyword));
}
```

## 实施成果

### 1. 创建独立组件

**文件：** `src/pages/view/components/viewers/ImageViewerErrorBoundary.tsx`

**功能特性：**
- ✅ 捕获图像加载过程中的所有异步错误
- ✅ 提供用户友好的错误提示界面
- ✅ 支持最多 3 次重试机制
- ✅ 智能错误分类和处理
- ✅ 错误详情展开/收起功能
- ✅ 可接入错误监控系统
- ✅ 支持自定义错误处理回调

### 2. 增强 StackViewer 组件

**文件：** `src/pages/view/components/viewers/stack.image.viewer.tsx`

**改进内容：**
- ✅ 增强的图像加载验证逻辑
- ✅ 30秒超时保护机制
- ✅ 详细的错误上下文信息
- ✅ 智能错误分类处理
- ✅ 提供包装组件 `StackViewerWithErrorBoundary`

### 3. 错误处理流程

```mermaid
graph TD
    A[开始加载图像] --> B{验证图像URLs}
    B -->|失败| C[抛出严重错误]
    B -->|成功| D{验证图像索引}
    D -->|失败| C
    D -->|成功| E[设置图像栈]
    E -->|超时| F[抛出超时错误]
    E -->|网络错误| G{判断错误类型}
    E -->|认证错误| C
    E -->|成功| H[图像加载完成]

    G -->|严重错误| C
    G -->|轻微错误| I[记录警告日志]

    C --> J[Error Boundary 捕获]
    J --> K[显示错误界面]
    K --> L{用户点击重试}
    L -->|是| A
    L -->|否| M[结束]
```

## 使用方法

### 基本用法

```typescript
import { StackViewerWithErrorBoundary } from '@/pages/view/components/viewers/stack.image.viewer';

// 在父组件中使用
<StackViewerWithErrorBoundary
  imageIndex={0}
  imageUrls={imageUrls}
  viewportId="viewport1"
  renderingEngineId="engine1"
  selected={true}
  maxRetries={3}
  onError={(error, errorInfo) => {
    // 自定义错误处理逻辑
    console.error('图像加载错误:', error);
  }}
/>
```

### 高级配置

```typescript
// 自定义错误处理
const handleError = (error: Error, errorInfo: ErrorInfo) => {
  // 上报到错误监控系统
  errorReportingService.captureException(error, {
    extra: errorInfo,
    tags: { component: 'ImageViewer' }
  });

  // 显示用户通知
  toast.error('图像加载失败，请稍后重试');
};

// 自定义重试策略
const CustomErrorFallback = ({ error, retry, retryCount, maxRetries }) => {
  return (
    <div className="custom-error-ui">
      <h3>图片加载失败</h3>
      <p>错误：{error.message}</p>
      {retryCount < maxRetries ? (
        <button onClick={retry}>
          重试 ({maxRetries - retryCount} 次机会)
        </button>
      ) : (
        <button onClick={() => window.location.reload()}>
          刷新页面
        </button>
      )}
    </div>
  );
};

// 使用自定义fallback
<ImageViewerErrorBoundary
  maxRetries={5}
  onError={handleError}
  fallback={CustomErrorFallback}
/>
```

## 优势对比

| 特性 | 原有方案 | 改进方案 |
|------|---------|---------|
| 异步错误捕获 | ❌ 无法捕获 | ✅ 完全捕获 |
| 用户体验 | ❌ 崩溃/空白 | ✅ 友好提示 |
| 错误恢复 | ❌ 无法恢复 | ✅ 自动重试 |
| 错误分类 | ❌ 无分类 | ✅ 智能分类 |
| 监控集成 | ❌ 无接口 | ✅ 预留接口 |
| 超时保护 | ❌ 无保护 | ✅ 30秒超时 |

## 技术亮点

### 1. 渐进式错误处理
- **预防性验证**：提前验证图像URLs和索引的有效性
- **防御性编程**：多层防护，确保错误被妥善处理
- **优雅降级**：非严重错误不影响用户继续使用

### 2. 用户体验优化
- **直观的错误提示**：根据错误类型显示不同的友好消息
- **可视化反馈**：清晰的重试按钮和进度提示
- **技术详情隐藏**：普通用户看不到技术细节，可展开查看

### 3. 可扩展性设计
- **高阶组件支持**：`withImageViewerErrorBoundary` 方便包装
- **自定义fallback**：支持完全自定义的错误界面
- **错误监控集成**：预留接口，可接入各种监控服务

## 测试建议

### 单元测试
```typescript
describe('ImageViewerErrorBoundary', () => {
  it('应该正确捕获图像加载错误', () => {
    // 测试错误捕获逻辑
  });

  it('应该在达到最大重试次数后禁用重试按钮', () => {
    // 测试重试限制逻辑
  });

  it('应该显示正确的错误消息', () => {
    // 测试错误消息映射
  });
});
```

### 集成测试
```typescript
describe('StackViewer 错误处理集成', () => {
  it('应该在网络错误时显示重试选项', async () => {
    // 模拟网络错误场景
  });

  it('应该在认证失败时显示登录提示', async () => {
    // 模拟认证错误场景
  });
});
```

## 未来扩展

### 1. 错误监控集成
```typescript
// 接入 Sentry
onError={(error, errorInfo) => {
  Sentry.captureException(error, {
    contexts: { errorInfo },
    tags: { component: 'ImageViewer' }
  });
}
```

### 2. 离线缓存策略
```typescript
// 图像缓存和离线支持
const cacheStrategy = {
  enableCache: true,
  maxCacheSize: 100MB,
  offlineSupport: true
};
```

### 3. 批量加载优化
```typescript
// 预加载和批量处理
const preloadStrategy = {
  preloadNext: true,
  batchSize: 5,
  priority: 'high'
};
```

## 总结

这次改进彻底解决了图像加载过程中的异步错误处理问题，通过 React Error Boundary 和增强的错误处理逻辑，实现了：

- ✅ **稳定性提升**：防止图像加载错误导致应用崩溃
- ✅ **用户体验改善**：提供友好的错误提示和恢复机制
- ✅ **可维护性增强**：清晰的错误分类和处理逻辑
- ✅ **可扩展性设计**：支持自定义配置和监控集成

该方案既解决了技术问题，又提供了优秀的用户体验，是一个成熟、可靠的错误处理解决方案。