# 移除资源库接口 include_subprojects 参数

**日期**: 2026-02-11  
**类型**: API 优化  
**影响范围**: 资源库 API

## 变更内容

移除资源库接口中的 `include_subprojects` 参数，简化 API 设计。

## 背景

在实现 `get_parent_project_id()` 自动转换逻辑后，`include_subprojects` 参数已经失去原有意义：

**之前的设计意图**：
- `include_subprojects=false` → 仅查询当前项目资源
- `include_subprojects=true` → 查询当前项目及所有子项目资源

**现在的实际行为**：
- 传入父项目ID → 查询父项目资源（所有子项目共享）
- 传入子项目ID → 自动转换为父项目ID → 查询父项目资源

由于项目级资源（角色/场景/道具）本身就存储在父项目级别，子项目自动继承父项目资源，因此 `include_subprojects` 参数变得冗余。

## 移除的内容

### 1. API 层参数移除

**文件**: `server/app/api/v1/resource_library.py`

移除以下接口的 `include_subprojects` 参数：
- `GET /projects/{project_id}/resource-library/characters`
- `GET /projects/{project_id}/resource-library/locations`
- `GET /projects/{project_id}/resource-library/props`
- `GET /projects/{project_id}/resource-library/footage-resources`

**修改前**：
```python
async def get_characters(
    project_id: str,
    include_subprojects: bool = Query(False, description="是否包含子项目资源"),
    ...
):
    result = await service.get_characters(
        project_id=str(parent_project_id),
        include_subprojects=include_subprojects,
        ...
    )
```

**修改后**：
```python
async def get_characters(
    project_id: str,
    # include_subprojects 参数已移除
    ...
):
    result = await service.get_characters(
        project_id=str(parent_project_id),
        # 不再传递 include_subprojects
        ...
    )
```

### 2. 服务层参数移除

**文件**: `server/app/services/resource_library_service.py`

移除以下方法的 `include_subprojects` 参数：
- `get_characters()`
- `get_locations()`
- `get_props()`
- `get_footage_resources()`

### 3. 辅助方法移除

移除不再使用的辅助方法：
- `_get_screenplay_ids()` - 获取项目及子项目的剧本ID列表
- `_get_project_ids()` - 获取项目及子项目的ID列表

### 4. 实拍资源查询简化

**修改前**：
```python
# 获取项目及其子项目的ID列表
project_ids = await self._get_project_ids(project_id, include_subprojects)
```

**修改后**：
```python
# 获取项目ID列表（仅当前项目）
project_ids = [UUID(project_id)]
```

## 影响评估

### 后端影响
- ✅ **无破坏性变更**：参数已移除，前端需要同步更新
- ✅ **代码更简洁**：减少约 80 行代码
- ✅ **逻辑更清晰**：移除冗余参数，避免混淆

### 前端影响
- ⚠️ **需要同步修改**：前端需要移除 `includeSubprojects` 参数传递
- 影响文件：
  - `client/src/services/api/resource-library.ts`
  - `client/src/mocks/resource-library.ts`

## 迁移指南

### 前端代码修改

**修改前**：
```typescript
// client/src/services/api/resource-library.ts
export interface ResourceLibraryParams {
  search?: string;
  page?: number;
  pageSize?: number;
  includeSubprojects?: boolean;  // ❌ 需要移除
}

const queryParams = {
  search: params.search,
  page: params.page,
  page_size: params.pageSize,
  include_subprojects: params.includeSubprojects,  // ❌ 需要移除
};
```

**修改后**：
```typescript
// client/src/services/api/resource-library.ts
export interface ResourceLibraryParams {
  search?: string;
  page?: number;
  pageSize?: number;
  // includeSubprojects 参数已移除
}

const queryParams = {
  search: params.search,
  page: params.page,
  page_size: params.pageSize,
  // include_subprojects 参数已移除
};
```

## 验证步骤

```bash
# 1. 检查代码语法
docker exec jointo-server-app python -m py_compile app/api/v1/resource_library.py
docker exec jointo-server-app python -m py_compile app/services/resource_library_service.py

# 2. 重启服务验证
docker-compose restart jointo-server-app

# 3. 检查 API 文档
# 访问 http://localhost:8000/docs
# 确认资源库接口不再显示 include_subprojects 参数

# 4. 测试接口
# 使用父项目ID调用
curl -X GET "http://localhost:8000/api/v1/projects/{parent_project_id}/resource-library/characters?page=1&page_size=20"

# 使用子项目ID调用（应自动转换为父项目ID）
curl -X GET "http://localhost:8000/api/v1/projects/{sub_project_id}/resource-library/characters?page=1&page_size=20"
```

## 技术细节

### 资源查询逻辑

**角色/场景/道具**：
```python
# 1. 转换子项目ID为父项目ID
parent_project_id = await project_service.get_parent_project_id(UUID(project_id))

# 2. 直接查询父项目的资源
characters = await character_repo.get_by_project_id(parent_project_id, skip, limit)
```

**实拍资源**：
```python
# 1. 转换子项目ID为父项目ID
parent_project_id = await project_service.get_parent_project_id(UUID(project_id))

# 2. 仅查询当前项目的实拍资源
project_ids = [UUID(parent_project_id)]
stmt = select(ProjectResource).where(
    ProjectResource.project_id.in_(project_ids),
    ProjectResource.type == ResourceType.FOOTAGE,
)
```

### 项目资源继承关系

```
父项目 (parent_project_id = NULL)
├── 角色/场景/道具（存储在父项目级别）
├── 子项目 A (parent_project_id = 父项目ID)
│   └── 自动继承父项目的角色/场景/道具
└── 子项目 B (parent_project_id = 父项目ID)
    └── 自动继承父项目的角色/场景/道具
```

## 相关文档

- [项目元素 parent_id 解析优化](./2026-02-11-project-elements-parent-id-resolution.md)
- [移除未使用的 tags-with-resources 接口](./2026-02-11-remove-unused-tags-with-resources-endpoint.md)