# 附件服务分类优化方案

> **创建日期**：2025-01-27  
> **状态**：已完成 ✅

---

## 背景

现有附件服务的文件分类过于简单（script/image/video/other），无法满足视频制作平台的实际业务需求。经过深度分析，识别出 13 种潜在的附件分类场景。

---

## 需求分析

### 视频制作平台的七大使用场景

1. **剧本创作阶段**：剧本文档、参考资料
2. **前期筹备阶段**：拍摄计划、预算表、场地照片、合同
3. **素材收集阶段**：参考图片、参考视频、音乐素材
4. **制作过程阶段**：原始素材、工程文件、字体文件
5. **协作审批阶段**：审批文件、反馈文档、截图
6. **版权法务阶段**：版权证明、授权书
7. **成品交付阶段**：成品视频、字幕、封面图

### 识别的 13 种附件分类

1. script（剧本）
2. document（文档）
3. image（图片）
4. video（视频）
5. audio（音频）
6. subtitle（字幕）
7. font（字体）
8. project（工程文件）
9. archive（压缩包）
10. model（3D模型）
11. reference（参考资料）
12. contract（合同法务）
13. other（其他）

---

## 优化方案

### 方案选择

**用户决策**：保持简洁，只支持 4 大核心类别，其他功能后续扩展。

**最终方案**：

- document（文档类）
- image（图片类）
- video（视频类）
- audio（音频类）

---

## 实施细节

### 1. 文档类（document）

**合并内容**：

- 原 `script` 分类合并到 `document`
- 新增办公文档支持

**支持格式**：

- 剧本：PDF、Word (.doc/.docx)、TXT、Markdown
- 办公文档：Excel (.xls/.xlsx)

**大小限制**：100MB（原 50MB）

**MIME 类型**：

```python
ALLOWED_DOCUMENT_TYPES = {
    'application/pdf',
    'application/msword',
    'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
    'application/vnd.ms-excel',
    'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
    'text/plain',
    'text/markdown'
}
```

### 2. 图片类（image）

**扩展内容**：

- 新增 WebP、BMP 支持
- 新增设计格式（PSD、AI）支持

**支持格式**：

- 常用：JPG、PNG、GIF、WebP、BMP
- 设计：PSD、AI

**大小限制**：20MB（原 10MB）

**MIME 类型**：

```python
ALLOWED_IMAGE_TYPES = {
    'image/jpeg',
    'image/png',
    'image/gif',
    'image/webp',
    'image/bmp',
    'image/vnd.adobe.photoshop',  # PSD
    'application/postscript'  # AI
}
```

### 3. 视频类（video）

**扩展内容**：

- 新增 MKV、WebM 支持

**支持格式**：MP4、MOV、AVI、MKV、WebM

**大小限制**：2GB（原 500MB）

**MIME 类型**：

```python
ALLOWED_VIDEO_TYPES = {
    'video/mp4',
    'video/quicktime',
    'video/x-msvideo',
    'video/x-matroska',
    'video/webm'
}
```

### 4. 音频类（audio）

**新增分类**：

- 完全新增的文件类型

**支持格式**：MP3、WAV、AAC、FLAC、M4A

**大小限制**：100MB

**MIME 类型**：

```python
ALLOWED_AUDIO_TYPES = {
    'audio/mpeg',  # MP3
    'audio/wav',
    'audio/x-wav',
    'audio/aac',
    'audio/flac',
    'audio/mp4'  # M4A
}
```

---

## 数据库变更

### attachments 表

**category 字段枚举值变更**：

```sql
-- 旧值
category IN ('script', 'image', 'video', 'other')

-- 新值
category IN ('document', 'image', 'video', 'audio')
```

**迁移策略**：

```sql
-- 将现有 script 分类迁移到 document
UPDATE attachments
SET category = 'document'
WHERE category = 'script' AND deleted_at IS NULL;

-- 将现有 other 分类根据 MIME 类型重新分类
UPDATE attachments
SET category = 'audio'
WHERE category = 'other'
  AND mime_type LIKE 'audio/%'
  AND deleted_at IS NULL;

UPDATE attachments
SET category = 'document'
WHERE category = 'other'
  AND deleted_at IS NULL;
```

---

## API 变更

### 上传接口

**请求参数变更**：

```
旧：category: 'script' | 'image' | 'video' | 'other'
新：category: 'document' | 'image' | 'video' | 'audio'
```

**默认值变更**：

```python
旧：category: str = 'other'
新：category: str = 'document'
```

### 查询接口

**category 参数值变更**：

```
GET /api/v1/attachments?category=document  # 原 script
GET /api/v1/attachments?category=audio     # 新增
```

---

## 文件大小限制对比

| 分类              | 旧限制 | 新限制 | 变化  |
| ----------------- | ------ | ------ | ----- |
| script → document | 50MB   | 100MB  | +100% |
| image             | 10MB   | 20MB   | +100% |
| video             | 500MB  | 2GB    | +300% |
| audio             | -      | 100MB  | 新增  |
| other             | 100MB  | -      | 移除  |

---

## 优势

### 1. 更清晰的分类

- 文档类涵盖所有文档类型（剧本、办公文档）
- 音频类独立出来，便于管理音乐、音效、配音

### 2. 更大的文件支持

- 文档类：支持更大的 Excel、PPT 文件
- 图片类：支持高清图片
- 视频类：支持原始素材上传

### 3. 更多的格式支持

- 文档类：Excel
- 图片类：WebP、BMP、PSD、AI
- 视频类：MKV、WebM
- 音频类：完整的音频格式支持

### 4. 保持简洁

- 只有 4 个核心分类，易于理解和使用
- 为未来扩展预留空间

---

## 后续扩展建议

### 短期（可选）

- subtitle（字幕）：SRT、ASS、VTT
- font（字体）：TTF、OTF、WOFF

### 中期（可选）

- project（工程文件）：AEP、PRPROJ、PSD
- archive（压缩包）：ZIP、RAR、7Z

### 长期（可选）

- model（3D模型）：OBJ、FBX、GLTF
- reference（参考资料）
- contract（合同法务）

---

## 兼容性

### 向后兼容

- 现有 `script` 分类的文件自动迁移到 `document`
- 现有 `other` 分类的音频文件自动迁移到 `audio`
- API 保持兼容，只是参数值变更

### 前端适配

- 更新上传组件的 category 选项
- 更新文件列表的筛选器
- 更新文件图标映射

---

## 总结

本次优化在保持简洁的前提下，显著提升了附件服务的实用性：

- ✅ 合并剧本到文档类，统一文档管理
- ✅ 新增音频类，支持音乐、音效、配音
- ✅ 扩展文件格式支持（Excel、PPT、WebP、MKV等）
- ✅ 提升文件大小限制，满足专业需求
- ✅ 保持 4 个核心分类，易于使用

---

**创建者**：AI Assistant  
**审核者**：待审核  
**状态**：已完成 ✅