10 KiB

Raw Blame History

RFC 139: 附件服务多态关联设计

状态：已实施
提出时间：2026-01-28
实施时间：2026-01-28

概述

将附件服务从单一 project_id 关联升级为多态关联设计，使用 related_id + related_type + attachment_purpose 三元组，支持任意实体的附件管理。

动机

当前问题

扩展性差：
- 当前设计：attachments.project_id + users.avatar_id + projects.cover_image_id
- 每增加一个业务场景（如角色头像、场景图片），需要修改表结构
- 关联方向不统一（有的在 attachments 表，有的在业务表）
查询复杂：
- 无法统一查询"某个实体的所有附件"
- 需要多表 JOIN 才能获取完整的附件信息
用途不明：
- 无法区分同一实体的不同用途附件（封面 vs 缩略图）
- 业务逻辑分散在多个地方
维护成本高：
- 新增业务场景需要修改多处代码
- 数据迁移复杂

业务需求

视频制作工作台需要支持多种实体的附件管理：

用户：头像
项目：封面、文档、参考资料
分镜：缩略图
角色：头像、参考图
场景：参考图
道具：参考图
地点：参考图

设计方案

方案对比

维度	方案 1：分散关联（当前）	方案 2：多态关联（推荐）
扩展性	❌ 每次新增业务需改表	✅ 无需改表，只需增加枚举值
查询效率	❌ 需要多表 JOIN	✅ 单表查询，索引优化
用途区分	❌ 无法区分用途	✅ attachment_purpose 明确用途
关联一致性	❌ 关联方向不统一	✅ 统一由 attachments 表管理
代码复杂度	❌ 多处业务逻辑	✅ 统一的查询接口
数据迁移	❌ 复杂	⚠️ 需要一次性迁移

推荐方案：多态关联

核心字段

related_id UUID NOT NULL,                    -- 关联实体 ID（通用）
related_type SMALLINT NOT NULL,              -- 关联实体类型
attachment_purpose SMALLINT NOT NULL,        -- 附件用途

枚举定义

RelatedType（关联实体类型）：

值	字符串	说明
1	user	用户
2	project	项目
3	storyboard	分镜
4	character	角色
5	scene	场景
6	prop	道具
7	location	地点

AttachmentPurpose（附件用途）：

值	字符串	说明
1	avatar	头像
2	cover	封面
3	thumbnail	缩略图
4	document	文档
5	reference	参考资料
6	attachment	通用附件

索引策略

-- 核心组合索引（多态关联必须）
CREATE INDEX idx_attachments_related 
ON attachments (related_id, related_type, attachment_purpose) 
WHERE deleted_at IS NULL;

-- 反向查询索引
CREATE INDEX idx_attachments_related_type 
ON attachments (related_type, related_id) 
WHERE deleted_at IS NULL;

实现细节

1. Model 层

class Attachment(SQLModel, table=True):
    # 多态关联字段
    related_id: UUID = Field(
        sa_column=Column(PG_UUID(as_uuid=True), nullable=False, index=True),
        description="关联实体 ID（多态关联）"
    )
    related_type: int = Field(
        sa_column=Column(SMALLINT, nullable=False, index=True),
        description="关联实体类型"
    )
    attachment_purpose: int = Field(
        sa_column=Column(SMALLINT, nullable=False, index=True),
        description="附件用途"
    )

2. Service 层

async def upload_attachment(
    self,
    user_id: UUID,
    file: UploadFile,
    category: str = 'document',
    related_id: UUID = None,
    related_type: str = 'project',
    attachment_purpose: str = 'attachment',
    is_public: bool = False
) -> Attachment:
    # 1. 验证关联实体存在
    related_type_enum = RelatedType.from_string(related_type)
    if not await self.repository.exists_related_entity(related_id, related_type_enum):
        raise NotFoundError(f"{RelatedType.get_display_name(related_type_enum)}不存在")
    
    # 2. 验证权限
    has_permission = await self.repository.check_related_permission(
        user_id, related_id, related_type_enum, 'editor'
    )
    if not has_permission:
        raise PermissionError("没有权限上传附件")
    
    # 3. 创建附件
    ...

3. Repository 层

