# lzit-user-behavior-analysis

**Repository Path**: azureroots/lzit-user-behavior-analysis

## Basic Information

- **Project Name**: lzit-user-behavior-analysis
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-21
- **Last Updated**: 2025-12-22

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 电商用户行为离线分析平台

这是一个基于Python Flask开发的电商用户行为离线分析平台，采用分层架构设计，用于分析和展示电商平台的用户行为数据。

## 项目介绍与技术栈

### 项目概述
本系统是一个完整的电商用户行为离线分析平台，提供数据统计、可视化展示和API接口等功能。系统采用现代化的Web技术栈和分层架构设计，具有良好的可维护性和扩展性。

### 技术栈
- **后端框架**：Python 3.10+ + Flask
- **前端技术**：Bootstrap + ECharts（通过CDN引入）
- **数据库**：MySQL 8.0+（默认）/ SQLite（可选）
- **依赖管理**：uv（现代化Python包管理工具）
- **架构模式**：分层架构（Models-DAO-Service-Controller）

### 核心功能
- **数据统计**：显示总用户数、总行为数、整体转化率
- **数据可视化**：
  - 用户行为转化漏斗图
  - 近30天PV/UV趋势折线图
  - 热门商品Top 50排行及转化率分析
- **数据加载**：支持CSV数据文件导入和重新加载
- **RESTful API**：提供完整的API接口用于数据访问
- **分层架构**：采用模型-DAO-服务-控制器的分层架构设计

## 核心配置

### 环境变量配置
项目使用`.env`文件管理环境变量，主要配置项包括：

```env
# 数据库配置
DB_TYPE=mysql                      # 数据库类型：mysql 或 sqlite
SQLITE_DB_PATH=user_behavior.db  # SQLite数据库文件名

# MySQL配置（默认使用MySQL）
MYSQL_HOST=localhost
MYSQL_PORT=3306
MYSQL_USER=root
MYSQL_PASSWORD=your_mysql_password  # 替换为你的MySQL密码
MYSQL_DATABASE=user_behavior_analysis

# Flask配置
FLASK_ENV=development
FLASK_DEBUG=True
FLASK_HOST=127.0.0.1
FLASK_PORT=5000
SECRET_KEY=your-secret-key-here     # 替换为生成的安全密钥

# 应用配置
DATA_FILE=init_data/UserBehavior.csv
CHUNK_SIZE=10000                    # CSV分块读取大小
```

### 项目结构
```
lzit-user-behavior-analysis/
├── app/                    # 应用主目录
│   ├── models/            # 数据模型层
│   │   ├── __init__.py
│   │   ├── base.py
│   │   ├── user_behavior.py
│   │   ├── daily_stats.py
│   │   └── hot_items.py
│   ├── dao/               # 数据访问层
│   │   ├── __init__.py
│   │   ├── user_behavior_dao.py
│   │   ├── daily_stats_dao.py
│   │   └── hot_items_dao.py
│   ├── services/          # 业务逻辑层
│   │   ├── __init__.py
│   │   ├── user_behavior_service.py
│   │   ├── daily_stats_service.py
│   │   └── hot_items_service.py
│   ├── controllers/       # 控制器层
│   │   ├── __init__.py
│   │   ├── user_behavior_controller.py
│   │   ├── daily_stats_controller.py
│   │   └── hot_items_controller.py
│   ├── config/            # 配置管理
│   │   ├── __init__.py
│   │   └── config.py
│   └── __init__.py
├── templates/             # HTML模板目录
│   ├── base.html          # 基础模板
│   ├── index.html         # 首页模板
│   ├── hot_items.html     # 热门商品页面模板
│   ├── funnel.html        # 漏斗分析页面模板
│   ├── trends.html        # 趋势分析页面模板
│   ├── reload_data.html   # 数据重新加载页面模板
│   ├── reload_success.html # 数据加载成功页面模板
│   └── reload_error.html  # 数据加载错误页面模板
├── init_data/             # 数据初始化目录
│   ├── UserBehavior.csv   # 用户行为数据文件
│   └── generate_data.py   # 模拟数据生成脚本
├── app.py                 # Flask主程序
├── .env.example           # 环境变量示例文件
├── .env                   # 环境变量配置文件
├── pyproject.toml         # 项目依赖配置
└── README.md              # 项目说明文档
```

## 项目启动步骤

### 前提条件
- Windows 10/11 操作系统
- 已安装 uv（Python包管理工具）
- 已安装并启动 MySQL 8.0+ 服务器

### 步骤1：克隆项目
```bash
git clone <项目地址>
cd lzit-user-behavior-analysis
```

### 步骤2：配置环境变量
```bash
# 复制环境变量示例文件
cp .env.example .env
```

编辑`.env`文件，配置MySQL数据库连接信息：
```env
MYSQL_HOST=localhost
MYSQL_PORT=3306
MYSQL_USER=root
MYSQL_PASSWORD=your_mysql_password  # 替换为你的MySQL密码
MYSQL_DATABASE=user_behavior_analysis
```

