@kne/fastify-file-manager 3.0.1-alpha.3 → 3.0.3

package/index.js

@@ -22,6 +22,14 @@ module.exports = fp(
         },
         createAuthenticate: () => {
           return [];
+        },
+        // 文件夹能力依赖 @kne/fastify-group，需先注册；设为 false 可关闭
+        enableFolder: true,
+        groupName: 'group',
+        // 上传自动挂载文件系统时的默认业务域
+        defaultFolderType: 'admin-file-system',
+        getAuthenticate: () => {
+          return [];
         }
       },
       options

package/libs/controllers/index.js

@@ -1,148 +1,568 @@
 const fp = require('fastify-plugin');
 
+const DEFAULT_FOLDER_TYPE = 'admin-file-system';
+
+const readMultipartField = (file, name) => {
+  const field = file?.fields?.[name];
+  if (!field) {
+    return undefined;
+  }
+  const target = Array.isArray(field) ? field[0] : field;
+  return target?.value;
+};
+
+const pickUploadFolderParams = (request, file, defaultType) => {
+  const path =
+    request.query?.path !== undefined
+      ? request.query.path
+      : request.body?.path !== undefined
+        ? request.body.path
+        : readMultipartField(file, 'path');
+  const type =
+    request.query?.type || request.body?.type || readMultipartField(file, 'type') || defaultType || DEFAULT_FOLDER_TYPE;
+  const language = request.query?.language || request.body?.language || readMultipartField(file, 'language');
+  // 未传 path 时挂到根目录
+  return { path: path === undefined ? '' : path, type, language };
+};
+
+const attachUploadedRecord = async ({ services, record, path, type, language }) => {
+  if (!services.folder) {
+    return null;
+  }
+  if (!type) {
+    throw new Error('挂载文件系统时必须传入 type');
+  }
+  const parentId = await services.folder.ensurePath({ type, path, language });
+  return await services.folder.attachRecord({
+    type,
+    parentId,
+    record,
+    language,
+    linked: true
+  });
+};
+
 module.exports = fp(async (fastify, options) => {
   const { services } = fastify.fileManager;
-  fastify.post(`${options.prefix}/upload`, {
-    onRequest: options.createAuthenticate('file:write'), schema: {
-      summary: '上传文件', description: '上传单个文件到服务器或配置的存储服务', query: {
-        type: 'object', properties: {
-          namespace: { type: 'string', description: '文件分类命名空间' }
+  const defaultFolderType = options.defaultFolderType || DEFAULT_FOLDER_TYPE;
+
+  fastify.post(
+    `${options.prefix}/upload`,
+    {
+      onRequest: options.createAuthenticate('file:write'),
+      schema: {
+        summary: '上传文件',
+        description:
+          '上传单个文件到服务器或配置的存储服务。保存成功后自动挂到文件系统（默认 type=admin-file-system，未传 path 时挂到根目录；传 path 则按路径创建并挂载）',
+        query: {
+          type: 'object',
+          properties: {
+            namespace: { type: 'string', description: '文件分类命名空间' },
+            path: {
+              type: 'string',
+              description: '文件系统文件夹路径，如 a/b/c；未传则挂到根目录；路径不存在则自动创建'
+            },
+            type: {
+              type: 'string',
+              description: '文件系统业务域 type，默认 admin-file-system'
+            },
+            language: { type: 'string', description: '语言' }
+          }
         }
       }
+    },
+    async request => {
+      const file = await request.file();
+      if (!file) {
+        throw new Error('不能获取到上传文件');
+      }
+      const record = await services.fileRecord.uploadToFileSystem({
+        file,
+        namespace: request.query.namespace || options.namespace
+      });
+      const { path, type, language } = pickUploadFolderParams(request, file, defaultFolderType);
+      const folder = await attachUploadedRecord({ services, record, path, type, language });
+      return folder ? Object.assign({}, record, { folder }) : record;
     }
-  }, async request => {
-    const file = await request.file();
-    if (!file) {
-      throw new Error('不能获取到上传文件');
+  );
+
+  fastify.post(
+    `${options.prefix}/uploadUrl`,
+    {
+      onRequest: options.createAuthenticate('file:write'),
+      schema: {
+        summary: '上传URL文件',
+        description:
+          '上传单个文件到服务器或配置的存储服务。保存成功后自动挂到文件系统（默认 type=admin-file-system，未传 path 时挂到根目录；传 path 则按路径创建并挂载）',
+        body: {
+          type: 'object',
+          properties: {
+            url: { type: 'string', description: '文件url' },
+            namespace: { type: 'string', description: '文件分类命名空间' },
+            path: {
+              type: 'string',
+              description: '文件系统文件夹路径，如 a/b/c；未传则挂到根目录；路径不存在则自动创建'
+            },
+            type: {
+              type: 'string',
+              description: '文件系统业务域 type，默认 admin-file-system'
+            },
+            language: { type: 'string', description: '语言' }
+          }
+        }
+      }
+    },
+    async request => {
+      const record = await services.fileRecord.uploadFromUrl({
+        url: request.body.url,
+        namespace: request.body.namespace || options.namespace
+      });
+      const { path, type, language } = pickUploadFolderParams(request, null, defaultFolderType);
+      const folder = await attachUploadedRecord({ services, record, path, type, language });
+      return folder ? Object.assign({}, record, { folder }) : record;
     }
-    return await services.fileRecord.uploadToFileSystem({
-      file, namespace: request.query.namespace || options.namespace
-    });
-  });
+  );
 
-  fastify.post(`${options.prefix}/uploadUrl`, {
-    onRequest: options.createAuthenticate('file:write'), schema: {
-      summary: '上传URL文件', description: '上传单个文件到服务器或配置的存储服务', body: {
-        type: 'object', properties: {
-          url: { type: 'string', description: '文件url' },
-          namespace: { type: 'string', description: '文件分类命名空间' }
+  fastify.get(
+    `${options.prefix}/file-url/:id`,
+    {
+      onRequest: options.createAuthenticate('file:read'),
+      schema: {
+        summary: '获取文件url',
+        description: '获取文件url',
+        params: {
+          type: 'object',
+          required: ['id'],
+          properties: {
+            id: { type: 'string', description: '文件id' }
+          }
         }
       }
+    },
+    async request => {
+      const { id } = request.params;
+      return await services.fileRecord.getFileUrl({ id });
     }
-  }, async request => {
-    return await services.fileRecord.uploadFromUrl({
-      url: request.body.url, namespace: request.body.namespace || options.namespace
-    });
-  });
+  );
 
-  fastify.get(`${options.prefix}/file-url/:id`, {
-    onRequest: options.createAuthenticate('file:read'), schema: {
-      summary: '获取文件url', description: '获取文件url', params: {
-        type: 'object', required: ['id'], properties: {
-          id: { type: 'string', description: '文件id' }
+  fastify.get(
+    `${options.prefix}/file-id/:id`,
+    {
+      onRequest: options.createAuthenticate('file:read'),
+      schema: {
+        summary: '获取文件信息',
+        description: '获取文件信息',
+        query: {
+          type: 'object',
+          properties: {
+            attachment: { type: 'boolean', description: '是否下载' },
+            filename: { type: 'string', description: '下载文件名' }
+          }
+        },
+        params: {
+          type: 'object',
+          required: ['id'],
+          properties: {
+            id: { type: 'string', description: '文件id' }
+          }
         }
       }
+    },
+    async (request, reply) => {
+      const { id } = request.params;
+      const { attachment, filename: targetFilename } = request.query;
+      const { filePath, targetFile, filename, mimetype, ...props } = await services.fileRecord.getFileInfo({
+        id
+      });
+      if (targetFile) {
+        const outputFilename = encodeURIComponent(targetFilename || filename);
+        reply.header('Content-Type', mimetype);
+        reply.header('Content-Disposition', attachment ? `attachment; filename="${outputFilename}"` : `filename="${outputFilename}"`);
+        return reply.send(targetFile);
+      }
+      return attachment ? reply.download(filePath, targetFilename || filename) : reply.sendFile(filePath);
     }
-  }, async request => {
-    const { id } = request.params;
-    return await services.fileRecord.getFileUrl({ id });
-  });
+  );
 
-  fastify.get(`${options.prefix}/file-id/:id`, {
-    onRequest: options.createAuthenticate('file:read'), schema: {
-      summary: '获取文件信息', description: '获取文件信息', query: {
-        type: 'object', properties: {
-          attachment: { type: 'boolean', description: '是否下载' },
-          filename: { type: 'string', description: '下载文件名' }
+  fastify.post(
+    `${options.prefix}/file-list`,
+    {
+      onRequest: options.createAuthenticate('file:mange'),
+      schema: {
+        summary: '获取文件列表',
+        description: '查询指定命名空间下的文件列表',
+        body: {
+          type: 'object',
+          properties: {
+            perPage: { type: 'number', description: '每页数量' },
+            currentPage: { type: 'number', description: '当前页数' },
+            filter: {
+              type: 'object',
+              properties: {
+                namespace: { type: 'string', description: '文件分类命名空间' },
+                size: { type: 'array', items: { type: 'number' }, description: '文件大小' },
+                filename: { type: 'string', description: '文件名' }
+              }
+            }
+          }
         }
-      }, params: {
-        type: 'object', required: ['id'], properties: {
-          id: { type: 'string', description: '文件id' }
+      }
+    },
+    async request => {
+      const { filter, perPage, currentPage } = Object.assign(
+        {},
+        {
+          perPage: 20,
+          currentPage: 1
+        },
+        request.body
+      );
+      return await services.fileRecord.getFileList({
+        filter,
+        perPage,
+        currentPage
+      });
+    }
+  );
+
+  // Replace file
+
+  fastify.post(
+    `${options.prefix}/replace-file`,
+    {
+      onRequest: options.createAuthenticate('file:mange'),
+      schema: {
+        summary: '替换文件',
+        description: '替换文件',
+        query: {
+          type: 'object',
+          properties: {
+            id: { type: 'string', description: '文件id' }
+          }
         }
       }
+    },
+    async request => {
+      const file = await request.file();
+      if (!file) {
+        throw new Error('不能获取到上传文件');
+      }
+      return await services.fileRecord.uploadToFileSystem({ id: request.query.id, file });
     }
-  }, async (request, reply) => {
-    const { id } = request.params;
-    const { attachment, filename: targetFilename } = request.query;
-    const { filePath, targetFile, filename, mimetype, ...props } = await services.fileRecord.getFileInfo({
-      id
-    });
-    if (targetFile) {
-      const outputFilename = encodeURIComponent(targetFilename || filename);
-      reply.header('Content-Type', mimetype);
-      reply.header('Content-Disposition', attachment ? `attachment; filename="${outputFilename}"` : `filename="${outputFilename}"`);
-      return reply.send(targetFile);
+  );
+
+  fastify.post(
+    `${options.prefix}/rename-file`,
+    {
+      onRequest: options.createAuthenticate('file:mange'),
+      schema: {
+        summary: '重命名文件',
+        description: '重命名文件',
+        body: {
+          type: 'object',
+          properties: {
+            id: { type: 'string', description: '文件id' },
+            filename: { type: 'string', description: '新文件名' }
+          }
+        }
+      }
+    },
+    async request => {
+      await services.fileRecord.renameFile(request.body);
+      return {};
     }
-    return attachment ? reply.download(filePath, targetFilename || filename) : reply.sendFile(filePath);
-  });
+  );
 
-  fastify.post(`${options.prefix}/file-list`, {
-    onRequest: options.createAuthenticate('file:mange'), schema: {
-      summary: '获取文件列表', description: '查询指定命名空间下的文件列表', body: {
-        type: 'object', properties: {
-          perPage: { type: 'number', description: '每页数量' },
-          currentPage: { type: 'number', description: '当前页数' },
-          filter: {
-            type: 'object', properties: {
-              namespace: { type: 'string', description: '文件分类命名空间' },
-              size: { type: 'array', items: { type: 'number' }, description: '文件大小' },
-              filename: { type: 'string', description: '文件名' }
-            }
+  fastify.post(
+    `${options.prefix}/delete-files`,
+    {
+      onRequest: options.createAuthenticate('file:mange'),
+      schema: {
+        summary: '删除文件',
+        description: '删除文件',
+        body: {
+          type: 'object',
+          required: ['ids'],
+          properties: {
+            ids: { type: 'array', items: { type: 'string' }, description: '文件id列表' }
           }
         }
       }
+    },
+    async request => {
+      const { ids } = request.body;
+      await services.fileRecord.deleteFiles({ ids });
+      return {};
     }
-  }, async request => {
-    const { filter, perPage, currentPage } = Object.assign({}, {
-      perPage: 20, currentPage: 1
-    }, request.body);
-    return await services.fileRecord.getFileList({
-      filter, perPage, currentPage
-    });
-  });
+  );
 
-  // Replace file
+  fastify.post(
+    `${options.prefix}/download-files`,
+    {
+      onRequest: options.createAuthenticate('file:mange'),
+      schema: {
+        summary: '批量下载压缩包',
+        description: '将选中文件打包为 zip 并下载',
+        body: {
+          type: 'object',
+          required: ['ids'],
+          properties: {
+            ids: { type: 'array', items: { type: 'string' }, description: '文件id列表' },
+            filename: { type: 'string', description: '下载压缩包文件名，默认 files.zip' }
+          }
+        }
+      }
+    },
+    async (request, reply) => {
+      const { ids, filename } = request.body;
+      if (!Array.isArray(ids) || ids.length === 0) {
+        throw new Error('请选择要下载的文件');
+      }
+      const compressStream = await services.fileRecord.getCompressFileStream({ ids, type: 'zip' });
+      const outputFilename = encodeURIComponent(filename || 'files.zip');
+      reply.header('Content-Type', 'application/zip');
+      reply.header('Content-Disposition', `attachment; filename="${outputFilename}"`);
+      return reply.send(compressStream);
+    }
+  );
+
+  if (options.enableFolder === false || !services.folder) {
+    return;
+  }
+
+  const getFolderAuthenticate = action => {
+    if (typeof options.getAuthenticate === 'function') {
+      return options.getAuthenticate(action);
+    }
+    return [];
+  };
 
-  fastify.post(`${options.prefix}/replace-file`, {
-    onRequest: options.createAuthenticate('file:mange'), schema: {
-      summary: '替换文件', description: '替换文件', query: {
-        type: 'object', properties: {
-          id: { type: 'string', description: '文件id' }
+  const withDefaultFolderType = source => async request => {
+    const current = request[source] || {};
+    if (!current.type) {
+      request[source] = Object.assign({}, current, { type: defaultFolderType });
+    }
+  };
+
+  const folderOnRequest = (action, source) => {
+    const auth = getFolderAuthenticate(action);
+    const hooks = [withDefaultFolderType(source)].concat(Array.isArray(auth) ? auth : [auth].filter(Boolean));
+    return hooks;
+  };
+
+  fastify.get(
+    `${options.prefix}/folder/tree`,
+    {
+      onRequest: folderOnRequest('read', 'query'),
+      schema: {
+        summary: '获取文件夹树',
+        description: '基于 fastify-group 获取指定 type 的文件树；未传 type 时使用 defaultFolderType',
+        query: {
+          type: 'object',
+          properties: {
+            type: { type: 'string', description: '业务域类型，默认 admin-file-system' },
+            language: { type: 'string', description: '语言' }
+          }
         }
       }
+    },
+    async request => {
+      return await services.folder.getTree(request.query);
     }
-  }, async request => {
-    const file = await request.file();
-    if (!file) {
-      throw new Error('不能获取到上传文件');
+  );
+
+  fastify.post(
+    `${options.prefix}/folder/mkdir`,
+    {
+      onRequest: getFolderAuthenticate('write'),
+      schema: {
+        summary: '新建文件夹',
+        description: '在指定 type 下创建文件夹节点',
+        body: {
+          type: 'object',
+          required: ['type', 'name'],
+          properties: {
+            type: { type: 'string', description: '业务域类型' },
+            name: { type: 'string', description: '文件夹名称' },
+            parentId: { type: 'string', description: '父文件夹 id' },
+            language: { type: 'string', description: '语言' }
+          }
+        }
+      }
+    },
+    async request => {
+      return await services.folder.mkdir(request.body);
     }
-    return await services.fileRecord.uploadToFileSystem({ id: request.query.id, file });
-  });
+  );
 
-  fastify.post(`${options.prefix}/rename-file`, {
-    onRequest: options.createAuthenticate('file:mange'), schema: {
-      summary: '重命名文件', description: '重命名文件', body: {
-        type: 'object', properties: {
-          id: { type: 'string', description: '文件id' }, filename: { type: 'string', description: '新文件名' }
+  fastify.post(
+    `${options.prefix}/folder/upload`,
+    {
+      onRequest: getFolderAuthenticate('write'),
+      schema: {
+        summary: '上传文件到文件夹',
+        description: '上传文件实体并在 group 中创建文件节点',
+        query: {
+          type: 'object',
+          required: ['type'],
+          properties: {
+            type: { type: 'string', description: '业务域类型' },
+            parentId: { type: 'string', description: '父文件夹 id' },
+            namespace: { type: 'string', description: '文件命名空间' },
+            language: { type: 'string', description: '语言' }
+          }
         }
       }
+    },
+    async request => {
+      const file = await request.file();
+      if (!file) {
+        throw new Error('不能获取到上传文件');
+      }
+      return await services.folder.upload({
+        type: request.query.type,
+        parentId: request.query.parentId,
+        namespace: request.query.namespace,
+        language: request.query.language,
+        file
+      });
     }
-  }, async request => {
-    await services.fileRecord.renameFile(request.body);
-    return {};
-  });
+  );
 
-  fastify.post(`${options.prefix}/delete-files`, {
-    onRequest: options.createAuthenticate('file:mange'), schema: {
-      summary: '删除文件', description: '删除文件', body: {
-        type: 'object', required: ['ids'], properties: {
-          ids: { type: 'array', items: { type: 'string' }, description: '文件id列表' }
+  fastify.post(
+    `${options.prefix}/folder/remove`,
+    {
+      onRequest: getFolderAuthenticate('delete'),
+      schema: {
+        summary: '删除文件夹节点',
+        description: '递归删除节点及其子孙；文件节点同步删除 file-record',
+        body: {
+          type: 'object',
+          required: ['type', 'id'],
+          properties: {
+            type: { type: 'string', description: '业务域类型' },
+            id: { type: 'string', description: '节点 id' },
+            language: { type: 'string', description: '语言' }
+          }
         }
       }
+    },
+    async request => {
+      return await services.folder.remove(request.body);
     }
-  }, async request => {
-    const { ids } = request.body;
-    await services.fileRecord.deleteFiles({ ids });
-    return {};
-  });
+  );
+
+  fastify.post(
+    `${options.prefix}/folder/move`,
+    {
+      onRequest: getFolderAuthenticate('write'),
+      schema: {
+        summary: '移动文件夹节点',
+        description: '将一个或多个文件/文件夹节点移动到目标文件夹（parentId 为空表示根目录）',
+        body: {
+          type: 'object',
+          required: ['type', 'ids'],
+          properties: {
+            type: { type: 'string', description: '业务域类型' },
+            ids: {
+              type: 'array',
+              items: { type: 'string' },
+              minItems: 1,
+              description: '要移动的节点 id 列表'
+            },
+            parentId: { type: ['string', 'null'], description: '目标父文件夹 id，空为根目录' },
+            language: { type: 'string', description: '语言' }
+          }
+        }
+      }
+    },
+    async request => {
+      return await services.folder.move(request.body);
+    }
+  );
+
+  fastify.post(
+    `${options.prefix}/folder/copy`,
+    {
+      onRequest: getFolderAuthenticate('write'),
+      schema: {
+        summary: '复制文件夹节点',
+        description:
+          '将一个或多个文件/文件夹节点复制到目标文件夹（parentId 为空表示根目录）；文件以 linked 节点挂载，文件夹递归复制',
+        body: {
+          type: 'object',
+          required: ['type', 'ids'],
+          properties: {
+            type: { type: 'string', description: '业务域类型' },
+            ids: {
+              type: 'array',
+              items: { type: 'string' },
+              minItems: 1,
+              description: '要复制的节点 id 列表'
+            },
+            parentId: { type: ['string', 'null'], description: '目标父文件夹 id，空为根目录' },
+            language: { type: 'string', description: '语言' }
+          }
+        }
+      }
+    },
+    async request => {
+      return await services.folder.copy(request.body);
+    }
+  );
+
+  fastify.post(
+    `${options.prefix}/folder/rename`,
+    {
+      onRequest: getFolderAuthenticate('write'),
+      schema: {
+        summary: '重命名文件夹节点',
+        description: '重命名文件或文件夹节点；文件节点同步更新 file-record 文件名',
+        body: {
+          type: 'object',
+          required: ['type', 'id', 'name'],
+          properties: {
+            type: { type: 'string', description: '业务域类型' },
+            id: { type: 'string', description: '节点 id' },
+            name: { type: 'string', description: '新名称' },
+            language: { type: 'string', description: '语言' }
+          }
+        }
+      }
+    },
+    async request => {
+      return await services.folder.rename(request.body);
+    }
+  );
+
+  fastify.post(
+    `${options.prefix}/folder/add-files`,
+    {
+      onRequest: getFolderAuthenticate('write'),
+      preHandler: withDefaultFolderType('body'),
+      schema: {
+        summary: '将已有文件挂到文件夹树',
+        description:
+          '把文件库中已有文件以 linked 节点形式加入指定文件夹（parentId 为空表示根目录）；删除该类节点不会删除文件库实体；未传 type 时使用 defaultFolderType',
+        body: {
+          type: 'object',
+          required: ['ids'],
+          properties: {
+            type: { type: 'string', description: '业务域类型，默认 admin-file-system' },
+            ids: {
+              type: 'array',
+              items: { type: 'string' },
+              minItems: 1,
+              description: '文件库 file-record id 列表'
+            },
+            parentId: { type: ['string', 'null'], description: '目标父文件夹 id，空为根目录' },
+            language: { type: 'string', description: '语言' }
+          }
+        }
+      }
+    },
+    async request => {
+      return await services.folder.addFiles(request.body);
+    }
+  );
 });

package/libs/services/file-record.js

@@ -15,10 +15,28 @@ module.exports = fp(async (fastify, fastifyOptions) => {
 
   const sanitizeFilename = filename => filename.replace(/[\\/:*?"<>|\0]/g, '_');
 
+  const isUuid = value =>
+    /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(String(value || ''));
+
   const detail = async ({ id, uuid, namespace }) => {
-    const file = await models.fileRecord.findOne({
-      where: { uuid: String(id || uuid).split('?')[0] }
-    });
+    const key = String(id || uuid || '')
+      .split('?')[0]
+      .trim();
+    if (!key) {
+      throw new Error('文件不存在');
+    }
+
+    let file = null;
+    // uuid 列是 UUID 类型：非 uuid 字符串会直接抛 invalid input syntax，不能先查再 fallback
+    if (isUuid(key)) {
+      file = await models.fileRecord.findOne({
+        where: { uuid: key }
+      });
+    }
+    // 兼容历史节点把主键写进 options.fileId / 接口传主键的情况
+    if (!file) {
+      file = await models.fileRecord.findByPk(key);
+    }
 
     if (!file) {
       throw new Error('文件不存在');
@@ -381,15 +399,22 @@ module.exports = fp(async (fastify, fastifyOptions) => {
     await fs.mkdir(tmpPath);
     const files = [];
     for (const file of fileList) {
-      const filepath = path.resolve(tmpPath, file.filename);
-      const writeStream = fs.createWriteStream(filepath);
-      const fileStream = await getFileReadStream(file);
-      fileStream.pipe(writeStream);
-      await new Promise((resolve, reject) => {
-        writeStream.on('finish', resolve);
-        writeStream.on('error', reject);
-      });
-      files.push(filepath);
+      try {
+        const fileStream = await getFileReadStream(file);
+        const filepath = path.resolve(tmpPath, file.filename);
+        const writeStream = fs.createWriteStream(filepath);
+        fileStream.pipe(writeStream);
+        await new Promise((resolve, reject) => {
+          writeStream.on('finish', resolve);
+          writeStream.on('error', reject);
+        });
+        files.push(filepath);
+      } catch (error) {
+        console.warn(`skip invalid file: ${file.uuid}`, error.message);
+      }
+    }
+    if (files.length === 0) {
+      throw new Error('No valid files to compress');
     }
     const compressStream = new compressing[type].Stream();
     files.forEach(filepath => {

package/libs/services/folder.js

@@ -0,0 +1,611 @@
+const fp = require('fastify-plugin');
+
+module.exports = fp(async (fastify, fastifyOptions) => {
+  if (fastifyOptions.enableFolder === false) {
+    return;
+  }
+
+  const groupName = fastifyOptions.groupName || 'group';
+  const group = fastify[groupName];
+  if (!group?.services) {
+    throw new Error(`文件夹功能需要先注册 @kne/fastify-group（fastify.${groupName}）`);
+  }
+
+  const { services } = fastify.fileManager;
+  const groupServices = group.services;
+
+  const getNodeKind = node => {
+    const kind = node?.options?.kind;
+    if (kind === 'file' || kind === 'folder') {
+      return kind;
+    }
+    return node?.options?.fileId ? 'file' : 'folder';
+  };
+
+  const isUuidLike = value =>
+    /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(String(value || ''));
+
+  const resolveRecordFileId = record => {
+    if (!record) {
+      return '';
+    }
+    const uuid = typeof record.getDataValue === 'function' ? record.getDataValue('uuid') : record.uuid;
+    if (uuid) {
+      return String(uuid);
+    }
+    const id = typeof record.getDataValue === 'function' ? record.getDataValue('id') : record.id;
+    return String(id || '');
+  };
+
+  const findChildByName = async ({ type, parentId, name, language, tenantId }) => {
+    const where = Object.assign(
+      { type, parentId: parentId || null, name },
+      language ? { language } : {},
+      tenantId != null ? { tenantId } : {}
+    );
+    const node = await group.models.tag.findOne({ where });
+    return node ? (typeof node.get === 'function' ? node.get({ plain: true }) : node) : null;
+  };
+
+  const assertUniqueSiblingName = async ({ type, parentId, name, language, tenantId, excludeId }) => {
+    const existing = await findChildByName({ type, parentId: parentId || null, name, language, tenantId });
+    if (existing && String(existing.id) !== String(excludeId || '')) {
+      throw new Error(`同一文件夹下已存在同名文件或文件夹：${name}`);
+    }
+  };
+
+  const collectFileIds = nodes => {
+    const ids = [];
+    const walk = list => {
+      (list || []).forEach(node => {
+        const plain = typeof node.get === 'function' ? node.get({ plain: true }) : node;
+        if (getNodeKind(plain) === 'file' && plain.options?.fileId) {
+          ids.push(plain.options.fileId);
+        }
+        if (plain.children?.length) {
+          walk(plain.children);
+        }
+      });
+    };
+    walk(nodes);
+    return ids;
+  };
+
+  const enrichTree = async tree => {
+    const fileIds = collectFileIds(tree);
+    if (fileIds.length === 0) {
+      return tree;
+    }
+
+    const uniqueIds = [...new Set(fileIds.map(String))];
+    const fileMap = new Map();
+    await Promise.all(
+      uniqueIds.map(async id => {
+        try {
+          const file = await services.fileRecord.getFileInstance({ id });
+          fileMap.set(String(id), file);
+        } catch (e) {
+          // 文件记录缺失时仍返回树节点
+        }
+      })
+    );
+
+    const mapNode = node => {
+      const plain = { ...node };
+      const kind = getNodeKind(plain);
+      plain.options = Object.assign({}, plain.options, { kind });
+      if (kind === 'file' && plain.options.fileId) {
+        const file = fileMap.get(String(plain.options.fileId));
+        if (file) {
+          plain.options = Object.assign({}, plain.options, {
+            size: file.size,
+            mimetype: file.mimetype,
+            filename: file.filename
+          });
+          if (file.createdAt) {
+            plain.createdAt = file.createdAt;
+          }
+          if (file.updatedAt) {
+            plain.updatedAt = file.updatedAt;
+          }
+        }
+      }
+      if (plain.children?.length) {
+        plain.children = plain.children.map(mapNode);
+      }
+      return plain;
+    };
+
+    return (tree || []).map(mapNode);
+  };
+
+  const getTree = async ({ type, language, tenantId }) => {
+    if (!type) {
+      throw new Error('必须传入类型');
+    }
+    const tree = await groupServices.groupList({ type, language, output: 'tree', tenantId });
+    return enrichTree(tree);
+  };
+
+  const mkdir = async ({ type, name, parentId, language, tenantId }) => {
+    if (!type) {
+      throw new Error('必须传入类型');
+    }
+    if (!name) {
+      throw new Error('必须传入文件夹名称');
+    }
+    await assertUniqueSiblingName({ type, parentId: parentId || null, name, language, tenantId });
+    const tag = await groupServices.save({
+      type,
+      name,
+      parentId: parentId || null,
+      language,
+      tenantId,
+      options: { kind: 'folder' }
+    });
+    return typeof tag.get === 'function' ? tag.get({ plain: true }) : tag;
+  };
+
+  const upload = async ({ type, parentId, file, namespace, language, tenantId }) => {
+    if (!type) {
+      throw new Error('必须传入类型');
+    }
+    if (!file) {
+      throw new Error('不能获取到上传文件');
+    }
+
+    const targetParentId = parentId || null;
+    await assertUniqueSiblingName({
+      type,
+      parentId: targetParentId,
+      name: file.filename,
+      language,
+      tenantId
+    });
+
+    const record = await services.fileRecord.uploadToFileSystem({
+      file,
+      namespace: namespace || fastifyOptions.namespace
+    });
+
+    const tag = await groupServices.save({
+      type,
+      name: record.filename,
+      parentId: targetParentId,
+      language,
+      tenantId,
+      options: {
+        kind: 'file',
+        fileId: resolveRecordFileId(record),
+        size: record.size,
+        mimetype: record.mimetype
+      }
+    });
+
+    const plain = typeof tag.get === 'function' ? tag.get({ plain: true }) : tag;
+    return Object.assign({}, plain, { file: record });
+  };
+
+  const remove = async ({ type, id, language, tenantId }) => {
+    if (!type) {
+      throw new Error('必须传入类型');
+    }
+    if (!id) {
+      throw new Error('必须传入节点 id');
+    }
+
+    const root = await groupServices.detail({ id, type, language, tenantId });
+    if (!root) {
+      throw new Error('节点不存在');
+    }
+
+    const descendantIds = await groupServices.getDescendantIds({ id, type, language, tenantId });
+    const fileIds = [];
+
+    for (const nodeId of descendantIds) {
+      const node = await groupServices.detail({ id: nodeId, type, language, tenantId });
+      if (!node) {
+        continue;
+      }
+      const plain = typeof node.get === 'function' ? node.get({ plain: true }) : node;
+      // linked 节点只删树，不删文件库实体
+      if (getNodeKind(plain) === 'file' && plain.options?.fileId && plain.options?.linked !== true) {
+        fileIds.push(plain.options.fileId);
+      }
+    }
+
+    if (fileIds.length > 0) {
+      await services.fileRecord.deleteFiles({ ids: [...new Set(fileIds)] });
+    }
+
+    // 先删子孙再删根，避免残留
+    const orderedIds = descendantIds.slice().reverse();
+    for (const nodeId of orderedIds) {
+      await groupServices.remove({ id: nodeId, type, language, tenantId });
+    }
+
+    return {};
+  };
+
+  const move = async ({ type, ids, parentId, language, tenantId }) => {
+    if (!type) {
+      throw new Error('必须传入类型');
+    }
+    const idList = Array.isArray(ids) ? ids.filter(Boolean) : ids ? [ids] : [];
+    if (idList.length === 0) {
+      throw new Error('必须传入节点 id');
+    }
+
+    const targetParentId = parentId || null;
+    if (targetParentId) {
+      const parent = await groupServices.detail({ id: targetParentId, type, language, tenantId });
+      if (!parent) {
+        throw new Error('目标文件夹不存在');
+      }
+      const parentPlain = typeof parent.get === 'function' ? parent.get({ plain: true }) : parent;
+      if (getNodeKind(parentPlain) !== 'folder') {
+        throw new Error('只能移动到文件夹');
+      }
+    }
+
+    const results = [];
+    for (const id of idList) {
+      const node = await groupServices.detail({ id, type, language, tenantId });
+      if (!node) {
+        throw new Error(`节点不存在: ${id}`);
+      }
+      const plain = typeof node.get === 'function' ? node.get({ plain: true }) : node;
+      await assertUniqueSiblingName({
+        type,
+        parentId: targetParentId,
+        name: plain.name,
+        language,
+        tenantId,
+        excludeId: plain.id
+      });
+      const tag = await groupServices.save({
+        id,
+        type,
+        parentId: targetParentId,
+        language,
+        tenantId
+      });
+      results.push(typeof tag.get === 'function' ? tag.get({ plain: true }) : tag);
+    }
+    return results;
+  };
+
+  const listDirectChildren = async ({ type, parentId, language, tenantId }) => {
+    const where = Object.assign(
+      { type, parentId: parentId || null },
+      language ? { language } : {},
+      tenantId != null ? { tenantId } : {}
+    );
+    const rows = await group.models.tag.findAll({ where });
+    return rows.map(item => (typeof item.get === 'function' ? item.get({ plain: true }) : item));
+  };
+
+  const copyNodeRecursive = async ({ type, sourceId, parentId, language, tenantId }) => {
+    const node = await groupServices.detail({ id: String(sourceId), type, language, tenantId });
+    if (!node) {
+      throw new Error(`节点不存在: ${sourceId}`);
+    }
+    const plain = typeof node.get === 'function' ? node.get({ plain: true }) : node;
+    await assertUniqueSiblingName({
+      type,
+      parentId: parentId || null,
+      name: plain.name,
+      language,
+      tenantId
+    });
+
+    if (getNodeKind(plain) === 'folder') {
+      const created = await mkdir({
+        type,
+        name: plain.name,
+        parentId: parentId || null,
+        language,
+        tenantId
+      });
+      const children = await listDirectChildren({ type, parentId: plain.id, language, tenantId });
+      for (const child of children) {
+        await copyNodeRecursive({
+          type,
+          sourceId: child.id,
+          parentId: created.id,
+          language,
+          tenantId
+        });
+      }
+      return created;
+    }
+
+    const fileId = plain.options?.fileId;
+    if (!fileId) {
+      throw new Error(`文件节点缺少 fileId: ${plain.name}`);
+    }
+    const tag = await groupServices.save({
+      type,
+      name: plain.name,
+      parentId: parentId || null,
+      language,
+      tenantId,
+      options: {
+        kind: 'file',
+        fileId,
+        size: plain.options?.size,
+        mimetype: plain.options?.mimetype,
+        linked: true
+      }
+    });
+    return typeof tag.get === 'function' ? tag.get({ plain: true }) : tag;
+  };
+
+  const copy = async ({ type, ids, parentId, language, tenantId }) => {
+    if (!type) {
+      throw new Error('必须传入类型');
+    }
+    const idList = Array.isArray(ids) ? ids.filter(Boolean) : ids ? [ids] : [];
+    if (idList.length === 0) {
+      throw new Error('必须传入节点 id');
+    }
+
+    const targetParentId = parentId || null;
+    if (targetParentId) {
+      const parent = await groupServices.detail({ id: targetParentId, type, language, tenantId });
+      if (!parent) {
+        throw new Error('目标文件夹不存在');
+      }
+      const parentPlain = typeof parent.get === 'function' ? parent.get({ plain: true }) : parent;
+      if (getNodeKind(parentPlain) !== 'folder') {
+        throw new Error('只能复制到文件夹');
+      }
+    }
+
+    const results = [];
+    for (const id of idList) {
+      if (targetParentId) {
+        const descendantIds = await groupServices.getDescendantIds({
+          id: String(id),
+          type,
+          language,
+          tenantId
+        });
+        if (descendantIds.map(String).includes(String(targetParentId))) {
+          throw new Error('不能复制到自身或其子文件夹');
+        }
+      }
+      results.push(
+        await copyNodeRecursive({
+          type,
+          sourceId: id,
+          parentId: targetParentId,
+          language,
+          tenantId
+        })
+      );
+    }
+    return results;
+  };
+
+  const rename = async ({ type, id, name, language, tenantId }) => {
+    if (!type) {
+      throw new Error('必须传入类型');
+    }
+    if (!id) {
+      throw new Error('必须传入节点 id');
+    }
+    if (!name) {
+      throw new Error('必须传入名称');
+    }
+
+    const node = await groupServices.detail({ id: String(id), type, language, tenantId });
+    if (!node) {
+      throw new Error('节点不存在');
+    }
+    const plain = typeof node.get === 'function' ? node.get({ plain: true }) : node;
+    await assertUniqueSiblingName({
+      type,
+      parentId: plain.parentId || null,
+      name,
+      language,
+      tenantId,
+      excludeId: plain.id
+    });
+    // 直接 update，避免 group.save 在查不到 id 时误走创建
+    await node.update({ name });
+    const tag = await groupServices.detail({ id: String(id), type, language, tenantId });
+
+    // linked 节点只改树显示名，不改文件库实体
+    if (getNodeKind(plain) === 'file' && plain.options?.fileId && plain.options?.linked !== true) {
+      try {
+        await services.fileRecord.renameFile({ id: plain.options.fileId, filename: name });
+      } catch (e) {
+        // 树节点已改名；文件记录缺失时不阻断
+      }
+    }
+
+    return typeof tag.get === 'function' ? tag.get({ plain: true }) : tag || Object.assign({}, plain, { name });
+  };
+
+  const normalizePathSegments = folderPath =>
+    String(folderPath || '')
+      .replace(/\\/g, '/')
+      .split('/')
+      .map(segment => segment.trim())
+      .filter(segment => segment && segment !== '.' && segment !== '..');
+
+  /**
+   * 按路径逐级确保文件夹存在（不存在则创建），返回叶子文件夹 id；空路径返回 null（根目录）
+   */
+  const ensurePath = async ({ type, path: folderPath, language, tenantId }) => {
+    if (!type) {
+      throw new Error('必须传入类型');
+    }
+    const segments = normalizePathSegments(folderPath);
+    let parentId = null;
+    for (const name of segments) {
+      const existing = await findChildByName({ type, parentId, name, language, tenantId });
+      if (existing) {
+        if (getNodeKind(existing) !== 'folder') {
+          throw new Error(`路径冲突：${name} 不是文件夹`);
+        }
+        parentId = existing.id;
+        continue;
+      }
+      const created = await mkdir({ type, name, parentId, language, tenantId });
+      parentId = created.id;
+    }
+    return parentId;
+  };
+
+  /**
+   * 将已上传的文件记录挂到文件夹树（默认 linked，删除树节点不删文件实体）
+   */
+  const attachRecord = async ({ type, parentId, record, language, tenantId, linked = true }) => {
+    if (!type) {
+      throw new Error('必须传入类型');
+    }
+    if (!record) {
+      throw new Error('必须传入文件记录');
+    }
+    const targetParentId = parentId || null;
+    if (targetParentId) {
+      const parent = await groupServices.detail({ id: targetParentId, type, language, tenantId });
+      if (!parent) {
+        throw new Error('目标文件夹不存在');
+      }
+      const parentPlain = typeof parent.get === 'function' ? parent.get({ plain: true }) : parent;
+      if (getNodeKind(parentPlain) !== 'folder') {
+        throw new Error('只能加入到文件夹');
+      }
+    }
+
+    const linkedFileId = resolveRecordFileId(record);
+    const siblingWhere = Object.assign(
+      { type, parentId: targetParentId },
+      language ? { language } : {},
+      tenantId != null ? { tenantId } : {}
+    );
+    const siblings = await group.models.tag.findAll({ where: siblingWhere });
+    const alreadyMounted = siblings.some(item => {
+      const plain = typeof item.get === 'function' ? item.get({ plain: true }) : item;
+      return getNodeKind(plain) === 'file' && String(plain.options?.fileId) === linkedFileId;
+    });
+    if (alreadyMounted) {
+      return null;
+    }
+
+    await assertUniqueSiblingName({
+      type,
+      parentId: targetParentId,
+      name: record.filename,
+      language,
+      tenantId
+    });
+
+    const tag = await groupServices.save({
+      type,
+      name: record.filename,
+      parentId: targetParentId,
+      language,
+      tenantId,
+      options: {
+        kind: 'file',
+        fileId: linkedFileId,
+        size: record.size,
+        mimetype: record.mimetype,
+        ...(linked ? { linked: true } : {})
+      }
+    });
+    return typeof tag.get === 'function' ? tag.get({ plain: true }) : tag;
+  };
+
+  const addFiles = async ({ type, parentId, ids, language, tenantId }) => {
+    if (!type) {
+      throw new Error('必须传入类型');
+    }
+    const idList = [...new Set((Array.isArray(ids) ? ids : ids ? [ids] : []).filter(Boolean).map(String))];
+    if (idList.length === 0) {
+      throw new Error('必须传入文件 id');
+    }
+
+    const targetParentId = parentId || null;
+    if (targetParentId) {
+      const parent = await groupServices.detail({ id: targetParentId, type, language, tenantId });
+      if (!parent) {
+        throw new Error('目标文件夹不存在');
+      }
+      const parentPlain = typeof parent.get === 'function' ? parent.get({ plain: true }) : parent;
+      if (getNodeKind(parentPlain) !== 'folder') {
+        throw new Error('只能加入到文件夹');
+      }
+    }
+
+    // 同目录下已挂载的 fileId（兼容历史存主键的数据）
+    const siblingWhere = Object.assign(
+      { type, parentId: targetParentId },
+      language ? { language } : {},
+      tenantId != null ? { tenantId } : {}
+    );
+    const siblings = await group.models.tag.findAll({ where: siblingWhere });
+    const existingFileIds = new Set();
+    const existingNames = new Set();
+    siblings.forEach(item => {
+      const plain = typeof item.get === 'function' ? item.get({ plain: true }) : item;
+      if (plain.name) {
+        existingNames.add(String(plain.name));
+      }
+      if (getNodeKind(plain) === 'file' && plain.options?.fileId != null) {
+        existingFileIds.add(String(plain.options.fileId));
+      }
+    });
+
+    const results = [];
+    for (const fileId of idList) {
+      const record = await services.fileRecord.getFileInstance({ id: fileId });
+      // 列表入参多为 uuid；若是历史主键则从记录上取 uuid，禁止把雪花主键写入 options.fileId
+      const linkedFileId = isUuidLike(fileId) ? String(fileId) : resolveRecordFileId(record);
+      // 已在目标目录则跳过，避免重复挂载
+      if (existingFileIds.has(linkedFileId) || existingFileIds.has(String(record.id)) || existingFileIds.has(String(fileId))) {
+        continue;
+      }
+      if (existingNames.has(String(record.filename))) {
+        throw new Error(`同一文件夹下已存在同名文件或文件夹：${record.filename}`);
+      }
+      const tag = await groupServices.save({
+        type,
+        name: record.filename,
+        parentId: targetParentId,
+        language,
+        tenantId,
+        options: {
+          kind: 'file',
+          fileId: linkedFileId,
+          size: record.size,
+          mimetype: record.mimetype,
+          linked: true
+        }
+      });
+      existingFileIds.add(linkedFileId);
+      existingNames.add(String(record.filename));
+      results.push(typeof tag.get === 'function' ? tag.get({ plain: true }) : tag);
+    }
+    return results;
+  };
+
+  Object.assign(services, {
+    folder: {
+      getTree,
+      mkdir,
+      upload,
+      remove,
+      move,
+      copy,
+      rename,
+      addFiles,
+      ensurePath,
+      attachRecord
+    }
+  });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kne/fastify-file-manager",
-  "version": "3.0.1-alpha.3",
+  "version": "3.0.3",
   "description": "用于管理静态文件上传查看等",
   "main": "index.js",
   "scripts": {
@@ -35,7 +35,8 @@
   "devDependencies": {
     "@fastify/env": "^5.0.2",
     "@kne/fastify-aliyun": "^1.1.1",
-    "@kne/fastify-sequelize": "^2.0.1",
+    "@kne/fastify-group": "^0.2.5",
+    "@kne/fastify-sequelize": "^3.2.0",
     "fastify": "^5.3.2",
     "husky": "^9.0.11",
     "mocha": "^11.7.5",
@@ -44,6 +45,7 @@
     "sqlite3": "^5.1.7"
   },
   "peerDependencies": {
+    "@kne/fastify-group": "*",
     "@kne/fastify-namespace": "*",
     "@kne/fastify-sequelize": "*",
     "fastify-plugin": ">=5"