add event

Date Format Handling for ClickHouse Events API.md

@@ -0,0 +1,47 @@
+
+# Date Format Handling for ClickHouse Events API
+
+## Problem Description
+
+The event tracking API was experiencing issues with date format compatibility when inserting records into the ClickHouse database. ClickHouse has specific requirements for datetime formats, particularly for its `DateTime64` type fields, which weren't being properly addressed in the original implementation.
+
+## Root Cause
+
+- JavaScript's default date serialization (`toISOString()`) produces formats like `2023-08-24T12:34:56.789Z`, which include `T` as a separator and `Z` as the UTC timezone indicator
+- ClickHouse prefers datetime values in the format `YYYY-MM-DD HH:MM:SS.SSS` for seamless parsing
+- The mismatch between these formats was causing insertion errors in the database
+
+## Solution Implemented
+
+We created a `formatDateTime` utility function that properly formats JavaScript Date objects for ClickHouse compatibility:
+
+```typescript
+const formatDateTime = (date: Date) => {
+  return date.toISOString().replace('T', ' ').replace('Z', '');
+};
+```
+
+This function:
+1. Takes a JavaScript Date object as input
+2. Converts it to ISO format string
+3. Replaces the 'T' separator with a space
+4. Removes the trailing 'Z' UTC indicator
+
+The solution was applied to all date fields in the event payload:
+- `event_time`
+- `link_created_at`
+- `link_expires_at`
+
+## Additional Improvements
+
+- We standardized date handling by using a consistent `currentTime` variable
+- Added type checking for JSON fields to ensure proper serialization
+- Improved error handling for date parsing failures
+
+## Best Practices for ClickHouse Date Handling
+
+1. Always format dates as `YYYY-MM-DD HH:MM:SS.SSS` when inserting into ClickHouse
+2. Use consistent date handling utilities across your application
+3. Consider timezone handling explicitly when needed
+4. For query parameters, use ClickHouse's `parseDateTimeBestEffort` function when possible
+5. Test with various date formats and edge cases to ensure robustness

app/(app)/analytics/devices/page.tsx

@@ -0,0 +1,309 @@
+"use client";
+
+import { useState, useEffect, useRef } from 'react';
+import { fetchData } from '@/app/api/utils';
+import { DeviceAnalytics } from '@/app/api/types';
+import { Chart, PieController, ArcElement, Tooltip, Legend, CategoryScale, LinearScale } from 'chart.js';
+
+// 注册Chart.js组件
+Chart.register(PieController, ArcElement, Tooltip, Legend, CategoryScale, LinearScale);
+
+export default function DeviceAnalyticsPage() {
+  const [deviceData, setDeviceData] = useState<DeviceAnalytics | null>(null);
+  const [isLoading, setIsLoading] = useState(true);
+  const [error, setError] = useState<string | null>(null);
+  const [dateRange, setDateRange] = useState({
+    from: new Date('2024-02-01'),
+    to: new Date('2025-03-05')
+  });
+
+  // 创建图表引用
+  const deviceTypesChartRef = useRef<HTMLCanvasElement>(null);
+  const browsersChartRef = useRef<HTMLCanvasElement>(null);
+  const osChartRef = useRef<HTMLCanvasElement>(null);
+  
+  // 图表实例引用
+  const deviceTypesChartInstance = useRef<Chart | null>(null);
+  const browsersChartInstance = useRef<Chart | null>(null);
+  const osChartInstance = useRef<Chart | null>(null);
+
+  // 颜色配置
+  const COLORS = {
+    deviceTypes: ['rgba(59, 130, 246, 0.8)', 'rgba(96, 165, 250, 0.8)', 'rgba(147, 197, 253, 0.8)', 'rgba(191, 219, 254, 0.8)', 'rgba(219, 234, 254, 0.8)'],
+    browsers: ['rgba(16, 185, 129, 0.8)', 'rgba(52, 211, 153, 0.8)', 'rgba(110, 231, 183, 0.8)', 'rgba(167, 243, 208, 0.8)', 'rgba(209, 250, 229, 0.8)'],
+    os: ['rgba(239, 68, 68, 0.8)', 'rgba(248, 113, 113, 0.8)', 'rgba(252, 165, 165, 0.8)', 'rgba(254, 202, 202, 0.8)', 'rgba(254, 226, 226, 0.8)']
+  };
+
+  useEffect(() => {
+    const fetchDeviceData = async () => {
+      try {
+        setIsLoading(true);
+        setError(null);
+
+        const response = await fetch(`/api/events/devices?startTime=${dateRange.from.toISOString().split('T')[0]}T00:00:00Z&endTime=${dateRange.to.toISOString().split('T')[0]}T23:59:59Z`);
+        if (!response.ok) throw new Error('Failed to fetch device data');
+        
+        const data = await response.json();
+        setDeviceData(data.data);
+      } catch (err) {
+        setError(err instanceof Error ? err.message : 'An error occurred');
+      } finally {
+        setIsLoading(false);
+      }
+    };
+
+    fetchDeviceData();
+  }, [dateRange]);
+
+  // 初始化和更新图表
+  useEffect(() => {
+    if (!deviceData || isLoading) return;
+
+    // 销毁旧的图表实例
+    if (deviceTypesChartInstance.current) {
+      deviceTypesChartInstance.current.destroy();
+    }
+    if (browsersChartInstance.current) {
+      browsersChartInstance.current.destroy();
+    }
+    if (osChartInstance.current) {
+      osChartInstance.current.destroy();
+    }
+
+    // 创建设备类型图表
+    if (deviceTypesChartRef.current && deviceData.deviceTypes.length > 0) {
+      const ctx = deviceTypesChartRef.current.getContext('2d');
+      if (ctx) {
+        deviceTypesChartInstance.current = new Chart(ctx, {
+          type: 'pie',
+          data: {
+            labels: deviceData.deviceTypes.map(item => item.type),
+            datasets: [{
+              data: deviceData.deviceTypes.map(item => item.count),
+              backgroundColor: COLORS.deviceTypes,
+              borderColor: COLORS.deviceTypes.map(color => color.replace('0.8', '1')),
+              borderWidth: 1
+            }]
+          },
+          options: {
+            responsive: true,
+            plugins: {
+              legend: {
+                position: 'bottom',
+                labels: {
+                  color: 'white'
+                }
+              },
+              tooltip: {
+                callbacks: {
+                  label: function(context) {
+                    const label = context.label || '';
+                    const value = context.raw as number;
+                    const total = (context.chart.data.datasets[0].data as number[]).reduce((a, b) => (a as number) + (b as number), 0);
+                    const percentage = Math.round((value * 100) / total);
+                    return `${label}: ${value} (${percentage}%)`;
+                  }
+                }
+              }
+            }
+          }
+        });
+      }
+    }
+
+    // 创建浏览器图表
+    if (browsersChartRef.current && deviceData.browsers.length > 0) {
+      const ctx = browsersChartRef.current.getContext('2d');
+      if (ctx) {
+        browsersChartInstance.current = new Chart(ctx, {
+          type: 'pie',
+          data: {
+            labels: deviceData.browsers.map(item => item.name),
+            datasets: [{
+              data: deviceData.browsers.map(item => item.count),
+              backgroundColor: COLORS.browsers,
+              borderColor: COLORS.browsers.map(color => color.replace('0.8', '1')),
+              borderWidth: 1
+            }]
+          },
+          options: {
+            responsive: true,
+            plugins: {
+              legend: {
+                position: 'bottom',
+                labels: {
+                  color: 'white'
+                }
+              },
+              tooltip: {
+                callbacks: {
+                  label: function(context) {
+                    const label = context.label || '';
+                    const value = context.raw as number;
+                    const total = (context.chart.data.datasets[0].data as number[]).reduce((a, b) => (a as number) + (b as number), 0);
+                    const percentage = Math.round((value * 100) / total);
+                    return `${label}: ${value} (${percentage}%)`;
+                  }
+                }
+              }
+            }
+          }
+        });
+      }
+    }
+
+    // 创建操作系统图表
+    if (osChartRef.current && deviceData.operatingSystems.length > 0) {
+      const ctx = osChartRef.current.getContext('2d');
+      if (ctx) {
+        osChartInstance.current = new Chart(ctx, {
+          type: 'pie',
+          data: {
+            labels: deviceData.operatingSystems.map(item => item.name),
+            datasets: [{
+              data: deviceData.operatingSystems.map(item => item.count),
+              backgroundColor: COLORS.os,
+              borderColor: COLORS.os.map(color => color.replace('0.8', '1')),
+              borderWidth: 1
+            }]
+          },
+          options: {
+            responsive: true,
+            plugins: {
+              legend: {
+                position: 'bottom',
+                labels: {
+                  color: 'white'
+                }
+              },
+              tooltip: {
+                callbacks: {
+                  label: function(context) {
+                    const label = context.label || '';
+                    const value = context.raw as number;
+                    const total = (context.chart.data.datasets[0].data as number[]).reduce((a, b) => (a as number) + (b as number), 0);
+                    const percentage = Math.round((value * 100) / total);
+                    return `${label}: ${value} (${percentage}%)`;
+                  }
+                }
+              }
+            }
+          }
+        });
+      }
+    }
+
+    // 清理函数
+    return () => {
+      if (deviceTypesChartInstance.current) {
+        deviceTypesChartInstance.current.destroy();
+      }
+      if (browsersChartInstance.current) {
+        browsersChartInstance.current.destroy();
+      }
+      if (osChartInstance.current) {
+        osChartInstance.current.destroy();
+      }
+    };
+  }, [deviceData, isLoading]);
+
+  return (
+    <div className="container mx-auto px-4 py-8">
+      {/* 页面标题 */}
+      <div className="mb-8">
+        <h1 className="text-2xl font-bold text-white">Device Analytics</h1>
+        <p className="mt-2 text-white">Analyze visitor distribution by devices, browsers, and operating systems</p>
+      </div>
+
+      {/* 时间范围选择器 */}
+      <div className="bg-card-bg rounded-xl p-6 mb-8">
+        <div className="grid grid-cols-1 md:grid-cols-2 gap-4">
+          <div>
+            <label className="block text-sm font-medium text-text-secondary mb-1">Start Date</label>
+            <input
+              type="date"
+              className="block w-full px-3 py-2 bg-background border border-card-border rounded-md text-sm"
+              value={dateRange.from.toISOString().split('T')[0]}
+              onChange={e => setDateRange(prev => ({ ...prev, from: new Date(e.target.value) }))}
+            />
+          </div>
+          <div>
+            <label className="block text-sm font-medium text-text-secondary mb-1">End Date</label>
+            <input
+              type="date"
+              className="block w-full px-3 py-2 bg-background border border-card-border rounded-md text-sm"
+              value={dateRange.to.toISOString().split('T')[0]}
+              onChange={e => setDateRange(prev => ({ ...prev, to: new Date(e.target.value) }))}
+            />
+          </div>
+        </div>
+      </div>
+
+      {/* 设备类型分析 */}
+      <div className="grid grid-cols-1 lg:grid-cols-3 gap-8 mb-8">
+        {/* 设备类型 */}
+        <div className="bg-card-bg rounded-xl p-6">
+          <h3 className="text-lg font-medium text-white mb-4">Device Types</h3>
+          {deviceData && deviceData.deviceTypes.length > 0 ? (
+            <div className="h-64">
+              <canvas ref={deviceTypesChartRef} />
+            </div>
+          ) : (
+            <div className="flex justify-center items-center h-64 text-text-secondary">
+              No data available
+            </div>
+          )}
+        </div>
+
+        {/* 浏览器 */}
+        <div className="bg-card-bg rounded-xl p-6">
+          <h3 className="text-lg font-medium text-white mb-4">Browsers</h3>
+          {deviceData && deviceData.browsers.length > 0 ? (
+            <div className="h-64">
+              <canvas ref={browsersChartRef} />
+            </div>
+          ) : (
+            <div className="flex justify-center items-center h-64 text-text-secondary">
+              No data available
+            </div>
+          )}
+        </div>
+
+        {/* 操作系统 */}
+        <div className="bg-card-bg rounded-xl p-6">
+          <h3 className="text-lg font-medium text-white mb-4">Operating Systems</h3>
+          {deviceData && deviceData.operatingSystems.length > 0 ? (
+            <div className="h-64">
+              <canvas ref={osChartRef} />
+            </div>
+          ) : (
+            <div className="flex justify-center items-center h-64 text-text-secondary">
+              No data available
+            </div>
+          )}
+        </div>
+      </div>
+
+      {/* 加载状态 */}
+      {isLoading && (
+        <div className="flex justify-center items-center p-8">
+          <div className="w-8 h-8 border-t-2 border-b-2 border-accent-blue rounded-full animate-spin"></div>
+        </div>
+      )}
+
+      {/* 错误状态 */}
+      {error && (
+        <div className="flex justify-center items-center p-8 text-accent-red">
+          <p>{error}</p>
+        </div>
+      )}
+
+      {/* 无数据状态 */}
+      {!isLoading && !error && !deviceData && (
+        <div className="flex justify-center items-center p-8 text-text-secondary">
+          <p>No device data available</p>
+        </div>
+      )}
+    </div>
+  );
+} 

