图片上传优化总结

> **文档版本**: v1.0.0
> **创建日期**: 2026-02-12
> **最后更新**: 2026-02-12
> **维护人**: 未来鸟FutureBird码巢企业服务引擎开发组
> **状态**: [最新]

---

# 图片上传优化总结

## 优化的文件

### 1. 新增文件

#### `src/hooks/useImageUpload.ts`
- **功能**: 统一的图片上传Hook
- **特性**:
  - 支持上传进度显示
  - 自动验证文件类型和大小
  - 统一的错误处理
  - 支持取消上传
  - 自动显示成功/失败提示

**使用方式**:
```typescript
const imageUpload = useImageUpload();

// 上传图片
const result = await imageUpload.uploadFile(file, 'category');

// 监听状态
- imageUpload.data: 上传结果
- imageUpload.loading: 上传中
- imageUpload.progress: 上传进度 (0-100)
- imageUpload.error: 错误信息
```

#### `src/components/media/MediaSelector.tsx`
- **功能**: 完整的图库选择器组件
- **特性**:
  - 瀑布流布局，图片按比例自适应
  - 左侧分类树，支持层级结构
  - 拖拽上传
  - 搜索功能
  - 图片预览
  - 响应式设计

### 2. 优化的文件

#### `src/app/admin/settings/brand/page.tsx`
**优化内容**:
- ✅ 使用 `useImageUpload` Hook 替代手动上传
- ✅ 添加上传进度显示
- ✅ 优化上传交互体验
- ✅ 集成完整的图库选择器

#### `src/app/brand-settings/page.tsx`
**优化内容**:
- ✅ 实现真实的对象存储上传（之前是TODO）
- ✅ 使用 `useImageUpload` Hook
- ✅ 添加上传进度显示
- ✅ 添加文件类型和大小验证
- ✅ 优化上传按钮状态

#### `src/app/admin/settings/media/page.tsx`
**现状**: 已经使用统一上传接口，无需修改

## 上传接口统一

所有图片上传都使用统一接口：
```
POST /api/v1/media/upload
```

**请求参数**:
- `file`: 文件
- `category`: 分类（可选，默认为general）

**响应**:
```json
{
  "success": true,
  "data": {
    "id": "uuid",
    "fileName": "文件名.jpg",
    "fileUrl": "https://...",
    "category": "general",
    "fileSize": 12345,
    "mimeType": "image/jpeg",
    "createdAt": "2026-02-02 16:00:00"
  }
}
```

## 支持的文件类型

- `image/jpeg` (.jpg, .jpeg)
- `image/png` (.png)
- `image/gif` (.gif)
- `image/webp` (.webp)
- `image/svg+xml` (.svg)
- `image/x-icon` (.ico)

## 文件大小限制

- 默认限制: 20MB
- Logo限制: 2MB
- Favicon限制: 1MB
- 品牌设置Logo限制: 5MB

## 存储位置

- **对象存储**: 七牛云（使用七牛云原生SDK）
- **Bucket**: wlnsaas
- **自定义域名**: https://saas.28.cq.cn

## 使用示例

### 示例1: 品牌设置页面上传Logo

```typescript
import { useImageUpload } from '@/hooks/useImageUpload';

function BrandSettings() {
  const logoUpload = useImageUpload();

return (
    <Upload
      customRequest={async ({ file, onSuccess }) => {
        try {
          const url = await handleUpload(file);
          onSuccess({ url });
        } catch (error) {
          // 错误已在useImageUpload中处理
        }
      }}
    >
      <div>
        {logoUpload.loading ? (
          <Progress percent={logoUpload.progress} />
        ) : (
          <UploadOutlined />
        )}
      </div>
    </Upload>
  );
}
```

### 示例2: 使用图库选择器

```typescript
import MediaSelector from '@/components/media/MediaSelector';

function MyComponent() {
  const [open, setOpen] = useState(false);

const handleSelect = (item: MediaItem) => {
    console.log('选择的图片:', item);
    setLogoUrl(item.fileUrl);
  };

return (
    <>
      <Button onClick={() => setOpen(true)}>
        从图库选择
      </Button>

<MediaSelector
        open={open}
        onClose={() => setOpen(false)}
        onSelect={handleSelect}
        title="选择图片"
      />
    </>
  );
}
```

## 最佳实践

1. **统一使用 Hook**: 所有图片上传都应使用 `useImageUpload` Hook
2. **显示进度**: 大文件上传时显示上传进度
3. **文件验证**: 在客户端验证文件类型和大小
4. **错误处理**: 提供清晰的错误提示
5. **使用图库**: 对于需要选择已有图片的场景，使用 MediaSelector 组件

## 检查清单

- [x] 创建统一的图片上传Hook (`useImageUpload`)
- [x] 优化品牌设置页面上传 (`/admin/settings/brand`)
- [x] 实现品牌设置页面上传 (`/brand-settings`)
- [x] 创建完整的图库选择器 (`MediaSelector`)
- [x] 添加上传进度显示
- [x] 添加文件验证
- [x] 统一错误处理
- [x] 优化用户交互体验
- [x] 瀑布流布局优化

## 后续优化建议

1. 添加图片压缩功能（上传前自动压缩）
2. 添加批量上传功能
3. 添加图片裁剪功能
4. 添加图片编辑功能
5. 支持更多图片格式（如 AVIF）
6. 添加上传历史记录