@kne/fastify-live-components-site 0.1.0

package/README.md

@@ -0,0 +1,95 @@
+# fastify-live-components-site
+
+### 描述
+
+Fastify 插件：为 LiveComponentEditor 提供远程站点文件树与短链访问管理
+
+### 安装
+
+```shell
+npm i --save @kne/fastify-live-components-site
+```
+
+### 概述
+
+# Live Components Site
+
+为 `LiveComponentEditor` 提供远程站点文件树 API，并通过 shorten 短码免登录访问；站点链接由 admin 管理。
+
+## 能力
+
+- 管理端：创建/修改/开启关闭/删除站点，签发含 shorten 的访问 host
+- 公开端：`{prefix}/{shorten}/*` 文件树读写，路径 shorten 校验，无需登录
+- `GET {prefix}/content/{contentShorten}`：直出后端已保存 content（`text/plain`）；短码由 `content-share` 签发，URL **不含**站点 shorten，可设有效期并可管理删除
+
+
+### 示例
+
+### API
+
+# API
+
+## 配置项
+
+| 属性名 | 说明 | 类型 | 默认值 |
+|-----|----|----|-----|
+| name | 命名空间 | string | `liveComponentsSite` |
+| prefix | 路由前缀 | string | `/api/v1/live-components-site` |
+| dbTableNamePrefix | 表前缀 | string | `t_live_components_site_` |
+| siteTargetType | shorten target.type（站点） | string | `live-components-site` |
+| contentTargetType | shorten target.type（内容分享） | string | `live-components-site-content` |
+| getSiteHost | 由 shorten 组装站点 host | `(shorten) => string` | `` `${prefix}/${shorten}` `` |
+| getContentHost | 内容短链基址（不含站点 shorten） | `() => string` | `` `${prefix}` `` → 访问路径 `` `${prefix}/content/{code}` `` |
+| getShortenServices | 注入 shorten 服务 | `() => services` | `() => fastify.shorten.services` |
+| getAuthenticate | 按功能返回鉴权中间件 | `(type) => middleware[]` | 见下表 |
+
+### getAuthenticate(type)
+
+| type | 默认 |
+|------|------|
+| `entry` | 校验 path `:shorten`，写入 `request.authenticatePayload` |
+| `site` / `site:create` / `site:manage` | `[authenticate.user, authenticate.admin]` |
+
+## 管理端（需登录 admin）
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| GET | `{prefix}/site/list` | 列表，`filter.status` / `filter.keyword`，`perPage` / `currentPage` |
+| GET | `{prefix}/site/detail` | 详情，`?id=` |
+| POST | `{prefix}/site/create` | 创建并签发 shorten，body: `{ name, defaultPermission?, status?, options? }` |
+| POST | `{prefix}/site/save` | 修改，body: `{ id, name?, status?, defaultPermission?, options? }`；`status`: `open` / `closed` |
+| POST | `{prefix}/site/remove` | 删除，body: `{ id }` |
+
+创建返回含 `shorten`、`host`（可直接作为前端 `sites[].host`）。
+
+站点字段：`status` `open` 开启 / `closed` 关闭；关闭后公开 API 返回 403，host/shorten 不变。站点与 shorten 均不过期。
+
+## 公开端（path 含 shorten，无需登录）
+
+`host` 形态：`{origin}{prefix}/{shorten}`
+
+**CORS**：下列公开接口与内容访问接口均允许任意 Origin（`Access-Control-Allow-Origin: *`），并支持 `OPTIONS` 预检。站点管理接口（`{prefix}/site/*`）不启用该跨域策略。
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| GET | `{host}/getFolderTree` | 文件树 |
+| GET | `{host}/get?id=` | 读文件（JSON：`{ id, name, permission, content }`） |
+| GET | `{prefix}/content/{contentShorten}` | 直出已保存 content（`text/plain`，无 `{code,data}`；不带站点 shorten） |
+| POST | `{host}/content-share/create` | `{ id, expiresIn? }`，`expiresIn` 为秒，空/省略为永久；返回 `{ shorten, url, expires }`，`url` 为 `{prefix}/content/{shorten}` |
+| GET | `{host}/content-share/list?id=` | 列出该文件未过期的内容短链 |
+| POST | `{host}/content-share/remove` | `{ shorten }` |
+| POST | `{host}/createFolder` | `{ parentId, name }` |
+| POST | `{host}/create` | `{ parentId, name, content? }` |
+| POST | `{host}/save` | `{ id, content }` |
+| POST | `{host}/rename` | `{ id, name }` |
+| POST | `{host}/remove` | `{ ids: string[] }` |
+
+树节点：`{ id, name, type: 'file'|'directory', permission: 'r'|'rw', children? }`。
+
+错误：无效/过期 shorten → 401；站点关闭 → 403。
+
+## Shorten target
+
+```json
+{ "type": "live-components-site", "siteId": "<id>" }
+```