生成并配置Flask安全密钥：
```bash
uv run python -c "import secrets; print(secrets.token_hex(32))"
```
将生成的密钥替换`.env`文件中的`SECRET_KEY=your-secret-key-here`。

### 步骤3：创建MySQL数据库
使用MySQL客户端执行以下SQL命令：
```sql
CREATE DATABASE user_behavior_analysis CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
```

### 步骤4：使用uv管理项目依赖
```bash
# 使用uv同步项目依赖（推荐方式）
uv sync

# 如果需要添加新依赖，使用：
# uv add <package_name>
```

### 步骤5：生成模拟数据（可选）
```bash
# 使用uv运行数据生成脚本
uv run init_data/generate_data.py

# 或者指定生成记录数量
uv run init_data/generate_data.py -n 10000

# 显示详细输出
uv run init_data/generate_data.py -v
```

### 步骤6：启动应用
```bash
# 使用uv运行Flask应用
uv run app.py
```

应用将在 `http://localhost:5000` 启动。

## 访问方式

### 主要页面
1. **首页** (`http://localhost:5000/`)：显示基本统计信息，包括总用户数、总行为数和整体转化率
2. **转化漏斗** (`http://localhost:5000/funnel`)：展示用户行为转化漏斗图
3. **趋势分析** (`http://localhost:5000/trends`)：展示近30天PV/UV趋势折线图
4. **热门商品** (`http://localhost:5000/hot_items`)：展示热门商品Top 50排行及转化率分析
5. **重新加载数据** (`http://localhost:5000/reload_data`)：数据重新加载页面

### API接口
#### 用户行为数据接口
- `GET /api/overview`：获取用户行为统计概览
- `GET /api/funnel`：获取用户行为转化漏斗数据
- `GET /api/trends?days=30`：获取近N天PV/UV趋势数据
- `GET /api/hot_items?limit=50`：获取热门商品排行榜数据

#### 数据管理接口
- `POST /api/reload_data`：重新加载CSV数据并更新分析结果

## 数据格式

项目使用阿里天池UserBehavior.csv格式的数据，包含以下字段：

- `user_id`: 用户ID
- `item_id`: 商品ID
- `category_id`: 商品类别ID
- `behavior`: 用户行为类型 ('pv', 'cart', 'fav', 'buy')
- `timestamp`: 时间戳（Unix时间戳格式）

## 架构说明

本项目采用分层架构设计，将系统划分为以下几层：

1. **模型层 (Models)**：定义系统中的数据模型类，如UserBehavior、DailyStats、HotItems等
2. **数据访问层 (DAO)**：负责数据库操作，提供数据的增删改查功能
3. **业务逻辑层 (Service)**：实现业务逻辑，处理复杂的业务规则和计算
4. **控制器层 (Controller)**：处理HTTP请求，调用业务逻辑层，返回响应

这种分层架构的优点：
- 职责分离，代码结构清晰
- 易于维护和扩展
- 提高代码复用性
- 便于单元测试

## 性能考虑

- 使用分块读取CSV文件，避免内存溢出
- 数据库表添加适当索引提高查询效率
- 前端图表使用ECharts，支持大数据量渲染
- 分析结果缓存到数据库，避免重复计算

## 注意事项

1. 本项目默认使用MySQL 8.0+数据库，需要提前安装并配置MySQL服务器
2. 首次运行前需要确保有UserBehavior.csv数据文件或使用generate_data.py生成数据
3. 如果修改了`.env`文件，需要重启应用才能生效
4. SECRET_KEY是Flask应用的安全密钥，必须替换为随机生成的密钥，不要使用默认值
5. 确保`.env`文件不被提交到版本控制系统

## 故障排除

### 常见问题

1. **端口占用**
   - 如果5000端口被占用，可以修改`.env`文件中的`FLASK_PORT`配置

2. **MySQL连接失败**
   - 检查MySQL服务是否已启动
   - 验证`.env`文件中的数据库连接参数是否正确
   - 确保数据库用户有足够的权限
   - 确认MySQL版本为8.0+

3. **依赖安装问题**
   - 使用`uv sync`重新同步依赖
   - 如果问题仍然存在，删除`.venv`目录后重新执行`uv sync`

4. **数据加载失败**
   - 确保数据库连接正常
   - 检查数据文件路径是否正确
   - 验证CSV文件格式是否符合要求

5. **页面显示异常**
   - 检查浏览器控制台是否有JavaScript错误
   - 确认ECharts库是否正确加载
   - 验证API接口返回的数据格式是否正确

## 扩展功能

可以考虑添加以下功能：

- 实时数据更新
- 更多维度的用户行为分析
- 用户画像分析
- 商品推荐系统
- 异常行为检测
- 数据导出功能
- 用户行为路径分析