# StatisticalAnalysis

**Repository Path**: DevPool/StatisticalAnalysis

## Basic Information

- **Project Name**: StatisticalAnalysis
- **Description**: 埋点统计管理系统是一个基于 Spring Boot + MyBatis Plus + MySQL + Redis + RocketMQ 的完整事件追踪和统计分析平台。系统支持多客户端数据采集、实时统计分析、数据导出和系统监控等功能。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-10-27
- **Last Updated**: 2025-10-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 埋点统计管理系统

## 📋 项目简介

埋点统计管理系统是一个基于 Spring Boot + MyBatis Plus + MySQL + Redis + RocketMQ 的完整事件追踪和统计分析平台。系统支持多客户端数据采集、实时统计分析、数据导出和系统监控等功能。

### 🎯 核心功能

- **数据采集**: 支持 Web、小程序、Android、iOS 等多客户端事件数据采集
- **统计分析**: 多维度数据统计、实时 PV/UV 分析、客户端分布分析、页面停留时长统计
- **全埋点追踪**: 自动采集用户行为数据，包括点击、滚动、输入、焦点等事件
- **数据导出**: Excel 报表导出，支持事件数据、统计报表、客户端分布
- **系统监控**: 实时系统性能监控、健康检查、性能指标分析
- **API 文档**: 完整的 Swagger/OpenAPI 文档，支持在线测试

### 🛠️ 技术栈

- **后端框架**: Spring Boot 3.4.7
- **ORM 框架**: MyBatis Plus 3.5.7
- **数据库**: MySQL 8.0
- **缓存**: Redis
- **消息队列**: RocketMQ
- **API 文档**: SpringDoc OpenAPI 3.0
- **Excel 导出**: Apache POI
- **监控**: Spring Boot Actuator

## 🚀 快速开始

### 环境要求

- JDK 17+
- Maven 3.6+
- MySQL 8.0+
- Redis 6.0+
- RocketMQ 4.9+

### 安装步骤

1. **克隆项目**
```bash
git clone <repository-url>
cd StatisticalAnalysis
```

2. **数据库配置**
```sql
-- 创建数据库
CREATE DATABASE statistical_analysis DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

-- 执行初始化脚本
USE statistical_analysis;
SOURCE src/main/resources/sql/schema.sql;
```

3. **配置文件修改**
编辑 `src/main/resources/application.properties`：
```properties
# MySQL 配置
spring.datasource.url=jdbc:mysql://localhost:3306/statistical_analysis
spring.datasource.username=your_username
spring.datasource.password=your_password

# Redis 配置
spring.redis.host=localhost
spring.redis.port=6379
spring.redis.password=your_redis_password

# RocketMQ 配置
rocketmq.name-server=localhost:9876
```

4. **启动服务**
```bash
# 编译项目
mvn clean compile

# 运行应用
mvn spring-boot:run
```

### 访问地址

- **应用首页**: http://localhost:8080/statistical-analysis
- **API 文档**: http://localhost:8080/statistical-analysis/swagger-ui.html
- **健康检查**: http://localhost:8080/statistical-analysis/actuator/health

## 📊 功能模块详解

### 1. 数据采集模块

#### 事件数据结构
```json
{
  "eventId": "page_view_001",
  "eventType": "page_view",
  "eventName": "页面访问",
  "userId": "user_001",
  "sessionId": "session_001",
  "pageUrl": "/home",
  "pageTitle": "首页",
  "userAgent": "Mozilla/5.0...",
  "ipAddress": "192.168.1.1",
  "clientTimestamp": 1640995200000,
  "stayDuration": 5000
}
```

