docs/v1.0/server/changelogs/2026-02-11-resource-library-remove-include-subprojects.md

移除资源库接口 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

修改前：

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,
        ...
    )

修改后：

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. 实拍资源查询简化

修改前：

# 获取项目及其子项目的ID列表
project_ids = await self._get_project_ids(project_id, include_subprojects)

修改后：

# 获取项目ID列表（仅当前项目）
project_ids = [UUID(project_id)]

影响评估

后端影响

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

前端影响

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

迁移指南

前端代码修改

修改前：

// 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,  // ❌ 需要移除
};

修改后：

// 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 参数已移除
};

验证步骤

# 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"

技术细节

资源查询逻辑

角色/场景/道具：

# 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)

实拍资源：

# 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 解析优化
• 移除未使用的 tags-with-resources 接口