@kne/fastify-file-manager 3.0.7 → 3.0.9

package/libs/controllers/index.js

@@ -1,7 +1,23 @@
 const fp = require('fastify-plugin');
+const { num, list, success, empty, fileRecordProperties, fileRecord, folderNode, folderTreeNode } = require('../schema/response');
 
 const DEFAULT_FOLDER_TYPE = 'admin-file-system';
 
+const TAG_FILE = '文件管理-文件';
+const TAG_LIBRARY = '文件管理-文件库';
+const TAG_FOLDER = '文件管理-文件夹';
+
+const uploadedRecord = description =>
+  success(description, {
+    type: 'object',
+    additionalProperties: true,
+    properties: Object.assign({}, fileRecordProperties, {
+      folder: Object.assign({}, folderNode, { description: '自动挂载到文件系统生成的文件节点；同目录已挂载同一文件时不重复挂载，此时无该字段' })
+    })
+  });
+
+const TENANT_ID = '租户 ID；接口不校验，按原样传给文件夹服务用于隔离不同租户的树（通常由宿主鉴权钩子注入）';
+
 const readMultipartField = (file, name) => {
   const field = file?.fields?.[name];
   if (!field) {
@@ -51,9 +67,10 @@ module.exports = fp(async (fastify, options) => {
     {
       onRequest: options.createAuthenticate('file:write'),
       schema: {
+        tags: [TAG_FILE],
         summary: '上传文件',
         description:
-          '上传单个文件到服务器或配置的存储服务。保存成功后自动挂到文件系统（默认 type=admin-file-system，未传 path 时挂到根目录；传 path 则按路径创建并挂载）',
+          '上传单个文件到服务器或配置的存储服务。保存成功后自动挂到文件系统（默认 type=admin-file-system，未传 path 时挂到根目录；传 path 则按路径创建并挂载）。请求为 multipart/form-data，文件字段名为 file；path、type、language 也可作为表单字段传入（query 优先）',
         query: {
           type: 'object',
           properties: {
@@ -68,7 +85,8 @@ module.exports = fp(async (fastify, options) => {
             },
             language: { type: 'string', description: '语言' }
           }
-        }
+        },
+        response: uploadedRecord('上传后的文件记录，挂载到文件系统时带 folder')
       }
     },
     async request => {
@@ -91,13 +109,14 @@ module.exports = fp(async (fastify, options) => {
     {
       onRequest: options.createAuthenticate('file:write'),
       schema: {
+        tags: [TAG_FILE],
         summary: '上传URL文件',
         description:
-          '上传单个文件到服务器或配置的存储服务。保存成功后自动挂到文件系统（默认 type=admin-file-system，未传 path 时挂到根目录；传 path 则按路径创建并挂载）',
+          '服务端下载 url 指向的文件并保存到服务器或配置的存储服务，文件名优先取 url 的 filename 参数，其次响应头 Content-Disposition，再次 url 路径末段。保存成功后自动挂到文件系统（默认 type=admin-file-system，未传 path 时挂到根目录；传 path 则按路径创建并挂载）',
         body: {
           type: 'object',
           properties: {
-            url: { type: 'string', description: '文件url' },
+            url: { type: 'string', description: '文件url，服务端会发起下载，下载失败返回错误' },
             namespace: { type: 'string', description: '文件分类命名空间' },
             path: {
               type: 'string',
@@ -109,7 +128,8 @@ module.exports = fp(async (fastify, options) => {
             },
             language: { type: 'string', description: '语言' }
           }
-        }
+        },
+        response: uploadedRecord('保存后的文件记录，挂载到文件系统时带 folder')
       }
     },
     async request => {
@@ -128,14 +148,18 @@ module.exports = fp(async (fastify, options) => {
     {
       onRequest: options.createAuthenticate('file:read'),
       schema: {
+        tags: [TAG_FILE],
         summary: '获取文件url',
-        description: '获取文件url',
+        description: '获取文件访问地址：本地存储返回 {prefix}/file/{hash}{扩展名}?filename={文件名}（本地文件不存在返回 404），OSS 存储返回 ossAdapter.getFileLink 的结果',
         params: {
           type: 'object',
           required: ['id'],
           properties: {
-            id: { type: 'string', description: '文件id' }
+            id: { type: 'string', description: '文件id（uuid，兼容主键）' }
           }
+        },
+        response: {
+          200: { description: '文件访问地址；本地存储时为 text/plain 字符串' }
         }
       }
     },
@@ -150,21 +174,25 @@ module.exports = fp(async (fastify, options) => {
     {
       onRequest: options.createAuthenticate('file:read'),
       schema: {
+        tags: [TAG_FILE],
         summary: '获取文件信息',
-        description: '获取文件信息',
+        description: '直接输出文件内容（非 JSON）：OSS 存储下载后按原 MIME 类型返回；本地存储通过静态文件服务返回。attachment 为 true 时以附件形式下载',
         query: {
           type: 'object',
           properties: {
-            attachment: { type: 'boolean', description: '是否下载' },
-            filename: { type: 'string', description: '下载文件名' }
+            attachment: { type: 'boolean', description: '是否下载（Content-Disposition: attachment）' },
+            filename: { type: 'string', description: '下载文件名，默认原文件名' }
           }
         },
         params: {
           type: 'object',
           required: ['id'],
           properties: {
-            id: { type: 'string', description: '文件id' }
+            id: { type: 'string', description: '文件id（uuid，兼容主键）' }
           }
+        },
+        response: {
+          200: { description: '文件二进制内容，Content-Type 为文件 MIME 类型' }
         }
       }
     },
@@ -189,23 +217,36 @@ module.exports = fp(async (fastify, options) => {
     {
       onRequest: options.createAuthenticate('file:mange'),
       schema: {
+        tags: [TAG_LIBRARY],
         summary: '获取文件列表',
-        description: '查询指定命名空间下的文件列表',
+        description: '分页查询文件库，按创建时间倒序',
         body: {
           type: 'object',
           properties: {
-            perPage: { type: 'number', description: '每页数量' },
-            currentPage: { type: 'number', description: '当前页数' },
+            perPage: { type: 'number', description: '每页数量，默认 20' },
+            currentPage: { type: 'number', description: '当前页数，默认 1' },
             filter: {
               type: 'object',
+              description: '筛选条件',
               properties: {
-                namespace: { type: 'string', description: '文件分类命名空间' },
-                size: { type: 'array', items: { type: 'number' }, description: '文件大小' },
-                filename: { type: 'string', description: '文件名' }
+                id: { description: '按文件 uuid 精确匹配' },
+                namespace: { type: 'string', description: '文件分类命名空间，模糊匹配' },
+                size: { type: 'array', items: { type: 'number' }, description: '文件大小范围 [最小, 最大]，单位 KB，0 或空表示不限' },
+                filename: { type: 'string', description: '文件名，模糊匹配' },
+                createdAt: { description: '创建时间范围，形如 { startTime, endTime }，可只传其一' },
+                updatedAt: { description: '更新时间范围，形如 { startTime, endTime }，可只传其一' }
               }
             }
           }
-        }
+        },
+        response: success('文件分页列表', {
+          type: 'object',
+          additionalProperties: true,
+          properties: {
+            pageData: list('当前页文件列表', fileRecord),
+            totalCount: num('符合条件的文件总数')
+          }
+        })
       }
     },
     async request => {
@@ -232,14 +273,16 @@ module.exports = fp(async (fastify, options) => {
     {
       onRequest: options.createAuthenticate('file:mange'),
       schema: {
+        tags: [TAG_LIBRARY],
         summary: '替换文件',
-        description: '替换文件',
+        description: '用上传的新文件（multipart/form-data，字段名 file）覆盖指定文件记录的内容与文件名，文件 id 不变；未传 id 时新建文件记录。不会挂载到文件系统',
         query: {
           type: 'object',
           properties: {
-            id: { type: 'string', description: '文件id' }
+            id: { type: 'string', description: '要替换的文件id（uuid，兼容主键）' }
           }
-        }
+        },
+        response: success('替换后的文件记录', fileRecord)
       }
     },
     async request => {
@@ -256,15 +299,17 @@ module.exports = fp(async (fastify, options) => {
     {
       onRequest: options.createAuthenticate('file:mange'),
       schema: {
+        tags: [TAG_LIBRARY],
         summary: '重命名文件',
-        description: '重命名文件',
+        description: '修改文件记录的文件名；新文件名无扩展名时沿用原扩展名，非法字符替换为下划线',
         body: {
           type: 'object',
           properties: {
-            id: { type: 'string', description: '文件id' },
+            id: { type: 'string', description: '文件id（uuid，兼容主键）' },
             filename: { type: 'string', description: '新文件名' }
           }
-        }
+        },
+        response: empty('重命名成功')
       }
     },
     async request => {
@@ -278,15 +323,17 @@ module.exports = fp(async (fastify, options) => {
     {
       onRequest: options.createAuthenticate('file:mange'),
       schema: {
+        tags: [TAG_LIBRARY],
         summary: '删除文件',
-        description: '删除文件',
+        description: '按 uuid 删除文件记录（不删除存储中的文件实体，也不删除文件夹树中引用它的节点）',
         body: {
           type: 'object',
           required: ['ids'],
           properties: {
-            ids: { type: 'array', items: { type: 'string' }, description: '文件id列表' }
+            ids: { type: 'array', items: { type: 'string' }, description: '文件id（uuid）列表' }
           }
-        }
+        },
+        response: empty('删除成功')
       }
     },
     async request => {
@@ -301,15 +348,19 @@ module.exports = fp(async (fastify, options) => {
     {
       onRequest: options.createAuthenticate('file:mange'),
       schema: {
+        tags: [TAG_LIBRARY],
         summary: '批量下载压缩包',
-        description: '将选中文件打包为 zip 并下载',
+        description: '将选中文件打包为 zip 并下载；无效文件会被跳过，全部无效时返回错误',
         body: {
           type: 'object',
           required: ['ids'],
           properties: {
-            ids: { type: 'array', items: { type: 'string' }, description: '文件id列表' },
+            ids: { type: 'array', items: { type: 'string' }, description: '文件id（uuid）列表' },
             filename: { type: 'string', description: '下载压缩包文件名，默认 files.zip' }
           }
+        },
+        response: {
+          200: { description: 'zip 压缩包文件流，Content-Type 为 application/zip，以附件形式下载' }
         }
       }
     },
@@ -355,16 +406,19 @@ module.exports = fp(async (fastify, options) => {
     {
       onRequest: folderOnRequest('read', 'query'),
       schema: {
+        tags: [TAG_FOLDER],
         summary: '获取文件夹树',
-        description: '获取指定 type 的文件树；kind=folder 时仅返回文件夹节点；未传 type 时使用 defaultFolderType',
+        description: '获取指定 type 的文件树；kind=folder 时仅返回文件夹节点；未传 type 时使用 defaultFolderType。文件节点会补充文件记录的 size、mimetype、filename 与时间',
         query: {
           type: 'object',
           properties: {
             type: { type: 'string', description: '业务域类型，默认 admin-file-system' },
             language: { type: 'string', description: '语言' },
-            kind: { type: 'string', description: '传 folder 时仅返回文件夹树' }
+            kind: { type: 'string', description: '传 folder（或 foldersOnly）时仅返回文件夹树' },
+            tenantId: { description: TENANT_ID }
           }
-        }
+        },
+        response: success('根节点列表，子节点在 children 中', { type: 'array', items: folderTreeNode })
       }
     },
     async request => {
@@ -377,8 +431,9 @@ module.exports = fp(async (fastify, options) => {
     {
       onRequest: folderOnRequest('read', 'body'),
       schema: {
+        tags: [TAG_FOLDER],
         summary: '分页获取目录子节点',
-        description: '按 parentId 分页列出直接子节点；文件夹优先，再按名称排序；未传 type 时使用 defaultFolderType',
+        description: '按 parentId 分页列出直接子节点；文件夹优先，再按名称排序；未传 type 时使用 defaultFolderType。perPage 最大 200',
         body: {
           type: 'object',
           properties: {
@@ -389,7 +444,15 @@ module.exports = fp(async (fastify, options) => {
             keyword: { type: 'string', description: '按名称模糊搜索' },
             language: { type: 'string', description: '语言' }
           }
-        }
+        },
+        response: success('子节点分页列表', {
+          type: 'object',
+          additionalProperties: true,
+          properties: {
+            pageData: list('当前页子节点列表', folderNode),
+            totalCount: num('直接子节点总数')
+          }
+        })
       }
     },
     async request => {
@@ -417,18 +480,21 @@ module.exports = fp(async (fastify, options) => {
     {
       onRequest: getFolderAuthenticate('write'),
       schema: {
+        tags: [TAG_FOLDER],
         summary: '新建文件夹',
-        description: '在指定 type 下创建文件夹节点',
+        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: '语言' }
+            parentId: { type: 'string', description: '父文件夹 id，不传为根目录' },
+            language: { type: 'string', description: '语言' },
+            tenantId: { description: TENANT_ID }
           }
-        }
+        },
+        response: success('创建的文件夹节点', folderNode)
       }
     },
     async request => {
@@ -441,8 +507,9 @@ module.exports = fp(async (fastify, options) => {
     {
       onRequest: getFolderAuthenticate('write'),
       schema: {
+        tags: [TAG_FOLDER],
         summary: '上传文件到文件夹',
-        description: '上传文件实体并在 group 中创建文件节点。通过 path 定位目标目录（经 ensurePath 解析/创建；空字符串为根目录）',
+        description: '上传文件实体（multipart/form-data，字段名 file）并在 group 中创建文件节点。通过 path 定位目标目录（经 ensurePath 解析/创建；空字符串为根目录）；同目录重名时文件名自动追加 [_时间戳]',
         query: {
           type: 'object',
           required: ['type'],
@@ -452,7 +519,8 @@ module.exports = fp(async (fastify, options) => {
             namespace: { type: 'string', description: '文件命名空间' },
             language: { type: 'string', description: '语言' }
           }
-        }
+        },
+        response: success('创建的文件节点，file 为上传的文件记录', Object.assign({}, folderNode, { properties: Object.assign({}, folderNode.properties, { file: fileRecord }) }))
       }
     },
     async request => {
@@ -475,17 +543,20 @@ module.exports = fp(async (fastify, options) => {
     {
       onRequest: getFolderAuthenticate('delete'),
       schema: {
+        tags: [TAG_FOLDER],
         summary: '删除文件夹节点',
-        description: '递归删除节点及其子孙；文件节点同步删除 file-record',
+        description: '递归删除节点及其子孙；文件节点同步删除 file-record（linked 引用节点只删树节点，不删文件记录）',
         body: {
           type: 'object',
           required: ['type', 'id'],
           properties: {
             type: { type: 'string', description: '业务域类型' },
             id: { type: 'string', description: '节点 id' },
-            language: { type: 'string', description: '语言' }
+            language: { type: 'string', description: '语言' },
+            tenantId: { description: TENANT_ID }
           }
-        }
+        },
+        response: empty('删除成功')
       }
     },
     async request => {
@@ -498,8 +569,9 @@ module.exports = fp(async (fastify, options) => {
     {
       onRequest: getFolderAuthenticate('write'),
       schema: {
+        tags: [TAG_FOLDER],
         summary: '移动文件夹节点',
-        description: '将一个或多个文件/文件夹节点移动到目标文件夹（parentId 为空表示根目录）',
+        description: '将一个或多个文件/文件夹节点移动到目标文件夹（parentId 为空表示根目录）；目标须为文件夹，目标下重名返回错误',
         body: {
           type: 'object',
           required: ['type', 'ids'],
@@ -512,9 +584,11 @@ module.exports = fp(async (fastify, options) => {
               description: '要移动的节点 id 列表'
             },
             parentId: { type: ['string', 'null'], description: '目标父文件夹 id，空为根目录' },
-            language: { type: 'string', description: '语言' }
+            language: { type: 'string', description: '语言' },
+            tenantId: { description: TENANT_ID }
           }
-        }
+        },
+        response: success('移动后的节点列表', { type: 'array', items: folderNode })
       }
     },
     async request => {
@@ -527,6 +601,7 @@ module.exports = fp(async (fastify, options) => {
     {
       onRequest: getFolderAuthenticate('write'),
       schema: {
+        tags: [TAG_FOLDER],
         summary: '复制文件夹节点',
         description:
           '将一个或多个文件/文件夹节点复制到目标文件夹（parentId 为空表示根目录）；文件以 linked 节点挂载，文件夹递归复制',
@@ -542,9 +617,11 @@ module.exports = fp(async (fastify, options) => {
               description: '要复制的节点 id 列表'
             },
             parentId: { type: ['string', 'null'], description: '目标父文件夹 id，空为根目录' },
-            language: { type: 'string', description: '语言' }
+            language: { type: 'string', description: '语言' },
+            tenantId: { description: TENANT_ID }
           }
-        }
+        },
+        response: success('复制生成的顶层节点列表（与 ids 一一对应）', { type: 'array', items: folderNode })
       }
     },
     async request => {
@@ -557,8 +634,9 @@ module.exports = fp(async (fastify, options) => {
     {
       onRequest: getFolderAuthenticate('write'),
       schema: {
+        tags: [TAG_FOLDER],
         summary: '重命名文件夹节点',
-        description: '重命名文件或文件夹节点；文件节点同步更新 file-record 文件名',
+        description: '重命名文件或文件夹节点；文件节点同步更新 file-record 文件名（linked 引用节点只改树节点名称）；同一文件夹下重名返回错误',
         body: {
           type: 'object',
           required: ['type', 'id', 'name'],
@@ -566,9 +644,11 @@ module.exports = fp(async (fastify, options) => {
             type: { type: 'string', description: '业务域类型' },
             id: { type: 'string', description: '节点 id' },
             name: { type: 'string', description: '新名称' },
-            language: { type: 'string', description: '语言' }
+            language: { type: 'string', description: '语言' },
+            tenantId: { description: TENANT_ID }
           }
-        }
+        },
+        response: success('重命名后的节点', folderNode)
       }
     },
     async request => {
@@ -582,6 +662,7 @@ module.exports = fp(async (fastify, options) => {
       onRequest: getFolderAuthenticate('write'),
       preHandler: withDefaultFolderType('body'),
       schema: {
+        tags: [TAG_FOLDER],
         summary: '将已有文件挂到文件夹树',
         description:
           '把文件库中已有文件以 linked 节点形式加入指定文件夹（parentId 为空表示根目录）；删除该类节点不会删除文件库实体；未传 type 时使用 defaultFolderType',
@@ -597,9 +678,11 @@ module.exports = fp(async (fastify, options) => {
               description: '文件库 file-record id 列表'
             },
             parentId: { type: ['string', 'null'], description: '目标父文件夹 id，空为根目录' },
-            language: { type: 'string', description: '语言' }
+            language: { type: 'string', description: '语言' },
+            tenantId: { description: TENANT_ID }
           }
-        }
+        },
+        response: success('新挂载的文件节点列表；目标目录已挂载的文件会跳过，不出现在结果中', { type: 'array', items: folderNode })
       }
     },
     async request => {

package/libs/schema/response.js

@@ -0,0 +1,53 @@
+// 响应 schema 会参与 fast-json-stringify 序列化：对象一律 additionalProperties: true 以免裁掉未声明字段；
+// 用 nullable 而非类型数组（类型数组遇到不匹配的值会直接 500），类型不确定的字段（如 id、日期、JSON 列）只写说明不声明类型
+const str = description => ({ type: 'string', nullable: true, description });
+const num = description => ({ type: 'number', nullable: true, description });
+const any = description => ({ description });
+const list = (description, items) => ({ type: 'array', nullable: true, description, items });
+const obj = (description, properties = {}) => ({ type: 'object', nullable: true, description, additionalProperties: true, properties });
+
+const success = (description, schema) => ({
+  200: Object.assign({}, schema || { type: 'object' }, { description })
+});
+
+const empty = (description = '操作成功，返回空对象') => success(description);
+
+const fileRecordProperties = {
+  id: any('文件 ID（即 uuid），用于 file-url / file-id 等接口'),
+  uuid: any('文件 uuid'),
+  filename: str('文件名（已替换非法字符）'),
+  hash: str('文件内容 md5，存储文件名为 {hash}{扩展名}'),
+  namespace: str('文件分类命名空间'),
+  size: num('文件大小（字节）'),
+  encoding: str('上传编码'),
+  mimetype: str('文件 MIME 类型'),
+  storageType: str('存储类型：local 本地文件系统，oss 远程 OSS 存储'),
+  options: any('扩展字段（JSON）'),
+  createdAt: any('创建时间'),
+  updatedAt: any('更新时间'),
+  deletedAt: any('删除时间，未删除为 null')
+};
+
+const fileRecord = obj('文件记录', fileRecordProperties);
+
+const folderNodeProperties = {
+  id: any('节点 ID'),
+  tenantId: any('租户 ID'),
+  type: str('业务域类型'),
+  code: str('节点编码'),
+  name: str('节点名称（文件节点为显示文件名）'),
+  language: str('语言'),
+  description: str('描述'),
+  index: num('排序'),
+  parentId: any('父文件夹节点 ID，根目录为 null'),
+  options: any('节点扩展信息（JSON）：kind 节点类型 file/folder；文件节点含 fileId（文件 uuid）、size、mimetype、filename，linked 为 true 表示引用文件库已有文件（删除节点不删文件实体）'),
+  createdAt: any('创建时间（文件节点在树/列表中取文件记录的时间）'),
+  updatedAt: any('更新时间（文件节点在树/列表中取文件记录的时间）'),
+  deletedAt: any('删除时间，未删除为 null')
+};
+
+const folderNode = obj('文件夹树节点', folderNodeProperties);
+
+const folderTreeNode = obj('文件夹树节点', Object.assign({}, folderNodeProperties, { children: list('子节点列表，结构同本节点', obj('子节点')) }));
+
+module.exports = { str, num, any, list, obj, success, empty, fileRecordProperties, fileRecord, folderNodeProperties, folderNode, folderTreeNode };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kne/fastify-file-manager",
-  "version": "3.0.7",
+  "version": "3.0.9",
   "description": "用于管理静态文件上传查看等",
   "main": "index.js",
   "scripts": {