#### 全埋点数据结构
```json
{
  "sessionId": "session_001",
  "userId": "user_001",
  "pageUrl": "/home",
  "pageTitle": "首页",
  "actionType": "click",
  "elementInfo": {
    "tagName": "button",
    "id": "submit-btn",
    "className": "btn-primary",
    "textContent": "提交",
    "selector": "#submit-btn",
    "position": {
      "x": 100,
      "y": 200,
      "width": 80,
      "height": 40
    }
  },
  "stayDuration": 5000,
  "scrollDepth": 75,
  "viewportInfo": {
    "width": 1920,
    "height": 1080,
    "screenWidth": 1920,
    "screenHeight": 1080
  },
  "clientTimestamp": 1640995200000,
  "userAgent": "Mozilla/5.0...",
  "ipAddress": "192.168.1.1"
}
```

#### API 接口
- `POST /api/tracking/event` - 单条事件采集
- `POST /api/tracking/events/batch` - 批量事件采集
- `POST /api/auto-tracking/event` - 单条全埋点事件采集
- `POST /api/auto-tracking/events/batch` - 批量全埋点事件采集
- `GET /api/auto-tracking/session/{sessionId}/page-views` - 获取会话页面浏览序列
- `GET /api/auto-tracking/user/{userId}/behavior-path` - 获取用户行为路径
- `GET /api/tracking/health` - 健康检查

### 2. 统计分析模块

#### 统计维度
- 时间维度：按小时、按天统计
- 事件类型维度：页面访问、按钮点击、表单提交等
- 客户端维度：Web、小程序、Android、iOS
- 用户维度：独立用户数、平均事件数
- 页面停留时长：平均停留时长、最长停留时长、停留时长分布
- 用户行为分析：页面浏览序列、行为路径分析

#### API 接口
- `GET /api/statistics/basic` - 基础统计信息
- `GET /api/statistics/event-type-distribution` - 事件类型分布
- `GET /api/statistics/client-type-distribution` - 客户端分布
- `GET /api/statistics/realtime` - 实时 PV/UV
- `GET /api/statistics/time-series` - 时间序列数据
- `GET /api/statistics/page-duration` - 页面停留时长统计
- `GET /api/statistics/realtime-avg-duration` - 实时平均停留时长

### 3. 全埋点追踪模块

#### 行为类型支持
- **页面浏览** (page_view): 页面访问和离开事件
- **点击事件** (click): 按钮、链接等元素点击
- **滚动事件** (scroll): 页面滚动深度和位置
- **输入事件** (input): 表单输入和文本编辑
- **焦点事件** (focus/blur): 元素焦点变化
- **鼠标事件** (mouseover/mouseout): 鼠标悬停和移出
- **窗口事件** (resize): 窗口大小变化
- **可见性事件** (visibility_change): 页面可见性变化

#### 数据采集能力
- **元素级追踪**: 精确到具体DOM元素的交互行为
- **页面停留时长**: 自动计算页面停留时间
- **滚动深度分析**: 记录用户滚动行为
- **视口信息**: 设备屏幕和视口尺寸
- **性能指标**: 页面加载和渲染性能
- **自定义属性**: 灵活扩展业务属性

#### API 接口
- `POST /api/auto-tracking/event` - 单条全埋点事件采集
- `POST /api/auto-tracking/events/batch` - 批量全埋点事件采集
- `GET /api/auto-tracking/session/{sessionId}/page-views` - 获取会话页面浏览序列
- `GET /api/auto-tracking/user/{userId}/behavior-path` - 获取用户行为路径

### 4. 数据导出模块

#### 导出功能
- **事件数据导出**: 导出原始事件数据到 Excel
- **统计报表导出**: 包含汇总统计和详细数据
- **客户端分布导出**: 客户端类型分布报表
- **全埋点数据导出**: 导出全埋点行为数据
- **页面停留时长报表**: 停留时长分析报表

#### API 接口
- `POST /api/export/events/excel` - 导出事件数据
- `POST /api/export/statistics/excel` - 导出统计报表
- `POST /api/export/client-distribution/excel` - 导出客户端分布
- `POST /api/export/auto-tracking/excel` - 导出全埋点数据
- `POST /api/export/page-duration/excel` - 导出页面停留时长报表

