@linyjs/plugin-docs 0.0.13

package/examples/analytics-plugin/src/server/index.ts

@@ -0,0 +1,349 @@
+import type { IModule, IServiceDef } from '@linyjs/server-module-interface';
+
+/**
+ * 分析数据服务 - 收集和聚合应用使用数据
+ */
+class AnalyticsService {
+  private metrics: Map<string, any[]> = new Map();
+  private users: Map<string, any> = new Map();
+
+  /**
+   * 记录用户行为事件
+   */
+  async trackEvent(eventName: string, userId: string, data: any) {
+    const event = {
+      id: Date.now(),
+      eventName,
+      userId,
+      timestamp: new Date().toISOString(),
+      data
+    };
+
+    if (!this.metrics.has(eventName)) {
+      this.metrics.set(eventName, []);
+    }
+
+    this.metrics.get(eventName)!.push(event);
+
+    return { success: true, eventId: event.id };
+  }
+
+  /**
+   * 获取指定时间范围内的统计汇总
+   */
+  async getAnalytics(startDate: string, endDate: string) {
+    const start = new Date(startDate);
+    const end = new Date(endDate);
+
+    const result: any = {
+      totalEvents: 0,
+      eventsByDay: {},
+      eventTypes: {},
+      activeUsers: 0,
+      topEvents: []
+    };
+
+    // 统计各类事件
+    for (const [eventName, events] of this.metrics.entries()) {
+      const filtered = events.filter(event => {
+        const eventDate = new Date(event.timestamp);
+        return eventDate >= start && eventDate <= end;
+      });
+
+      if (filtered.length > 0) {
+        result.eventTypes[eventName] = filtered.length;
+        result.totalEvents += filtered.length;
+
+        // 统计每日事件
+        filtered.forEach(event => {
+          const day = event.timestamp.split('T')[0];
+          result.eventsByDay[day] = (result.eventsByDay[day] || 0) + 1;
+        });
+
+        // 记录活跃用户
+        const uniqueUsers = new Set(filtered.map(e => e.userId));
+        result.activeUsers = Math.max(result.activeUsers, uniqueUsers.size);
+      }
+    }
+
+    // 计算热门事件
+    result.topEvents = Object.entries(result.eventTypes)
+      .sort(([,a], [,b]) => (b as number) - (a as number))
+      .slice(0, 10)
+      .map(([name, count]) => ({ name, count }));
+
+    return result;
+  }
+
+  /**
+   * 获取实时在线用户数（模拟）
+   */
+  async getRealTimeStats() {
+    // 模拟实时数据
+    const onlineUsers = Math.floor(Math.random() * 100) + 50;
+    const currentEvents = Math.floor(Math.random() * 20) + 5;
+
+    return {
+      onlineUsers,
+      currentEvents,
+      serverTime: new Date().toISOString()
+    };
+  }
+
+  /**
+   * 定时聚合任务 - 每小时运行一次
+   */
+  async runHourlyAggregation() {
+    const now = new Date();
+    const hourStart = new Date(now.getFullYear(), now.getMonth(), now.getDate(), now.getHours());
+    const hourEnd = new Date(hourStart.getTime() + 60 * 60 * 1000);
+
+    const hourData = await this.getAnalytics(hourStart.toISOString(), hourEnd.toISOString());
+
+    // 这里可以将聚合数据保存到数据库，现在只返回
+    return {
+      period: `${hourStart.toISOString()} to ${hourEnd.toISOString()}`,
+      summary: hourData
+    };
+  }
+
+  /**
+   * 用户留存率分析
+   */
+  async getUserRetention(days: number = 7) {
+    const now = new Date();
+    const retentionData: any = {
+      dayIntervals: [],
+      newUsers: [],
+      returningUsers: []
+    };
+
+    // 模拟留存率数据
+    for (let i = 0; i < days; i++) {
+      const date = new Date(now.getTime() - i * 24 * 60 * 60 * 1000);
+      const dayKey = date.toISOString().split('T')[0];
+
+      retentionData.dayIntervals.push(dayKey);
+      retentionData.newUsers.push(Math.floor(Math.random() * 50) + 10);
+      retentionData.returningUsers.push(Math.floor(Math.random() * 30) + 5);
+    }
+
+    // 计算留存率
+    retentionData.retentionRates = retentionData.returningUsers.map((returning: number, index: number) => {
+      const newUsers = retentionData.newUsers[index] || 1;
+      return ((returning / newUsers) * 100).toFixed(1);
+    });
+
+    return retentionData;
+  }
+}
+
+/**
+ * 分析控制器 - 提供API接口
+ */
+class AnalyticsController {
+  private analyticsService: AnalyticsService;
+
+  constructor() {
+    this.analyticsService = new AnalyticsService();
+  }
+
+  getRoutes() {
+    return [
+      // POST /api/analytics/track - 记录事件
+      {
+        method: 'POST' as const,
+        path: '/api/analytics/track',
+        middlewares: [],
+        responseType: 'json' as const,
+        handler: async (params: any, ctx: any) => {
+          try {
+            const { eventName, userId, data } = params.body;
+
+            if (!eventName || !userId) {
+              return {
+                status: 400,
+                data: { error: 'eventName and userId are required' }
+              };
+            }
+
+            const result = await this.analyticsService.trackEvent(eventName, userId, data);
+            return { success: true, data: result };
+          } catch (error: any) {
+            return {
+              status: 500,
+              data: { error: error.message }
+            };
+          }
+        }
+      },
+
+      // GET /api/analytics/summary - 获取分析摘要
+      {
+        method: 'GET' as const,
+        path: '/api/analytics/summary',
+        middlewares: [],
+        responseType: 'json' as const,
+        handler: async (params: any, ctx: any) => {
+          try {
+            const startDate = params.query?.start || new Date(Date.now() - 7 * 24 * 60 * 60 * 1000).toISOString();
+            const endDate = params.query?.end || new Date().toISOString();
+
+            const result = await this.analyticsService.getAnalytics(startDate, endDate);
+            return result;
+          } catch (error: any) {
+            return {
+              status: 500,
+              data: { error: error.message }
+            };
+          }
+        }
+      },
+
+      // GET /api/analytics/realtime - 获取实时统计
+      {
+        method: 'GET' as const,
+        path: '/api/analytics/realtime',
+        middlewares: [],
+        responseType: 'json' as const,
+        handler: async (params: any, ctx: any) => {
+          try {
+            const result = await this.analyticsService.getRealTimeStats();
+            return result;
+          } catch (error: any) {
+            return {
+              status: 500,
+              data: { error: error.message }
+            };
+          }
+        }
+      },
+
+      // GET /api/analytics/retention - 用户留存分析
+      {
+        method: 'GET' as const,
+        path: '/api/analytics/retention',
+        middlewares: [],
+        responseType: 'json' as const,
+        handler: async (params: any, ctx: any) => {
+          try {
+            const days = parseInt(params.query?.days || '7');
+            const result = await this.analyticsService.getUserRetention(days);
+            return result;
+          } catch (error: any) {
+            return {
+              status: 500,
+              data: { error: error.message }
+            };
+          }
+        }
+      },
+
+      // POST /api/analytics/aggregate - 手动触发聚合 (管理员用)
+      {
+        method: 'POST' as const,
+        path: '/api/analytics/aggregate',
+        middlewares: [],
+        responseType: 'json' as const,
+        handler: async (params: any, ctx: any) => {
+          try {
+            const result = await this.analyticsService.runHourlyAggregation();
+            return { success: true, data: result };
+          } catch (error: any) {
+            return {
+              status: 500,
+              data: { error: error.message }
+            };
+          }
+        }
+      }
+    ];
+  }
+}
+
+/**
+ * 定时任务服务
+ */
+class AnalyticsCronService {
+  private analyticsService: AnalyticsService;
+  private intervalId: NodeJS.Timeout | null = null;
+
+  constructor() {
+    this.analyticsService = new AnalyticsService();
+  }
+
+  /**
+   * 启动定时聚合任务
+   */
+  startHourlyAggregation() {
+    // 每小时执行一次聚合
+    this.intervalId = setInterval(async () => {
+      try {
+        const result = await this.analyticsService.runHourlyAggregation();
+        console.log('Analytics aggregation completed:', result.period);
+      } catch (error) {
+        console.error('Analytics aggregation failed:', error);
+      }
+    }, 60 * 60 * 1000); // 1小时
+
+    console.log('Started analytics hourly aggregation');
+  }
+
+  /**
+   * 停止定时聚合任务
+   */
+  stopHourlyAggregation() {
+    if (this.intervalId) {
+      clearInterval(this.intervalId);
+      this.intervalId = null;
+      console.log('Stopped analytics hourly aggregation');
+    }
+  }
+
+  /**
+   * 插件启动时调用
+   */
+  onModuleInit() {
+    this.startHourlyAggregation();
+  }
+
+  /**
+   * 插件销毁时调用
+   */
+  onModuleDestroy() {
+    this.stopHourlyAggregation();
+  }
+}
+
+const analyticsControllerDef: IServiceDef = {
+  serviceTag: 'analyticsController',
+  serviceImpl: AnalyticsController,
+  meta: { usageType: 'controller' }
+};
+
+const analyticsCronDef: IServiceDef = {
+  serviceTag: 'analyticsCron',
+  serviceImpl: AnalyticsCronService,
+  meta: {
+    usageType: 'service',
+    lifecycle: {
+      init: 'onModuleInit',
+      destroy: 'onModuleDestroy'
+    }
+  }
+};
+
+/**
+ * 服务端模块
+ */
+export const analyticsServerModule: IModule = {
+  name: 'analyticsServer',
+  serviceDefs: [analyticsControllerDef, analyticsCronDef]
+};
+
+// 导出服务类供其他插件使用
+export {
+  AnalyticsService,
+  AnalyticsController,
+  AnalyticsCronService
+};