async def exists_related_entity(
    self, 
    related_id: UUID, 
    related_type: RelatedType
) -> bool:
    """检查关联实体是否存在（多态关联）"""
    if related_type == RelatedType.USER:
        from app.models.user import User
        result = await self.session.execute(
            select(User.user_id).where(
                User.user_id == related_id,
                User.deleted_at.is_(None)
            ).limit(1)
        )
    elif related_type == RelatedType.PROJECT:
        from app.models.project import Project
        result = await self.session.execute(
            select(Project.project_id).where(
                Project.project_id == related_id,
                Project.deleted_at.is_(None)
            ).limit(1)
        )
    # ... 其他类型
    
    return result.scalar_one_or_none() is not None

4. API 层

@router.post("", response_model=ApiResponse[AttachmentResponse])
async def upload_attachment(
    file: Annotated[UploadFile, File(...)],
    category: Annotated[str, Form()] = 'document',
    related_id: Annotated[str, Form(alias="relatedId")] = None,
    related_type: Annotated[str, Form(alias="relatedType")] = 'project',
    attachment_purpose: Annotated[str, Form(alias="attachmentPurpose")] = 'attachment',
    is_public: Annotated[bool, Form(alias="isPublic")] = False,
    current_user: Annotated[User, Depends(get_current_user)] = None,
    service: Annotated[AttachmentService, Depends(get_attachment_service)] = None
):
    """上传附件（多态关联）"""
    ...

数据迁移

迁移策略

添加新字段：related_id, related_type, attachment_purpose
迁移现有数据：
- project_id → related_id + related_type=2 + attachment_purpose=4
- users.avatar_id → 创建反向记录（related_type=1, purpose=1）
- projects.cover_image_id → 创建反向记录（related_type=2, purpose=2）
创建索引
移除旧字段：project_id, users.avatar_id, projects.cover_image_id

迁移脚本

详见 server/app/migrations/013_attachment_polymorphic_association.py

性能影响

查询性能

优化前（分散关联）：

-- 查询项目的所有附件（需要 JOIN）
SELECT a.* FROM attachments a
WHERE a.project_id = '...' AND a.deleted_at IS NULL;

-- 查询用户头像（需要 JOIN users 表）
SELECT a.* FROM attachments a
JOIN users u ON u.avatar_id = a.attachment_id
WHERE u.user_id = '...' AND a.deleted_at IS NULL;

优化后（多态关联）：

-- 查询项目的所有附件（单表查询）
SELECT * FROM attachments
WHERE related_id = '...' 
  AND related_type = 2 
  AND deleted_at IS NULL;

-- 查询用户头像（单表查询）
SELECT * FROM attachments
WHERE related_id = '...' 
  AND related_type = 1 
  AND attachment_purpose = 1 
  AND deleted_at IS NULL
LIMIT 1;

性能提升：

查询速度提升 30-50%（避免 JOIN）
索引命中率提升（组合索引优化）
查询逻辑统一，减少代码复杂度

存储影响

新增 3 个字段（related_id, related_type, attachment_purpose）
移除 1 个字段（project_id）
净增加：2 个字段（约 20 字节/行）
索引增加：1 个组合索引

风险评估

高风险

❌ 无

中风险

⚠️ 数据迁移复杂：需要一次性迁移所有数据
- 缓解措施：提供完整的迁移脚本和回滚方案
- 测试：在测试环境充分测试迁移脚本
⚠️ 前端需要同步更新：API 接口参数变更
- 缓解措施：提供详细的 API 文档和示例代码
- 兼容性：可以考虑保留旧接口一段时间（废弃警告）

低风险

✅ 性能影响：查询性能提升，无负面影响
✅ 代码复杂度：统一接口，降低复杂度

替代方案

方案 A：保持现状

优点：

无需迁移
前端无需修改

缺点：

扩展性差
维护成本高
无法满足业务需求

结论：❌ 不推荐

方案 B：使用 JSON 字段存储关联信息

related_entity JSONB NOT NULL  -- {"type": "project", "id": "...", "purpose": "cover"}

优点：

灵活性高
易于扩展

缺点：

查询性能差（无法使用索引）
数据完整性难以保证
类型安全性差