### 4. 系统监控模块

#### 监控指标
- **系统信息**: CPU、内存、操作系统
- **JVM 监控**: 堆内存、非堆内存、GC 信息
- **应用统计**: PV/UV、总事件数、在线用户数
- **组件状态**: 数据库、Redis 连接状态

#### API 接口
- `GET /api/monitor/system` - 系统监控信息
- `GET /api/monitor/health` - 健康检查
- `GET /api/monitor/app-overview` - 应用概览
- `GET /api/monitor/performance` - 性能指标

## 🗄️ 数据库设计

### 核心数据表

#### 1. 埋点事件表 (tracking_event)
```sql
CREATE TABLE `tracking_event` (
    `id` bigint(20) NOT NULL AUTO_INCREMENT COMMENT '主键ID',
    `event_id` varchar(64) NOT NULL COMMENT '事件ID',
    `event_type` varchar(50) NOT NULL COMMENT '事件类型',
    `event_name` varchar(100) NOT NULL COMMENT '事件名称',
    `user_id` varchar(64) DEFAULT NULL COMMENT '用户ID',
    `session_id` varchar(64) DEFAULT NULL COMMENT '会话ID',
    `page_url` varchar(500) DEFAULT NULL COMMENT '页面URL',
    `page_title` varchar(200) DEFAULT NULL COMMENT '页面标题',
    `element_selector` varchar(500) DEFAULT NULL COMMENT '元素选择器',
    `event_data` json DEFAULT NULL COMMENT '事件数据（JSON格式）',
    `user_agent` text DEFAULT NULL COMMENT '用户代理',
    `ip_address` varchar(45) DEFAULT NULL COMMENT 'IP地址',
    `device_info` varchar(200) DEFAULT NULL COMMENT '设备信息',
    `client_type` varchar(20) DEFAULT NULL COMMENT '客户端类型',
    `client_version` varchar(50) DEFAULT NULL COMMENT '客户端版本',
    `client_timestamp` bigint(20) NOT NULL COMMENT '客户端时间戳',
    `stay_duration` bigint(20) DEFAULT NULL COMMENT '页面停留时长（毫秒）',
    `create_time` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
    `update_time` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
    PRIMARY KEY (`id`),
    KEY `idx_event_id` (`event_id`),
    KEY `idx_event_type` (`event_type`),
    KEY `idx_user_id` (`user_id`),
    KEY `idx_session_id` (`session_id`),
    KEY `idx_create_time` (`create_time`),
    KEY `idx_client_timestamp` (`client_timestamp`)
) COMMENT='埋点事件表';
```

#### 2. 全埋点事件表 (auto_tracking_event)
```sql
CREATE TABLE `auto_tracking_event` (
    `id` bigint(20) NOT NULL AUTO_INCREMENT COMMENT '主键ID',
    `event_id` varchar(64) NOT NULL COMMENT '事件ID',
    `session_id` varchar(64) NOT NULL COMMENT '会话ID',
    `user_id` varchar(64) DEFAULT NULL COMMENT '用户ID',
    `page_url` varchar(500) NOT NULL COMMENT '页面URL',
    `page_title` varchar(200) DEFAULT NULL COMMENT '页面标题',
    `action_type` varchar(50) NOT NULL COMMENT '行为类型',
    `element_info` json DEFAULT NULL COMMENT '元素信息（JSON格式）',
    `stay_duration` bigint(20) DEFAULT NULL COMMENT '页面停留时长（毫秒）',
    `scroll_depth` int(11) DEFAULT NULL COMMENT '滚动深度（百分比）',
    `viewport_info` json DEFAULT NULL COMMENT '视口信息（JSON格式）',
    `performance_metrics` json DEFAULT NULL COMMENT '性能指标（JSON格式）',
    `custom_attributes` json DEFAULT NULL COMMENT '自定义属性（JSON格式）',
    `client_timestamp` bigint(20) NOT NULL COMMENT '客户端时间戳',
    `user_agent` text DEFAULT NULL COMMENT '用户代理',
    `ip_address` varchar(45) DEFAULT NULL COMMENT 'IP地址',
    `device_info` varchar(200) DEFAULT NULL COMMENT '设备信息',
    `client_type` varchar(20) DEFAULT NULL COMMENT '客户端类型',
    `client_version` varchar(50) DEFAULT NULL COMMENT '客户端版本',
    `create_time` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
    `update_time` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
    PRIMARY KEY (`id`),
    KEY `idx_event_id` (`event_id`),
    KEY `idx_session_id` (`session_id`),
    KEY `idx_user_id` (`user_id`),
    KEY `idx_action_type` (`action_type`),
    KEY `idx_create_time` (`create_time`),
    KEY `idx_client_timestamp` (`client_timestamp`)
) COMMENT='全埋点事件表';
```