app/(app)/dashboard/page.tsx

@@ -2,11 +2,11 @@
 
 import { useState, useEffect } from 'react';
 import { addDays, format } from 'date-fns';
-import { DateRangePicker } from '../components/ui/DateRangePicker';
-import TimeSeriesChart from '../components/charts/TimeSeriesChart';
-import GeoAnalytics from '../components/analytics/GeoAnalytics';
-import DeviceAnalytics from '../components/analytics/DeviceAnalytics';
-import { EventsSummary, TimeSeriesData, GeoData, DeviceAnalytics as DeviceAnalyticsType } from '../api/types';
+import { DateRangePicker } from '@/app/components/ui/DateRangePicker';
+import TimeSeriesChart from '@/app/components/charts/TimeSeriesChart';
+import GeoAnalytics from '@/app/components/analytics/GeoAnalytics';
+import DeviceAnalytics from '@/app/components/analytics/DeviceAnalytics';
+import { EventsSummary, TimeSeriesData, GeoData, DeviceAnalytics as DeviceAnalyticsType } from '@/app/api/types';
 
 export default function DashboardPage() {
   const [dateRange, setDateRange] = useState({

app/(app)/events/page.tsx

@@ -1,9 +1,9 @@
 "use client";
 
 import { useState, useEffect } from 'react';
-import { format } from 'date-fns';
-import { DateRangePicker } from '../components/ui/DateRangePicker';
-import { Event } from '../api/types';
+import { addDays, format } from 'date-fns';
+import { DateRangePicker } from '@/app/components/ui/DateRangePicker';
+import { Event } from '@/app/api/types';
 
 export default function EventsPage() {
   const [dateRange, setDateRange] = useState({

app/(app)/layout.tsx

@@ -0,0 +1,66 @@
+import '../globals.css';
+import type { Metadata } from 'next';
+import { Inter } from 'next/font/google';
+import Link from 'next/link';
+
+const inter = Inter({ subsets: ['latin'] });
+
+export const metadata: Metadata = {
+  title: 'ShortURL Analytics',
+  description: 'Analytics dashboard for ShortURL service',
+};
+
+export default function AppLayout({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  return (
+    <div className={inter.className}>
+      <div className="min-h-screen bg-gray-50 dark:bg-gray-900">
+        <nav className="bg-white dark:bg-gray-800 border-b border-gray-200 dark:border-gray-700">
+          <div className="container mx-auto px-4">
+            <div className="flex items-center justify-between h-16">
+              <div className="flex items-center">
+                <Link href="/" className="text-xl font-bold text-gray-900 dark:text-gray-100">
+                  ShortURL Analytics
+                </Link>
+                <div className="hidden md:block ml-10">
+                  <div className="flex items-baseline space-x-4">
+                    <Link
+                      href="/dashboard"
+                      className="text-gray-500 dark:text-gray-400 hover:text-gray-900 dark:hover:text-gray-100 px-3 py-2 rounded-md text-sm font-medium"
+                    >
+                      Dashboard
+                    </Link>
+                    <Link
+                      href="/events"
+                      className="text-gray-500 dark:text-gray-400 hover:text-gray-900 dark:hover:text-gray-100 px-3 py-2 rounded-md text-sm font-medium"
+                    >
+                      Events
+                    </Link>
+                    <Link
+                      href="/analytics/geo"
+                      className="text-gray-500 dark:text-gray-400 hover:text-gray-900 dark:hover:text-gray-100 px-3 py-2 rounded-md text-sm font-medium"
+                    >
+                      Geographic
+                    </Link>
+                    <Link
+                      href="/analytics/devices"
+                      className="text-gray-500 dark:text-gray-400 hover:text-gray-900 dark:hover:text-gray-100 px-3 py-2 rounded-md text-sm font-medium"
+                    >
+                      Devices
+                    </Link>
+                  </div>
+                </div>
+              </div>
+            </div>
+          </div>
+        </nav>
+        <main className="py-10">
+          {children}
+        </main>
+      </div>
+    </div>
+  );
+} 

app/(app)/page.tsx

@@ -0,0 +1,59 @@
+import Link from 'next/link';
+
+export default function Home() {
+  return (
+    <div className="container mx-auto px-4">
+      <div className="max-w-2xl mx-auto py-16">
+        <h1 className="text-4xl font-bold text-gray-900 dark:text-gray-100 mb-8">
+          Welcome to ShortURL Analytics
+        </h1>
+        <div className="grid gap-6">
+          <Link
+            href="/dashboard"
+            className="block p-6 bg-white dark:bg-gray-800 rounded-lg shadow hover:shadow-md transition-shadow"
+          >
+            <h2 className="text-xl font-semibold text-gray-900 dark:text-gray-100 mb-2">
+              Dashboard
+            </h2>
+            <p className="text-gray-600 dark:text-gray-400">
+              View your overall analytics and key metrics
+            </p>
+          </Link>
+          <Link
+            href="/events"
+            className="block p-6 bg-white dark:bg-gray-800 rounded-lg shadow hover:shadow-md transition-shadow"
+          >
+            <h2 className="text-xl font-semibold text-gray-900 dark:text-gray-100 mb-2">
+              Events
+            </h2>
+            <p className="text-gray-600 dark:text-gray-400">
+              Track and analyze event data
+            </p>
+          </Link>
+          <Link
+            href="/analytics/geo"
+            className="block p-6 bg-white dark:bg-gray-800 rounded-lg shadow hover:shadow-md transition-shadow"
+          >
+            <h2 className="text-xl font-semibold text-gray-900 dark:text-gray-100 mb-2">
+              Geographic Analysis
+            </h2>
+            <p className="text-gray-600 dark:text-gray-400">
+              Explore visitor locations and geographic patterns
+            </p>
+          </Link>
+          <Link
+            href="/analytics/devices"
+            className="block p-6 bg-white dark:bg-gray-800 rounded-lg shadow hover:shadow-md transition-shadow"
+          >
+            <h2 className="text-xl font-semibold text-gray-900 dark:text-gray-100 mb-2">
+              Device Analytics
+            </h2>
+            <p className="text-gray-600 dark:text-gray-400">
+              Understand how users access your links
+            </p>
+          </Link>
+        </div>
+      </div>
+    </div>
+  );
+} 

app/(swagger)/swagger/page.tsx

@@ -0,0 +1,997 @@
+"use client";
+
+import { useEffect } from 'react';
+import SwaggerUI from 'swagger-ui-react';
+import 'swagger-ui-react/swagger-ui.css';
+
+export default function SwaggerPage() {
+  useEffect(() => {
+    // 设置页面标题
+    document.title = 'API Documentation - ShortURL Analytics';
+  }, []);
+
+  // Swagger配置
+  const swaggerConfig = {
+    openapi: '3.0.0',
+    info: {
+      title: 'ShortURL Analytics API',
+      version: '1.0.0',
+      description: 'API documentation for ShortURL Analytics service',
+      contact: {
+        name: 'API Support',
+        email: 'support@example.com',
+      },
+      license: {
+        name: 'MIT',
+        url: 'https://opensource.org/licenses/MIT',
+      },
+    },
+    servers: [
+      {
+        url: '/api',
+        description: 'API Server',
+      },
+    ],
+    tags: [
+      {
+        name: 'events',
+        description: 'Event tracking and analytics endpoints',
+      },
+    ],
+    paths: {
+      '/events/track': {
+        post: {
+          tags: ['events'],
+          summary: 'Track new event',
+          description: 'Record a new event in the analytics system',
+          requestBody: {
+            required: true,
+            content: {
+              'application/json': {
+                schema: {
+                  $ref: '#/components/schemas/EventInput',
+                },
+                examples: {
+                  clickEvent: {
+                    summary: 'Basic click event',
+                    value: {
+                      event_type: 'click',
+                      link_id: 'link_123',
+                      link_slug: 'promo2023',
+                      link_original_url: 'https://example.com/promotion',
+                      visitor_id: '6ec0bd7f-11c0-43da-975e-2a8ad9ebae0b'
+                    }
+                  },
+                  conversionEvent: {
+                    summary: 'Conversion event',
+                    value: {
+                      event_type: 'conversion',
+                      link_id: 'link_123',
+                      link_slug: 'promo2023',
+                      visitor_id: '6ec0bd7f-11c0-43da-975e-2a8ad9ebae0b',
+                      conversion_type: 'purchase',
+                      conversion_value: 99.99
+                    }
+                  },
+                  completeEvent: {
+                    summary: 'Complete event with all fields',
+                    value: {
+                      // Core event fields
+                      event_id: '123e4567-e89b-12d3-a456-426614174000',
+                      event_time: '2025-03-26T10:30:00.000Z',
+                      event_type: 'click',
+                      event_attributes: '{"source":"email_campaign","campaign_id":"spring_sale_2025"}',
+                      
+                      // Link information
+                      link_id: 'link_abc123',
+                      link_slug: 'summer-promo',
+                      link_label: 'Summer Promotion 2025',
+                      link_title: 'Summer Sale 50% Off',
+                      link_original_url: 'https://example.com/summer-sale-2025',
+                      link_attributes: '{"utm_campaign":"summer_2025","discount_code":"SUMMER50"}',
+                      link_created_at: '2025-03-20T08:00:00.000Z',
+                      link_expires_at: '2025-09-30T23:59:59.000Z',
+                      link_tags: '["promotion","summer","sale"]',
+                      
+                      // User information
+                      user_id: 'user_12345',
+                      user_name: 'John Doe',
+                      user_email: 'john.doe@example.com',
+                      user_attributes: '{"subscription_tier":"premium","account_created":"2024-01-15"}',
+                      
+                      // Team information
+                      team_id: 'team_67890',
+                      team_name: 'Marketing Team',
+                      team_attributes: '{"department":"marketing","region":"APAC"}',
+                      
+                      // Project information
+                      project_id: 'proj_54321',
+                      project_name: 'Summer Campaign 2025',
+                      project_attributes: '{"goals":"increase_sales","budget":"10000"}',
+                      
+                      // QR code information
+                      qr_code_id: 'qr_98765',
+                      qr_code_name: 'Summer Flyer QR',
+                      qr_code_attributes: '{"size":"large","color":"#FF5500","logo":true}',
+                      
+                      // Visitor information
+                      visitor_id: '6ec0bd7f-11c0-43da-975e-2a8ad9ebae0b',
+                      session_id: '7fc1bd8f-22d1-54eb-986f-3b9be5ecaf1c',
+                      ip_address: '203.0.113.42',
+                      country: 'United States',
+                      city: 'San Francisco',
+                      device_type: 'mobile',
+                      browser: 'Chrome',
+                      os: 'iOS',
+                      user_agent: 'Mozilla/5.0 (iPhone; CPU iPhone OS 16_5 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/16.5 Mobile/15E148 Safari/604.1',
+                      
+                      // Referrer information
+                      referrer: 'https://www.google.com/search?q=summer+sale',
+                      utm_source: 'google',
+                      utm_medium: 'organic',
+                      utm_campaign: 'summer_promotion',
+                      
+                      // Interaction information
+                      time_spent_sec: 145,
+                      is_bounce: false,
+                      is_qr_scan: true,
+                      conversion_type: 'signup',
+                      conversion_value: 0
+                    }
+                  }
+                }
+              }
+            }
+          },
+          responses: {
+            '201': {
+              description: 'Event successfully tracked',
+              content: {
+                'application/json': {
+                  schema: {
+                    type: 'object',
+                    properties: {
+                      success: {
+                        type: 'boolean',
+                        example: true
+                      },
+                      message: {
+                        type: 'string',
+                        example: 'Event tracked successfully'
+                      },
+                      event_id: {
+                        type: 'string',
+                        format: 'uuid',
+                        example: '123e4567-e89b-12d3-a456-426614174000'
+                      }
+                    }
+                  }
+                }
+              }
+            },
+            '400': {
+              description: 'Bad request',
+              content: {
+                'application/json': {
+                  schema: {
+                    $ref: '#/components/schemas/Error'
+                  },
+                  example: {
+                    error: 'Missing required field: event_type'
+                  }
+                }
+              }
+            },
+            '500': {
+              description: 'Server error',
+              content: {
+                'application/json': {
+                  schema: {
+                    type: 'object',
+                    properties: {
+                      error: {
+                        type: 'string'
+                      },
+                      details: {
+                        type: 'string'
+                      }
+                    }
+                  },
+                  example: {
+                    error: 'Failed to track event',
+                    details: 'Database connection error'
+                  }
+                }
+              }
+            }
+          }
+        }
+      },
+      '/events': {
+        get: {
+          tags: ['events'],
+          summary: 'Get events',
+          description: 'Retrieve events within a specified time range with pagination support',
+          parameters: [
+            {
+              name: 'startTime',
+              in: 'query',
+              required: true,
+              schema: {
+                type: 'string',
+                format: 'date-time',
+              },
+              description: 'Start time for events query (ISO 8601 format)',
+            },
+            {
+              name: 'endTime',
+              in: 'query',
+              required: true,
+              schema: {
+                type: 'string',
+                format: 'date-time',
+              },
+              description: 'End time for events query (ISO 8601 format)',
+            },
+            {
+              name: 'page',
+              in: 'query',
+              schema: {
+                type: 'integer',
+                default: 1,
+                minimum: 1,
+              },
+              description: 'Page number for pagination',
+            },
+            {
+              name: 'pageSize',
+              in: 'query',
+              schema: {
+                type: 'integer',
+                default: 50,
+                minimum: 1,
+                maximum: 100,
+              },
+              description: 'Number of items per page',
+            },
+          ],
+          responses: {
+            '200': {
+              description: 'Successful response',
+              content: {
+                'application/json': {
+                  schema: {
+                    type: 'object',
+                    properties: {
+                      data: {
+                        type: 'array',
+                        items: {
+                          $ref: '#/components/schemas/Event',
+                        },
+                      },
+                      pagination: {
+                        $ref: '#/components/schemas/Pagination',
+                      },
+                    },
+                  },
+                },
+              },
+            },
+            '400': {
+              description: 'Bad request',
+              content: {
+                'application/json': {
+                  schema: {
+                    $ref: '#/components/schemas/Error',
+                  },
+                },
+              },
+            },
+          },
+        },
+      },
+      '/events/summary': {
+        get: {
+          tags: ['events'],
+          summary: 'Get events summary',
+          description: 'Get aggregated statistics for events within a specified time range',
+          parameters: [
+            {
+              name: 'startTime',
+              in: 'query',
+              required: true,
+              schema: {
+                type: 'string',
+                format: 'date-time',
+              },
+              description: 'Start time for summary (ISO 8601 format)',
+            },
+            {
+              name: 'endTime',
+              in: 'query',
+              required: true,
+              schema: {
+                type: 'string',
+                format: 'date-time',
+              },
+              description: 'End time for summary (ISO 8601 format)',
+            },
+          ],
+          responses: {
+            '200': {
+              description: 'Successful response',
+              content: {
+                'application/json': {
+                  schema: {
+                    $ref: '#/components/schemas/EventsSummary',
+                  },
+                },
+              },
+            },
+            '400': {
+              description: 'Bad request',
+              content: {
+                'application/json': {
+                  schema: {
+                    $ref: '#/components/schemas/Error',
+                  },
+                },
+              },
+            },
+          },
+        },
+      },
+      '/events/time-series': {
+        get: {
+          tags: ['events'],
+          summary: 'Get time series data',
+          description: 'Get time-based analytics data for events',
+          parameters: [
+            {
+              name: 'startTime',
+              in: 'query',
+              required: true,
+              schema: {
+                type: 'string',
+                format: 'date-time',
+              },
+              description: 'Start time for time series data (ISO 8601 format)',
+            },
+            {
+              name: 'endTime',
+              in: 'query',
+              required: true,
+              schema: {
+                type: 'string',
+                format: 'date-time',
+              },
+              description: 'End time for time series data (ISO 8601 format)',
+            },
+          ],
+          responses: {
+            '200': {
+              description: 'Successful response',
+              content: {
+                'application/json': {
+                  schema: {
+                    type: 'object',
+                    properties: {
+                      data: {
+                        type: 'array',
+                        items: {
+                          $ref: '#/components/schemas/TimeSeriesData',
+                        },
+                      },
+                    },
+                  },
+                },
+              },
+            },
+            '400': {
+              description: 'Bad request',
+              content: {
+                'application/json': {
+                  schema: {
+                    $ref: '#/components/schemas/Error',
+                  },
+                },
+              },
+            },
+          },
+        },
+      },
+      '/events/geo': {
+        get: {
+          tags: ['events'],
+          summary: 'Get geographic data',
+          description: 'Get geographic distribution of events',
+          parameters: [
+            {
+              name: 'startTime',
+              in: 'query',
+              required: true,
+              schema: {
+                type: 'string',
+                format: 'date-time',
+              },
+              description: 'Start time for geographic data (ISO 8601 format)',
+            },
+            {
+              name: 'endTime',
+              in: 'query',
+              required: true,
+              schema: {
+                type: 'string',
+                format: 'date-time',
+              },
+              description: 'End time for geographic data (ISO 8601 format)',
+            },
+          ],
+          responses: {
+            '200': {
+              description: 'Successful response',
+              content: {
+                'application/json': {
+                  schema: {
+                    type: 'object',
+                    properties: {
+                      data: {
+                        type: 'array',
+                        items: {
+                          $ref: '#/components/schemas/GeoData',
+                        },
+                      },
+                    },
+                  },
+                },
+              },
+            },
+            '400': {
+              description: 'Bad request',
+              content: {
+                'application/json': {
+                  schema: {
+                    $ref: '#/components/schemas/Error',
+                  },
+                },
+              },
+            },
+          },
+        },
+      },
+      '/events/devices': {
+        get: {
+          tags: ['events'],
+          summary: 'Get device analytics data',
+          description: 'Get device-related analytics for events',
+          parameters: [
+            {
+              name: 'startTime',
+              in: 'query',
+              required: true,
+              schema: {
+                type: 'string',
+                format: 'date-time',
+              },
+              description: 'Start time for device analytics (ISO 8601 format)',
+            },
+            {
+              name: 'endTime',
+              in: 'query',
+              required: true,
+              schema: {
+                type: 'string',
+                format: 'date-time',
+              },
+              description: 'End time for device analytics (ISO 8601 format)',
+            },
+          ],
+          responses: {
+            '200': {
+              description: 'Successful response',
+              content: {
+                'application/json': {
+                  schema: {
+                    type: 'object',
+                    properties: {
+                      data: {
+                        $ref: '#/components/schemas/DeviceAnalytics',
+                      },
+                    },
+                  },
+                },
+              },
+            },
+            '400': {
+              description: 'Bad request',
+              content: {
+                'application/json': {
+                  schema: {
+                    $ref: '#/components/schemas/Error',
+                  },
+                },
+              },
+            },
+          },
+        },
+      },
+    },
+    components: {
+      schemas: {
+        EventInput: {
+          type: 'object',
+          required: ['event_type'],
+          properties: {
+            // Core event fields
+            event_id: {
+              type: 'string',
+              format: 'uuid',
+              description: '事件唯一标识符，用于唯一标识事件记录。若不提供则自动生成UUID'
+            },
+            event_time: {
+              type: 'string',
+              format: 'date-time',
+              description: '事件发生的时间戳（ISO 8601格式），记录事件发生的精确时间。若不提供则使用当前服务器时间'
+            },
+            event_type: {
+              type: 'string',
+              enum: ['click', 'conversion', 'redirect', 'error'],
+              description: '事件类型，用于分类不同的用户交互行为。click表示点击事件，conversion表示转化事件，redirect表示重定向事件，error表示错误事件'
+            },
+            event_attributes: {
+              type: 'string',
+              description: '事件附加属性的JSON字符串，用于存储与特定事件相关的自定义数据，例如事件来源、关联活动ID等'
+            },
+            
+            // Link information
+            link_id: {
+              type: 'string',
+              description: '短链接的唯一标识符，用于关联事件与特定短链接'
+            },
+            link_slug: {
+              type: 'string',
+              description: '短链接的短码/slug部分，即URL路径中的短字符串，用于生成短链接URL'
+            },
+            link_label: {
+              type: 'string',
+              description: '短链接的标签名称，用于分类和组织管理短链接'
+            },
+            link_title: {
+              type: 'string',
+              description: '短链接的标题，用于在管理界面或分析报告中显示链接的易读名称'
+            },
+            link_original_url: {
+              type: 'string',
+              format: 'uri',
+              description: '短链接对应的原始目标URL，即用户访问短链接后将被重定向到的实际URL'
+            },
+            link_attributes: {
+              type: 'string',
+              description: '链接附加属性的JSON字符串，用于存储与链接相关的自定义数据，如营销活动信息、目标受众等'
+            },
+            link_created_at: {
+              type: 'string',
+              format: 'date-time',
+              description: '短链接创建时间，记录链接何时被创建'
+            },
+            link_expires_at: {
+              type: 'string',
+              format: 'date-time',
+              nullable: true,
+              description: '短链接过期时间，指定链接何时失效，值为null表示永不过期'
+            },
+            link_tags: {
+              type: 'string',
+              description: '链接标签的JSON数组字符串，用于通过标签对链接进行分类和过滤'
+            },
+            
+            // User information
+            user_id: {
+              type: 'string',
+              description: '创建链接的用户ID，用于跟踪哪个用户创建了短链接'
+            },
+            user_name: {
+              type: 'string',
+              description: '用户名称，用于在报表中展示更易读的用户身份'
+            },
+            user_email: {
+              type: 'string',
+              format: 'email',
+              description: '用户电子邮件地址，可用于通知和报告分发'
+            },
+            user_attributes: {
+              type: 'string',
+              description: '用户附加属性的JSON字符串，存储用户相关的额外信息，如订阅级别、账户创建日期等'
+            },
+            
+            // Team information
+            team_id: {
+              type: 'string',
+              description: '团队ID，用于标识链接归属的团队，支持多团队使用场景'
+            },
+            team_name: {
+              type: 'string',
+              description: '团队名称，用于在报表和管理界面中显示更友好的团队标识'
+            },
+            team_attributes: {
+              type: 'string',
+              description: '团队附加属性的JSON字符串，存储团队相关的额外信息，如部门、地区等'
+            },
+            
+            // Project information
+            project_id: {
+              type: 'string',
+              description: '项目ID，用于将链接归类到特定项目下，便于项目级别的分析'
+            },
+            project_name: {
+              type: 'string',
+              description: '项目名称，提供更具描述性的项目标识，用于报表和管理界面'
+            },
+            project_attributes: {
+              type: 'string',
+              description: '项目附加属性的JSON字符串，存储项目相关的额外信息，如目标、预算等'
+            },
+            
+            // QR code information
+            qr_code_id: {
+              type: 'string',
+              description: '二维码ID，标识与事件关联的二维码，用于跟踪二维码的使用情况'
+            },
+            qr_code_name: {
+              type: 'string',
+              description: '二维码名称，提供更具描述性的二维码标识，便于管理和报表'
+            },
+            qr_code_attributes: {
+              type: 'string',
+              description: '二维码附加属性的JSON字符串，存储与二维码相关的额外信息，如尺寸、颜色、logo等'
+            },
+            
+            // Visitor information
+            visitor_id: {
+              type: 'string',
+              format: 'uuid',
+              description: '访问者唯一标识符，用于跟踪和识别独立访问者，分析用户行为'
+            },
+            session_id: {
+              type: 'string',
+              description: '会话标识符，用于将同一访问者的多个事件分组到同一会话中'
+            },
+            ip_address: {
+              type: 'string',
+              description: '访问者的IP地址，用于地理位置分析和安全监控'
+            },
+            country: {
+              type: 'string',
+              description: '访问者所在国家，用于地理分布分析'
+            },
+            city: {
+              type: 'string',
+              description: '访问者所在城市，提供更精细的地理位置分析'
+            },
+            device_type: {
+              type: 'string',
+              description: '访问者使用的设备类型（如mobile、desktop、tablet等），用于设备分布分析'
+            },
+            browser: {
+              type: 'string',
+              description: '访问者使用的浏览器（如Chrome、Safari、Firefox等），用于浏览器分布分析'
+            },
+            os: {
+              type: 'string',
+              description: '访问者使用的操作系统（如iOS、Android、Windows等），用于操作系统分布分析'
+            },
+            user_agent: {
+              type: 'string',
+              description: '访问者的User-Agent字符串，包含有关浏览器、操作系统和设备的详细信息'
+            },
+            
+            // Referrer information
+            referrer: {
+              type: 'string',
+              description: '引荐来源URL，指示用户从哪个网站或页面访问短链接，用于分析流量来源'
+            },
+            utm_source: {
+              type: 'string',
+              description: 'UTM来源参数，标识流量的来源渠道，如Google、Facebook、Newsletter等'
+            },
+            utm_medium: {
+              type: 'string',
+              description: 'UTM媒介参数，标识营销媒介类型，如cpc、email、social等'
+            },
+            utm_campaign: {
+              type: 'string',
+              description: 'UTM活动参数，标识特定的营销活动名称，用于跟踪不同活动的效果'
+            },
+            
+            // Interaction information
+            time_spent_sec: {
+              type: 'number',
+              description: '用户停留时间（秒），表示用户在目标页面上花费的时间，用于分析用户参与度'
+            },
+            is_bounce: {
+              type: 'boolean',
+              description: '是否为跳出访问，表示用户是否在查看单个页面后离开，不与网站进一步交互'
+            },
+            is_qr_scan: {
+              type: 'boolean',
+              description: '是否来自二维码扫描，用于区分和分析二维码带来的流量'
+            },
+            conversion_type: {
+              type: 'string',
+              description: '转化类型，表示事件触发的转化类型，如注册、购买、下载等，用于细分不同类型的转化'
+            },
+            conversion_value: {
+              type: 'number',
+              description: '转化价值，表示转化事件的经济价值或重要性，如购买金额、潜在客户价值等'
+            }
+          }
+        },
+        Event: {
+          type: 'object',
+          required: ['event_id', 'event_type', 'event_time', 'visitor_id'],
+          properties: {
+            event_id: {
+              type: 'string',
+              format: 'uuid',
+              description: '事件唯一标识符，用于唯一标识事件记录',
+            },
+            event_type: {
+              type: 'string',
+              enum: ['click', 'conversion'],
+              description: '事件类型，用于分类不同的用户交互行为。click表示点击事件，conversion表示转化事件',
+            },
+            event_time: {
+              type: 'string',
+              format: 'date-time',
+              description: '事件发生的时间戳，记录事件发生的精确时间',
+            },
+            link_id: {
+              type: 'string',
+              description: '短链接的唯一标识符，用于关联事件与特定短链接',
+            },
+            link_slug: {
+              type: 'string',
+              description: '短链接的短码/slug部分，即URL路径中的短字符串',
+            },
+            link_original_url: {
+              type: 'string',
+              format: 'uri',
+              description: '短链接对应的原始目标URL，即用户访问短链接后将被重定向到的实际URL',
+            },
+            visitor_id: {
+              type: 'string',
+              format: 'uuid',
+              description: '访问者唯一标识符，用于跟踪和识别独立访问者，分析用户行为',
+            },
+            device_type: {
+              type: 'string',
+              description: '访问者使用的设备类型（如mobile、desktop、tablet等），用于设备分布分析',
+            },
+            browser: {
+              type: 'string',
+              description: '访问者使用的浏览器（如Chrome、Safari、Firefox等），用于浏览器分布分析',
+            },
+            os: {
+              type: 'string',
+              description: '访问者使用的操作系统（如iOS、Android、Windows等），用于操作系统分布分析',
+            },
+            country: {
+              type: 'string',
+              description: '访问者所在国家，用于地理分布分析',
+            },
+            region: {
+              type: 'string',
+              description: '访问者所在地区/省份，提供中等精细度的地理位置分析',
+            },
+            city: {
+              type: 'string',
+              description: '访问者所在城市，提供更精细的地理位置分析',
+            },
+            referrer: {
+              type: 'string',
+              description: '引荐来源URL，指示用户从哪个网站或页面访问短链接，用于分析流量来源',
+            },
+            conversion_type: {
+              type: 'string',
+              description: '转化类型，表示事件触发的转化类型，如注册、购买、下载等（仅当event_type为conversion时有效）',
+            },
+            conversion_value: {
+              type: 'number',
+              description: '转化价值，表示转化事件的经济价值或重要性，如购买金额、潜在客户价值等（仅当event_type为conversion时有效）',
+            },
+          },
+        },
+        EventsSummary: {
+          type: 'object',
+          required: ['totalEvents', 'uniqueVisitors'],
+          properties: {
+            totalEvents: {
+              type: 'integer',
+              description: '时间段内的事件总数，包括所有类型的事件总计',
+            },
+            uniqueVisitors: {
+              type: 'integer',
+              description: '时间段内的独立访问者数量，基于唯一访问者ID计算',
+            },
+            totalConversions: {
+              type: 'integer',
+              description: '时间段内的转化事件总数，用于衡量营销效果',
+            },
+            averageTimeSpent: {
+              type: 'number',
+              description: '平均停留时间（秒），表示用户平均在目标页面上停留的时间，是用户参与度的重要指标',
+            },
+          },
+        },
+        TimeSeriesData: {
+          type: 'object',
+          properties: {
+            timestamp: {
+              type: 'string',
+              format: 'date-time',
+              description: '时间序列中的时间点，表示数据采集的精确时间',
+            },
+            events: {
+              type: 'number',
+              description: '该时间点的事件数量，显示事件随时间的分布趋势',
+            },
+            visitors: {
+              type: 'number',
+              description: '该时间点的独立访问者数量，显示访问者随时间的分布趋势',
+            },
+            conversions: {
+              type: 'number',
+              description: '该时间点的转化数量，显示转化随时间的分布趋势',
+            },
+          },
+        },
+        GeoData: {
+          type: 'object',
+          properties: {
+            location: {
+              type: 'string',
+              description: '位置标识符，可以是国家、地区或城市的组合标识',
+            },
+            country: {
+              type: 'string',
+              description: '国家名称，表示访问者所在的国家',
+            },
+            region: {
+              type: 'string',
+              description: '地区/省份名称，表示访问者所在的地区或省份',
+            },
+            city: {
+              type: 'string',
+              description: '城市名称，表示访问者所在的城市',
+            },
+            visits: {
+              type: 'number',
+              description: '来自该位置的访问次数，用于分析不同地区的流量分布',
+            },
+            visitors: {
+              type: 'number',
+              description: '来自该位置的独立访问者数量，用于分析不同地区的用户分布',
+            },
+            percentage: {
+              type: 'number',
+              description: '占总访问量的百分比，便于直观比较不同地区的流量占比',
+            },
+          },
+        },
+        DeviceAnalytics: {
+          type: 'object',
+          properties: {
+            deviceTypes: {
+              type: 'array',
+              items: {
+                type: 'object',
+                properties: {
+                  type: {
+                    type: 'string',
+                    description: '设备类型，如mobile、desktop、tablet等，用于设备类型分析',
+                  },
+                  count: {
+                    type: 'number',
+                    description: '使用该设备类型的访问次数，用于统计各类设备的使用情况',
+                  },
+                  percentage: {
+                    type: 'number',
+                    description: '该设备类型占总访问量的百分比，便于比较不同设备类型的使用占比',
+                  },
+                },
+              },
+            },
+            browsers: {
+              type: 'array',
+              items: {
+                type: 'object',
+                properties: {
+                  name: {
+                    type: 'string',
+                    description: '浏览器名称，如Chrome、Safari、Firefox等，用于浏览器使用分析',
+                  },
+                  count: {
+                    type: 'number',
+                    description: '使用该浏览器的访问次数，用于统计各类浏览器的使用情况',
+                  },
+                  percentage: {
+                    type: 'number',
+                    description: '该浏览器占总访问量的百分比，便于比较不同浏览器的使用占比',
+                  },
+                },
+              },
+            },
+            operatingSystems: {
+              type: 'array',
+              items: {
+                type: 'object',
+                properties: {
+                  name: {
+                    type: 'string',
+                    description: '操作系统名称，如iOS、Android、Windows等，用于操作系统使用分析',
+                  },
+                  count: {
+                    type: 'number',
+                    description: '使用该操作系统的访问次数，用于统计各类操作系统的使用情况',
+                  },
+                  percentage: {
+                    type: 'number',
+                    description: '该操作系统占总访问量的百分比，便于比较不同操作系统的使用占比',
+                  },
+                },
+              },
+            },
+          },
+        },
+        Pagination: {
+          type: 'object',
+          required: ['page', 'pageSize', 'totalItems', 'totalPages'],
+          properties: {
+            page: {
+              type: 'integer',
+              description: '当前页码，表示结果集中的当前页面位置',
+            },
+            pageSize: {
+              type: 'integer',
+              description: '每页项目数，表示每页显示的结果数量',
+            },
+            totalItems: {
+              type: 'integer',
+              description: '总项目数，表示符合查询条件的结果总数',
+            },
+            totalPages: {
+              type: 'integer',
+              description: '总页数，基于总项目数和每页项目数计算得出',
+            },
+          },
+        },
+        Error: {
+          type: 'object',
+          required: ['code', 'message'],
+          properties: {
+            code: {
+              type: 'string',
+              description: '错误代码，用于标识特定类型的错误，便于客户端处理不同错误情况',
+            },
+            message: {
+              type: 'string',
+              description: '错误消息，提供关于错误的人类可读描述，帮助理解错误原因',
+            },
+          },
+        },
+      },
+    },
+  };
+
+  return (
+    <div className="container mx-auto px-4 py-8">
+      <div className="mb-8">
+        <h1 className="text-3xl font-bold mb-2">API Documentation</h1>
+        <p className="text-gray-600">
+          Explore and test the ShortURL Analytics API endpoints using the interactive documentation below.
+        </p>
+      </div>
+      <SwaggerUI spec={swaggerConfig} />
+    </div>
+  );
+} 

app/analytics/devices/page.tsx

@@ -1,150 +0,0 @@
-"use client";
-
-import { useState, useEffect } from 'react';
-import { DeviceAnalytics } from '../../api/types';
-
-export default function DeviceAnalyticsPage() {
-  const [deviceData, setDeviceData] = useState<DeviceAnalytics | null>(null);
-  const [isLoading, setIsLoading] = useState(true);
-  const [error, setError] = useState<string | null>(null);
-  const [dateRange, setDateRange] = useState({
-    from: new Date('2024-02-01'),
-    to: new Date('2025-03-05')
-  });
-
-  useEffect(() => {
-    const fetchDeviceData = async () => {
-      try {
-        setIsLoading(true);
-        setError(null);
-
-        const response = await fetch(`/api/events/devices?startTime=${dateRange.from.toISOString().split('T')[0]}T00:00:00Z&endTime=${dateRange.to.toISOString().split('T')[0]}T23:59:59Z`);
-        if (!response.ok) throw new Error('Failed to fetch device data');
-        
-        const data = await response.json();
-        setDeviceData(data.data);
-      } catch (err) {
-        setError(err instanceof Error ? err.message : 'An error occurred');
-      } finally {
-        setIsLoading(false);
-      }
-    };
-
-    fetchDeviceData();
-  }, [dateRange]);
-
-  return (
-    <div className="container mx-auto px-4 py-8">
-      {/* 页面标题 */}
-      <div className="mb-8">
-        <h1 className="text-2xl font-bold text-foreground">Device Analytics</h1>
-        <p className="mt-2 text-text-secondary">Analyze visitor distribution by devices, browsers, and operating systems</p>
-      </div>
-
-      {/* 时间范围选择器 */}
-      <div className="bg-card-bg rounded-xl p-6 mb-8">
-        <div className="grid grid-cols-1 md:grid-cols-2 gap-4">
-          <div>
-            <label className="block text-sm font-medium text-text-secondary mb-1">Start Date</label>
-            <input
-              type="date"
-              className="block w-full px-3 py-2 bg-background border border-card-border rounded-md text-sm"
-              value={dateRange.from.toISOString().split('T')[0]}
-              onChange={e => setDateRange(prev => ({ ...prev, from: new Date(e.target.value) }))}
-            />
-          </div>
-          <div>
-            <label className="block text-sm font-medium text-text-secondary mb-1">End Date</label>
-            <input
-              type="date"
-              className="block w-full px-3 py-2 bg-background border border-card-border rounded-md text-sm"
-              value={dateRange.to.toISOString().split('T')[0]}
-              onChange={e => setDateRange(prev => ({ ...prev, to: new Date(e.target.value) }))}
-            />
-          </div>
-        </div>
-      </div>
-
-      {/* 设备类型分析 */}
-      <div className="grid grid-cols-1 lg:grid-cols-3 gap-8 mb-8">
-        {/* 设备类型 */}
-        <div className="bg-card-bg rounded-xl p-6">
-          <h3 className="text-lg font-medium text-white mb-4">Device Types</h3>
-          {deviceData?.deviceTypes.map(item => (
-            <div key={item.type} className="mb-4 last:mb-0">
-              <div className="flex justify-between items-center mb-1">
-                <span className="text-sm text-white">{item.type}</span>
-                <span className="text-sm text-white">{item.count} ({item.percentage.toFixed(1)}%)</span>
-              </div>
-              <div className="w-full bg-background rounded-full h-2">
-                <div
-                  className="bg-blue-500 h-2 rounded-full"
-                  style={{ width: `${item.percentage}%` }}
-                />
-              </div>
-            </div>
-          ))}
-        </div>
-
-        {/* 浏览器 */}
-        <div className="bg-card-bg rounded-xl p-6">
-          <h3 className="text-lg font-medium text-white mb-4">Browsers</h3>
-          {deviceData?.browsers.map(item => (
-            <div key={item.name} className="mb-4 last:mb-0">
-              <div className="flex justify-between items-center mb-1">
-                <span className="text-sm text-white">{item.name}</span>
-                <span className="text-sm text-white">{item.count} ({item.percentage.toFixed(1)}%)</span>
-              </div>
-              <div className="w-full bg-background rounded-full h-2">
-                <div
-                  className="bg-green-500 h-2 rounded-full"
-                  style={{ width: `${item.percentage}%` }}
-                />
-              </div>
-            </div>
-          ))}
-        </div>
-
-        {/* 操作系统 */}
-        <div className="bg-card-bg rounded-xl p-6">
-          <h3 className="text-lg font-medium text-white mb-4">Operating Systems</h3>
-          {deviceData?.operatingSystems.map(item => (
-            <div key={item.name} className="mb-4 last:mb-0">
-              <div className="flex justify-between items-center mb-1">
-                <span className="text-sm text-white">{item.name}</span>
-                <span className="text-sm text-white">{item.count} ({item.percentage.toFixed(1)}%)</span>
-              </div>
-              <div className="w-full bg-background rounded-full h-2">
-                <div
-                  className="bg-red-500 h-2 rounded-full"
-                  style={{ width: `${item.percentage}%` }}
-                />
-              </div>
-            </div>
-          ))}
-        </div>
-      </div>
-
-      {/* 加载状态 */}
-      {isLoading && (
-        <div className="flex justify-center items-center p-8">
-          <div className="w-8 h-8 border-t-2 border-b-2 border-accent-blue rounded-full animate-spin"></div>
-        </div>
-      )}
-
-      {/* 错误状态 */}
-      {error && (
-        <div className="flex justify-center items-center p-8 text-accent-red">
-          <p>{error}</p>
-        </div>
-      )}
-
-      {/* 无数据状态 */}
-      {!isLoading && !error && !deviceData && (
-        <div className="flex justify-center items-center p-8 text-text-secondary">
-          <p>No device data available</p>
-        </div>
-      )}
-    </div>
-  );
-} 

app/api/events/track/route.ts

@@ -0,0 +1,137 @@
+import { NextRequest, NextResponse } from 'next/server';
+import { Event } from '../../types';
+import { v4 as uuid } from 'uuid';
+import clickhouse from '@/lib/clickhouse';
+
+// 将时间格式化为ClickHouse兼容的格式：YYYY-MM-DD HH:MM:SS.SSS
+const formatDateTime = (date: Date) => {
+  return date.toISOString().replace('T', ' ').replace('Z', '');
+};
+
+// Handler for POST request to track events
+export async function POST(req: NextRequest) {
+  try {
+    // Parse request body
+    const eventData = await req.json();
+    
+    // Validate required fields
+    if (!eventData.event_type) {
+      return NextResponse.json(
+        { error: 'Missing required field: event_type' },
+        { status: 400 }
+      );
+    }
+    
+    // 获取当前时间并格式化
+    const currentTime = formatDateTime(new Date());
+    
+    // Set default values for required fields if missing
+    const event: Event = {
+      // Core event fields
+      event_id: eventData.event_id || uuid(),
+      event_time: eventData.event_time ? formatDateTime(new Date(eventData.event_time)) : currentTime,
+      event_type: eventData.event_type,
+      event_attributes: eventData.event_attributes || '{}',
+      
+      // Link information
+      link_id: eventData.link_id || '',
+      link_slug: eventData.link_slug || '',
+      link_label: eventData.link_label || '',
+      link_title: eventData.link_title || '',
+      link_original_url: eventData.link_original_url || '',
+      link_attributes: eventData.link_attributes || '{}',
+      link_created_at: eventData.link_created_at ? formatDateTime(new Date(eventData.link_created_at)) : currentTime,
+      link_expires_at: eventData.link_expires_at ? formatDateTime(new Date(eventData.link_expires_at)) : null,
+      link_tags: eventData.link_tags || '[]',
+      
+      // User information
+      user_id: eventData.user_id || '',
+      user_name: eventData.user_name || '',
+      user_email: eventData.user_email || '',
+      user_attributes: eventData.user_attributes || '{}',
+      
+      // Team information
+      team_id: eventData.team_id || '',
+      team_name: eventData.team_name || '',
+      team_attributes: eventData.team_attributes || '{}',
+      
+      // Project information
+      project_id: eventData.project_id || '',
+      project_name: eventData.project_name || '',
+      project_attributes: eventData.project_attributes || '{}',
+      
+      // QR code information
+      qr_code_id: eventData.qr_code_id || '',
+      qr_code_name: eventData.qr_code_name || '',
+      qr_code_attributes: eventData.qr_code_attributes || '{}',
+      
+      // Visitor information
+      visitor_id: eventData.visitor_id || uuid(),
+      session_id: eventData.session_id || uuid(),
+      ip_address: eventData.ip_address || req.headers.get('x-forwarded-for')?.toString() || '',
+      country: eventData.country || '',
+      city: eventData.city || '',
+      device_type: eventData.device_type || '',
+      browser: eventData.browser || '',
+      os: eventData.os || '',
+      user_agent: eventData.user_agent || req.headers.get('user-agent')?.toString() || '',
+      
+      // Referrer information
+      referrer: eventData.referrer || req.headers.get('referer')?.toString() || '',
+      utm_source: eventData.utm_source || '',
+      utm_medium: eventData.utm_medium || '',
+      utm_campaign: eventData.utm_campaign || '',
+      
+      // Interaction information
+      time_spent_sec: eventData.time_spent_sec || 0,
+      is_bounce: eventData.is_bounce !== undefined ? eventData.is_bounce : true,
+      is_qr_scan: eventData.is_qr_scan !== undefined ? eventData.is_qr_scan : false,
+      conversion_type: eventData.conversion_type || '',
+      conversion_value: eventData.conversion_value || 0,
+    };
+    
+    // 确保JSON字符串字段的正确处理
+    if (typeof event.event_attributes === 'object') {
+      event.event_attributes = JSON.stringify(event.event_attributes);
+    }
+    if (typeof event.link_attributes === 'object') {
+      event.link_attributes = JSON.stringify(event.link_attributes);
+    }
+    if (typeof event.user_attributes === 'object') {
+      event.user_attributes = JSON.stringify(event.user_attributes);
+    }
+    if (typeof event.team_attributes === 'object') {
+      event.team_attributes = JSON.stringify(event.team_attributes);
+    }
+    if (typeof event.project_attributes === 'object') {
+      event.project_attributes = JSON.stringify(event.project_attributes);
+    }
+    if (typeof event.qr_code_attributes === 'object') {
+      event.qr_code_attributes = JSON.stringify(event.qr_code_attributes);
+    }
+    if (typeof event.link_tags === 'object') {
+      event.link_tags = JSON.stringify(event.link_tags);
+    }
+    
+    // Insert event into ClickHouse
+    await clickhouse.insert({
+      table: 'events',
+      values: [event],
+      format: 'JSONEachRow',
+    });
+    
+    // Return success response
+    return NextResponse.json({ 
+      success: true, 
+      message: 'Event tracked successfully',
+      event_id: event.event_id 
+    }, { status: 201 });
+    
+  } catch (error) {
+    console.error('Error tracking event:', error);
+    return NextResponse.json(
+      { error: 'Failed to track event', details: (error as Error).message },
+      { status: 500 }
+    );
+  }
+} 

app/components/analytics/DeviceAnalytics.tsx

@@ -1,6 +1,8 @@
 "use client";
 
-import { DeviceAnalytics as DeviceAnalyticsType } from '../../api/types';
+import { useEffect, useRef } from 'react';
+import { DeviceAnalytics as DeviceAnalyticsType } from '@/app/api/types';
+import { Chart, PieController, ArcElement, Tooltip, Legend } from 'chart.js';
 
 interface DeviceAnalyticsProps {
   data: DeviceAnalyticsType;

app/components/analytics/GeoAnalytics.tsx

@@ -1,6 +1,8 @@
 "use client";
 
-import { GeoData } from '../../api/types';
+import { useEffect, useRef } from 'react';
+import { GeoData } from '@/app/api/types';
+import { Chart, PieController, ArcElement, Tooltip, Legend } from 'chart.js';
 
 interface GeoAnalyticsProps {
   data: GeoData[];

app/components/charts/TimeSeriesChart.tsx

@@ -16,7 +16,7 @@ import {
   ChartOptions,
   TooltipItem
 } from 'chart.js';
-import { TimeSeriesData } from '../../api/types';
+import { TimeSeriesData } from '@/app/api/types';
 
 // 注册 Chart.js 组件
 ChartJS.register(

app/layout.tsx

@@ -1,68 +1,21 @@
 import './globals.css';
 import type { Metadata } from 'next';
-import { Inter } from 'next/font/google';
-import Link from 'next/link';
-
-const inter = Inter({ subsets: ['latin'] });
 
 export const metadata: Metadata = {
-  title: 'ShortURL Analytics',
-  description: 'Analytics dashboard for ShortURL service',
+  title: 'Link Management & Analytics',
+  description: 'Track and analyze shortened links',
 };
 
 export default function RootLayout({
   children,
-}: {
+}: Readonly<{
   children: React.ReactNode;
-}) {
+}>) {
   return (
-    <html lang="en">
-      <body className={inter.className}>
-        <div className="min-h-screen bg-gray-50 dark:bg-gray-900">
-          <nav className="bg-white dark:bg-gray-800 border-b border-gray-200 dark:border-gray-700">
-            <div className="container mx-auto px-4">
-              <div className="flex items-center justify-between h-16">
-                <div className="flex items-center">
-                  <Link href="/" className="text-xl font-bold text-gray-900 dark:text-gray-100">
-                    ShortURL Analytics
-                  </Link>
-                  <div className="hidden md:block ml-10">
-                    <div className="flex items-baseline space-x-4">
-                      <Link
-                        href="/dashboard"
-                        className="text-gray-500 dark:text-gray-400 hover:text-gray-900 dark:hover:text-gray-100 px-3 py-2 rounded-md text-sm font-medium"
-                      >
-                        Dashboard
-                      </Link>
-                      <Link
-                        href="/events"
-                        className="text-gray-500 dark:text-gray-400 hover:text-gray-900 dark:hover:text-gray-100 px-3 py-2 rounded-md text-sm font-medium"
-                      >
-                        Events
-                      </Link>
-                      <Link
-                        href="/analytics/geo"
-                        className="text-gray-500 dark:text-gray-400 hover:text-gray-900 dark:hover:text-gray-100 px-3 py-2 rounded-md text-sm font-medium"
-                      >
-                        Geographic
-                      </Link>
-                      <Link
-                        href="/analytics/devices"
-                        className="text-gray-500 dark:text-gray-400 hover:text-gray-900 dark:hover:text-gray-100 px-3 py-2 rounded-md text-sm font-medium"
-                      >
-                        Devices
-                      </Link>
-                    </div>
-                  </div>
-                </div>
-              </div>
-            </div>
-          </nav>
-          <main className="py-10">
-            {children}
-          </main>
-        </div>
+    <html lang="en" suppressHydrationWarning>
+      <body>
+        {children}
       </body>
     </html>
   );
-}
+} 

app/layouts.tsx

@@ -1,21 +0,0 @@
-import './globals.css';
-import type { Metadata } from 'next';
-
-export const metadata: Metadata = {
-  title: 'Link Management & Analytics',
-  description: 'Track and analyze shortened links',
-};
-
-export default function RootLayout({
-  children,
-}: Readonly<{
-  children: React.ReactNode;
-}>) {
-  return (
-    <html lang="en" suppressHydrationWarning>
-      <body>
-        {children}
-      </body>
-    </html>
-  );
-} 

docs/swagger-setup.md

@@ -0,0 +1,151 @@
+# Setting up Swagger UI in Next.js
+
+This guide explains how to set up Swagger UI in a Next.js application using route groups.
+
+## Directory Structure
+
+The recommended directory structure for Swagger documentation:
+
+```
+app/
+  (swagger)/           # Route group for swagger-related pages
+    swagger/          # Actual swagger route
+      page.tsx       # Swagger UI component
+```
+
+## Installation
+
+1. Add Swagger UI dependencies to your project:
+
+```json
+{
+  "dependencies": {
+    "swagger-ui-react": "^5.12.0",
+    "swagger-ui-dist": "^5.12.0"
+  },
+  "devDependencies": {
+    "@types/swagger-ui-react": "^4.18.3"
+  }
+}
+```
+
+2. Install webpack style loaders for handling Swagger UI CSS:
+
+```bash
+pnpm add -D style-loader css-loader
+```
+
+## Next.js Configuration
+
+Create or update `next.config.js` to handle Swagger UI CSS:
+
+```javascript
+/** @type {import('next').NextConfig} */
+const nextConfig = {
+  transpilePackages: ['swagger-ui-react'],
+  webpack: (config) => {
+    config.module.rules.push({
+      test: /\.css$/,
+      use: ['style-loader', 'css-loader'],
+    });
+    return config;
+  },
+};
+
+module.exports = nextConfig;
+```
+
+## Swagger UI Component
+
+Create `app/(swagger)/swagger/page.tsx`:
+
+```typescript
+"use client";
+
+import { useEffect } from 'react';
+import SwaggerUI from 'swagger-ui-react';
+import 'swagger-ui-react/swagger-ui.css';
+
+export default function SwaggerPage() {
+  useEffect(() => {
+    document.title = 'API Documentation - ShortURL Analytics';
+  }, []);
+
+  const swaggerConfig = {
+    openapi: '3.0.0',
+    info: {
+      title: 'Your API Title',
+      version: '1.0.0',
+      description: 'API documentation',
+      contact: {
+        name: 'API Support',
+        email: 'support@example.com',
+      },
+      license: {
+        name: 'MIT',
+        url: 'https://opensource.org/licenses/MIT',
+      },
+    },
+    // ... your API configuration
+  };
+
+  return (
+    <div className="container mx-auto px-4 py-8">
+      <div className="mb-8">
+        <h1 className="text-3xl font-bold mb-2">API Documentation</h1>
+        <p className="text-gray-600">
+          Explore and test the API endpoints using the interactive documentation below.
+        </p>
+      </div>
+      <SwaggerUI spec={swaggerConfig} />
+    </div>
+  );
+}
+```
+
+## Best Practices
+
+1. **Route Groups**: Use route groups `(groupname)` to organize related pages without affecting the URL structure.
+
+2. **API Documentation**:
+   - Add detailed descriptions for all endpoints
+   - Include parameter descriptions and constraints
+   - Define response schemas
+   - Document error responses
+   - Use appropriate data formats (UUID, URI, etc.)
+   - Group related endpoints using tags
+
+3. **Swagger Configuration**:
+   - Add contact information
+   - Include license details
+   - Set appropriate servers configuration
+   - Define required fields
+   - Add parameter validations (min/max values)
+
+## Common Issues
+
+1. **Route Conflicts**: Avoid parallel routes that resolve to the same path. For example, don't have both `app/swagger/page.tsx` and `app/(group)/swagger/page.tsx` as they would conflict.
+
+2. **CSS Loading**: Make sure to:
+   - Import Swagger UI CSS
+   - Configure webpack in `next.config.js`
+   - Use the `"use client"` directive as Swagger UI is a client-side component
+
+3. **React Version Compatibility**: Be aware of potential peer dependency warnings between Swagger UI React and your React version. You might need to use `--legacy-peer-deps` or adjust your React version accordingly.
+
+## Accessing the Documentation
+
+After setup, your Swagger documentation will be available at `/swagger` in your application. The UI provides:
+- Interactive API documentation
+- Request/response examples
+- Try-it-out functionality
+- Schema definitions
+- Error responses
+
+## Maintenance
+
+Keep your Swagger documentation up-to-date by:
+- Updating the OpenAPI specification when adding or modifying endpoints
+- Maintaining accurate parameter descriptions
+- Keeping example values relevant
+- Updating response schemas when data structures change 

next.config.js

@@ -0,0 +1,13 @@
+/** @type {import('next').NextConfig} */
+const nextConfig = {
+  transpilePackages: ['swagger-ui-react'],
+  webpack: (config) => {
+    config.module.rules.push({
+      test: /\.css$/,
+      use: ['style-loader', 'css-loader'],
+    });
+    return config;
+  },
+};
+
+module.exports = nextConfig; 

package-lock.json

@@ -10,12 +10,14 @@
       "dependencies": {
         "@clickhouse/client": "^1.11.0",
         "@types/chart.js": "^2.9.41",
+        "@types/recharts": "^1.8.29",
         "@types/uuid": "^10.0.0",
         "chart.js": "^4.4.8",
         "date-fns": "^4.1.0",
         "next": "15.2.3",
         "react": "^19.0.0",
         "react-dom": "^19.0.0",
+        "recharts": "^2.15.1",
         "uuid": "^10.0.0"
       },
       "devDependencies": {
@@ -43,6 +45,18 @@
         "url": "https://github.com/sponsors/sindresorhus"
       }
     },
+    "node_modules/@babel/runtime": {
+      "version": "7.27.0",
+      "resolved": "https://registry.npmjs.org/@babel/runtime/-/runtime-7.27.0.tgz",
+      "integrity": "sha512-VtPOkrdPHZsKc/clNqyi9WUA8TINkZ4cGk63UUE3u4pmB2k+ZMQRDuIOagv8UVd6j7k0T3+RRIb7beKTebNbcw==",
+      "license": "MIT",
+      "dependencies": {
+        "regenerator-runtime": "^0.14.0"
+      },
+      "engines": {
+        "node": ">=6.9.0"
+      }
+    },
     "node_modules/@clickhouse/client": {
       "version": "1.11.0",
       "resolved": "https://registry.npmjs.org/@clickhouse/client/-/client-1.11.0.tgz",
@@ -1156,6 +1170,69 @@
         "moment": "^2.10.2"
       }
     },
+    "node_modules/@types/d3-array": {
+      "version": "3.2.1",
+      "resolved": "https://registry.npmjs.org/@types/d3-array/-/d3-array-3.2.1.tgz",
+      "integrity": "sha512-Y2Jn2idRrLzUfAKV2LyRImR+y4oa2AntrgID95SHJxuMUrkNXmanDSed71sRNZysveJVt1hLLemQZIady0FpEg==",
+      "license": "MIT"
+    },
+    "node_modules/@types/d3-color": {
+      "version": "3.1.3",
+      "resolved": "https://registry.npmjs.org/@types/d3-color/-/d3-color-3.1.3.tgz",
+      "integrity": "sha512-iO90scth9WAbmgv7ogoq57O9YpKmFBbmoEoCHDB2xMBY0+/KVrqAaCDyCE16dUspeOvIxFFRI+0sEtqDqy2b4A==",
+      "license": "MIT"
+    },
+    "node_modules/@types/d3-ease": {
+      "version": "3.0.2",
+      "resolved": "https://registry.npmjs.org/@types/d3-ease/-/d3-ease-3.0.2.tgz",
+      "integrity": "sha512-NcV1JjO5oDzoK26oMzbILE6HW7uVXOHLQvHshBUW4UMdZGfiY6v5BeQwh9a9tCzv+CeefZQHJt5SRgK154RtiA==",
+      "license": "MIT"
+    },
+    "node_modules/@types/d3-interpolate": {
+      "version": "3.0.4",
+      "resolved": "https://registry.npmjs.org/@types/d3-interpolate/-/d3-interpolate-3.0.4.tgz",
+      "integrity": "sha512-mgLPETlrpVV1YRJIglr4Ez47g7Yxjl1lj7YKsiMCb27VJH9W8NVM6Bb9d8kkpG/uAQS5AmbA48q2IAolKKo1MA==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/d3-color": "*"
+      }
+    },
+    "node_modules/@types/d3-path": {
+      "version": "1.0.11",
+      "resolved": "https://registry.npmjs.org/@types/d3-path/-/d3-path-1.0.11.tgz",
+      "integrity": "sha512-4pQMp8ldf7UaB/gR8Fvvy69psNHkTpD/pVw3vmEi8iZAB9EPMBruB1JvHO4BIq9QkUUd2lV1F5YXpMNj7JPBpw==",
+      "license": "MIT"
+    },
+    "node_modules/@types/d3-scale": {
+      "version": "4.0.9",
+      "resolved": "https://registry.npmjs.org/@types/d3-scale/-/d3-scale-4.0.9.tgz",
+      "integrity": "sha512-dLmtwB8zkAeO/juAMfnV+sItKjlsw2lKdZVVy6LRr0cBmegxSABiLEpGVmSJJ8O08i4+sGR6qQtb6WtuwJdvVw==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/d3-time": "*"
+      }
+    },
+    "node_modules/@types/d3-shape": {
+      "version": "1.3.12",
+      "resolved": "https://registry.npmjs.org/@types/d3-shape/-/d3-shape-1.3.12.tgz",
+      "integrity": "sha512-8oMzcd4+poSLGgV0R1Q1rOlx/xdmozS4Xab7np0eamFFUYq71AU9pOCJEFnkXW2aI/oXdVYJzw6pssbSut7Z9Q==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/d3-path": "^1"
+      }
+    },
+    "node_modules/@types/d3-time": {
+      "version": "3.0.4",
+      "resolved": "https://registry.npmjs.org/@types/d3-time/-/d3-time-3.0.4.tgz",
+      "integrity": "sha512-yuzZug1nkAAaBlBBikKZTgzCeA+k1uy4ZFwWANOfKw5z5LRhV0gNA7gNkKm7HoK+HRN0wX3EkxGk0fpbWhmB7g==",
+      "license": "MIT"
+    },
+    "node_modules/@types/d3-timer": {
+      "version": "3.0.2",
+      "resolved": "https://registry.npmjs.org/@types/d3-timer/-/d3-timer-3.0.2.tgz",
+      "integrity": "sha512-Ps3T8E8dZDam6fUyNiMkekK3XUsaUEik+idO9/YjPtfj2qruF8tFBXS7XhtE4iIXBLxhmLjP3SXpLhVf21I9Lw==",
+      "license": "MIT"
+    },
     "node_modules/@types/estree": {
       "version": "1.0.6",
       "resolved": "https://registry.npmjs.org/@types/estree/-/estree-1.0.6.tgz",
@@ -1191,7 +1268,6 @@
       "version": "19.0.12",
       "resolved": "https://registry.npmjs.org/@types/react/-/react-19.0.12.tgz",
       "integrity": "sha512-V6Ar115dBDrjbtXSrS+/Oruobc+qVbbUxDFC1RSbRqLt5SYvxxyIDrSC85RWml54g+jfNeEMZhEj7wW07ONQhA==",
-      "dev": true,
       "license": "MIT",
       "dependencies": {
         "csstype": "^3.0.2"
@@ -1207,6 +1283,16 @@
         "@types/react": "^19.0.0"
       }
     },
+    "node_modules/@types/recharts": {
+      "version": "1.8.29",
+      "resolved": "https://registry.npmjs.org/@types/recharts/-/recharts-1.8.29.tgz",
+      "integrity": "sha512-ulKklaVsnFIIhTQsQw226TnOibrddW1qUQNFVhoQEyY1Z7FRQrNecFCGt7msRuJseudzE9czVawZb17dK/aPXw==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/d3-shape": "^1",
+        "@types/react": "*"
+      }
+    },
     "node_modules/@types/uuid": {
       "version": "10.0.0",
       "resolved": "https://registry.npmjs.org/@types/uuid/-/uuid-10.0.0.tgz",
@@ -2047,6 +2133,15 @@
       "integrity": "sha512-IV3Ou0jSMzZrd3pZ48nLkT9DA7Ag1pnPzaiQhpW7c3RbcqqzvzzVu+L8gfqMp/8IM2MQtSiqaCxrrcfu8I8rMA==",
       "license": "MIT"
     },
+    "node_modules/clsx": {
+      "version": "2.1.1",
+      "resolved": "https://registry.npmjs.org/clsx/-/clsx-2.1.1.tgz",
+      "integrity": "sha512-eYm0QWBtUrBWZWG0d386OGAw16Z995PiOVo2B7bjWSbHedGl5e0ZWaq65kOGgUSNesEIDkB9ISbTg/JK9dhCZA==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=6"
+      }
+    },
     "node_modules/color": {
       "version": "4.2.3",
       "resolved": "https://registry.npmjs.org/color/-/color-4.2.3.tgz",
@@ -2118,9 +2213,129 @@
       "version": "3.1.3",
       "resolved": "https://registry.npmjs.org/csstype/-/csstype-3.1.3.tgz",
       "integrity": "sha512-M1uQkMl8rQK/szD0LNhtqxIPLpimGm8sOBwU7lLnCpSbTyY3yeU1Vc7l4KT5zT4s/yOxHH5O7tIuuLOCnLADRw==",
-      "dev": true,
       "license": "MIT"
     },
+    "node_modules/d3-array": {
+      "version": "3.2.4",
+      "resolved": "https://registry.npmjs.org/d3-array/-/d3-array-3.2.4.tgz",
+      "integrity": "sha512-tdQAmyA18i4J7wprpYq8ClcxZy3SC31QMeByyCFyRt7BVHdREQZ5lpzoe5mFEYZUWe+oq8HBvk9JjpibyEV4Jg==",
+      "license": "ISC",
+      "dependencies": {
+        "internmap": "1 - 2"
+      },
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/d3-color": {
+      "version": "3.1.0",
+      "resolved": "https://registry.npmjs.org/d3-color/-/d3-color-3.1.0.tgz",
+      "integrity": "sha512-zg/chbXyeBtMQ1LbD/WSoW2DpC3I0mpmPdW+ynRTj/x2DAWYrIY7qeZIHidozwV24m4iavr15lNwIwLxRmOxhA==",
+      "license": "ISC",
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/d3-ease": {
+      "version": "3.0.1",
+      "resolved": "https://registry.npmjs.org/d3-ease/-/d3-ease-3.0.1.tgz",
+      "integrity": "sha512-wR/XK3D3XcLIZwpbvQwQ5fK+8Ykds1ip7A2Txe0yxncXSdq1L9skcG7blcedkOX+ZcgxGAmLX1FrRGbADwzi0w==",
+      "license": "BSD-3-Clause",
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/d3-format": {
+      "version": "3.1.0",
+      "resolved": "https://registry.npmjs.org/d3-format/-/d3-format-3.1.0.tgz",
+      "integrity": "sha512-YyUI6AEuY/Wpt8KWLgZHsIU86atmikuoOmCfommt0LYHiQSPjvX2AcFc38PX0CBpr2RCyZhjex+NS/LPOv6YqA==",
+      "license": "ISC",
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/d3-interpolate": {
+      "version": "3.0.1",
+      "resolved": "https://registry.npmjs.org/d3-interpolate/-/d3-interpolate-3.0.1.tgz",
+      "integrity": "sha512-3bYs1rOD33uo8aqJfKP3JWPAibgw8Zm2+L9vBKEHJ2Rg+viTR7o5Mmv5mZcieN+FRYaAOWX5SJATX6k1PWz72g==",
+      "license": "ISC",
+      "dependencies": {
+        "d3-color": "1 - 3"
+      },
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/d3-path": {
+      "version": "3.1.0",
+      "resolved": "https://registry.npmjs.org/d3-path/-/d3-path-3.1.0.tgz",
+      "integrity": "sha512-p3KP5HCf/bvjBSSKuXid6Zqijx7wIfNW+J/maPs+iwR35at5JCbLUT0LzF1cnjbCHWhqzQTIN2Jpe8pRebIEFQ==",
+      "license": "ISC",
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/d3-scale": {
+      "version": "4.0.2",
+      "resolved": "https://registry.npmjs.org/d3-scale/-/d3-scale-4.0.2.tgz",
+      "integrity": "sha512-GZW464g1SH7ag3Y7hXjf8RoUuAFIqklOAq3MRl4OaWabTFJY9PN/E1YklhXLh+OQ3fM9yS2nOkCoS+WLZ6kvxQ==",
+      "license": "ISC",
+      "dependencies": {
+        "d3-array": "2.10.0 - 3",
+        "d3-format": "1 - 3",
+        "d3-interpolate": "1.2.0 - 3",
+        "d3-time": "2.1.1 - 3",
+        "d3-time-format": "2 - 4"
+      },
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/d3-shape": {
+      "version": "3.2.0",
+      "resolved": "https://registry.npmjs.org/d3-shape/-/d3-shape-3.2.0.tgz",
+      "integrity": "sha512-SaLBuwGm3MOViRq2ABk3eLoxwZELpH6zhl3FbAoJ7Vm1gofKx6El1Ib5z23NUEhF9AsGl7y+dzLe5Cw2AArGTA==",
+      "license": "ISC",
+      "dependencies": {
+        "d3-path": "^3.1.0"
+      },
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/d3-time": {
+      "version": "3.1.0",
+      "resolved": "https://registry.npmjs.org/d3-time/-/d3-time-3.1.0.tgz",
+      "integrity": "sha512-VqKjzBLejbSMT4IgbmVgDjpkYrNWUYJnbCGo874u7MMKIWsILRX+OpX/gTk8MqjpT1A/c6HY2dCA77ZN0lkQ2Q==",
+      "license": "ISC",
+      "dependencies": {
+        "d3-array": "2 - 3"
+      },
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/d3-time-format": {
+      "version": "4.1.0",
+      "resolved": "https://registry.npmjs.org/d3-time-format/-/d3-time-format-4.1.0.tgz",
+      "integrity": "sha512-dJxPBlzC7NugB2PDLwo9Q8JiTR3M3e4/XANkreKSUxF8vvXKqm1Yfq4Q5dl8budlunRVlUUaDUgFt7eA8D6NLg==",
+      "license": "ISC",
+      "dependencies": {
+        "d3-time": "1 - 3"
+      },
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/d3-timer": {
+      "version": "3.0.1",
+      "resolved": "https://registry.npmjs.org/d3-timer/-/d3-timer-3.0.1.tgz",
+      "integrity": "sha512-ndfJ/JxxMd3nw31uyKoY2naivF+r29V+Lc0svZxe1JvvIRmi8hUsrMvdOwgS1o6uBHmiz91geQ0ylPP0aj1VUA==",
+      "license": "ISC",
+      "engines": {
+        "node": ">=12"
+      }
+    },
     "node_modules/damerau-levenshtein": {
       "version": "1.0.8",
       "resolved": "https://registry.npmjs.org/damerau-levenshtein/-/damerau-levenshtein-1.0.8.tgz",
@@ -2210,6 +2425,12 @@
         }
       }
     },
