# 新建项目时共享素材功能实现（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`。

---

## 使用说明

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

---

## 相关文档

- [ADR 02: 跨项目资源共享](../../adrs/02-cross-project-resource-sharing.md)
- [跨项目资源共享：选择资源后的入库与关联](../guides/cross-project-resource-sharing-persistence.md)