#### 3. 统计聚合表
- `event_statistics_hourly` - 小时级事件统计
- `event_statistics_daily` - 天级事件统计
- `user_behavior_path` - 用户行为路径分析

## 🔧 配置说明

### 应用配置

#### 数据库配置
```properties
# MySQL 连接池配置
spring.datasource.hikari.maximum-pool-size=20
spring.datasource.hikari.minimum-idle=5
spring.datasource.hikari.idle-timeout=300000
spring.datasource.hikari.connection-timeout=20000
```

#### Redis 配置
```properties
# Redis 连接池配置
spring.redis.lettuce.pool.max-active=20
spring.redis.lettuce.pool.max-wait=-1
spring.redis.lettuce.pool.max-idle=10
spring.redis.lettuce.pool.min-idle=5
```

#### 日志配置
```properties
# 日志级别配置
logging.level.com.wangzs.statisticalanalysis=INFO
logging.level.org.springframework.web=INFO
logging.level.org.apache.ibatis=WARN

# 日志文件配置
logging.file.name=logs/statistical-analysis.log
logging.pattern.file=%d{yyyy-MM-dd HH:mm:ss} [%thread] %-5level %logger{50} - %msg%n
```

### 监控配置

#### Actuator 端点
```properties
# 启用监控端点
management.endpoints.web.exposure.include=health,info,metrics,env
management.endpoint.health.show-details=always
management.metrics.export.prometheus.enabled=true
```

## 📈 性能优化

### 1. 数据库优化

#### 索引设计
```sql
-- 事件表索引
CREATE INDEX idx_event_create_time ON tracking_event(create_time);
CREATE INDEX idx_event_user_id ON tracking_event(user_id);
CREATE INDEX idx_event_session_id ON tracking_event(session_id);
CREATE INDEX idx_event_client_type ON tracking_event(client_type);
```

#### 查询优化
- 使用分页查询避免大数据量查询
- 合理使用索引覆盖查询
- 定期清理历史数据

### 2. 缓存优化

#### Redis 缓存策略
```java
// 统计结果缓存 5 分钟
redisTemplate.opsForValue().set(cacheKey, result, 5, TimeUnit.MINUTES);

// 实时数据缓存 24 小时
redisTemplate.expire(pvKey, 24, TimeUnit.HOURS);
```

### 3. 全埋点技术实现