+    "node_modules/decimal.js-light": {
+      "version": "2.5.1",
+      "resolved": "https://registry.npmjs.org/decimal.js-light/-/decimal.js-light-2.5.1.tgz",
+      "integrity": "sha512-qIMFpTMZmny+MMIitAB6D7iVPEorVw6YQRWkvarTkT4tBeSLLiHzcwj6q0MmYSFCiVpiqPJTJEYIrpcPzVEIvg==",
+      "license": "MIT"
+    },
     "node_modules/deep-is": {
       "version": "0.1.4",
       "resolved": "https://registry.npmjs.org/deep-is/-/deep-is-0.1.4.tgz",
@@ -2276,6 +2497,16 @@
         "node": ">=0.10.0"
       }
     },
+    "node_modules/dom-helpers": {
+      "version": "5.2.1",
+      "resolved": "https://registry.npmjs.org/dom-helpers/-/dom-helpers-5.2.1.tgz",
+      "integrity": "sha512-nRCa7CK3VTrM2NmGkIy4cbK7IZlgBE/PYMn55rrXefr5xXDP0LdtfPnblFDoVdcAfslJ7or6iqAUnx0CCGIWQA==",
+      "license": "MIT",
+      "dependencies": {
+        "@babel/runtime": "^7.8.7",
+        "csstype": "^3.0.2"
+      }
+    },
     "node_modules/dunder-proto": {
       "version": "1.0.1",
       "resolved": "https://registry.npmjs.org/dunder-proto/-/dunder-proto-1.0.1.tgz",
@@ -2925,6 +3156,12 @@
         "node": ">=0.10.0"
       }
     },