package/index.js

@@ -0,0 +1,83 @@
+const fp = require('fastify-plugin');
+const path = require('node:path');
+
+const SITE_TARGET_TYPE = 'live-components-site';
+const CONTENT_TARGET_TYPE = 'live-components-site-content';
+
+module.exports = fp(
+  async (fastify, options) => {
+    options = Object.assign(
+      {},
+      {
+        dbTableNamePrefix: 't_live_components_site_',
+        name: 'liveComponentsSite',
+        prefix: '/api/v1/live-components-site',
+        siteTargetType: SITE_TARGET_TYPE,
+        contentTargetType: CONTENT_TARGET_TYPE,
+        getSiteHost: null,
+        // 内容短链基址（不含站点 shorten），默认 `${prefix}` → `${prefix}/content/{code}`
+        getContentHost: null,
+        getShortenServices: () => {
+          if (!fastify.shorten) {
+            throw new Error('fastify-shorten plugin must be registered before @kne/fastify-live-components-site, or set options.getShortenServices');
+          }
+          return fastify.shorten.services;
+        },
+        getAuthenticate: type => {
+          if (type === 'entry') {
+            return [
+              async request => {
+                await fastify[options.name].services.site.authenticateEntry(request);
+              }
+            ];
+          }
+          if (!fastify.account) {
+            return [
+              () => {
+                throw new Error('fastify-account plugin must be registered before @kne/fastify-live-components-site, or set options.getAuthenticate');
+              }
+            ];
+          }
+          const { authenticate } = fastify.account;
+          switch (type) {
+            case 'site':
+            case 'site:create':
+            case 'site:manage':
+            default:
+              return [authenticate.user, authenticate.admin];
+          }
+        }
+      },
+      options
+    );
+
+    if (typeof options.getSiteHost !== 'function') {
+      options.getSiteHost = shorten => `${options.prefix}/${shorten}`;
+    }
+    if (typeof options.getContentHost !== 'function') {
+      options.getContentHost = () => options.prefix;
+    }
+
+    fastify.register(require('@kne/fastify-namespace'), {
+      options,
+      name: options.name,
+      modules: [
+        [
+          'models',
+          await fastify.sequelize.addModels(path.resolve(__dirname, './libs/models'), {
+            prefix: options.dbTableNamePrefix
+          })
+        ],
+        ['services', path.resolve(__dirname, './libs/services')],
+        ['controllers', path.resolve(__dirname, './libs/controllers')]
+      ]
+    });
+  },
+  {
+    name: 'fastify-live-components-site',
+    dependencies: ['fastify-sequelize']
+  }
+);
+
+module.exports.SITE_TARGET_TYPE = SITE_TARGET_TYPE;
+module.exports.CONTENT_TARGET_TYPE = CONTENT_TARGET_TYPE;

package/libs/controllers/entry.js