#### 前端集成示例
```javascript
// 全埋点数据采集示例
class AutoTracker {
    constructor() {
        this.sessionId = this.generateSessionId();
        this.pageStartTime = Date.now();
        this.initEventListeners();
    }
    
    // 页面浏览事件
    trackPageView(pageInfo) {
        const data = {
            sessionId: this.sessionId,
            pageUrl: pageInfo.url,
            pageTitle: pageInfo.title,
            actionType: 'page_view',
            clientTimestamp: Date.now(),
            stayDuration: Date.now() - this.pageStartTime
        };
        this.sendToServer(data);
    }
    
    // 点击事件
    trackClick(element, event) {
        const data = {
            sessionId: this.sessionId,
            actionType: 'click',
            elementInfo: {
                tagName: element.tagName,
                id: element.id,
                className: element.className,
                textContent: element.textContent,
                selector: this.getElementSelector(element)
            },
            clientTimestamp: Date.now()
        };
        this.sendToServer(data);
    }
    
    // 滚动事件
    trackScroll() {
        const scrollDepth = Math.round((window.scrollY + window.innerHeight) / document.body.scrollHeight * 100);
        const data = {
            sessionId: this.sessionId,
            actionType: 'scroll',
            scrollDepth: scrollDepth,
            clientTimestamp: Date.now()
        };
        this.sendToServer(data);
    }
}
```

### 4. 异步处理

#### RocketMQ 消息队列
- 事件采集异步处理，提高吞吐量
- 批量消息处理，减少数据库压力
- 消息重试机制，保证数据可靠性

#### 批量处理优化
```java
// 批量处理全埋点事件
public boolean recordAutoTrackingEventsBatch(List<AutoTrackingDTO> trackingDTOs) {
    try {
        List<AutoTrackingEntity> entities = trackingDTOs.stream()
                .map(this::convertToEntity)
                .peek(entity -> entity.setEventId(generateEventId()))
                .collect(Collectors.toList());
        
        boolean saveResult = saveBatch(entities);
        
        if (saveResult) {
            // 批量记录实时统计
            for (AutoTrackingEntity entity : entities) {
                recordRealTimeStats(entity);
            }
        }
        
        return saveResult;
    } catch (Exception e) {
        log.error("批量记录全埋点事件异常: error={}", e.getMessage(), e);
        return false;
    }
}
```

## 🐛 故障排除

### 常见问题

#### 1. 数据库连接失败
```bash
# 检查数据库服务状态
systemctl status mysql

# 检查连接配置
cat src/main/resources/application.properties | grep spring.datasource
```

#### 2. Redis 连接失败
```bash
# 检查 Redis 服务状态
systemctl status redis

# 测试 Redis 连接
redis-cli ping
```

#### 3. RocketMQ 连接失败
```bash
# 检查 RocketMQ 服务状态
systemctl status rocketmq

# 检查 NameServer
mqadmin clusterList -n localhost:9876
```

### 日志分析

#### 日志文件位置
```bash
# 应用日志
tail -f logs/statistical-analysis.log

# 错误日志
grep "ERROR" logs/statistical-analysis.log

# 慢查询日志
grep "SLOW" logs/statistical-analysis.log
```

## 🔄 部署指南

### Docker 部署

#### Dockerfile
```dockerfile
FROM openjdk:17-jdk-slim
VOLUME /tmp
COPY target/StatisticalAnalysis-0.0.1-SNAPSHOT.jar app.jar
ENTRYPOINT ["java","-jar","/app.jar"]
```

#### Docker Compose
```yaml
version: '3.8'
services:
  mysql:
    image: mysql:8.0
    environment:
      MYSQL_ROOT_PASSWORD: root
      MYSQL_DATABASE: statistical_analysis
    ports:
      - "3306:3306"
    
  redis:
    image: redis:6.2-alpine
    ports:
      - "6379:6379"
    
  rocketmq:
    image: rocketmqinc/rocketmq:4.9.0
    ports:
      - "9876:9876"
    
  app:
    build: .
    ports:
      - "8080:8080"
    depends_on:
      - mysql
      - redis
      - rocketmq
```

### 生产环境配置

#### 应用配置
```properties
# 生产环境配置
spring.profiles.active=prod

# 数据库连接池
spring.datasource.hikari.maximum-pool-size=50
spring.datasource.hikari.minimum-idle=10

# Redis 连接池
spring.redis.lettuce.pool.max-active=50
spring.redis.lettuce.pool.max-idle=20

# 日志级别
logging.level.com.wangzs.statisticalanalysis=WARN
```

