@kne/fastify-message 1.0.13 → 1.0.14

package/libs/controllers/main.js

@@ -1,5 +1,8 @@
 const fp = require('fastify-plugin');
 
+const RECORD_TAG = '消息-发送记录';
+const TEMPLATE_TAG = '消息-消息模版';
+
 module.exports = fp(async (fastify, options) => {
   const { services } = fastify[options.name];
 
@@ -9,16 +12,18 @@ module.exports = fp(async (fastify, options) => {
     {
       onRequest: options.getAuthenticate('record'),
       schema: {
-        description: '获取消息发送记录列表',
+        tags: [RECORD_TAG],
+        description: '分页获取消息发送记录列表，按创建时间倒序；perPage 最大 100',
         summary: '查看发送记录',
         querystring: {
           type: 'object',
           properties: {
             currentPage: { type: 'integer', default: 1, description: '页码' },
-            perPage: { type: 'integer', default: 20, description: '每页数量' },
+            perPage: { type: 'integer', default: 20, description: '每页数量，超过 100 按 100 处理' },
             filter: {
               type: 'object',
               default: {},
+              description: '筛选条件，均为精确匹配',
               properties: {
                 type: { type: 'integer', description: '发送类型: 0=邮件, 1=短信' },
                 code: { type: 'string', description: '模板编码' },
@@ -29,6 +34,7 @@ module.exports = fp(async (fastify, options) => {
         },
         response: {
           200: {
+            description: '发送记录分页结果',
             type: 'object',
             properties: {
               totalCount: { type: 'integer', description: '总数量' },
@@ -36,8 +42,10 @@ module.exports = fp(async (fastify, options) => {
               perPage: { type: 'integer', description: '每页数量' },
               pageData: {
                 type: 'array',
+                description: '当前页发送记录列表',
                 items: {
                   type: 'object',
+                  description: '发送记录',
                   properties: {
                     id: { type: 'string', description: '记录ID' },
                     name: { type: 'string', description: '发送对象（邮箱/手机号）' },
@@ -58,12 +66,12 @@ module.exports = fp(async (fastify, options) => {
     async request => {
       const { currentPage = 1, perPage = 20, filter = {} } = request.query;
       const { type, code, name } = filter;
-      
+
       const where = {};
       if (type !== undefined) where.type = type;
       if (code) where.code = code;
       if (name) where.name = name;
-      
+
       return await services.record.list({ filter: where, perPage: Math.min(perPage, 100), currentPage });
     }
   );
@@ -74,7 +82,8 @@ module.exports = fp(async (fastify, options) => {
     {
       onRequest: options.getAuthenticate('template:send'),
       schema: {
-        description: '根据模版发送消息',
+        tags: [TEMPLATE_TAG],
+        description: '使用指定模版渲染内容并通过对应类型的发送器（邮件 / 短信）发送，同时写入发送记录；模版不存在返回 404，模版已禁用返回 400',
         summary: '发送消息',
         body: {
           type: 'object',
@@ -82,11 +91,12 @@ module.exports = fp(async (fastify, options) => {
           properties: {
             templateId: { type: 'string', description: '模版ID' },
             name: { type: 'string', description: '发送对象（邮箱/手机号）' },
-            props: { type: 'object', description: '模版变量', additionalProperties: true }
+            props: { type: 'object', description: '模版变量，用于渲染模版内容，不传为空对象', additionalProperties: true }
           }
         },
         response: {
           200: {
+            description: '发送成功',
             type: 'object',
             properties: {
               success: { type: 'boolean', description: '是否发送成功' }
@@ -117,7 +127,8 @@ module.exports = fp(async (fastify, options) => {
     {
       onRequest: options.getAuthenticate('record'),
       schema: {
-        description: '获取单条消息发送记录详情',
+        tags: [RECORD_TAG],
+        description: '获取单条消息发送记录详情，记录不存在返回 404',
         summary: '查看发送记录详情',
         params: {
           type: 'object',
@@ -128,6 +139,7 @@ module.exports = fp(async (fastify, options) => {
         },
         response: {
           200: {
+            description: '发送记录详情',
             type: 'object',
             properties: {
               id: { type: 'string', description: '记录ID' },
@@ -162,16 +174,18 @@ module.exports = fp(async (fastify, options) => {
     {
       onRequest: options.getAuthenticate('template'),
       schema: {
-        description: '获取消息模版列表',
+        tags: [TEMPLATE_TAG],
+        description: '分页获取消息模版列表，按创建时间倒序；perPage 最大 100',
         summary: '查看消息模版',
         querystring: {
           type: 'object',
           properties: {
             currentPage: { type: 'integer', default: 1, description: '页码' },
-            perPage: { type: 'integer', default: 20, description: '每页数量' },
+            perPage: { type: 'integer', default: 20, description: '每页数量，超过 100 按 100 处理' },
             filter: {
               type: 'object',
               default: {},
+              description: '筛选条件，均为精确匹配',
               properties: {
                 type: { type: 'integer', description: '模版类型: 0=邮件, 1=短信' },
                 code: { type: 'string', description: '模版编码' },
@@ -183,6 +197,7 @@ module.exports = fp(async (fastify, options) => {
         },
         response: {
           200: {
+            description: '消息模版分页结果',
             type: 'object',
             properties: {
               totalCount: { type: 'integer', description: '总数量' },
@@ -190,8 +205,10 @@ module.exports = fp(async (fastify, options) => {
               perPage: { type: 'integer', description: '每页数量' },
               pageData: {
                 type: 'array',
+                description: '当前页消息模版列表',
                 items: {
                   type: 'object',
+                  description: '消息模版',
                   properties: {
                     id: { type: 'string', description: '模版ID' },
                     name: { type: 'string', description: '模版名称' },
@@ -212,13 +229,13 @@ module.exports = fp(async (fastify, options) => {
     async request => {
       const { currentPage = 1, perPage = 20, filter = {} } = request.query;
       const { type, code, level, status } = filter;
-      
+
       const where = {};
       if (type !== undefined) where.type = type;
       if (code) where.code = code;
       if (level !== undefined) where.level = level;
       if (status !== undefined) where.status = status;
-      
+
       return await services.template.list({ filter: where, perPage: Math.min(perPage, 100), currentPage });
     }
   );
@@ -229,7 +246,8 @@ module.exports = fp(async (fastify, options) => {
     {
       onRequest: options.getAuthenticate('template'),
       schema: {
-        description: '获取单个消息模版详情',
+        tags: [TEMPLATE_TAG],
+        description: '获取单个消息模版详情，模版不存在返回 404',
         summary: '查看消息模版详情',
         params: {
           type: 'object',
@@ -240,6 +258,7 @@ module.exports = fp(async (fastify, options) => {
         },
         response: {
           200: {
+            description: '消息模版详情',
             type: 'object',
             properties: {
               id: { type: 'string', description: '模版ID' },

package/libs/controllers/statistics.js

@@ -1,4 +1,7 @@
 const fp = require('fastify-plugin');
+const { success, statistics } = require('../schema/response');
+
+const TAG = '消息-统计';
 
 module.exports = fp(async (fastify, options) => {
   const { services } = fastify[options.name];
@@ -8,7 +11,9 @@ module.exports = fp(async (fastify, options) => {
     {
       onRequest: options.getAuthenticate('statistics'),
       schema: {
+        tags: [TAG],
         summary: '获取消息统计概览',
+        description: '按时间范围汇总消息发送数量、类型/模板分布、每日与按小时趋势，以及模板数量统计；不支持的 range 报错，其他查询异常时返回空统计',
         query: {
           type: 'object',
           properties: {
@@ -17,7 +22,8 @@ module.exports = fp(async (fastify, options) => {
             type: { type: 'integer', description: '按消息类型筛选: 0=邮件, 1=短信' },
             code: { type: 'string', description: '按模板编码筛选' }
           }
-        }
+        },
+        response: success('消息统计数据', statistics)
       }
     },
     async request => {
@@ -32,7 +38,9 @@ module.exports = fp(async (fastify, options) => {
     {
       onRequest: options.getAuthenticate('statistics'),
       schema: {
+        tags: [TAG],
         summary: 'SSE实时推送消息统计数据',
+        description: '以 text/event-stream 长连接按 interval 推送当天的实时统计（发送总数、类型/模板分布、按小时趋势等），客户端断开后停止；range 参数当前未使用',
         query: {
           type: 'object',
           properties: {
@@ -42,7 +50,8 @@ module.exports = fp(async (fastify, options) => {
             code: { type: 'string', description: '按模板编码筛选' },
             interval: { type: 'integer', minimum: 1, default: 5, description: '推送间隔时间（秒），最小1秒，默认5秒' }
           }
-        }
+        },
+        response: { 200: { description: 'text/event-stream 事件流，每条 data 为当天实时统计 JSON' } }
       }
     },
     async (request, reply) => {

package/libs/schema/response.js

@@ -0,0 +1,33 @@
+// 新增的响应 schema 只用于 OpenAPI 文档：字段可空、对象允许额外字段，避免序列化改变实际输出
+const str = description => ({ type: 'string', nullable: true, description });
+const num = description => ({ type: 'number', nullable: true, description });
+// 结构不固定的字段不声明类型，原样输出
+const any = description => ({ description });
+const obj = (description, properties = {}) => ({ type: 'object', nullable: true, additionalProperties: true, description, properties });
+
+const success = (description, schema) => ({ 200: Object.assign({}, schema || { type: 'object', additionalProperties: true }, { description }) });
+
+const MESSAGE_TYPE = '消息类型：0 邮件，1 短信';
+
+const statistics = {
+  type: 'object',
+  additionalProperties: true,
+  properties: {
+    range: str('时间范围：7d / 1m / 3m / 1y'),
+    rangeLabel: str('时间范围名称，如「近7天」'),
+    totalRecords: num('范围内发送的消息总数'),
+    byType: any(`按消息类型统计的发送数，键为类型（${MESSAGE_TYPE}）`),
+    byCode: any('按模板编码统计的发送数，键为模板编码'),
+    recentTrend: any('每日趋势，每项为 { date, count }'),
+    recentTrendByType: any('每日按类型趋势，每项为 { date, type, count }'),
+    hourlyTrend: any('按小时趋势，每项为 { date, hour, count }'),
+    hourlyTrendByType: any('按小时、类型趋势，每项为 { date, hour, type, count }'),
+    templateStats: obj('模板统计（不受时间范围筛选）', {
+      total: num('模板总数'),
+      byStatus: any('按状态统计的模板数，键为状态（0 启用，1 禁用）'),
+      byType: any(`按类型统计的模板数，键为类型（${MESSAGE_TYPE}）`)
+    })
+  }
+};
+
+module.exports = { str, num, any, obj, success, MESSAGE_TYPE, statistics };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kne/fastify-message",
-  "version": "1.0.13",
+  "version": "1.0.14",
   "description": "管理消息发送，支持sms消息，email消息等.",
   "main": "index.js",
   "scripts": {