+    "node_modules/eventemitter3": {
+      "version": "4.0.7",
+      "resolved": "https://registry.npmjs.org/eventemitter3/-/eventemitter3-4.0.7.tgz",
+      "integrity": "sha512-8guHBZCwKnFhYdHr2ysuRWErTwhoN2X8XELRlrRwpmfeY2jjuUN4taQMsULKUVo1K4DvZl+0pgfyoysHxvmvEw==",
+      "license": "MIT"
+    },
     "node_modules/fast-deep-equal": {
       "version": "3.1.3",
       "resolved": "https://registry.npmjs.org/fast-deep-equal/-/fast-deep-equal-3.1.3.tgz",
@@ -2932,6 +3169,15 @@
       "dev": true,
       "license": "MIT"
     },
+    "node_modules/fast-equals": {
+      "version": "5.2.2",
+      "resolved": "https://registry.npmjs.org/fast-equals/-/fast-equals-5.2.2.tgz",
+      "integrity": "sha512-V7/RktU11J3I36Nwq2JnZEM7tNm17eBJz+u25qdxBZeCKiX6BkVSZQjwWIr+IobgnZy+ag73tTZgZi7tr0LrBw==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=6.0.0"
+      }
+    },
     "node_modules/fast-glob": {
       "version": "3.3.1",
       "resolved": "https://registry.npmjs.org/fast-glob/-/fast-glob-3.3.1.tgz",
@@ -3393,6 +3639,15 @@
         "node": ">= 0.4"
       }
     },
