change config

README.md

@@ -1,36 +1,188 @@
-This is a [Next.js](https://nextjs.org) project bootstrapped with [`create-next-app`](https://nextjs.org/docs/app/api-reference/cli/create-next-app).
+# ShortURL Analytics系统详细分析
 
-## Getting Started
+## 总体架构
 
-First, run the development server:
+ShortURL Analytics是一个完整的短链接分析系统，基于Next.js 15构建，采用了前后端一体化的架构设计。该系统专注于提供短链接使用情况的详细分析和可视化，而非链接管理功能。
 
-```bash
+系统使用TypeScript提供类型安全，使用ClickHouse作为后端分析数据库，通过Tailwind CSS实现现代UI设计。整体架构采用了React客户端组件与Next.js API Routes相结合的方式，实现了高性能的数据分析和可视化。
-npm run dev
-# or
-yarn dev
-# or
-pnpm dev
-# or
-bun dev
-```
 
-Open [http://localhost:3000](http://localhost:3000) with your browser to see the result.
+## 数据流动流程
 
-You can start editing the page by modifying `app/page.tsx`. The page auto-updates as you edit the file.
+1. **数据采集层**：
+   - 通过`/api/analytics/track` API端点收集用户行为数据
+   - 客户端通过SDK或脚本将事件数据(点击、转化等)发送到服务器
+   - 服务器解析请求参数，并调用`trackEvent`函数进行数据存储
 
-This project uses [`next/font`](https://nextjs.org/docs/app/building-your-application/optimizing/fonts) to automatically optimize and load [Geist](https://vercel.com/font), a new font family for Vercel.
+2. **数据存储层**：
+   - 使用ClickHouse列式数据库存储大量的事件数据
+   - 主要数据表为`link_events`，存储所有访问和转化事件
+   - 对每个事件记录：访问者ID、会话ID、设备信息、时间戳、引荐来源等
 
-## Learn More
+3. **数据处理层**：
+   - `lib/analytics.ts`提供各种数据分析函数，使用SQL查询ClickHouse
+   - 支持时间范围过滤、时间粒度聚合、多维度分组和排序
+   - 对原始数据进行聚合计算，生成各类分析指标
 
-To learn more about Next.js, take a look at the following resources:
+4. **API层**：
+   - 提供多个API端点，对应不同的分析维度
+   - 每个API端点接收查询参数(如linkId、时间范围等)
+   - 调用相应的分析函数并返回格式化结果
 
-- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js features and API.
+5. **前端展示层**：
-- [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial.
+   - 使用React客户端组件获取和展示数据
+   - 支持交互式筛选、排序和可视化
+   - 实现响应式UI，适配不同设备
 
-You can check out [the Next.js GitHub repository](https://github.com/vercel/next.js) - your feedback and contributions are welcome!
+## 前端实现
 
-## Deploy on Vercel
+### 页面结构
 
-The easiest way to deploy your Next.js app is to use the [Vercel Platform](https://vercel.com/new?utm_medium=default-template&filter=next.js&utm_source=create-next-app&utm_campaign=create-next-app-readme) from the creators of Next.js.
+1. **主页 (app/page.tsx)**：
+   - 系统入口，提供导航到仪表盘和链接页面的链接
+   - 采用渐变背景和卡片设计，提供简洁美观的界面
 
-Check out our [Next.js deployment documentation](https://nextjs.org/docs/app/building-your-application/deploying) for more details.
+2. **链接列表页 (app/links/page.tsx)**：
+   - 显示所有短链接的表格视图
+   - 支持搜索、筛选和排序功能
+   - 实现分页加载和响应式布局
+   - 提供创建新链接的模态框入口(虽然实际创建功能不在此项目中)
+
+3. **链接详情页 (app/links/[id]/page.tsx)**：
+   - 使用动态路由显示单个链接的详细分析
+   - 包含多个选项卡展示不同分析维度
+   - 支持日期范围和时间粒度的动态调整
+   - 集成多种图表和可视化组件
+
+### 核心组件
+
+1. **StatsCard组件**：
+   - 显示单个统计指标，包括数值和变化百分比
+   - 支持不同颜色方案和单位格式
+   - 使用渐变条表示进度（百分比指标）
+
+2. **LinkDetailsCard组件**：
+   - 显示链接的基本信息和关键指标
+   - 支持标签显示和状态指示
+   - 提供详情展开和关闭功能
+
+3. **图表组件**：
+   - 使用客户端渲染实现各类数据可视化
+   - 实现柱状图、折线图、饼图、漏斗图等
+   - 支持交互式提示和动画效果
+
+4. **UI组件库**：
+   - 自定义设计的表单控件、按钮、下拉菜单等
+   - 实现主题一致性和品牌识别
+
+## 后端实现
+
+### API路由设计
+
+1. **数据追踪API**：
+   - `POST /api/analytics/track`：记录用户事件数据
+
+2. **分析数据API**：
+   - `GET /api/analytics/overview`：获取链接概览数据
+   - `GET /api/analytics/funnel`：获取转化漏斗数据
+   - `GET /api/analytics/trends`：获取访问趋势数据
+   - `GET /api/analytics/link-performance`：获取链接表现数据
+   - `GET /api/analytics/platform-distribution`：获取平台分布数据
+   - `GET /api/analytics/device-analysis`：获取设备分析数据
+   - `GET /api/analytics/popular-referrers`：获取热门引荐来源
+   - `GET /api/analytics/qr-code-analysis`：获取QR码分析数据
+   - `GET /api/analytics/overview-cards`：获取概览卡片数据
+
+3. **链接管理API**：
+   - `GET /api/links`：获取链接列表
+   - `GET /api/links/:id`：获取单个链接详情
+   - `GET /api/stats`：获取统计概览数据
+   - `GET /api/tags`：获取标签列表
+
+### 数据分析逻辑
+
+1. **访问分析**：
+   - 通过SQL聚合计算总访问量和独立访问者数
+   - 支持按小时、天、周、月等时间粒度聚合
+   - 提供环比和同比增长计算
+
+2. **转化漏斗分析**：
+   - 追踪用户从访问到最终转化的完整路径
+   - 计算每个阶段的转化率和流失率
+   - 识别转化路径中的瓶颈
+
+3. **设备和平台分析**：
+   - 从用户代理字符串提取设备和浏览器信息
+   - 统计不同设备类型、操作系统和浏览器的分布
+   - 分析移动端vs桌面端的使用情况
+
+4. **引荐来源分析**：
+   - 解析和分类引荐域名
+   - 统计各来源的访问量和转化率
+   - 识别最有价值的流量来源
+
+5. **QR码分析**：
+   - 追踪QR码扫描事件
+   - 分析地理位置、设备类型和时间分布
+   - 对比QR码和其他渠道的效果
+
+## 特色功能
+
+1. **实时数据处理**：
+   - 使用ClickHouse高性能列式存储快速分析大量事件数据
+   - API响应时间短，前端体验流畅
+
+2. **多维度分析**：
+   - 支持从多个角度分析短链接性能
+   - 可进行深度钻取分析，找出关键洞察
+
+3. **交互式可视化**：
+   - 前端实现多种图表类型，展示复杂数据关系
+   - 支持交互式筛选，调整视图粒度
+
+4. **响应式设计**：
+   - 桌面和移动设备均提供良好体验
+   - 各组件自适应不同屏幕尺寸
+
+5. **时间序列分析**：
+   - 支持历史趋势对比和时间序列预测
+   - 自动识别峰值和异常模式
+
+## 技术栈
+
+1. **前端**：
+   - 框架：Next.js 15.2.3
+   - UI库：自定义Tailwind CSS组件
+   - 状态管理：React Hooks (useState, useEffect)
+   - 数据获取：fetch API, SWR
+   - 路由：Next.js App Router
+
+2. **后端**：
+   - API：Next.js API Routes
+   - 数据库：ClickHouse
+   - 数据处理：原生SQL + TypeScript处理函数
+   - 性能优化：查询缓存和索引优化
+
+3. **基础设施**：
+   - 部署：Vercel (推测)
+   - 数据库托管：自托管或云服务ClickHouse
+   - 环境配置：.env.local文件
+
+## 实现挑战与解决方案
+
+1. **大数据处理**：
+   - 挑战：需处理大量事件数据并实时分析
+   - 解决方案：使用ClickHouse高性能列式数据库，优化SQL查询
+
+2. **复杂可视化**：
+   - 挑战：在前端展示复杂的分析图表
+   - 解决方案：自定义React图表组件，实现各类数据可视化
+
+3. **前后端数据一致性**：
+   - 挑战：确保API返回的数据格式与前端需求一致
+   - 解决方案：使用TypeScript接口定义统一的数据类型
+
+4. **性能优化**：
+   - 挑战：确保在大量数据情况下UI响应迅速
+   - 解决方案：实现数据分页、虚拟滚动和懒加载
+
+这个ShortURL Analytics系统通过前后端协同工作，为短链接提供全面细致的数据分析能力，帮助用户理解短链接效果，优化营销策略，提高用户参与度和转化率。系统设计体现了现代Web应用的最佳实践，并针对数据分析场景进行了特别优化。

next.config.ts

@@ -8,7 +8,7 @@ const nextConfig: NextConfig = {
   // 配置实验性选项
   experimental: {
     // 禁用外部目录处理，避免monorepo问题
-    externalDir: true,
+    // externalDir: true,
   },
   
   // 禁用严格模式，避免开发时重复渲染

package.json

@@ -3,9 +3,9 @@
   "version": "0.1.0",
   "private": true,
   "scripts": {
-    "dev": "NEXT_TELEMETRY_DISABLED=1 next dev",
+    "dev": "next dev --turbo",
-    "build": "NEXT_TELEMETRY_DISABLED=1 next build",
+    "build": "next build",
-    "start": "NEXT_TELEMETRY_DISABLED=1 next start",
+    "start": "next start",
     "lint": "next lint"
   },
   "dependencies": {
@@ -26,5 +26,6 @@
     "eslint-config-next": "15.2.3",
     "tailwindcss": "^4",
     "typescript": "^5"
-  }
+  },
+  "packageManager": "pnpm@9.15.4+sha512.b2dc20e2fc72b3e18848459b37359a32064663e5627a51e4c74b2c29dd8e8e0491483c3abb40789cfd578bf362fb6ba8261b05f0387d76792ed6e23ea3b1b6a0"
 }