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

> **任务名称**：附件与资源管理架构优化  
> **创建时间**：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 表需要定期清理无引用的记录

---

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