@kne/fastify-live-components-site 0.1.9 → 0.1.10

package/libs/controllers/entry.js

@@ -1,5 +1,25 @@
 const fp = require('fastify-plugin');
 const { allowCors, handleOptions, normalizeHooks } = require('../utils/cors');
+const { str, bool, any, list, obj, success, PERMISSION, SITE_STATUS, nodeBase, treeNode, contentShare } = require('../schema/response');
+
+const TAG_SITE = 'Live组件站点-站点信息';
+const TAG_AI = 'Live组件站点-AI';
+const TAG_FILE = 'Live组件站点-文件';
+const TAG_SHARE = 'Live组件站点-内容分享';
+
+const ENTRY_HINT = '通过站点短码 shorten 鉴权（站点须存在且为开启状态，关闭返回 403，短码无效返回 401），允许任意 Origin 跨域';
+
+const shortenParams = {
+  type: 'object',
+  required: ['shorten'],
+  properties: {
+    shorten: { type: 'string', description: '站点公开访问短码（不区分大小写）' }
+  }
+};
+
+const PARENT_ID = '父文件夹节点 ID，为空表示根目录；父节点须为可写文件夹';
+
+const fileNode = obj('文件节点', nodeBase);
 
 module.exports = fp(async (fastify, options) => {
   const { services } = fastify[options.name];
@@ -28,14 +48,17 @@ module.exports = fp(async (fastify, options) => {
     {
       onRequest: allowCors,
       schema: {
+        tags: [TAG_SHARE],
         summary: '通过内容短码直出已保存 content（text/plain，无 code/data；不带站点 shorten）',
+        description: '公开访问，无需站点短码；短码无效或已过期返回 401，所属站点关闭返回 403。允许任意 Origin 跨域',
         params: {
           type: 'object',
           required: ['contentShorten'],
           properties: {
-            contentShorten: { type: 'string' }
+            contentShorten: { type: 'string', description: '内容分享短码（不区分大小写）' }
           }
-        }
+        },
+        response: success('文件已保存的内容原文，Content-Type 为 text/plain; charset=utf-8', { type: 'string' })
       }
     },
     async (request, reply) => {
@@ -52,14 +75,20 @@ module.exports = fp(async (fastify, options) => {
     {
       onRequest: withEntryAuth,
       schema: {
+        tags: [TAG_SITE],
         summary: '站点信息（含是否支持 AI）',
-        params: {
+        description: ENTRY_HINT,
+        params: shortenParams,
+        response: success('站点公开信息', {
           type: 'object',
-          required: ['shorten'],
+          additionalProperties: true,
           properties: {
-            shorten: { type: 'string' }
+            name: str('站点名称'),
+            status: str(SITE_STATUS),
+            defaultPermission: str(`新建节点默认${PERMISSION}`),
+            aiEnabled: bool('是否可用 AI 生成：插件配置了 ai.getAIModel 且站点 options.aiEnabled 不为 false')
           }
-        }
+        })
       }
     },
     async request => {
@@ -72,26 +101,38 @@ module.exports = fp(async (fastify, options) => {
     {
       onRequest: withEntryAuth,
       schema: {
+        tags: [TAG_AI],
         summary: '创建 AI 流式任务，返回 streamToken',
-        params: {
+        description: `${ENTRY_HINT}。站点未开启 AI 返回 403；refine 模式 messages 不能为空。任务暂存于内存，2 分钟内需用 streamToken 调用 ai/stream 消费`,
+        params: shortenParams,
+        body: {
           type: 'object',
-          required: ['shorten'],
           properties: {
-            shorten: { type: 'string' }
+            mode: { type: 'string', description: '任务模式：generate 生成代码，其它值按 refine（完善需求对话）处理' },
+            messages: { type: 'array', description: '对话历史，元素形如 { role: user|assistant, content }，其它 role 或空 content 会被忽略' },
+            content: { type: 'string', description: '编辑器当前整份源码' },
+            scope: { type: 'object', description: '编辑器当前 scope（可用变量/组件声明）' },
+            props: { description: '编辑器当前组件参数，形如 { name: { type, defaultValue } }；非对象时忽略' },
+            libs: { type: 'array', description: '可用依赖库标识列表，元素会转为字符串' },
+            remotes: { type: 'array', description: '可用远程组件包列表，用于在 stream 阶段拉取组件文档索引' },
+            selection: {
+              type: 'object',
+              description: '编辑器选中片段；传入时 AI 只针对选中部分',
+              properties: {
+                code: { description: '选中片段源码' },
+                startLine: { description: '选中片段起始行' },
+                label: { description: '选中片段名称，用于提示' }
+              }
+            }
           }
         },
-        body: {
+        response: success('任务已创建', {
           type: 'object',
+          additionalProperties: true,
           properties: {
-            mode: { type: 'string' },
-            messages: { type: 'array' },
-            content: { type: 'string' },
-            scope: { type: 'object' },
-            libs: { type: 'array' },
-            remotes: { type: 'array' },
-            selection: { type: 'object' }
+            streamToken: str('一次性流式任务令牌，传给 ai/stream 的 token')
           }
-        }
+        })
       }
     },
     async request => {
@@ -104,20 +145,19 @@ module.exports = fp(async (fastify, options) => {
     {
       onRequest: withEntryAuth,
       schema: {
+        tags: [TAG_AI],
         summary: 'SSE 推送 AI 流式输出',
-        params: {
-          type: 'object',
-          required: ['shorten'],
-          properties: {
-            shorten: { type: 'string' }
-          }
-        },
+        description: `${ENTRY_HINT}。token 只能消费一次，无效或过期返回 404；成功后以 text/event-stream 推送 data: {...} 事件直到结束`,
+        params: shortenParams,
         query: {
           type: 'object',
           required: ['token'],
           properties: {
-            token: { type: 'string' }
+            token: { type: 'string', description: 'ai/start 返回的 streamToken' }
           }
+        },
+        response: {
+          200: { description: 'text/event-stream 事件流，每条为 data: JSON；出错时推送 { text: 错误信息, done: true } 后结束' }
         }
       }
     },
@@ -131,14 +171,11 @@ module.exports = fp(async (fastify, options) => {
     {
       onRequest: withEntryAuth,
       schema: {
+        tags: [TAG_FILE],
         summary: '获取站点文件树',
-        params: {
-          type: 'object',
-          required: ['shorten'],
-          properties: {
-            shorten: { type: 'string' }
-          }
-        }
+        description: `${ENTRY_HINT}。同级按类型（文件夹在前）、名称排序`,
+        params: shortenParams,
+        response: success('根节点列表，文件夹带 children', { type: 'array', items: treeNode })
       }
     },
     async request => {
@@ -151,21 +188,27 @@ module.exports = fp(async (fastify, options) => {
     {
       onRequest: withEntryAuth,
       schema: {
+        tags: [TAG_FILE],
         summary: '读取文件内容',
-        params: {
+        description: `${ENTRY_HINT}。节点不存在返回 404，非文件返回 400`,
+        params: shortenParams,
+        query: {
           type: 'object',
-          required: ['shorten'],
+          required: ['id'],
           properties: {
-            shorten: { type: 'string' }
+            id: { type: 'string', description: '文件节点 ID' }
           }
         },
-        query: {
+        response: success('文件内容', {
           type: 'object',
-          required: ['id'],
+          additionalProperties: true,
           properties: {
-            id: { type: 'string' }
+            id: any('节点 ID（字符串）'),
+            name: str('文件名'),
+            permission: str(PERMISSION),
+            content: str('文件内容，未保存过为空字符串')
           }
-        }
+        })
       }
     },
     async request => {
@@ -178,22 +221,19 @@ module.exports = fp(async (fastify, options) => {
     {
       onRequest: withEntryAuth,
       schema: {
+        tags: [TAG_SHARE],
         summary: '创建文件内容分享短链（可设有效期）',
-        params: {
-          type: 'object',
-          required: ['shorten'],
-          properties: {
-            shorten: { type: 'string' }
-          }
-        },
+        description: `${ENTRY_HINT}。只能分享文件；生成的短链通过 content/:contentShorten 公开访问`,
+        params: shortenParams,
         body: {
           type: 'object',
           required: ['id'],
           properties: {
-            id: { type: 'string' },
-            expiresIn: { type: ['number', 'null'] }
+            id: { type: 'string', description: '文件节点 ID' },
+            expiresIn: { type: ['number', 'null'], description: '有效期（秒），不传、null 或不大于 0 表示永久有效' }
           }
-        }
+        },
+        response: success('创建的分享短链', contentShare)
       }
     },
     async request => {
@@ -206,21 +246,18 @@ module.exports = fp(async (fastify, options) => {
     {
       onRequest: withEntryAuth,
       schema: {
+        tags: [TAG_SHARE],
         summary: '列出文件已有内容分享短链',
-        params: {
-          type: 'object',
-          required: ['shorten'],
-          properties: {
-            shorten: { type: 'string' }
-          }
-        },
+        description: `${ENTRY_HINT}。按创建时间倒序；已过期的分享会在查询时被删除并移除短码，不出现在结果中`,
+        params: shortenParams,
         query: {
           type: 'object',
           required: ['id'],
           properties: {
-            id: { type: 'string' }
+            id: { type: 'string', description: '文件节点 ID' }
           }
-        }
+        },
+        response: success('未过期的分享短链列表', { type: 'array', items: contentShare })
       }
     },
     async request => {
@@ -233,21 +270,24 @@ module.exports = fp(async (fastify, options) => {
     {
       onRequest: withEntryAuth,
       schema: {
+        tags: [TAG_SHARE],
         summary: '删除文件内容分享短链',
-        params: {
+        description: `${ENTRY_HINT}。删除分享记录并移除内容短码；分享不存在返回 404`,
+        params: shortenParams,
+        body: {
           type: 'object',
           required: ['shorten'],
           properties: {
-            shorten: { type: 'string' }
+            shorten: { type: 'string', description: '要删除的内容分享短码（不区分大小写）' }
           }
         },
-        body: {
+        response: success('删除成功', {
           type: 'object',
-          required: ['shorten'],
+          additionalProperties: true,
           properties: {
-            shorten: { type: 'string' }
+            shorten: str('已删除的内容短码（大写）')
           }
-        }
+        })
       }
     },
     async request => {
@@ -260,22 +300,19 @@ module.exports = fp(async (fastify, options) => {
     {
       onRequest: withEntryAuth,
       schema: {
+        tags: [TAG_FILE],
         summary: '创建文件夹',
-        params: {
-          type: 'object',
-          required: ['shorten'],
-          properties: {
-            shorten: { type: 'string' }
-          }
-        },
+        description: `${ENTRY_HINT}。同级重名返回 400 DUPLICATE_NAME；新节点权限取站点 defaultPermission`,
+        params: shortenParams,
         body: {
           type: 'object',
           required: ['name'],
           properties: {
-            parentId: { type: ['string', 'null'] },
-            name: { type: 'string' }
+            parentId: { type: ['string', 'null'], description: PARENT_ID },
+            name: { type: 'string', description: '文件夹名称，去除首尾空格后不能为空' }
           }
-        }
+        },
+        response: success('创建的文件夹', obj('文件夹节点', Object.assign({}, nodeBase, { children: list('子节点，新建时为空数组', obj('子节点')) })))
       }
     },
     async request => {
@@ -288,23 +325,20 @@ module.exports = fp(async (fastify, options) => {
     {
       onRequest: withEntryAuth,
       schema: {
+        tags: [TAG_FILE],
         summary: '创建文件',
-        params: {
-          type: 'object',
-          required: ['shorten'],
-          properties: {
-            shorten: { type: 'string' }
-          }
-        },
+        description: `${ENTRY_HINT}。同级重名返回 400 DUPLICATE_NAME；新节点权限取站点 defaultPermission`,
+        params: shortenParams,
         body: {
           type: 'object',
           required: ['name'],
           properties: {
-            parentId: { type: ['string', 'null'] },
-            name: { type: 'string' },
-            content: { type: 'string' }
+            parentId: { type: ['string', 'null'], description: PARENT_ID },
+            name: { type: 'string', description: '文件名称，去除首尾空格后不能为空' },
+            content: { type: 'string', description: '初始文件内容，默认空字符串' }
           }
-        }
+        },
+        response: success('创建的文件', fileNode)
       }
     },
     async request => {
@@ -317,22 +351,26 @@ module.exports = fp(async (fastify, options) => {
     {
       onRequest: withEntryAuth,
       schema: {
+        tags: [TAG_FILE],
         summary: '保存文件内容',
-        params: {
+        description: `${ENTRY_HINT}。只读节点返回 403，非文件返回 400`,
+        params: shortenParams,
+        body: {
           type: 'object',
-          required: ['shorten'],
+          required: ['id'],
           properties: {
-            shorten: { type: 'string' }
+            id: { type: 'string', description: '文件节点 ID' },
+            content: { type: 'string', description: '新的文件内容，不传保存为空字符串' }
           }
         },
-        body: {
+        response: success('保存后的文件内容', {
           type: 'object',
-          required: ['id'],
+          additionalProperties: true,
           properties: {
-            id: { type: 'string' },
-            content: { type: 'string' }
+            id: any('节点 ID（字符串）'),
+            content: str('保存后的文件内容')
           }
-        }
+        })
       }
     },
     async request => {
@@ -345,22 +383,19 @@ module.exports = fp(async (fastify, options) => {
     {
       onRequest: withEntryAuth,
       schema: {
+        tags: [TAG_FILE],
         summary: '重命名节点',
-        params: {
-          type: 'object',
-          required: ['shorten'],
-          properties: {
-            shorten: { type: 'string' }
-          }
-        },
+        description: `${ENTRY_HINT}。只读节点返回 403，同级重名返回 400 DUPLICATE_NAME`,
+        params: shortenParams,
         body: {
           type: 'object',
           required: ['id', 'name'],
           properties: {
-            id: { type: 'string' },
-            name: { type: 'string' }
+            id: { type: 'string', description: '文件或文件夹节点 ID' },
+            name: { type: 'string', description: '新名称，去除首尾空格后不能为空' }
           }
-        }
+        },
+        response: success('重命名后的节点', fileNode)
       }
     },
     async request => {
@@ -373,22 +408,27 @@ module.exports = fp(async (fastify, options) => {
     {
       onRequest: withEntryAuth,
       schema: {
+        tags: [TAG_FILE],
         summary: '移动文件或文件夹到目标目录',
-        params: {
-          type: 'object',
-          required: ['shorten'],
-          properties: {
-            shorten: { type: 'string' }
-          }
-        },
+        description: `${ENTRY_HINT}。目标与当前目录相同、移动到自身或自身子目录返回 400 INVALID_MOVE_TARGET；目标目录下重名返回 400 DUPLICATE_NAME`,
+        params: shortenParams,
         body: {
           type: 'object',
           required: ['id'],
           properties: {
-            id: { type: 'string' },
-            parentId: { type: ['string', 'null'] }
+            id: { type: 'string', description: '要移动的节点 ID' },
+            parentId: { type: ['string', 'null'], description: '目标文件夹节点 ID，为空表示移动到根目录' }
           }
-        }
+        },
+        response: success(
+          '移动后的节点',
+          obj(
+            '节点',
+            Object.assign({}, nodeBase, {
+              parentId: any('新的父节点 ID，根目录为 null')
+            })
+          )
+        )
       }
     },
     async request => {
@@ -401,24 +441,28 @@ module.exports = fp(async (fastify, options) => {
     {
       onRequest: withEntryAuth,
       schema: {
+        tags: [TAG_FILE],
         summary: '删除节点',
-        params: {
-          type: 'object',
-          required: ['shorten'],
-          properties: {
-            shorten: { type: 'string' }
-          }
-        },
+        description: `${ENTRY_HINT}。按顺序逐个删除，遇到只读节点（403）或非空文件夹（400）即中止，已删除的不回滚；删除文件时一并删除其内容分享短链`,
+        params: shortenParams,
         body: {
           type: 'object',
           required: ['ids'],
           properties: {
             ids: {
               type: 'array',
-              items: { type: 'string' }
+              items: { type: 'string' },
+              description: '要删除的节点 ID 列表'
             }
           }
-        }
+        },
+        response: success('删除成功', {
+          type: 'object',
+          additionalProperties: true,
+          properties: {
+            ids: list('已删除的节点 ID 列表', any('节点 ID（字符串）'))
+          }
+        })
       }
     },
     async request => {

package/libs/controllers/site.js

@@ -1,4 +1,15 @@
 const fp = require('fastify-plugin');
+const { num, list, success, empty, PERMISSION, SITE_STATUS, site } = require('../schema/response');
+
+const TAG = 'Live组件站点管理后台-站点';
+
+const siteOptions = {
+  type: 'object',
+  description: '站点扩展配置（JSON），原样保存',
+  properties: {
+    aiEnabled: { description: '是否开启 AI 生成，传 false 关闭；未传视为开启（需同时配置插件 ai.getAIModel）' }
+  }
+};
 
 module.exports = fp(async (fastify, options) => {
   const { services } = fastify[options.name];
@@ -8,15 +19,33 @@ module.exports = fp(async (fastify, options) => {
     {
       onRequest: options.getAuthenticate('site'),
       schema: {
+        tags: [TAG],
         summary: '站点列表',
+        description: '分页查询站点，按创建时间倒序；可按状态与名称关键字筛选',
         query: {
           type: 'object',
           properties: {
-            filter: { type: 'object', default: {} },
-            perPage: { type: 'number', default: 20 },
-            currentPage: { type: 'number', default: 1 }
+            filter: {
+              type: 'object',
+              default: {},
+              description: '筛选条件，如 filter[status]=open',
+              properties: {
+                status: { description: `按状态筛选，${SITE_STATUS}；其它值忽略` },
+                keyword: { description: '按站点名称模糊匹配' }
+              }
+            },
+            perPage: { type: 'number', default: 20, description: '每页条数' },
+            currentPage: { type: 'number', default: 1, description: '当前页码，从 1 开始' }
+          }
+        },
+        response: success('站点分页列表', {
+          type: 'object',
+          additionalProperties: true,
+          properties: {
+            pageData: list('当前页站点列表', site),
+            totalCount: num('符合条件的站点总数')
           }
-        }
+        })
       }
     },
     async request => {
@@ -29,14 +58,17 @@ module.exports = fp(async (fastify, options) => {
     {
       onRequest: options.getAuthenticate('site'),
       schema: {
+        tags: [TAG],
         summary: '站点详情',
+        description: '按 ID 获取站点信息，含公开入口地址 host；站点不存在返回 404',
         query: {
           type: 'object',
           required: ['id'],
           properties: {
-            id: { type: 'string' }
+            id: { type: 'string', description: '站点 ID' }
           }
-        }
+        },
+        response: success('站点详情', site)
       }
     },
     async request => {
@@ -49,17 +81,20 @@ module.exports = fp(async (fastify, options) => {
     {
       onRequest: options.getAuthenticate('site:create'),
       schema: {
+        tags: [TAG],
         summary: '创建站点并签发 shorten 链接',
+        description: '创建站点后通过 shorten 服务签发站点公开访问短码，返回带 host 的站点信息',
         body: {
           type: 'object',
           required: ['name'],
           properties: {
-            name: { type: 'string' },
-            defaultPermission: { type: 'string', enum: ['r', 'rw'] },
-            status: { type: 'string', enum: ['open', 'closed'] },
-            options: { type: 'object' }
+            name: { type: 'string', description: '站点名称，去除首尾空格后不能为空' },
+            defaultPermission: { type: 'string', enum: ['r', 'rw'], description: `新建节点默认${PERMISSION}；默认 rw` },
+            status: { type: 'string', enum: ['open', 'closed'], description: `${SITE_STATUS}；默认 open` },
+            options: siteOptions
           }
-        }
+        },
+        response: success('创建后的站点', site)
       }
     },
     async request => {
@@ -72,18 +107,21 @@ module.exports = fp(async (fastify, options) => {
     {
       onRequest: options.getAuthenticate('site:manage'),
       schema: {
+        tags: [TAG],
         summary: '修改站点（含开启/关闭）',
+        description: '只更新传入的字段；shorten、时间字段不可修改。关闭后站点公开入口与内容短链返回 403，重新开启后沿用原 host',
         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' }
+            id: { type: 'string', description: '站点 ID' },
+            name: { type: 'string', description: '站点名称，传入时去除首尾空格后不能为空' },
+            status: { type: 'string', enum: ['open', 'closed'], description: SITE_STATUS },
+            defaultPermission: { type: 'string', enum: ['r', 'rw'], description: `新建节点默认${PERMISSION}` },
+            options: Object.assign({}, siteOptions, { description: '站点扩展配置（JSON），整体覆盖原值' })
           }
-        }
+        },
+        response: empty('保存成功')
       }
     },
     async request => {
@@ -97,14 +135,17 @@ module.exports = fp(async (fastify, options) => {
     {
       onRequest: options.getAuthenticate('site:manage'),
       schema: {
+        tags: [TAG],
         summary: '删除站点',
+        description: '删除站点及其全部文件节点、内容分享记录，并移除站点短码与内容短码',
         body: {
           type: 'object',
           required: ['id'],
           properties: {
-            id: { type: 'string' }
+            id: { type: 'string', description: '站点 ID' }
           }
-        }
+        },
+        response: empty('删除成功')
       }
     },
     async request => {

package/libs/schema/response.js

@@ -0,0 +1,50 @@
+// 响应 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 bool = description => ({ type: 'boolean', 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 PERMISSION = '权限：r 只读，rw 可读写';
+const SITE_STATUS = '站点状态：open 开启，closed 关闭';
+
+const site = obj('站点', {
+  id: any('站点 ID（字符串）'),
+  name: str('站点名称'),
+  shorten: str('站点公开访问短码'),
+  host: str('站点公开入口地址，由 getSiteHost(shorten) 生成，默认 {prefix}/{shorten}'),
+  status: str(SITE_STATUS),
+  defaultPermission: str(`新建节点默认${PERMISSION}`),
+  options: any('站点扩展配置（JSON），如 aiEnabled: false 关闭 AI'),
+  createdAt: any('创建时间'),
+  updatedAt: any('更新时间'),
+  deletedAt: any('删除时间，未删除为 null')
+});
+
+const nodeBase = {
+  id: any('节点 ID（字符串）'),
+  name: str('节点名称'),
+  type: str('节点类型：file 文件，directory 文件夹'),
+  permission: str(PERMISSION)
+};
+
+const treeNode = obj('文件树节点', Object.assign({}, nodeBase, { children: list('子节点列表（仅文件夹有），结构同本节点', obj('子节点')) }));
+
+const contentShare = obj('内容分享短链', {
+  id: any('分享记录 ID（字符串）'),
+  nodeId: any('文件节点 ID（字符串）'),
+  shorten: str('内容短码（大写）'),
+  expires: any('过期时间，null 表示永久有效'),
+  url: str('内容访问地址：{getContentHost()}/content/{shorten}，不带站点短码'),
+  createdAt: any('创建时间')
+});
+
+module.exports = { str, num, bool, any, list, obj, success, empty, PERMISSION, SITE_STATUS, site, nodeBase, treeNode, contentShare };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kne/fastify-live-components-site",
-  "version": "0.1.9",
+  "version": "0.1.10",
   "description": "Fastify 插件：为 LiveComponentEditor 提供远程站点文件树与短链访问管理",
   "main": "index.js",
   "scripts": {