@@ -0,0 +1,321 @@
+const fp = require('fastify-plugin');
+const { allowCors, handleOptions, normalizeHooks } = require('../utils/cors');
+
+module.exports = fp(async (fastify, options) => {
+  const { services } = fastify[options.name];
+  const entryAuth = options.getAuthenticate('entry');
+  const withEntryAuth = [allowCors, ...normalizeHooks(entryAuth)];
+
+  // 预检：内容访问 + 站点公开入口（不含 /site 管理）
+  fastify.options(
+    `${options.prefix}/content/:contentShorten`,
+    {
+      schema: { hide: true }
+    },
+    handleOptions
+  );
+  fastify.options(
+    `${options.prefix}/:shorten/*`,
+    {
+      schema: { hide: true }
+    },
+    handleOptions
+  );
+
+  // 公开内容短链：不带站点 shorten，须注册在 /:shorten/* 之前
+  fastify.get(
+    `${options.prefix}/content/:contentShorten`,
+    {
+      onRequest: allowCors,
+      schema: {
+        summary: '通过内容短码直出已保存 content（text/plain，无 code/data；不带站点 shorten）',
+        params: {
+          type: 'object',
+          required: ['contentShorten'],
+          properties: {
+            contentShorten: { type: 'string' }
+          }
+        }
+      }
+    },
+    async (request, reply) => {
+      const content = await services.contentShare.resolveByCode({
+        contentShorten: request.params.contentShorten
+      });
+      reply.type('text/plain; charset=utf-8');
+      return content;
+    }
+  );
+
+  fastify.get(
+    `${options.prefix}/:shorten/getFolderTree`,
+    {
+      onRequest: withEntryAuth,
+      schema: {
+        summary: '获取站点文件树',
+        params: {
+          type: 'object',
+          required: ['shorten'],
+          properties: {
+            shorten: { type: 'string' }
+          }
+        }
+      }
+    },
+    async request => {
+      return services.node.getFolderTree(request.authenticatePayload);
+    }
+  );
+
+  fastify.get(
+    `${options.prefix}/:shorten/get`,
+    {
+      onRequest: withEntryAuth,
+      schema: {
+        summary: '读取文件内容',
+        params: {
+          type: 'object',
+          required: ['shorten'],
+          properties: {
+            shorten: { type: 'string' }
+          }
+        },
+        query: {
+          type: 'object',
+          required: ['id'],
+          properties: {
+            id: { type: 'string' }
+          }
+        }
+      }
+    },
+    async request => {
+      return services.node.get(request.authenticatePayload, request.query);
+    }
+  );
+
+  fastify.post(
+    `${options.prefix}/:shorten/content-share/create`,
+    {
+      onRequest: withEntryAuth,
+      schema: {
+        summary: '创建文件内容分享短链（可设有效期）',
+        params: {
+          type: 'object',
+          required: ['shorten'],
+          properties: {
+            shorten: { type: 'string' }
+          }
+        },
+        body: {
+          type: 'object',
+          required: ['id'],
+          properties: {
+            id: { type: 'string' },
+            expiresIn: { type: ['number', 'null'] }
+          }
+        }
+      }
+    },
+    async request => {
+      return services.contentShare.create(request.authenticatePayload, request.body);
+    }
+  );
+
+  fastify.get(
+    `${options.prefix}/:shorten/content-share/list`,
+    {
+      onRequest: withEntryAuth,
+      schema: {
+        summary: '列出文件已有内容分享短链',
+        params: {
+          type: 'object',
+          required: ['shorten'],
+          properties: {
+            shorten: { type: 'string' }
+          }
+        },
+        query: {
+          type: 'object',
+          required: ['id'],
+          properties: {
+            id: { type: 'string' }
+          }
+        }
+      }
+    },
+    async request => {
+      return services.contentShare.list(request.authenticatePayload, request.query);
+    }
+  );
+
+  fastify.post(
+    `${options.prefix}/:shorten/content-share/remove`,
+    {
+      onRequest: withEntryAuth,
+      schema: {
+        summary: '删除文件内容分享短链',
+        params: {
+          type: 'object',
+          required: ['shorten'],
+          properties: {
+            shorten: { type: 'string' }
+          }
+        },
+        body: {
+          type: 'object',
+          required: ['shorten'],
+          properties: {
+            shorten: { type: 'string' }
+          }
+        }
+      }
+    },
+    async request => {
+      return services.contentShare.remove(request.authenticatePayload, request.body);
+    }
+  );
+
+  fastify.post(
+    `${options.prefix}/:shorten/createFolder`,
+    {
+      onRequest: withEntryAuth,
+      schema: {
+        summary: '创建文件夹',
+        params: {
+          type: 'object',
+          required: ['shorten'],
+          properties: {
+            shorten: { type: 'string' }
+          }
+        },
+        body: {
+          type: 'object',
+          required: ['name'],
+          properties: {
+            parentId: { type: ['string', 'null'] },
+            name: { type: 'string' }
+          }
+        }
+      }
+    },
+    async request => {
+      return services.node.createFolder(request.authenticatePayload, request.body);
+    }
+  );
+
+  fastify.post(
+    `${options.prefix}/:shorten/create`,
+    {
+      onRequest: withEntryAuth,
+      schema: {
+        summary: '创建文件',
+        params: {
+          type: 'object',
+          required: ['shorten'],
+          properties: {
+            shorten: { type: 'string' }
+          }
+        },
+        body: {
+          type: 'object',
+          required: ['name'],
+          properties: {
+            parentId: { type: ['string', 'null'] },
+            name: { type: 'string' },
+            content: { type: 'string' }
+          }
+        }
+      }
+    },
+    async request => {
+      return services.node.create(request.authenticatePayload, request.body);
+    }
+  );
+
+  fastify.post(
+    `${options.prefix}/:shorten/save`,
+    {
+      onRequest: withEntryAuth,
+      schema: {
+        summary: '保存文件内容',
+        params: {
+          type: 'object',
+          required: ['shorten'],
+          properties: {
+            shorten: { type: 'string' }
+          }
+        },
+        body: {
+          type: 'object',
+          required: ['id'],
+          properties: {
+            id: { type: 'string' },
+            content: { type: 'string' }
+          }
+        }
+      }
+    },
+    async request => {
+      return services.node.save(request.authenticatePayload, request.body);
+    }
+  );
+
+  fastify.post(
+    `${options.prefix}/:shorten/rename`,
+    {
+      onRequest: withEntryAuth,
+      schema: {
+        summary: '重命名节点',
+        params: {
+          type: 'object',
+          required: ['shorten'],
+          properties: {
+            shorten: { type: 'string' }
+          }
+        },
+        body: {
+          type: 'object',
+          required: ['id', 'name'],
+          properties: {
+            id: { type: 'string' },
+            name: { type: 'string' }
+          }
+        }
+      }
+    },
+    async request => {
+      return services.node.rename(request.authenticatePayload, request.body);
+    }
+  );
+
+  fastify.post(
+    `${options.prefix}/:shorten/remove`,
+    {
+      onRequest: withEntryAuth,
+      schema: {
+        summary: '删除节点',
+        params: {
+          type: 'object',
+          required: ['shorten'],
+          properties: {
+            shorten: { type: 'string' }
+          }
+        },
+        body: {
+          type: 'object',
+          required: ['ids'],
+          properties: {
+            ids: {
+              type: 'array',
+              items: { type: 'string' }
+            }
+          }
+        }
+      }
+    },
+    async request => {
+      return services.node.remove(request.authenticatePayload, request.body);
+    }
+  );
+});

