3.2 KiB

Raw Blame History

新建项目时共享素材功能实现（ADR 02）

日期：2026-02-08
范围：后端 + 前端，新建项目时选择共享资源并入库关联

变更概要

数据库：新增表 project_resource_shares（迁移 20260208_1000），无物理外键，应用层校验。
后端：新增 Model/Schema/Repository/Service 支持共享记录创建；POST /api/v1/projects 请求体支持 sharedResources，创建项目后写入共享记录。
前端：CreateProjectDto 增加 sharedResources；选择共享资源后提交时转换为 API 格式并随创建项目请求发送。

后端

迁移

alembic/versions/20260208_1000_create_project_resource_shares_table.py
表：share_id（PK）、source_project_id、target_project_id、share_type、resource_type、resource_id、status、created_at、created_by、updated_at
唯一约束：(source_project_id, target_project_id, share_type, resource_type, resource_id)
索引：source、target、status

模型与枚举

app/models/project_resource_share.py：ProjectResourceShare、ShareType、ShareStatus
资源类型与现有 project_resources 一致：1=角色 2=场景 3=道具 4=素材

Schema

app/schemas/project.py：SharedResourceItem（sourceType/sourceId/shareType/resourceType，camelCase 别名）
ProjectCreate.shared_resources 可选列表

Repository / Service

ProjectResourceShareRepository：create、get_by_target_project、exists
ProjectResourceShareService.create_shares(target_project_id, shared_resources, user_id)：
- folder：展开文件夹下父项目，逐条校验权限并去重后插入 share_type=1
- project：校验权限后插入 share_type=1
- resource：按 resource_id 查源项目，校验权限后插入 share_type=3
权限：ProjectRepository.check_user_permission(..., "viewer")

项目创建流程

ProjectService.create_project：在创建项目并处理协作成员后，若 project_data.shared_resources 非空，调用 ProjectResourceShareService.create_shares，同一事务内完成。

前端

类型

client/src/types/project.ts：SharedResourceItemDto、CreateProjectDto.sharedResources

转换与提交

CreateProjectModal 内 buildSharedResourcesPayload(selectedResources)：将 SharedResource[]（folder/project/character/scene/prop）转为 SharedResourceItemDto[]（sourceType/sourceId/shareType/resourceType）。
提交时：sharedResources: selectedResources.length > 0 ? buildSharedResourcesPayload(selectedResources) : undefined。

使用说明

在创建项目弹窗中点击「选择资源」，在面板中勾选文件夹、项目或具体角色/场景/道具。
提交创建后，后端会先创建项目，再根据选中项写入 project_resource_shares（文件夹会展开为多个项目一条共享记录）。
仅当用户对源项目有查看权限时才会创建共享记录；无权限的源项目会被跳过并打日志。

相关文档