Activepieces 文件夹Folders机制深度解析从 API 到数据模型的轻量级流程组织层【免费下载链接】activepiecesAI Agents MCPs AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows AI Agents • MCPs for AI Agents项目地址: https://gitcode.com/GitHub_Trending/ac/activepieces导读文件夹Folders是 Activepieces 项目中面向流程Flow的轻量级组织层它不参与执行逻辑只负责在 UI 与 API 层面把大量流程按项目project归类、排序与计数帮助用户在复杂的自动化工作区中快速定位。本文基于仓库内 flows-execution/folders 知识文档结合后端 Fastify 插件实现、TypeORM 实体定义、共享类型与前端的 TanStack Query 封装完整讲解文件夹的核心概念、/v1/folders路由契约、upsert/重命名/删除等操作的内部行为以及UncategorizedFolderId等关键陷阱。读完本文你将掌握 Activepieces 文件夹从数据库表到API 响应的完整数据流能够直接对接其 REST 接口也能理解在二次开发或二次封装时需要注意的边界行为。一、文件夹是什么概念与定位在 Activepieces 的项目模型中文件夹是流程的项目内轻量级组织层。它由两个核心属性支撑displayName显示名在每个项目内唯一且唯一性校验是大小写不敏感的displayOrder显示顺序默认值为0用于前端排序展示。流程通过外键folderId挂靠到某个文件夹下文件夹本身没有嵌套层级也没有任何执行语义——它只影响组织与检索不影响流程的运行结果。从源码结构看这一设计刻意保持了轻量文件夹表只包含展示与归属字段没有任何运行时状态字段。涉及的三个主要模块层位置职责后端服务packages/server/api/src/app/flows/folder/模块/控制器、服务层、TypeORM 实体共享类型packages/core/execution/src/lib/flows/folders/Folder、FolderDto、UncategorizedFolderId、请求与列表响应 Schema前端packages/web/src/features/folders/API 客户端、TanStack Query hooks、重命名对话框备注早期版本的共享类型位于packages/core/shared/src/lib/automation/flows/folders/现已迁移至packages/core/execution/src/lib/flows/folders/知识文档于 2026-07-17 核实过路径。阅读旧版代码或社区资料时如遇路径不符以execution包为准。二、实体与数据模型字段、索引与外键Folder 实体的字段定义Folder实体的 TypeORM Schema 位于 folder.entity.ts字段如下字段类型说明idstringapId主键来自BaseColumnSchemaPartdisplayNamestring文件夹显示名项目内大小写不敏感唯一projectIdstringapId所属项目外键指向 project 表displayOrdernumber显示顺序默认0externalIdstring | null外部系统 ID可空用于外部同步场景created/updatedtimestamps由BaseColumnSchemaPart提供共享类型 folder.ts 用 zod 定义了与之一致的FolderSchema并额外声明export const Folder z.object({ ...BaseModelSchema, id: z.string(), projectId: z.string(), displayName: z.string(), displayOrder: z.number(), externalId: Nullable(z.string()), })两个唯一索引实体中定义了两个唯一索引idx_folder_project_id_display_name(projectId, displayName)唯一保证同一项目下不能出现两个同名文件夹配合服务层的大小写不敏感查询实现大小写不敏感唯一idx_folder_project_id_external_id(projectId, externalId)唯一且带WHERE externalId IS NOT NULL部分索引条件专为外部同步见下文upsertByExternalId设计。与项目/流程的关系many-to-one → projectonDelete: CASCADE项目被删除时其文件夹随级联删除外键约束名为fk_folder_projectone-to-many ← flow文件夹与流程是一对多关系逆侧在 flow 实体的folderId字段上flow.entity.ts 中folderId为nullable: true并建有非唯一索引idx_flow_folder_id。注意删除文件夹并不会级联删除流程——因为级联关系只定义在项目→文件夹方向文件夹→流程方向仅是一对多的引用这正是后文Gotchas里要强调的行为。三、FolderDto查询期计算的统计字段FolderDto是 API 对外返回的扩展类型在Folder基础上追加了两个运行时统计字段export type FolderDto Folder { numberOfFlows: number, numberOfTables: number }定义位置有两处、语义一致list-folders-response.ts 与 folder.ts。列表查询相关子查询correlated subqueries在服务层 folder.service.ts 的list()中统计字段通过两条相关子查询逐行计算const queryBuilder folderRepo() .createQueryBuilder(folder) .where(folder.projectId :projectId, { projectId }) .addSelect((subQuery) subQuery .select(COUNT(*)::int) .from(flow, flow) .where(flow.folderId folder.id), numberOfFlows) .addSelect((subQuery) subQuery .select(COUNT(*)::int) .from(table, tbl) .where(tbl.folderId folder.id), numberOfTables)即每个文件夹行都会执行两次COUNT(*)一次统计其下流程数、一次统计其下表格Tables数。这意味着FolderDto中的数字总是查询时实时计算的不落库、不缓存。单条查询并行计数getOneOrThrow()则通过Promise.all并行调用flowService.count()与tableService.count()得到同样的两个数字const [numberOfFlows, numberOfTables] await Promise.all([ flowService(log).count({ projectId, folderId }), tableService.count({ projectId, folderId }), ])两种路径列表、单查分别用 SQL 子查询和业务服务计数实现但对外暴露的FolderDto结构完全一致。另外新建文件夹时upsert真正插入新行直接返回numberOfFlows: 0, numberOfTables: 0避免了插入后的二次计数查询。四、API 路由全解/v1/folders 契约文件夹模块在 folder.module.ts 中以单个 Fastify 插件注册挂载前缀/v1/folders模块与控制器合二为一。所有路由都要求能从 body / query / 实体查询解析出projectId且通过securityAccess.project(...)做项目级授权读写分别要求WRITE_FLOW/READ_FLOW权限允许USER与SERVICE两类主体。方法路径说明权限POST/v1/folders创建upsert 语义WRITE_FLOWPOST/v1/folders/:id重命名WRITE_FLOWGET/v1/folders/:id获取单个文件夹含统计READ_FLOWGET/v1/folders分页列表含统计READ_FLOWDELETE/v1/folders/:id删除文件夹WRITE_FLOW请求 Schema共享类型定义folder-requests.ts 定义了四个请求结构export const CreateFolderRequest z.object({ displayName: z.string(), projectId: z.string(), }) export const UpdateFolderRequest z.object({ displayName: z.string(), }) export const DeleteFolderRequest z.object({ id: z.string(), }) export const ListFolderRequest z.object({ limit: z.coerce.number().optional(), cursor: z.string().optional(), projectId: z.string(), })关键点创建请求体需携带displayName与projectId重命名只需携带新的displayName列表支持limit后端默认分页大小为DEFAULT_PAGE_SIZE 10见 folder.module.ts与基于游标的cursor分页删除请求体携带目标id。列表分页游标 升序list()使用buildPaginator 游标解码paginationHelper.decodeCursor实现基于游标的分页排序方向固定为ASCorder: ASCconst paginator buildPaginator({ entity: FolderEntity, query: { limit, order: ASC, afterCursor: decodedCursor.nextCursor, beforeCursor: decodedCursor.previousCursor, }, })最终通过paginationHelper.createPage(...)包装成SeekPageFolderDto返回。前端 folders-api.ts 在list()中直接传limit: 1000000一次性拉取全部文件夹说明实际场景中文件夹数量通常远小于流程数量。五、核心行为创建即 Upsert、重命名校验与删除语义1. 创建是 Upsert大小写不敏感POST /v1/folders并非简单插入。upsert()的流程是先用LOWER(displayName)做大小写不敏感匹配查询getOneByDisplayNameCaseInsensitiveSQL 为LOWER(folder.displayName) LOWER(:displayName)若已存在同名文件夹 →转为更新直接调用update()改名实际上名字相同即幂等更新若不存在 → 用apId()生成新 ID 插入externalId默认等于自身idawait folderRepo().upsert({ id: folderId, projectId, displayName: request.displayName, externalId: folderId, }, [projectId, displayName])也就是说重复调用创建接口不会产生重复文件夹——同名忽略大小写请求会被合并到既有文件夹上。这与数据库唯一索引idx_folder_project_id_display_name互为双保险。2. 重命名校验允许保留自身名字update()对应POST /v1/folders/:id同样执行大小写不敏感查重但做了关键豁免——如果查到的同名文件夹就是当前文件夹自己则允许通过if (folderWithDisplayName folderWithDisplayName.id ! folderId) { throw new ActivepiecesError({ code: ErrorCode.VALIDATION, params: { message: Folder displayName is used }, }) }这保证了把文件夹改回它自己的名字例如仅大小写变化不会报错同时仍然拦截与其他文件夹重名。失败时返回ErrorCode.VALIDATION400 系错误消息为Folder displayName is used。3. 删除先取全量数据发审计事件再删除DELETE /v1/folders/:id的处理器在删除前先调用getOneOrThrow拿到完整文件夹数据用于发出FOLDER_DELETED审计事件然后再真正删除const folder await folderService(request.log).getOneOrThrow({ projectId, folderId }) applicationEvents(request.log).sendUserEvent(request, { action: ApplicationEventName.FOLDER_DELETED, data: { folder }, }) await folderService(request.log).delete({ projectId, folderId })这样保证审计事件里携带的是删除前的完整快照含numberOfFlows、numberOfTables。六、审计事件FOLDER_CREATED / FOLDER_UPDATED / FOLDER_DELETED三个写操作都会通过applicationEvents(request.log).sendUserEvent(...)发出应用事件操作事件数据载荷创建/合并FOLDER_CREATED完整createdFolder重命名FOLDER_UPDATED完整updatedFlow实际为更新后的 FolderDto删除FOLDER_DELETED删除前抓取的完整文件夹快照事件与路由处理器同处 folder.module.ts创建与更新事件在服务调用成功后、返回响应前发送删除事件则在删除动作之前发送见上文。这些事件可被审计日志、遥测等下游消费。七、关键陷阱Gotchas详解1.UncategorizedFolderId是字符串字面量NULL在共享类型 folder.ts 中export const UncategorizedFolderId NULL这是一个哨兵值sentinel并非数据库中的真实文件夹 ID。流程列表查询在未分类过滤场景下用它匹配folderId IS NULL的流程。调用方如前端列表、API 消费者应把它当作未分类的语义常量而不是一个可 GET 的真实文件夹 ID。2. 删除文件夹不会删除其下流程这是最容易踩的坑删除文件夹后其下流程不会被级联删除也不会被服务层自动置空folderId。由于 flow 实体的folderId可空这些流程会变成未分类状态。从源码看delete()只做folderRepo().delete({ id, projectId })没有任何更新 flow 的逻辑数据库外键方向也没有定义folder → flow的级联。需要清理时应自行在应用层先处理流程归属。3.displayOrder由客户端管理后端不维护displayOrder的排序逻辑也不提供排序接口——排序由前端负责。后端仅在实体层提供默认值0并在upsertByExternalId等同步路径中接受该字段。也就是说通过标准 REST API 创建/重命名文件夹时无法设置displayOrder它属于客户端展示层约定字段。4. 列表固定升序 逐行计数列表接口固定按ASC排序返回numberOfFlows/numberOfTables由相关子查询逐行计算。文件夹数量多、流程/表格量大时列表接口的开销会随行数线性增长这是该实现的可预期成本特征。八、外部同步路径externalId 与 upsertByExternalId除标准 REST 外服务层还暴露了一组面向外部系统同步的方法值得关注upsertByExternalId({ projectId, externalId, displayName, displayOrder })按(projectId, externalId)查找存在则更新displayName与displayOrder不存在则插入新行并保留外部 ID。配合部分唯一索引idx_folder_project_id_external_id实现幂等同步deleteByExternalId({ projectId, externalId })按外部 ID 删除不存在则静默返回isNil(existing)直接returnlistAllByProject({ projectId })返回项目下所有文件夹的裸Folder[]无统计字段。这些方法对应从外部系统导入/回写文件夹结构的场景例如项目导入导出、Git 同步类工具它们绕过了审计事件与 upsert 的显示名校验属于内部/批量路径使用时应自行保证数据一致性。九、前端集成API 客户端与 hooks前端文件夹功能集中在 packages/web/src/features/folders/三个子模块职责清晰api/folders-api.ts封装list/get/create/delete/renameFolder五个方法全部基于api客户端调用/v1/folders其中list()会从authenticationSession.getProjectId()自动注入当前项目 ID并以limit: 1000000拉全量hooks/folders-hooks.ts基于 TanStack Query 的 hooks管理文件夹数据的请求与缓存、失效invalidationscomponents/rename-folder-dialog.tsx重命名对话框对应POST /v1/folders/:id的交互入口。前端只读语义明确重命名走renameFolder(folderId, { displayName })创建走create({ displayName, projectId })与后端请求 Schema 一一对应可直接作为自定义前端集成的参照实现。十、版本与可用性文件夹功能在CE社区版/ EE企业版/ Cloud云版中完全可用无需任何 plan flag 或额外许可。它属于项目内的基础组织能力与 AI 相关、企业级 SSO/RBAC 等受限能力不同任何自托管部署参考 docs/install 的部署方式都可直接使用该模块。十一、二次开发与对接速查综合以上源码分析对接或扩展文件夹功能时可参考以下要点幂等创建POST /v1/folders是 upsert重复创建同名忽略大小写文件夹会返回既有文件夹可用于确保存在类逻辑重命名冲突返回VALIDATION错误消息Folder displayName is used允许保留自身原名未分类语义使用常量UncategorizedFolderId NULL表示无文件夹的流程不要试图对它发起GET /v1/folders/NULL删除副作用删除文件夹不删流程流程转为未分类如需整理需额外处理统计字段numberOfFlows/numberOfTables是查询期计算值列表为相关子查询、单查为并行计数、新建时直接返回 0排序后端列表固定 ASC前端可自行按displayOrder二次排序标准 API 不维护displayOrder审计三个写操作分别产生FOLDER_CREATED/FOLDER_UPDATED/FOLDER_DELETED事件删除事件载荷为删除前快照批量同步如需导入导出文件夹可参考upsertByExternalId/deleteByExternalId的幂等模式与externalId部分唯一索引设计。上述结论均可在 folder.service.ts、folder.module.ts、folder.entity.ts 与 folders 共享类型 中逐一核对可作为后续排障与二次开发的可靠依据。【免费下载链接】activepiecesAI Agents MCPs AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows AI Agents • MCPs for AI Agents项目地址: https://gitcode.com/GitHub_Trending/ac/activepieces创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Activepieces 文件夹（Folders）机制深度解析：从 API 到数据模型的轻量级流程组织层
Activepieces 文件夹Folders机制深度解析从 API 到数据模型的轻量级流程组织层【免费下载链接】activepiecesAI Agents MCPs AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows AI Agents • MCPs for AI Agents项目地址: https://gitcode.com/GitHub_Trending/ac/activepieces导读文件夹Folders是 Activepieces 项目中面向流程Flow的轻量级组织层它不参与执行逻辑只负责在 UI 与 API 层面把大量流程按项目project归类、排序与计数帮助用户在复杂的自动化工作区中快速定位。本文基于仓库内 flows-execution/folders 知识文档结合后端 Fastify 插件实现、TypeORM 实体定义、共享类型与前端的 TanStack Query 封装完整讲解文件夹的核心概念、/v1/folders路由契约、upsert/重命名/删除等操作的内部行为以及UncategorizedFolderId等关键陷阱。读完本文你将掌握 Activepieces 文件夹从数据库表到API 响应的完整数据流能够直接对接其 REST 接口也能理解在二次开发或二次封装时需要注意的边界行为。一、文件夹是什么概念与定位在 Activepieces 的项目模型中文件夹是流程的项目内轻量级组织层。它由两个核心属性支撑displayName显示名在每个项目内唯一且唯一性校验是大小写不敏感的displayOrder显示顺序默认值为0用于前端排序展示。流程通过外键folderId挂靠到某个文件夹下文件夹本身没有嵌套层级也没有任何执行语义——它只影响组织与检索不影响流程的运行结果。从源码结构看这一设计刻意保持了轻量文件夹表只包含展示与归属字段没有任何运行时状态字段。涉及的三个主要模块层位置职责后端服务packages/server/api/src/app/flows/folder/模块/控制器、服务层、TypeORM 实体共享类型packages/core/execution/src/lib/flows/folders/Folder、FolderDto、UncategorizedFolderId、请求与列表响应 Schema前端packages/web/src/features/folders/API 客户端、TanStack Query hooks、重命名对话框备注早期版本的共享类型位于packages/core/shared/src/lib/automation/flows/folders/现已迁移至packages/core/execution/src/lib/flows/folders/知识文档于 2026-07-17 核实过路径。阅读旧版代码或社区资料时如遇路径不符以execution包为准。二、实体与数据模型字段、索引与外键Folder 实体的字段定义Folder实体的 TypeORM Schema 位于 folder.entity.ts字段如下字段类型说明idstringapId主键来自BaseColumnSchemaPartdisplayNamestring文件夹显示名项目内大小写不敏感唯一projectIdstringapId所属项目外键指向 project 表displayOrdernumber显示顺序默认0externalIdstring | null外部系统 ID可空用于外部同步场景created/updatedtimestamps由BaseColumnSchemaPart提供共享类型 folder.ts 用 zod 定义了与之一致的FolderSchema并额外声明export const Folder z.object({ ...BaseModelSchema, id: z.string(), projectId: z.string(), displayName: z.string(), displayOrder: z.number(), externalId: Nullable(z.string()), })两个唯一索引实体中定义了两个唯一索引idx_folder_project_id_display_name(projectId, displayName)唯一保证同一项目下不能出现两个同名文件夹配合服务层的大小写不敏感查询实现大小写不敏感唯一idx_folder_project_id_external_id(projectId, externalId)唯一且带WHERE externalId IS NOT NULL部分索引条件专为外部同步见下文upsertByExternalId设计。与项目/流程的关系many-to-one → projectonDelete: CASCADE项目被删除时其文件夹随级联删除外键约束名为fk_folder_projectone-to-many ← flow文件夹与流程是一对多关系逆侧在 flow 实体的folderId字段上flow.entity.ts 中folderId为nullable: true并建有非唯一索引idx_flow_folder_id。注意删除文件夹并不会级联删除流程——因为级联关系只定义在项目→文件夹方向文件夹→流程方向仅是一对多的引用这正是后文Gotchas里要强调的行为。三、FolderDto查询期计算的统计字段FolderDto是 API 对外返回的扩展类型在Folder基础上追加了两个运行时统计字段export type FolderDto Folder { numberOfFlows: number, numberOfTables: number }定义位置有两处、语义一致list-folders-response.ts 与 folder.ts。列表查询相关子查询correlated subqueries在服务层 folder.service.ts 的list()中统计字段通过两条相关子查询逐行计算const queryBuilder folderRepo() .createQueryBuilder(folder) .where(folder.projectId :projectId, { projectId }) .addSelect((subQuery) subQuery .select(COUNT(*)::int) .from(flow, flow) .where(flow.folderId folder.id), numberOfFlows) .addSelect((subQuery) subQuery .select(COUNT(*)::int) .from(table, tbl) .where(tbl.folderId folder.id), numberOfTables)即每个文件夹行都会执行两次COUNT(*)一次统计其下流程数、一次统计其下表格Tables数。这意味着FolderDto中的数字总是查询时实时计算的不落库、不缓存。单条查询并行计数getOneOrThrow()则通过Promise.all并行调用flowService.count()与tableService.count()得到同样的两个数字const [numberOfFlows, numberOfTables] await Promise.all([ flowService(log).count({ projectId, folderId }), tableService.count({ projectId, folderId }), ])两种路径列表、单查分别用 SQL 子查询和业务服务计数实现但对外暴露的FolderDto结构完全一致。另外新建文件夹时upsert真正插入新行直接返回numberOfFlows: 0, numberOfTables: 0避免了插入后的二次计数查询。四、API 路由全解/v1/folders 契约文件夹模块在 folder.module.ts 中以单个 Fastify 插件注册挂载前缀/v1/folders模块与控制器合二为一。所有路由都要求能从 body / query / 实体查询解析出projectId且通过securityAccess.project(...)做项目级授权读写分别要求WRITE_FLOW/READ_FLOW权限允许USER与SERVICE两类主体。方法路径说明权限POST/v1/folders创建upsert 语义WRITE_FLOWPOST/v1/folders/:id重命名WRITE_FLOWGET/v1/folders/:id获取单个文件夹含统计READ_FLOWGET/v1/folders分页列表含统计READ_FLOWDELETE/v1/folders/:id删除文件夹WRITE_FLOW请求 Schema共享类型定义folder-requests.ts 定义了四个请求结构export const CreateFolderRequest z.object({ displayName: z.string(), projectId: z.string(), }) export const UpdateFolderRequest z.object({ displayName: z.string(), }) export const DeleteFolderRequest z.object({ id: z.string(), }) export const ListFolderRequest z.object({ limit: z.coerce.number().optional(), cursor: z.string().optional(), projectId: z.string(), })关键点创建请求体需携带displayName与projectId重命名只需携带新的displayName列表支持limit后端默认分页大小为DEFAULT_PAGE_SIZE 10见 folder.module.ts与基于游标的cursor分页删除请求体携带目标id。列表分页游标 升序list()使用buildPaginator 游标解码paginationHelper.decodeCursor实现基于游标的分页排序方向固定为ASCorder: ASCconst paginator buildPaginator({ entity: FolderEntity, query: { limit, order: ASC, afterCursor: decodedCursor.nextCursor, beforeCursor: decodedCursor.previousCursor, }, })最终通过paginationHelper.createPage(...)包装成SeekPageFolderDto返回。前端 folders-api.ts 在list()中直接传limit: 1000000一次性拉取全部文件夹说明实际场景中文件夹数量通常远小于流程数量。五、核心行为创建即 Upsert、重命名校验与删除语义1. 创建是 Upsert大小写不敏感POST /v1/folders并非简单插入。upsert()的流程是先用LOWER(displayName)做大小写不敏感匹配查询getOneByDisplayNameCaseInsensitiveSQL 为LOWER(folder.displayName) LOWER(:displayName)若已存在同名文件夹 →转为更新直接调用update()改名实际上名字相同即幂等更新若不存在 → 用apId()生成新 ID 插入externalId默认等于自身idawait folderRepo().upsert({ id: folderId, projectId, displayName: request.displayName, externalId: folderId, }, [projectId, displayName])也就是说重复调用创建接口不会产生重复文件夹——同名忽略大小写请求会被合并到既有文件夹上。这与数据库唯一索引idx_folder_project_id_display_name互为双保险。2. 重命名校验允许保留自身名字update()对应POST /v1/folders/:id同样执行大小写不敏感查重但做了关键豁免——如果查到的同名文件夹就是当前文件夹自己则允许通过if (folderWithDisplayName folderWithDisplayName.id ! folderId) { throw new ActivepiecesError({ code: ErrorCode.VALIDATION, params: { message: Folder displayName is used }, }) }这保证了把文件夹改回它自己的名字例如仅大小写变化不会报错同时仍然拦截与其他文件夹重名。失败时返回ErrorCode.VALIDATION400 系错误消息为Folder displayName is used。3. 删除先取全量数据发审计事件再删除DELETE /v1/folders/:id的处理器在删除前先调用getOneOrThrow拿到完整文件夹数据用于发出FOLDER_DELETED审计事件然后再真正删除const folder await folderService(request.log).getOneOrThrow({ projectId, folderId }) applicationEvents(request.log).sendUserEvent(request, { action: ApplicationEventName.FOLDER_DELETED, data: { folder }, }) await folderService(request.log).delete({ projectId, folderId })这样保证审计事件里携带的是删除前的完整快照含numberOfFlows、numberOfTables。六、审计事件FOLDER_CREATED / FOLDER_UPDATED / FOLDER_DELETED三个写操作都会通过applicationEvents(request.log).sendUserEvent(...)发出应用事件操作事件数据载荷创建/合并FOLDER_CREATED完整createdFolder重命名FOLDER_UPDATED完整updatedFlow实际为更新后的 FolderDto删除FOLDER_DELETED删除前抓取的完整文件夹快照事件与路由处理器同处 folder.module.ts创建与更新事件在服务调用成功后、返回响应前发送删除事件则在删除动作之前发送见上文。这些事件可被审计日志、遥测等下游消费。七、关键陷阱Gotchas详解1.UncategorizedFolderId是字符串字面量NULL在共享类型 folder.ts 中export const UncategorizedFolderId NULL这是一个哨兵值sentinel并非数据库中的真实文件夹 ID。流程列表查询在未分类过滤场景下用它匹配folderId IS NULL的流程。调用方如前端列表、API 消费者应把它当作未分类的语义常量而不是一个可 GET 的真实文件夹 ID。2. 删除文件夹不会删除其下流程这是最容易踩的坑删除文件夹后其下流程不会被级联删除也不会被服务层自动置空folderId。由于 flow 实体的folderId可空这些流程会变成未分类状态。从源码看delete()只做folderRepo().delete({ id, projectId })没有任何更新 flow 的逻辑数据库外键方向也没有定义folder → flow的级联。需要清理时应自行在应用层先处理流程归属。3.displayOrder由客户端管理后端不维护displayOrder的排序逻辑也不提供排序接口——排序由前端负责。后端仅在实体层提供默认值0并在upsertByExternalId等同步路径中接受该字段。也就是说通过标准 REST API 创建/重命名文件夹时无法设置displayOrder它属于客户端展示层约定字段。4. 列表固定升序 逐行计数列表接口固定按ASC排序返回numberOfFlows/numberOfTables由相关子查询逐行计算。文件夹数量多、流程/表格量大时列表接口的开销会随行数线性增长这是该实现的可预期成本特征。八、外部同步路径externalId 与 upsertByExternalId除标准 REST 外服务层还暴露了一组面向外部系统同步的方法值得关注upsertByExternalId({ projectId, externalId, displayName, displayOrder })按(projectId, externalId)查找存在则更新displayName与displayOrder不存在则插入新行并保留外部 ID。配合部分唯一索引idx_folder_project_id_external_id实现幂等同步deleteByExternalId({ projectId, externalId })按外部 ID 删除不存在则静默返回isNil(existing)直接returnlistAllByProject({ projectId })返回项目下所有文件夹的裸Folder[]无统计字段。这些方法对应从外部系统导入/回写文件夹结构的场景例如项目导入导出、Git 同步类工具它们绕过了审计事件与 upsert 的显示名校验属于内部/批量路径使用时应自行保证数据一致性。九、前端集成API 客户端与 hooks前端文件夹功能集中在 packages/web/src/features/folders/三个子模块职责清晰api/folders-api.ts封装list/get/create/delete/renameFolder五个方法全部基于api客户端调用/v1/folders其中list()会从authenticationSession.getProjectId()自动注入当前项目 ID并以limit: 1000000拉全量hooks/folders-hooks.ts基于 TanStack Query 的 hooks管理文件夹数据的请求与缓存、失效invalidationscomponents/rename-folder-dialog.tsx重命名对话框对应POST /v1/folders/:id的交互入口。前端只读语义明确重命名走renameFolder(folderId, { displayName })创建走create({ displayName, projectId })与后端请求 Schema 一一对应可直接作为自定义前端集成的参照实现。十、版本与可用性文件夹功能在CE社区版/ EE企业版/ Cloud云版中完全可用无需任何 plan flag 或额外许可。它属于项目内的基础组织能力与 AI 相关、企业级 SSO/RBAC 等受限能力不同任何自托管部署参考 docs/install 的部署方式都可直接使用该模块。十一、二次开发与对接速查综合以上源码分析对接或扩展文件夹功能时可参考以下要点幂等创建POST /v1/folders是 upsert重复创建同名忽略大小写文件夹会返回既有文件夹可用于确保存在类逻辑重命名冲突返回VALIDATION错误消息Folder displayName is used允许保留自身原名未分类语义使用常量UncategorizedFolderId NULL表示无文件夹的流程不要试图对它发起GET /v1/folders/NULL删除副作用删除文件夹不删流程流程转为未分类如需整理需额外处理统计字段numberOfFlows/numberOfTables是查询期计算值列表为相关子查询、单查为并行计数、新建时直接返回 0排序后端列表固定 ASC前端可自行按displayOrder二次排序标准 API 不维护displayOrder审计三个写操作分别产生FOLDER_CREATED/FOLDER_UPDATED/FOLDER_DELETED事件删除事件载荷为删除前快照批量同步如需导入导出文件夹可参考upsertByExternalId/deleteByExternalId的幂等模式与externalId部分唯一索引设计。上述结论均可在 folder.service.ts、folder.module.ts、folder.entity.ts 与 folders 共享类型 中逐一核对可作为后续排障与二次开发的可靠依据。【免费下载链接】activepiecesAI Agents MCPs AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows AI Agents • MCPs for AI Agents项目地址: https://gitcode.com/GitHub_Trending/ac/activepieces创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考