package/libs/controllers/site.js

@@ -0,0 +1,115 @@
+const fp = require('fastify-plugin');
+
+module.exports = fp(async (fastify, options) => {
+  const { services } = fastify[options.name];
+
+  fastify.get(
+    `${options.prefix}/site/list`,
+    {
+      onRequest: options.getAuthenticate('site'),
+      schema: {
+        summary: '站点列表',
+        query: {
+          type: 'object',
+          properties: {
+            filter: { type: 'object', default: {} },
+            perPage: { type: 'number', default: 20 },
+            currentPage: { type: 'number', default: 1 }
+          }
+        }
+      }
+    },
+    async request => {
+      return services.site.list(request.userInfo || {}, request.query);
+    }
+  );
+
+  fastify.get(
+    `${options.prefix}/site/detail`,
+    {
+      onRequest: options.getAuthenticate('site'),
+      schema: {
+        summary: '站点详情',
+        query: {
+          type: 'object',
+          required: ['id'],
+          properties: {
+            id: { type: 'string' }
+          }
+        }
+      }
+    },
+    async request => {
+      return services.site.detail(request.userInfo || {}, request.query);
+    }
+  );
+
+  fastify.post(
+    `${options.prefix}/site/create`,
+    {
+      onRequest: options.getAuthenticate('site:create'),
+      schema: {
+        summary: '创建站点并签发 shorten 链接',
+        body: {
+          type: 'object',
+          required: ['name'],
+          properties: {
+            name: { type: 'string' },
+            defaultPermission: { type: 'string', enum: ['r', 'rw'] },
+            status: { type: 'string', enum: ['open', 'closed'] },
+            options: { type: 'object' }
+          }
+        }
+      }
+    },
+    async request => {
+      return services.site.create(request.userInfo || {}, request.body);
+    }
+  );
+
+  fastify.post(
+    `${options.prefix}/site/save`,
+    {
+      onRequest: options.getAuthenticate('site:manage'),
+      schema: {
+        summary: '修改站点（含开启/关闭）',
+        body: {
+          type: 'object',
+          required: ['id'],
+          properties: {
+            id: { type: 'string' },
+            name: { type: 'string' },
+            status: { type: 'string', enum: ['open', 'closed'] },
+            defaultPermission: { type: 'string', enum: ['r', 'rw'] },
+            options: { type: 'object' }
+          }
+        }
+      }
+    },
+    async request => {
+      await services.site.save(request.userInfo || {}, request.body);
+      return {};
+    }
+  );
+
+  fastify.post(
+    `${options.prefix}/site/remove`,
+    {
+      onRequest: options.getAuthenticate('site:manage'),
+      schema: {
+        summary: '删除站点',
+        body: {
+          type: 'object',
+          required: ['id'],
+          properties: {
+            id: { type: 'string' }
+          }
+        }
+      }
+    },
+    async request => {
+      await services.site.remove(request.userInfo || {}, request.body);
+      return {};
+    }
+  );
+});