package/examples/analytics-plugin/tsconfig.json

@@ -0,0 +1,21 @@
+{
+  "compilerOptions": {
+    "target": "ES2017",
+    "module": "NodeNext",
+    "lib": ["ES2017", "DOM"],
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "allowSyntheticDefaultImports": true,
+    "strict": true,
+    "forceConsistentCasingInFileNames": true,
+    "moduleResolution": "NodeNext",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "jsx": "react-jsx",
+    "declaration": true,
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules"]
+}

package/examples/blog-plugin/README.md

@@ -0,0 +1,319 @@
+# Blog Plugin Example
+
+这是一个完整的博客插件示例，展示了 linyjs 插件开发的核心功能。
+
+## 功能特性
+
+- ✅ 文章发布和管理
+- ✅ 文章列表和详情页面  
+- ✅ 用户权限控制
+- ✅ MongoDB 数据持久化
+- ✅ RESTful API 设计
+- ✅ 响应式前端界面
+
+## 快速开始
+
+### 前置要求
+
+- Node.js >= 18.0
+- MongoDB >= 5.0
+- npm 或 yarn
+
+### 安装和运行
+
+```bash
+# 1. 安装依赖
+cd blog-plugin
+npm install
+
+# 2. 配置 MongoDB 连接
+export MONGODB_URI="mongodb://localhost:27017/linyjs-blog"
+
+# 3. 构建插件
+npm run build
+
+# 4. 启动开发服务器
+npm run dev
+```
+
+## 项目结构
+
+```
+blog-plugin/
+├── src/
+│   ├── server/
+│   │   ├── controllers/
+│   │   │   └── article-controller.ts    # 文章 CRUD 控制器
+│   │   ├── services/
+│   │   │   └── article-service.ts      # 业务逻辑层
+│   │   └── index.ts                 # 服务端入口
+│   ├── client/
+│   │   ├── components/
+│   │   │   ├── ArticleList.tsx         # 文章列表组件
+│   │   │   ├── ArticleDetail.tsx       # 文章详情组件
+│   │   │   └── ArticleForm.tsx         # 文章表单组件
+│   │   ├── pages/
+│   │   │   ├── ArticleListPage.tsx     # 文章列表页面
+│   │   │   ├── ArticleDetailPage.tsx   # 文章详情页面
+│   │   │   └── ArticleEditPage.tsx     # 文章编辑页面
+│   │   └── index.tsx                # 客户端入口
+│   └── shared/
+│       ├── types.ts                   # 共享类型定义
+│       └── constants.ts               # 共享常量
+├── package.json
+├── tsconfig.json
+└── README.md
+```
+
+## API 文档
+
+### 获取文章列表
+
+```http
+GET /api/articles
+```
+
+**查询参数:**
+- `page` - 页码 (默认: 1)
+- `limit` - 每页数量 (默认: 10)
+- `status` - 状态过滤: `published` | `draft` | `all` (默认: `published`)
+
+**响应示例:**
+```json
+{
+  "data": [
+    {
+      "id": "60b8f7d5f1b2c3d4e5f6a7b8",
+      "title": "我的第一篇文章",
+      "excerpt": "文章摘要内容...",
+      "author": "作者名",
+      "status": "published",
+      "createdAt": "2023-01-01T00:00:00.000Z",
+      "updatedAt": "2023-01-01T00:00:00.000Z"
+    }
+  ],
+  "total": 25,
+  "page": 1,
+  "limit": 10,
+  "totalPages": 3
+}
+```
+
+### 创建文章
+
+```http
+POST /api/articles
+Authorization: Bearer <token>
+Content-Type: application/json
+```
+
+**请求体:**
+```json
+{
+  "title": "文章标题",
+  "content": "文章内容...",
+  "excerpt": "文章摘要",
+  "status": "draft" | "published"
+}
+```
+
+### 获取文章详情
+
+```http
+GET /api/articles/{id}
+```
+
+### 更新文章
+
+```http
+PUT /api/articles/{id}
+Authorization: Bearer <token>
+```
+
+### 删除文章
+
+```http
+DELETE /api/articles/{id}
+Authorization: Bearer <token>
+```
+
+## 权限控制
+
+- **游客**: 只能查看已发布的文章
+- **作者**: 可以创建、编辑、删除自己的文章
+- **管理员**: 可以管理所有文章
+
+## 开发说明
+
+### 服务端模块
+
+服务端模块注册了文章控制器和服务:
+
+```typescript
+// src/server/index.ts
+export const blogServerModule: IModule = {
+  name: 'blogServer',
+  moduleDependencies: ['mdb', 'auth'],
+  serviceDefs: [
+    articleControllerDef,
+    articleServiceDef
+  ]
+};
+```
+
+### 客户端模块
+
+客户端模块提供了文章相关的页面和组件:
+
+```typescript
+// src/client/index.tsx
+export const blogClientModule: IModule = {
+  name: 'blogClient',
+  serviceDefs: [
+    articleListRoute,
+    articleDetailRoute,
+    articleEditRoute,
+    articleListComponent,
+    articleDetailComponent,
+    articleFormComponent
+  ]
+};
+```
+
+## 代码示例
+
+### 文章服务 - 数据操作
+
+```typescript
+// src/server/services/article-service.ts
+class ArticleService {
+  constructor(
+    private mongodbService: IMongoDBService,
+    private auth: IAuthService
+  ) {}
+
+  async createArticle(data: CreateArticleDto, userId: string) {
+    const db = this.mongodbService.getDb();
+    const collection = db.collection('articles');
+
+    const article = {
+      ...data,
+      authorId: userId,
+      createdAt: new Date(),
+      updatedAt: new Date()
+    };
+
+    const result = await collection.insertOne(article);
+    return {
+      id: result.insertedId,
+      ...article
+    };
+  }
+
+  async getArticles(filters: ArticleFilters = {}) {
+    const db = this.mongodbService.getDb();
+    const collection = db.collection('articles');
+
+    const query: any = {};
+
+    // 状态过滤
+    if (filters.status && filters.status !== 'all') {
+      query.status = filters.status;
+    } else if (!filters.status) {
+      query.status = 'published'; // 默认只显示已发布
+    }
+
+    const page = filters.page || 1;
+    const limit = Math.min(filters.limit || 10, 100);
+    const skip = (page - 1) * limit;
+
+    const [total, articles] = await Promise.all([
+      collection.countDocuments(query),
+      collection.find(query)
+        .sort({ createdAt: -1 })
+        .skip(skip)
+        .limit(limit)
+        .project({
+          content: 0 // 不返回完整内容
+        })
+        .toArray()
+    ]);
+
+    return {
+      data: articles,
+      total,
+      page,
+      limit,
+      totalPages: Math.ceil(total / limit)
+    };
+  }
+}
+```
+
+### 文章列表组件
+
+```typescript
+// src/client/components/ArticleList.tsx
+function ArticleList() {
+  const [articles, setArticles] = useState<Article[]>([]);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    loadArticles();
+  }, []);
+
+  const loadArticles = async () => {
+    try {
+      setLoading(true);
+      const response = await fetch('/api/articles');
+      const result = await response.json();
+      setArticles(result.data);
+    } catch (err) {
+      setError('加载文章失败');
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  if (loading) return <div>加载中...</div>;
+  if (error) return <div>错误: {error}</div>;
+
+  return (
+    <div className="article-list">
+      {articles.map(article => (
+        <ArticleCard key={article.id} article={article} />
+      ))}
+    </div>
+  );
+}
+```
+
+## 测试
+
+```bash
+# 构建测试
+npm run build
+
+# 包格式验证
+npx @linyjs/cli pack
+npx @linyjs/cli validate *.mpk
+```
+
+## 相关链接
+
+- 📖 [插件开发指南](../../docs/getting-started/quick-start.md)
+- 🔧 [API 参考](../../docs/api-reference/server-interface.md)
+- 📚 [服务端模块指南](../../docs/guides/server-module.md)
+- 🎨 [客户端模块指南](../../docs/guides/client-module.md)
+- 💾 [数据持久化](../../docs/guides/data-persistence.md) - 使用 MongoDB 模块
+- 🔐 [用户认证](../../docs/guides/authentication.md) - 使用 Auth 模块  
+- 🛡️ [权限管理](../../docs/guides/permissions.md) - 使用 Permission 模块
+
+## 许可证
+
+MIT License
+
+---
+
+这是一个完整的博客插件示例，可以作为开发类似插件的参考。查看完整实现代码了解更多细节。

package/examples/blog-plugin/dist/client/index.d.ts

@@ -0,0 +1,22 @@
+import type { IModule } from '@linyjs/client-module-interface';
+/**
+ * 文章列表组件
+ */
+declare function ArticleList(): import("react/jsx-runtime").JSX.Element;
+/**
+ * 文章详情组件
+ */
+declare function ArticleDetail(): import("react/jsx-runtime").JSX.Element;
+/**
+ * 文章编辑表单组件
+ */
+declare function ArticleForm(): import("react/jsx-runtime").JSX.Element;
+/**
+ * 博客主页组件
+ */
+declare function BlogHome(): import("react/jsx-runtime").JSX.Element;
+/**
+ * 客户端模块定义
+ */
+export declare const blogClientModule: IModule;
+export { BlogHome, ArticleList, ArticleDetail, ArticleForm };