+    "node_modules/internmap": {
+      "version": "2.0.3",
+      "resolved": "https://registry.npmjs.org/internmap/-/internmap-2.0.3.tgz",
+      "integrity": "sha512-5Hh7Y1wQbvY5ooGgPbDaL5iYLAPzMTUrjMulskHLH6wnv/A+1q5rgEaiuqEjB+oxGXIVZs1FF+R/KPN3ZSQYYg==",
+      "license": "ISC",
+      "engines": {
+        "node": ">=12"
+      }
+    },
     "node_modules/is-array-buffer": {
       "version": "3.0.5",
       "resolved": "https://registry.npmjs.org/is-array-buffer/-/is-array-buffer-3.0.5.tgz",
@@ -3834,7 +4089,6 @@
       "version": "4.0.0",
       "resolved": "https://registry.npmjs.org/js-tokens/-/js-tokens-4.0.0.tgz",
       "integrity": "sha512-RdJUflcE3cUzKiMqQgsCu06FPu9UdIJO0beYbPhHN4k6apgJtifcoCtT9bcxOpYBtpD2kCM6Sbzg4CausW/PKQ==",
-      "dev": true,
       "license": "MIT"
     },
     "node_modules/js-yaml": {
@@ -4199,6 +4453,12 @@
         "url": "https://github.com/sponsors/sindresorhus"
       }
     },
