docs/v1.0/.archive/server/attachment-redesign.md

附件与资源管理重新设计计划

任务名称：附件与资源管理架构优化
创建时间：2025-01-27
状态：待执行

---

1. 背景

问题分析

1. 表过大风险：如果所有文件（文档、图片、视频、音频）都存储在单一 attachments 表，随着项目增多，表会达到百万级甚至千万级记录
2. 业务混乱：角色/场景/道具素材与普通文档附件的使用场景完全不同，混在一起导致业务逻辑复杂
3. 资源分层需求：需要区分"系统资源库"、"素材市场"、"项目专属素材"三个层次
4. 查询性能：不同类型文件的查询模式不同，单表难以针对性优化

解决方案

业务分离 + 服务层统一：

• 不同业务场景的文件使用不同的表管理
• 通过公共服务层（FileStorageService）实现代码复用和去重
• 使用 file_checksums 表实现全局去重

---

2. 执行步骤

Step 1: 更新数据库设计文档

文件：docs/需求/database-design.md

修改内容：

1. 新增 project_resources 表（项目专属素材）
2. 调整 resources 表定义（系统资源库+素材市场）
3. 新增 file_checksums 表（全局去重）
4. 调整 attachments 表（简化为文档附件）
5. 更新 storyboard_resources 表（关联 project_resources）
6. 新增业务表字段：
   • users.avatar_id
   • projects.cover_image_id
   • storyboards.thumbnail_id

Step 2: 更新附件服务文档

文件：docs/需求/backend/04-services/attachment-service.md

修改内容：

1. 更新服务概述：明确 attachments 表只管理文档类附件
2. 简化文件分类：只保留 document、image 两类
3. 更新数据模型：
   • 移除 resource_id 关联
   • 保留 project_id、script_id 关联
   • 保留 uploaded_by 审计字段
4. 更新 API 接口：调整上传接口参数
5. 新增 FileStorageService 说明

Step 3: 更新资源服务文档

文件：docs/需求/backend/04-services/resource-service.md

修改内容：

1. 拆分为两个服务：
   • ResourceService（系统资源库+素材市场）
   • ProjectResourceService（项目专属素材）
2. 更新数据模型：
   • resources 表：系统资源库
   • project_resources 表：项目素材
3. 新增资源流转逻辑：
   • 从资源库复制到项目
   • 从项目发布到素材市场
4. 新增 API 接口：
   • 资源库查询、下载
   • 项目素材管理
   • 素材市场发布

Step 4: 创建文件存储服务文档

文件：docs/需求/backend/04-services/file-storage-service.md（新建）

内容：

1. 服务概述：统一的文件上传、下载、删除服务
2. 核心功能：
   • 文件上传（带去重）
   • 文件下载（预签名URL）
   • 文件删除
   • 校验和计算
3. 去重机制：file_checksums 表设计
4. 对象存储集成：MinIO/S3 接口

Step 5: 更新分镜服务文档

文件：docs/需求/backend/04-services/storyboard-service.md

修改内容：

1. 更新 storyboard_resources 关联：从 resources 改为 project_resources
2. 更新 API 接口：分镜添加素材的接口调整

Step 6: 创建方案文档

文件：docs/方案/attachment-and-resource-architecture.md（新建）

内容：

1. 架构设计说明
2. 表结构对比（调整前 vs 调整后）
3. 资源流转路径图
4. 数据量预估
5. 性能优化策略
6. 迁移方案（如果已有数据）

---

3. 涉及的文件

修改文件

1. docs/需求/database-design.md - 数据库设计
2. docs/需求/backend/04-services/attachment-service.md - 附件服务
3. docs/需求/backend/04-services/resource-service.md - 资源服务
4. docs/需求/backend/04-services/storyboard-service.md - 分镜服务

新建文件

1. docs/需求/backend/04-services/file-storage-service.md - 文件存储服务
2. docs/方案/attachment-and-resource-architecture.md - 架构方案文档

---

4. 关键设计点

4.1 表结构分层

attachments 表
├─ 用途：文档类附件（剧本、合同、参考资料）
├─ 关联：project_id, script_id
└─ 数据量：1-5万条（1000个项目）

resources 表
├─ 用途：系统资源库 + 素材市场
├─ 特点：is_public, is_official, price
└─ 数据量：1-10万条（公共资源）

project_resources 表
├─ 用途：项目专属素材（角色、场景、道具）
├─ 关联：project_id, source_resource_id
└─ 数据量：5-30万条（1000个项目）

file_checksums 表
├─ 用途：全局去重
└─ 数据量：与文件总数相当

4.2 资源流转路径

MVP 阶段（前期开发）：

项目素材库 (project_resources)
    ↓ 使用
分镜/时间轴 (storyboard_resources, timeline_items)

完整版（后期扩展）：

系统资源库 (resources, is_official=true)
    ↓ 复制
素材市场 (resources, is_public=true)
    ↓ 下载/复制
项目素材库 (project_resources)
    ↓ 使用
分镜/时间轴 (storyboard_resources, timeline_items)

注意：前期开发暂不实现 resources 表（系统资源库+素材市场），保留表结构设计供后续扩展。

4.3 一对一关系（业务表存附件ID）

• users.avatar_id → attachments
• projects.cover_image_id → attachments
• storyboards.thumbnail_id → attachments

4.4 一对多关系（附件表存业务ID）

• attachments.project_id → projects
• attachments.script_id → scripts
• project_resources.project_id → projects

---

5. 预期成果

✅ 数据库设计文档更新完成
✅ 附件服务文档更新完成
✅ 资源服务文档拆分并更新完成
✅ 文件存储服务文档创建完成
✅ 分镜服务文档更新完成
✅ 架构方案文档创建完成

---

6. 风险与注意事项

1. 数据迁移：如果已有数据，需要编写迁移脚本
2. API 兼容性：前端接口调用需要同步调整
3. 文件引用：确保所有文件引用关系正确
4. 去重逻辑：file_checksums 表需要定期清理无引用的记录

---

计划创建完成，等待用户批准执行。