# 共享资源选择面板接入真实 API

**日期**：2026-02-08  
**范围**：CreateProjectModal → ResourceSelectorPanel 使用真实接口替代 Mock

---

## 变更概要

- **文件夹/项目树**：使用 `folderApi.getTree()`（GET /folders/tree）拉取树，仅展示「我的项目」(folderCategory=1)，并包装为虚拟根「我的项目」。
- **项目下资源**：展开项目节点时懒加载，调用 `getProjectResources(projectId)`（GET /projects/:id/resources），将角色/场景/道具挂到该节点下。
- **API 路径**：统一 shared-resources 中接口为相对 baseURL（如 `/projects/:id/resources`），与 folderApi、projectApi 一致。

---

## 实现要点

1. **folderApi.getTree**  
   参数：`includeProjects: true`、`includeSubprojects: true`、`includeFullProjectFields: true`。  
   对返回的 `tree` 做顶层过滤：仅保留 `folderCategory === 1` 或 `subproject`，再映射为 `ResourceTreeNode`。项目节点初始 `children` 为空，由懒加载填充。

2. **getProjectResources(projectId, { pageSize: 200 })**  
   用于展开项目时拉取该项目的素材列表。将 `items` 中 `type` 为 character/scene/prop 的项转为树子节点（id=projectResourceId, type, name），不展示 footage。

3. **懒加载与 loading**  
   - 使用 `useQueries` 按「当前已展开的项目 id」批量请求资源。  
   - 合并 `loadedResourcesMap` 与 `baseTree` 得到最终展示树 `treeData`。  
   - 项目节点展开且对应请求未完成时，显示「加载角色/场景/道具...」占位。

4. **类型**  
   - `FolderTreeNode` 增加 `'subproject'`。  
   - `shared-resources` 导出 `ProjectResourceListItem`、`ProjectResourceListResult`，与后端分页列表一致。

---

## 涉及文件

- `client/src/services/api/shared-resources.ts`：修正路径、返回类型，`getProjectResources` 支持 pageSize。
- `client/src/components/features/project/ResourceSelectorPanel.tsx`：移除 Mock，接入 folderApi + getProjectResources，懒加载与 loading 状态。
- `client/src/types/shared-resource.ts`：FolderTreeNode.type 增加 `'subproject'`。

---

## 相关文档

- [2026-02-08-shared-resource-tree-api-analysis.md](./2026-02-08-shared-resource-tree-api-analysis.md)（树接口方案分析）
- [docs/server/guides/cross-project-resource-sharing-persistence.md](../../server/guides/cross-project-resource-sharing-persistence.md)（入库与关联）