+    "node_modules/lodash": {
+      "version": "4.17.21",
+      "resolved": "https://registry.npmjs.org/lodash/-/lodash-4.17.21.tgz",
+      "integrity": "sha512-v2kDEe57lecTulaDIuNTPy3Ry4gLGJ6Z1O3vE1krgXZNrsQ+LFTGHVxVjcXPs17LhbZVGedAJv8XZ1tvj5FvSg==",
+      "license": "MIT"
+    },
     "node_modules/lodash.merge": {
       "version": "4.6.2",
       "resolved": "https://registry.npmjs.org/lodash.merge/-/lodash.merge-4.6.2.tgz",
@@ -4210,7 +4470,6 @@
       "version": "1.4.0",
       "resolved": "https://registry.npmjs.org/loose-envify/-/loose-envify-1.4.0.tgz",
       "integrity": "sha512-lyuxPGr/Wfhrlem2CL/UcnUc1zcqKAImBDzukY7Y5F/yQiNdko6+fRLevlw1HgMySw7f611UIY408EtxRSoK3Q==",
-      "dev": true,
       "license": "MIT",
       "dependencies": {
         "js-tokens": "^3.0.0 || ^4.0.0"
@@ -4403,7 +4662,6 @@
       "version": "4.1.1",
       "resolved": "https://registry.npmjs.org/object-assign/-/object-assign-4.1.1.tgz",
       "integrity": "sha512-rJgTQnkUnH1sFw8yT6VSU3zD3sWmu6sZhIseY8VX+GRu3P6F7Fu+JNDoXfklElbLJSnc3FUQHVe4cU5hj+BcUg==",
-      "dev": true,
       "license": "MIT",
       "engines": {
         "node": ">=0.10.0"
@@ -4702,7 +4960,6 @@
       "version": "15.8.1",
       "resolved": "https://registry.npmjs.org/prop-types/-/prop-types-15.8.1.tgz",
       "integrity": "sha512-oj87CgZICdulUohogVAR7AjlC0327U4el4L6eAvOqCeudMDVU0NThNaV+b9Df4dXgSP1gXMTnPdhfe/2qDH5cg==",
-      "dev": true,
       "license": "MIT",
       "dependencies": {
         "loose-envify": "^1.4.0",
@@ -4766,7 +5023,75 @@
       "version": "16.13.1",
       "resolved": "https://registry.npmjs.org/react-is/-/react-is-16.13.1.tgz",
       "integrity": "sha512-24e6ynE2H+OKt4kqsOvNd8kBpV65zoxbA4BVsEOB3ARVWQki/DHzaUoC5KuON/BiccDaCCTZBuOcfZs70kR8bQ==",
-      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/react-smooth": {
+      "version": "4.0.4",
+      "resolved": "https://registry.npmjs.org/react-smooth/-/react-smooth-4.0.4.tgz",
+      "integrity": "sha512-gnGKTpYwqL0Iii09gHobNolvX4Kiq4PKx6eWBCYYix+8cdw+cGo3do906l1NBPKkSWx1DghC1dlWG9L2uGd61Q==",
+      "license": "MIT",
+      "dependencies": {
+        "fast-equals": "^5.0.1",
+        "prop-types": "^15.8.1",
+        "react-transition-group": "^4.4.5"
+      },
+      "peerDependencies": {
+        "react": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0",
+        "react-dom": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0"
+      }
+    },
+    "node_modules/react-transition-group": {
+      "version": "4.4.5",
+      "resolved": "https://registry.npmjs.org/react-transition-group/-/react-transition-group-4.4.5.tgz",
+      "integrity": "sha512-pZcd1MCJoiKiBR2NRxeCRg13uCXbydPnmB4EOeRrY7480qNWO8IIgQG6zlDkm6uRMsURXPuKq0GWtiM59a5Q6g==",
+      "license": "BSD-3-Clause",
+      "dependencies": {
+        "@babel/runtime": "^7.5.5",
+        "dom-helpers": "^5.0.1",
+        "loose-envify": "^1.4.0",
+        "prop-types": "^15.6.2"
+      },
+      "peerDependencies": {
+        "react": ">=16.6.0",
+        "react-dom": ">=16.6.0"
+      }
+    },
+    "node_modules/recharts": {
+      "version": "2.15.1",
+      "resolved": "https://registry.npmjs.org/recharts/-/recharts-2.15.1.tgz",
+      "integrity": "sha512-v8PUTUlyiDe56qUj82w/EDVuzEFXwEHp9/xOowGAZwfLjB9uAy3GllQVIYMWF6nU+qibx85WF75zD7AjqoT54Q==",
+      "license": "MIT",
+      "dependencies": {
+        "clsx": "^2.0.0",
+        "eventemitter3": "^4.0.1",
+        "lodash": "^4.17.21",
+        "react-is": "^18.3.1",
+        "react-smooth": "^4.0.4",
+        "recharts-scale": "^0.4.4",
+        "tiny-invariant": "^1.3.1",
+        "victory-vendor": "^36.6.8"
+      },
+      "engines": {
+        "node": ">=14"
+      },
+      "peerDependencies": {
+        "react": "^16.0.0 || ^17.0.0 || ^18.0.0 || ^19.0.0",
+        "react-dom": "^16.0.0 || ^17.0.0 || ^18.0.0 || ^19.0.0"
+      }
+    },
+    "node_modules/recharts-scale": {
+      "version": "0.4.5",
+      "resolved": "https://registry.npmjs.org/recharts-scale/-/recharts-scale-0.4.5.tgz",
+      "integrity": "sha512-kivNFO+0OcUNu7jQquLXAxz1FIwZj8nrj+YkOKc5694NbjCvcT6aSZiIzNzd2Kul4o4rTto8QVR9lMNtxD4G1w==",
+      "license": "MIT",
+      "dependencies": {
+        "decimal.js-light": "^2.4.1"
+      }
+    },
+    "node_modules/recharts/node_modules/react-is": {
+      "version": "18.3.1",
+      "resolved": "https://registry.npmjs.org/react-is/-/react-is-18.3.1.tgz",
+      "integrity": "sha512-/LLMVyas0ljjAtoYiPqYiL8VWXzUUdThrmU5+n20DZv+a+ClRoevUzw5JxU+Ieh5/c87ytoTBV9G1FiKfNJdmg==",
       "license": "MIT"
     },
     "node_modules/reflect.getprototypeof": {
@@ -4792,6 +5117,12 @@
         "url": "https://github.com/sponsors/ljharb"
       }
     },
+    "node_modules/regenerator-runtime": {
+      "version": "0.14.1",
+      "resolved": "https://registry.npmjs.org/regenerator-runtime/-/regenerator-runtime-0.14.1.tgz",
+      "integrity": "sha512-dYnhHh0nJoMfnkZs6GmmhFknAGRrLznOu5nc9ML+EJxGvrx6H7teuevqVqCuPcPK//3eDrrjQhehXVx9cnkGdw==",
+      "license": "MIT"
+    },
     "node_modules/regexp.prototype.flags": {
       "version": "1.5.4",
       "resolved": "https://registry.npmjs.org/regexp.prototype.flags/-/regexp.prototype.flags-1.5.4.tgz",
@@ -5410,6 +5741,12 @@
         "node": ">=6"
       }
     },
+    "node_modules/tiny-invariant": {
+      "version": "1.3.3",
+      "resolved": "https://registry.npmjs.org/tiny-invariant/-/tiny-invariant-1.3.3.tgz",
+      "integrity": "sha512-+FbBPE1o9QAYvviau/qC5SE3caw21q3xkvWKBtja5vgqOWIHHJ3ioaq1VPfn/Szqctz2bU/oYeKd9/z5BL+PVg==",
+      "license": "MIT"
+    },
     "node_modules/tinyglobby": {
       "version": "0.2.12",
       "resolved": "https://registry.npmjs.org/tinyglobby/-/tinyglobby-0.2.12.tgz",
@@ -5654,6 +5991,37 @@
         "uuid": "dist/bin/uuid"
       }
     },