#### 监控配置
```properties
# 生产环境监控
management.endpoints.web.exposure.include=health,info,metrics
management.endpoint.health.show-details=when-authorized
```

## 🎯 全埋点最佳实践

### 1. 数据采集策略

#### 页面停留时长计算
```javascript
// 页面进入时记录开始时间
window.addEventListener('load', () => {
    window.pageStartTime = Date.now();
});

// 页面离开时计算停留时长
window.addEventListener('beforeunload', () => {
    const stayDuration = Date.now() - window.pageStartTime;
    tracker.trackPageView({
        url: window.location.href,
        title: document.title,
        stayDuration: stayDuration
    });
});
```

#### 滚动深度追踪
```javascript
// 防抖处理滚动事件
let scrollTimer;
window.addEventListener('scroll', () => {
    clearTimeout(scrollTimer);
    scrollTimer = setTimeout(() => {
        tracker.trackScroll();
    }, 100);
});
```

### 2. 性能优化建议

#### 数据采样策略
- **高频事件采样**: 对滚动、鼠标移动等高频事件进行采样
- **批量发送**: 累积一定数量事件后批量发送到服务器
- **本地缓存**: 网络异常时本地缓存数据，恢复后重传

#### 内存管理
- **事件去重**: 避免重复记录相同事件
- **数据压缩**: 对大数据量字段进行压缩
- **定时清理**: 定期清理过期的本地缓存数据

### 3. 隐私保护

#### 敏感信息处理
- **IP地址脱敏**: 对IP地址进行脱敏处理
- **用户标识**: 使用匿名会话ID而非真实用户ID
- **数据加密**: 敏感数据传输时进行加密

#### 合规性考虑
- **用户同意**: 采集前获取用户明确同意
- **数据保留**: 设置合理的数据保留期限
- **删除机制**: 提供用户数据删除接口

## 🤝 贡献指南

### 开发规范

#### 代码规范
- 遵循阿里巴巴 Java 开发规范
- 使用 Lombok 减少样板代码
- 统一使用 SLF4J 日志框架

#### 提交规范
```bash
# 提交信息格式
feat: 添加新功能
fix: 修复 bug
docs: 更新文档
style: 代码格式调整
refactor: 代码重构
test: 添加测试
```

### 测试指南

#### 单元测试
```java
@SpringBootTest
class StatisticalAnalysisApplicationTests {
    
    @Test
    void contextLoads() {
        // 测试应用上下文加载
    }
}
```

#### 集成测试
```java
@SpringBootTest
@AutoConfigureTestDatabase
class TrackingControllerTest {
    
    @Test
    void testTrackEvent() {
        // 测试事件采集接口
    }
}
```

## 📄 许可证

本项目采用 MIT 许可证。详情请参阅 [LICENSE](LICENSE) 文件。

## 📞 联系方式

- 项目主页: [GitHub Repository]
- 问题反馈: [Issues]
- 邮箱: support@example.com

---

## 📈 版本更新记录

### v1.1.0 (2025-10-29)
- ✨ **新增功能**: 全埋点自动追踪系统
- ✨ **新增功能**: 页面停留时长统计
- ✨ **新增功能**: 用户行为路径分析
- ✨ **新增功能**: 滚动深度追踪
- ✨ **新增功能**: 元素级交互追踪
- 🐛 **修复问题**: MyBatis Plus 版本兼容性问题
- 🐛 **修复问题**: Redis UV 统计逻辑错误
- 📝 **文档更新**: 完善全埋点功能文档

### v1.0.0 (2024-10-27)
- 🎉 **初始版本**: 基础埋点统计系统
- ✅ **核心功能**: 事件采集、统计分析、数据导出
- ✅ **技术栈**: Spring Boot + MyBatis Plus + MySQL + Redis + RocketMQ

---

**最后更新**: 2025年10月29日
**当前版本**: v1.1.0
**项目状态**: 稳定运行，持续开发中