package/libs/models/content-share.js

@@ -0,0 +1,39 @@
+module.exports = ({ DataTypes, definePrimaryType }) => {
+  return {
+    model: {
+      siteId: Object.assign(definePrimaryType('siteId'), {
+        allowNull: false,
+        comment: '所属站点'
+      }),
+      nodeId: Object.assign(definePrimaryType('nodeId'), {
+        allowNull: false,
+        comment: '文件节点'
+      }),
+      shorten: {
+        type: DataTypes.STRING,
+        allowNull: false,
+        comment: '内容访问短码'
+      },
+      expires: {
+        type: DataTypes.DATE,
+        allowNull: true,
+        comment: '过期时间，空表示永久'
+      }
+    },
+    associate: ({ contentShare, site, node }) => {
+      contentShare.belongsTo(site, { foreignKey: 'siteId' });
+      contentShare.belongsTo(node, { foreignKey: 'nodeId' });
+    },
+    options: {
+      comment: 'Live 组件文件内容分享短链',
+      indexes: [
+        { fields: ['site_id', 'node_id'] },
+        {
+          fields: ['shorten'],
+          unique: true,
+          where: { deleted_at: null }
+        }
+      ]
+    }
+  };
+};

package/libs/models/node.js

@@ -0,0 +1,48 @@
+module.exports = ({ DataTypes, definePrimaryType }) => {
+  return {
+    model: {
+      parentId: Object.assign(definePrimaryType('parentId'), {
+        allowNull: true,
+        comment: '父节点 id，根节点为空'
+      }),
+      name: {
+        type: DataTypes.STRING,
+        allowNull: false,
+        comment: '节点名称'
+      },
+      type: {
+        type: DataTypes.STRING,
+        allowNull: false,
+        comment: '节点类型: file | directory'
+      },
+      permission: {
+        type: DataTypes.STRING,
+        allowNull: false,
+        defaultValue: 'rw',
+        comment: '权限: r | rw'
+      },
+      content: {
+        type: DataTypes.TEXT,
+        comment: '文件内容，目录为空'
+      }
+    },
+    associate: ({ node, site }) => {
+      node.belongsTo(site, {
+        foreignKey: 'siteId',
+        comment: '所属站点'
+      });
+    },
+    options: {
+      comment: 'Live 组件站点文件树节点',
+      indexes: [
+        { fields: ['site_id'] },
+        { fields: ['parent_id'] },
+        {
+          fields: ['site_id', 'parent_id', 'name'],
+          unique: true,
+          where: { deleted_at: null }
+        }
+      ]
+    }
+  };
+};