+    "node_modules/victory-vendor": {
+      "version": "36.9.2",
+      "resolved": "https://registry.npmjs.org/victory-vendor/-/victory-vendor-36.9.2.tgz",
+      "integrity": "sha512-PnpQQMuxlwYdocC8fIJqVXvkeViHYzotI+NJrCuav0ZYFoq912ZHBk3mCeuj+5/VpodOjPe1z0Fk2ihgzlXqjQ==",
+      "license": "MIT AND ISC",
+      "dependencies": {
+        "@types/d3-array": "^3.0.3",
+        "@types/d3-ease": "^3.0.0",
+        "@types/d3-interpolate": "^3.0.1",
+        "@types/d3-scale": "^4.0.2",
+        "@types/d3-shape": "^3.1.0",
+        "@types/d3-time": "^3.0.0",
+        "@types/d3-timer": "^3.0.0",
+        "d3-array": "^3.1.6",
+        "d3-ease": "^3.0.1",
+        "d3-interpolate": "^3.0.1",
+        "d3-scale": "^4.0.2",
+        "d3-shape": "^3.1.0",
+        "d3-time": "^3.0.0",
+        "d3-timer": "^3.0.1"
+      }
+    },
+    "node_modules/victory-vendor/node_modules/@types/d3-shape": {
+      "version": "3.1.7",
+      "resolved": "https://registry.npmjs.org/@types/d3-shape/-/d3-shape-3.1.7.tgz",
+      "integrity": "sha512-VLvUQ33C+3J+8p+Daf+nYSOsjB4GXp19/S/aGo60m9h1v6XaxjiT82lKVWJCfzhtuZ3yD7i/TPeC/fuKLLOSmg==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/d3-path": "*"
+      }
+    },
     "node_modules/which": {
       "version": "2.0.2",
       "resolved": "https://registry.npmjs.org/which/-/which-2.0.2.tgz",

package.json

@@ -25,12 +25,16 @@
   "dependencies": {
     "@clickhouse/client": "^1.11.0",
     "@types/chart.js": "^2.9.41",
+    "@types/recharts": "^1.8.29",
     "@types/uuid": "^10.0.0",
     "chart.js": "^4.4.8",
     "date-fns": "^4.1.0",
     "next": "15.2.3",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
+    "recharts": "^2.15.1",
+    "swagger-ui-dist": "^5.12.0",
+    "swagger-ui-react": "^5.12.0",
     "uuid": "^10.0.0"
   },
   "devDependencies": {
@@ -39,10 +43,13 @@
     "@types/node": "^20",
     "@types/react": "^19",
     "@types/react-dom": "^19",
+    "@types/swagger-ui-react": "^4.18.3",
+    "css-loader": "^7.1.2",
     "eslint": "^9",
     "eslint-config-next": "15.2.3",
+    "style-loader": "^4.0.0",
     "tailwindcss": "^4",
     "typescript": "^5"
   },
   "packageManager": "pnpm@9.15.4+sha512.b2dc20e2fc72b3e18848459b37359a32064663e5627a51e4c74b2c29dd8e8e0491483c3abb40789cfd578bf362fb6ba8261b05f0387d76792ed6e23ea3b1b6a0"
-}
+}