docs/v1.0/server/rfcs/003-attachment-service-opt.md

附件服务分类优化方案

创建日期：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 类型：

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 类型：

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 类型：

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

4. 音频类（audio）

新增分类：

• 完全新增的文件类型

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

大小限制：100MB

MIME 类型：

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

---

数据库变更

attachments 表

category 字段枚举值变更：

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

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

迁移策略：

-- 将现有 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'

默认值变更：

旧：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
审核者：待审核
状态：已完成 ✅