@linyjs/plugin-docs 0.1.0

package/examples/analytics-plugin/README.md

@@ -0,0 +1,416 @@
+# Analytics Plugin Example
+
+这是一个功能完整的分析插件示例，展示如何在 Linyjs 框架中构建数据分析系统。
+
+## ✨ 功能特点
+
+- **📊 实时数据统计** - 在线用户数、事件计数、系统状态
+- **📈 热门事件分析** - 追踪和统计用户行为事件
+- **🔄 定时数据聚合** - 每小时自动聚合分析数据
+- **👥 用户留存分析** - 分析用户激活和流失率
+- **🎨 响应式仪表盘** - 美观的数据可视化界面
+- **🛰️ 实时更新** - 自动刷新实时统计数据
+- **📅 多时间段分析** - 支持自定义时间范围的数据查询
+
+## 🏗️ 技术架构
+
+### 服务端组件
+
+- **AnalyticsService** - 核心分析逻辑，包括：
+  - 事件追踪和记录
+  - 数据聚合和分析
+  - 用户留存率计算
+  - 实时统计生成
+
+- **AnalyticsController** - REST API 接口，提供：
+  - `POST /api/analytics/track` - 事件追踪
+  - `GET /api/analytics/summary` - 分析摘要
+  - `GET /api/analytics/realtime` - 实时统计
+  - `GET /api/analytics/retention` - 留存分析
+  - `POST /api/analytics/aggregate` - 手动聚合
+
+- **AnalyticsCronService** - 定时任务服务：
+  - 后台每小时自动运行数据聚合
+  - 支持启动/停止生命周期管理
+  - 模拟生产环境下的定时任务
+
+### 客户端组件
+
+- **AnalyticsDashboard** - 主要仪表盘界面：
+  - 实时统计卡片展示
+  - 标签页式导航（概览 / 留存分析）
+  - 自动数据刷新
+  - 响应式布局设计
+
+- **AnalyticsTracker** - 事件追踪器组件：
+  - 可包装任意的点击元素
+  - 自动生成匿名用户 ID（未登录时）
+  - 支持自定义事件数据
+
+- **Charts & Visualization** - 数据可视化组件：
+  - SimpleChart - 简单的条形图组件
+  - StatsCard - 统计卡片组件
+  - RetentionChart - 留存分析图表
+
+## 🚀 快速开始
+
+### 安装依赖
+
+```bash
+npm install @linyjs/server-module-interface @linyjs/client-module-interface
+npm install --save-dev @linyjs/server-module-interface @linyjs/client-module-interface
+```
+
+### 注册插件
+
+在你的 Linyjs 应用中：
+
+```typescript
+// src/server.ts
+import { analyticsServerModule } from '@linyjs/example-analytics-plugin';
+
+const serverConfig = {
+  plugins: [
+    // ... 其他插件
+    analyticsServerModule
+  ]
+};
+```
+
+```typescript
+// src/client.ts  
+import { analyticsClientModule } from '@linyjs/example-analytics-plugin';
+
+const clientConfig = {
+  plugins: [
+    // ... 其他插件
+    analyticsClientModule
+  ]
+};
+```
+
+### 追踪事件
+
+```javascript
+// 追踪页面访问
+fetch('/api/analytics/track', {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify({
+    eventName: 'page_view',
+    userId: getCurrentUserId(), // 或从 cookie/localStorage 获取
+    data: {
+      page: '/products',
+      referrer: document.referrer,
+      sessionId: getSessionId()
+    }
+  })
+});
+
+// 追踪用户操作
+fetch('/api/analytics/track', {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify({
+    eventName: 'product_click',
+    userId: getCurrentUserId(),
+    data: {
+      productId: 'ABC123',
+      category: 'electronics',
+      source: 'product_list'
+    }
+  })
+});
+```
+
+### 使用追踪器组件
+
+```jsx
+import { AnalyticsTracker } from '@linyjs/example-analytics-plugin';
+
+function ProductCard({ product }) {
+  return (
+    <AnalyticsTracker
+      eventName="product_view"
+      userId={currentUserId}
+    >
+      <div className="product-card">
+        <h3>{product.name}</h3>
+        <p>{product.description}</p>
+        <button>查看详情</button>
+      </div>
+    </AnalyticsTracker>
+  );
+}
+```
+
+### 访问仪表盘
+
+启动应用后，在浏览器中访问：
+
+```
+http://localhost:3000/analytics
+```
+
+## 📊 API 文档
+
+### 追踪事件 (POST /api/analytics/track)
+
+```typescript
+interface TrackEventRequest {
+  eventName: string;
+  userId: string;
+  data: {
+    // 任意自定义数据
+    timestamp?: string;
+    [key: string]: any;
+  };
+}
+```
+
+**状态码:**
+- `200 OK` - 事件追踪成功
+- `400 Bad Request` - 缺少必要参数
+- `500 Internal Server Error` - 服务器错误
+
+### 获取分析摘要 (GET /api/analytics/summary)
+
+```typescript
+// 查询参数
+{
+  start?: string; // ISO 日期时间，默认 7 天前
+  end?: string;   // ISO 日期时间，默认当前时间  
+}
+```
+
+**返回数据:**
+```typescript
+{
+  totalEvents: number;
+  eventsByDay: { [date: string]: number };
+  eventTypes: { [eventName: string]: number };
+  activeUsers: number;
+  topEvents: { name: string; count: number }[];
+}
+```
+
+### 获取实时统计 (GET /api/analytics/realtime)
+
+**返回数据:**
+```typescript
+{
+  onlineUsers: number;
+  currentEvents: number;
+  serverTime: string;
+}
+```
+
+### 用户留存分析 (GET /api/analytics/retention)
+
+```typescript
+// 查询参数
+{
+  days?: number; // 天数，默认 7 天
+}
+```
+
+**返回数据:**
+```typescript
+{
+  dayIntervals: string[];               // 日期数组
+  newUsers: number[];                   // 每日新用户
+  returningUsers: number[];             // 每日回访用户
+  retentionRates: string[];             // 每日留存率
+}
+```
+
+## 🏃‍♂️ 使用场景示例
+
+### 1. 电商网站分析
+
+```javascript
+// 用户浏览商品
+trackEvent('product_view', userId, { productId: 'ABC123' });
+
+// 用户加入购物车
+trackEvent('add_to_cart', userId, { 
+  productId: 'ABC123',
+  quantity: 2,
+  value: 19.99
+});
+
+// 用户完成购买
+trackEvent('purchase', userId, {
+  orderId: 'ORD123',
+  value: 99.99,
+  items: 3
+});
+```
+
+### 2. SaaS 应用监控
+
+```javascript
+// 功能使用频次
+trackEvent('feature_used', userId, { feature: 'export_data' });
+
+// 页面停留时间
+trackEvent('page_duration', userId, {
+  page: '/dashboard',
+  duration: 45000 // 毫秒
+});
+
+// 错误追踪
+trackEvent('error_occurred', userId, {
+  errorType: 'validation',
+  page: '/form',
+  message: 'Email format invalid'
+});
+```
+
+## 🔧 自定义扩展
+
+### 添加新的分析指标
+
+```typescript
+// 在 AnalyticsService 中添加新方法
+class CustomAnalyticsService extends AnalyticsService {
+  
+  // 计算平均会话时长
+  async getAverageSessionDuration() {
+    const events = this.getAllEvents();
+    // 实现计算逻辑...
+    return averageDuration;
+  }
+
+  // 分析漏斗转化率
+  async getFunnelConversion(funnelSteps: string[]) {
+    // 实现漏斗分析逻辑...
+    return conversionRates;
+  }
+}
+```
+
+### 集成外部数据源
+
+```typescript
+// 添加外部数据聚合
+class ExternalDataSource {
+  
+  async integrateWithGoogleAnalytics() {
+    // 集成 Google Analytics 数据
+  }
+
+  async integrateWithMixpanel() {
+    // 集成 Mixpanel 数据
+  }
+}
+```
+
+## 🗄️ 生产环境配置
+
+### 数据库集成
+
+在生产环境中，建议将分析数据存储在数据库中：
+
+```typescript
+// 使用 MongoDB
+class MongoAnalyticsService extends AnalyticsService {
+  
+  async saveEvent(event) {
+    const collection = db.collection('events');
+    await collection.insertOne(event);
+  }
+
+  async aggregateEvents(start, end) {
+    const collection = db.collection('events');
+    return await collection.aggregate([ /* 聚合管道 */ ]);
+  }
+}
+```
+
+### Redis 缓存优化
+
+```typescript
+class CachedAnalyticsService {
+  
+  async getRealtimeStats() {
+    // 从 Redis 获取缓存的实时数据
+    let stats = await redis.get('analytics:realtime');
+    
+    if (!stats) {
+      stats = await this.generateRealtimeStats();
+      await redis.setex('analytics:realtime', 60, JSON.stringify(stats));
+    }
+    
+    return JSON.parse(stats);
+  }
+}
+```
+
+## 🧪 测试指南
+
+```typescript
+// 单元测试示例
+describe('AnalyticsService', () => {
+  let service: AnalyticsService;
+
+  beforeEach(() => {
+    service = new AnalyticsService();
+  });
+
+  it('should track events correctly', async () => {
+    const result = await service.trackEvent('test', 'user123', { value: 1 });
+    expect(result.success).toBe(true);
+    expect(result.eventId).toBeDefined();
+  });
+
+  it('should calculate analytics correctly', async () => {
+    await service.trackEvent('click', 'user1', {});
+    await service.trackEvent('click', 'user2', {});
+    
+    const stats = await service.getAnalytics(startDate, endDate);
+    expect(stats.totalEvents).toBe(2);
+    expect(stats.eventTypes['click']).toBe(2);
+  });
+});
+```
+
+## 📈 性能优化建议
+
+1. **批量写入** - 使用批量插入减少数据库操作
+2. **数据采样** - 对大量事件进行采样处理
+3. **异步处理** - 使用消息队列异步处理事件追踪
+4. **缓存策略** - 对常用查询结果进行缓存
+5. **索引优化** - 为数据库字段建立合适的索引
+
+## 🔒 安全和隐私
+
+- 用户数据匿名化
+- 敏感信息脱敏
+- 数据访问权限控制
+- 合规性检查（GDPR、CCPA）
+- 日志审计追踪
+
+## 📚 相关资源
+
+- [Linyjs 插件开发文档](../../docs/plugin-development.md)
+- [React 文档](https://react.dev/)
+- [TypeScript 文档](https://www.typescriptlang.org/)
+- [REST API 设计最佳实践](https://restfulapi.net/)
+
+## 🤝 贡献指南
+
+欢迎提交 Issue 和 Pull Request。请确保：
+
+1. 代码遵循项目编码规范
+2. 添加相应的测试用例
+3. 更新相关文档
+4. 说明修改的原因和影响
+
+---
+
+**示例受到以下工具和服务启发:**
+- Google Analytics
+- Mixpanel
+- Amplitude
+- Matomo

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

@@ -0,0 +1,36 @@
+import React from 'react';
+import type { IModule } from '@linyjs/client-module-interface';
+/**
+ * 实时统计卡片组件
+ */
+declare function StatsCard({ title, value, unit, description }: {
+    title: string;
+    value: React.ReactNode;
+    unit?: string;
+    description?: string;
+}): import("react/jsx-runtime").JSX.Element;
+/**
+ * 图表组件 (简化版)
+ */
+declare function SimpleChart({ data, title, type }: {
+    data: any[];
+    title: string;
+    type?: 'line' | 'bar';
+}): import("react/jsx-runtime").JSX.Element;
+/**
+ * 分析仪表盘主组件
+ */
+declare function AnalyticsDashboard(): import("react/jsx-runtime").JSX.Element;
+/**
+ * 分析事件追踪组件（可嵌入其他页面）
+ */
+declare function AnalyticsTracker({ eventName, userId, children }: {
+    eventName: string;
+    userId?: string;
+    children: React.ReactNode;
+}): import("react/jsx-runtime").JSX.Element;
+/**
+ * 客户端模块
+ */
+export declare const analyticsClientModule: IModule;
+export { AnalyticsDashboard, AnalyticsTracker, StatsCard, SimpleChart };

package/examples/analytics-plugin/dist/client/index.js

@@ -0,0 +1,173 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.analyticsClientModule = void 0;
+exports.AnalyticsDashboard = AnalyticsDashboard;
+exports.AnalyticsTracker = AnalyticsTracker;
+exports.StatsCard = StatsCard;
+exports.SimpleChart = SimpleChart;
+const jsx_runtime_1 = require("react/jsx-runtime");
+const react_1 = __importDefault(require("react"));
+const API_BASE = '/api/analytics';
+/**
+ * 实时统计卡片组件
+ */
+function StatsCard({ title, value, unit = '', description }) {
+    return ((0, jsx_runtime_1.jsxs)("div", { className: "bg-white p-6 rounded-lg shadow-md", children: [(0, jsx_runtime_1.jsx)("h3", { className: "text-sm font-medium text-gray-500 mb-2", children: title }), (0, jsx_runtime_1.jsxs)("div", { className: "flex items-baseline mb-2", children: [(0, jsx_runtime_1.jsx)("span", { className: "text-3xl font-bold text-gray-900", children: value }), unit && (0, jsx_runtime_1.jsx)("span", { className: "text-lg text-gray-500 ml-1", children: unit })] }), description && (0, jsx_runtime_1.jsx)("p", { className: "text-sm text-gray-600", children: description })] }));
+}
+/**
+ * 图表组件 (简化版)
+ */
+function SimpleChart({ data, title, type = 'line' }) {
+    return ((0, jsx_runtime_1.jsxs)("div", { className: "bg-white p-6 rounded-lg shadow-md", children: [(0, jsx_runtime_1.jsx)("h3", { className: "text-lg font-semibold mb-4", children: title }), (0, jsx_runtime_1.jsx)("div", { className: "space-y-2 max-h-64 overflow-y-auto", children: data.map((item, index) => {
+                    if (typeof item === 'object' && item.name && typeof item.count === 'number') {
+                        const maxCount = Math.max(...data.map(d => d.count || 1));
+                        const widthPercent = (item.count / maxCount) * 100;
+                        return ((0, jsx_runtime_1.jsxs)("div", { className: "flex items-center space-x-2", children: [(0, jsx_runtime_1.jsx)("div", { className: "w-24 text-sm text-gray-600 truncate", children: item.name }), (0, jsx_runtime_1.jsx)("div", { className: "flex-1 bg-gray-200 rounded-full h-4", children: (0, jsx_runtime_1.jsx)("div", { className: "bg-blue-600 h-4 rounded-full", style: { width: `${widthPercent}%` } }) }), (0, jsx_runtime_1.jsx)("div", { className: "w-12 text-sm text-gray-900 font-medium", children: item.count })] }, index));
+                    }
+                    return null;
+                }) })] }));
+}
+/**
+ * 留存分析组件
+ */
+function RetentionChart({ data }) {
+    var _a, _b, _c;
+    return ((0, jsx_runtime_1.jsxs)("div", { className: "bg-white p-6 rounded-lg shadow-md", children: [(0, jsx_runtime_1.jsx)("h3", { className: "text-lg font-semibold mb-4", children: "\u7528\u6237\u7559\u5B58\u5206\u6790" }), (0, jsx_runtime_1.jsxs)("div", { className: "grid grid-cols-2 gap-4 mb-4", children: [(0, jsx_runtime_1.jsxs)("div", { children: [(0, jsx_runtime_1.jsx)("h4", { className: "font-medium text-gray-900 mb-2", children: "\u65B0\u7528\u6237" }), (0, jsx_runtime_1.jsx)("div", { className: "space-y-1", children: (_a = data.newUsers) === null || _a === void 0 ? void 0 : _a.map((count, index) => ((0, jsx_runtime_1.jsxs)("div", { className: "flex justify-between text-sm", children: [(0, jsx_runtime_1.jsx)("span", { children: data.dayIntervals[index] }), (0, jsx_runtime_1.jsx)("span", { className: "font-medium", children: count })] }, index))) })] }), (0, jsx_runtime_1.jsxs)("div", { children: [(0, jsx_runtime_1.jsx)("h4", { className: "font-medium text-gray-900 mb-2", children: "\u56DE\u8BBF\u7528\u6237" }), (0, jsx_runtime_1.jsx)("div", { className: "space-y-1", children: (_b = data.returningUsers) === null || _b === void 0 ? void 0 : _b.map((count, index) => ((0, jsx_runtime_1.jsxs)("div", { className: "flex justify-between text-sm", children: [(0, jsx_runtime_1.jsx)("span", { children: data.dayIntervals[index] }), (0, jsx_runtime_1.jsx)("span", { className: "font-medium", children: count })] }, index))) })] })] }), (0, jsx_runtime_1.jsxs)("div", { children: [(0, jsx_runtime_1.jsx)("h4", { className: "font-medium text-gray-900 mb-2", children: "\u7559\u5B58\u7387" }), (0, jsx_runtime_1.jsx)("div", { className: "space-y-1", children: (_c = data.retentionRates) === null || _c === void 0 ? void 0 : _c.map((rate, index) => ((0, jsx_runtime_1.jsxs)("div", { className: "flex justify-between text-sm", children: [(0, jsx_runtime_1.jsx)("span", { children: data.dayIntervals[index] }), (0, jsx_runtime_1.jsxs)("span", { className: parseFloat(rate) > 60 ? 'text-green-600' : parseFloat(rate) > 30 ? 'text-yellow-600' : 'text-red-500', children: [rate, "%"] })] }, index))) })] })] }));
+}
+/**
+ * 分析仪表盘主组件
+ */
+function AnalyticsDashboard() {
+    const [stats, setStats] = react_1.default.useState(null);
+    const [realtimeStats, setRealtimeStats] = react_1.default.useState(null);
+    const [retentionData, setRetentionData] = react_1.default.useState(null);
+    const [loading, setLoading] = react_1.default.useState(true);
+    const [activeTab, setActiveTab] = react_1.default.useState('overview');
+    react_1.default.useEffect(() => {
+        loadAnalytics();
+        // 实时数据每30秒更新一次
+        const interval = setInterval(loadRealTimeStats, 30000);
+        loadRealTimeStats();
+        return () => clearInterval(interval);
+    }, []);
+    const loadAnalytics = async () => {
+        try {
+            setLoading(true);
+            const response = await fetch(`${API_BASE}/summary`);
+            const data = await response.json();
+            setStats(data);
+        }
+        catch (error) {
+            console.error('加载分析数据失败:', error);
+        }
+        finally {
+            setLoading(false);
+        }
+    };
+    const loadRealTimeStats = async () => {
+        try {
+            const response = await fetch(`${API_BASE}/realtime`);
+            const data = await response.json();
+            setRealtimeStats(data);
+        }
+        catch (error) {
+            console.error('加载实时数据失败:', error);
+        }
+    };
+    const loadRetentionData = async () => {
+        try {
+            const response = await fetch(`${API_BASE}/retention`);
+            const data = await response.json();
+            setRetentionData(data);
+        }
+        catch (error) {
+            console.error('加载留存数据失败:', error);
+        }
+    };
+    react_1.default.useEffect(() => {
+        if (activeTab === 'retention' && !retentionData) {
+            loadRetentionData();
+        }
+    }, [activeTab, retentionData]);
+    if (loading) {
+        return ((0, jsx_runtime_1.jsx)("div", { className: "min-h-screen bg-gray-50 flex items-center justify-center", children: (0, jsx_runtime_1.jsxs)("div", { className: "text-center", children: [(0, jsx_runtime_1.jsx)("div", { className: "animate-spin rounded-full h-12 w-12 border-b-2 border-blue-600 mx-auto mb-4" }), (0, jsx_runtime_1.jsx)("p", { className: "text-gray-600", children: "\u52A0\u8F7D\u5206\u6790\u6570\u636E\u4E2D..." })] }) }));
+    }
+    return ((0, jsx_runtime_1.jsxs)("div", { className: "min-h-screen bg-gray-50", children: [(0, jsx_runtime_1.jsx)("nav", { className: "bg-white shadow-sm border-b", children: (0, jsx_runtime_1.jsx)("div", { className: "max-w-7xl mx-auto px-4", children: (0, jsx_runtime_1.jsxs)("div", { className: "flex justify-between items-center py-4", children: [(0, jsx_runtime_1.jsx)("h1", { className: "text-2xl font-bold text-gray-900", children: "\u5206\u6790\u4EEA\u8868\u76D8" }), (0, jsx_runtime_1.jsx)("button", { onClick: loadAnalytics, className: "px-4 py-2 text-sm border border-gray-300 rounded-md hover:bg-gray-50", children: "\u5237\u65B0\u6570\u636E" })] }) }) }), (0, jsx_runtime_1.jsxs)("div", { className: "max-w-7xl mx-auto px-4 py-6", children: [(0, jsx_runtime_1.jsxs)("div", { className: "flex space-x-1 mb-6", children: [(0, jsx_runtime_1.jsx)("button", { onClick: () => setActiveTab('overview'), className: `px-4 py-2 text-sm font-medium rounded-md ${activeTab === 'overview'
+                                    ? 'bg-blue-600 text-white'
+                                    : 'text-gray-500 hover:text-gray-700'}`, children: "\u6982\u89C8" }), (0, jsx_runtime_1.jsx)("button", { onClick: () => setActiveTab('retention'), className: `px-4 py-2 text-sm font-medium rounded-md ${activeTab === 'retention'
+                                    ? 'bg-blue-600 text-white'
+                                    : 'text-gray-500 hover:text-gray-700'}`, children: "\u7559\u5B58\u5206\u6790" })] }), activeTab === 'overview' ? (
+                    /* 概览页面 */
+                    (0, jsx_runtime_1.jsxs)("div", { className: "space-y-6", children: [realtimeStats && ((0, jsx_runtime_1.jsxs)("div", { className: "grid grid-cols-1 md:grid-cols-3 gap-6 mb-8", children: [(0, jsx_runtime_1.jsx)(StatsCard, { title: "\u5F53\u524D\u5728\u7EBF\u7528\u6237", value: realtimeStats.onlineUsers || 0, description: "\u5B9E\u65F6\u6D3B\u8DC3\u7528\u6237\u6570" }), (0, jsx_runtime_1.jsx)(StatsCard, { title: "\u5F53\u524D\u4E8B\u4EF6\u6570", value: realtimeStats.currentEvents || 0, description: "\u6BCF\u5206\u949F\u5904\u7406\u7684\u4E8B\u4EF6" }), (0, jsx_runtime_1.jsx)(StatsCard, { title: "\u670D\u52A1\u5668\u65F6\u95F4", value: new Date(realtimeStats.serverTime).toLocaleTimeString(), description: "\u6570\u636E\u66F4\u65B0\u65F6\u95F4" })] })), stats && ((0, jsx_runtime_1.jsxs)("div", { className: "grid grid-cols-1 md:grid-cols-3 gap-6", children: [(0, jsx_runtime_1.jsx)(StatsCard, { title: "\u603B\u4E8B\u4EF6\u6570", value: stats.totalEvents || 0, description: "\u8FC7\u53BB7\u5929\u4E8B\u4EF6\u603B\u6570" }), (0, jsx_runtime_1.jsx)(StatsCard, { title: "\u6D3B\u8DC3\u7528\u6237\u6570", value: stats.activeUsers || 0, description: "\u8FC7\u53BB7\u5929\u6D3B\u8DC3\u7528\u6237" }), (0, jsx_runtime_1.jsx)(StatsCard, { title: "\u4E8B\u4EF6\u7C7B\u578B\u6570", value: Object.keys(stats.eventTypes || {}).length, description: "\u4E0D\u540C\u7C7B\u578B\u7684\u4E8B\u4EF6" })] })), stats && stats.topEvents && ((0, jsx_runtime_1.jsxs)("div", { className: "grid grid-cols-1 lg:grid-cols-2 gap-6", children: [(0, jsx_runtime_1.jsx)(SimpleChart, { data: stats.topEvents, title: "\u70ED\u95E8\u4E8B\u4EF6\u5206\u6790" }), (0, jsx_runtime_1.jsxs)("div", { className: "bg-white p-6 rounded-lg shadow-md", children: [(0, jsx_runtime_1.jsx)("h3", { className: "text-lg font-semibold mb-4", children: "\u4E8B\u4EF6\u7C7B\u578B\u5206\u5E03" }), (0, jsx_runtime_1.jsx)("div", { className: "space-y-2", children: Object.entries(stats.eventTypes || {}).map(([name, count]) => ((0, jsx_runtime_1.jsxs)("div", { className: "flex justify-between items-center", children: [(0, jsx_runtime_1.jsx)("span", { className: "text-sm text-gray-600", children: name }), (0, jsx_runtime_1.jsx)("span", { className: "font-medium", children: count })] }, name))) })] })] }))] })) : (
+                    /* 留存分析页面 */
+                    retentionData ? ((0, jsx_runtime_1.jsx)("div", { className: "grid grid-cols-1 gap-6", children: (0, jsx_runtime_1.jsx)(RetentionChart, { data: retentionData }) })) : ((0, jsx_runtime_1.jsx)("div", { className: "text-center py-12", children: (0, jsx_runtime_1.jsx)("button", { onClick: loadRetentionData, className: "px-6 py-2 bg-blue-600 text-white rounded-md hover:bg-blue-700", children: "\u52A0\u8F7D\u7559\u5B58\u6570\u636E" }) }))), !loading && !stats && ((0, jsx_runtime_1.jsxs)("div", { className: "text-center py-12", children: [(0, jsx_runtime_1.jsx)("p", { className: "text-gray-500 mb-4", children: "\u6682\u65E0\u5206\u6790\u6570\u636E" }), (0, jsx_runtime_1.jsx)("p", { className: "text-sm text-gray-400", children: "\u5F00\u59CB\u6536\u96C6\u5E94\u7528\u4F7F\u7528\u6570\u636E\u540E\uFF0C\u8FD9\u91CC\u5C06\u663E\u793A\u8BE6\u7EC6\u7684\u5206\u6790\u62A5\u544A" })] }))] })] }));
+}
+/**
+ * 分析事件追踪组件（可嵌入其他页面）
+ */
+function AnalyticsTracker({ eventName, userId, children }) {
+    const trackEvent = async () => {
+        try {
+            await fetch(`${API_BASE}/track`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({
+                    eventName,
+                    userId: userId || 'anonymous-' + Date.now(),
+                    data: { timestamp: new Date().toISOString() }
+                })
+            });
+        }
+        catch (error) {
+            console.error('追踪事件失败:', error);
+        }
+    };
+    return ((0, jsx_runtime_1.jsx)("div", { onClick: trackEvent, children: children }));
+}
+/**
+ * 客户端模块
+ */
+exports.analyticsClientModule = {
+    name: 'analyticsClient',
+    serviceDefs: [
+        {
+            serviceTag: 'analyticsRoute',
+            serviceImpl: class AnalyticsRouteService {
+                constructor() {
+                    this.basePath = '/analytics';
+                }
+                getRoutes() {
+                    return [
+                        {
+                            path: '/',
+                            component: AnalyticsDashboard,
+                            key: 'analytics-dashboard',
+                            meta: {
+                                title: '分析仪表盘 - linyjs分析插件',
+                                description: '查看应用使用统计和用户行为分析'
+                            }
+                        }
+                    ];
+                }
+            },
+            meta: { usageType: 'route' }
+        },
+        {
+            serviceTag: 'analyticsComponent',
+            serviceImpl: class AnalyticsComponentService {
+                getComponents() {
+                    return {
+                        AnalyticsDashboard,
+                        AnalyticsTracker,
+                        StatsCard,
+                        SimpleChart
+                    };
+                }
+            },
+            meta: { usageType: 'component' }
+        }
+    ]
+};

package/examples/analytics-plugin/dist/index.d.ts

@@ -0,0 +1,64 @@
+export { analyticsServerModule } from './server';
+export { analyticsClientModule } from './client';
+declare const analyticsPlugin: {
+    server: import("@linyjs/server-module-interface", { with: { "resolution-mode": "import" } }).IModule;
+    client: import("@linyjs/client-module-interface", { with: { "resolution-mode": "import" } }).IModule;
+};
+export default analyticsPlugin;
+/**
+ * @module @linyjs/example-analytics-plugin
+ *
+ * Analytics Plugin Example
+ * ===============
+ *
+ * Features:
+ * - 📊 Real-time analytics dashboard
+ * - 📈 User behavior tracking
+ * - 🔄 Hourly data aggregation (cron job)
+ * - 📈 User retention analysis
+ * - 🌊 Live metrics monitoring
+ * - 📱 Responsive web interface
+ *
+ * Server-side:
+ * - AnalyticsService: Core analytics logic
+ * - AnalyticsController: REST API endpoints
+ * - AnalyticsCronService: Background aggregation task
+ *
+ * Client-side:
+ * - AnalyticsDashboard: Main dashboard UI
+ * - AnalyticsTracker: Event tracking utility
+ * - Visual charts and metrics display
+ *
+ * API Endpoints:
+ * - POST /api/analytics/track - Track events
+ * - GET /api/analytics/summary - Get analytics summary
+ * - GET /api/analytics/realtime - Get real-time stats
+ * - GET /api/analytics/retention - Get user retention
+ * - POST /api/analytics/aggregate - Manual aggregation
+ *
+ * Usage:
+ *
+ * 1. Include in your Linyjs app:
+ * ```typescript
+ * import { analyticsServerModule } from '@linyjs/example-analytics-plugin';
+ *
+ * // In server config
+ * plugins: [analyticsServerModule]
+ * ```
+ *
+ * 2. Track events from client:
+ * ```javascript
+ * fetch('/api/analytics/track', {
+ *   method: 'POST',
+ *   headers: { 'Content-Type': 'application/json' },
+ *   body: JSON.stringify({
+ *     eventName: 'page_view',
+ *     userId: 'user123',
+ *     data: { page: '/home' }
+ *   })
+ * });
+ * ```
+ *
+ * 3. View analytics dashboard:
+ * Access at `/analytics` route in your app
+ */