# amazon-analytics-system

**Repository Path**: bxwpxx/amazon-analytics-system

## Basic Information

- **Project Name**: amazon-analytics-system
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-05-12
- **Last Updated**: 2026-06-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Amazon Analytics System

亚马逊商品数据采集、分析与可视化系统。自动从 amazon.com 爬取商品详情（价格、评论、评分、BSR 排名等），存入 MongoDB，通过 Spring Boot REST API 提供数据查询与 AI 分析，React 前端以 Dashboard、商品列表、品类分析、AI 洞察等形式呈现。

## 项目结构

```
amazon/
├── amazon_crawler/                  # Python 爬虫服务 (:8081)
│   ├── main.py                      # CLI 入口 (initial/schedule/single/status 等命令)
│   ├── config.py                    # 全局配置 (MongoDB/Redis/代理池/种子品类/关键词)
│   ├── crawler.py                   # 核心爬取引擎 (BSR发现 → 搜索发现 → 详情解析)
│   ├── anti_detect.py               # 反检测会话 (curl_cffi TLS指纹 + UA轮换 + Cookie)
│   ├── proxy_pool.py                # 代理池 (健康评分 + CAPTCHA指数冷却)
│   ├── smart_proxy_manager.py       # 代理拉取管理 (5个公开源 → 验证 → GeoIP过滤)
│   ├── scheduler.py                 # 定时调度器 (每日全量 + 每6h过期检查 + 任务队列)
│   ├── api.py                       # Flask HTTP API (接收后端触发的补充爬取)
│   ├── db.py                        # MongoDB/Redis 连接管理与索引创建
│   ├── log_utils.py                 # 日志格式化工具
│   ├── export_data.py               # 数据导出工具 (MongoDB → JSON)
│   ├── import_data.py               # 数据导入工具 (JSON → MongoDB)
│   ├── export_20260507_170810.json  # 种子数据 (供快速初始化数据库)
│   ├── requirements.txt             # Python 依赖
│   └── data/                        # ASIN 缓存目录 (运行时生成)
│
├── amazon-analytics-backend/        # Java Spring Boot 后端 (:8080)
│   ├── pom.xml                      # Maven 配置 (Spring Boot 3.2.5 + Java 21)
│   ├── README.md                    # 后端独立文档
│   └── src/main/java/org/example/
│       ├── AmazonAnalyticsApplication.java  # 启动入口
│       ├── model/Product.java              # MongoDB 文档映射 (含嵌套类)
│       ├── repository/ProductRepository.java # 数据访问接口
│       ├── dto/                     # 数据传输对象
│       │   ├── ApiResponse.java           # 统一响应体 {code, message, data}
│       │   ├── DashboardData.java         # 看板聚合 DTO
│       │   └── ProductDetailDTO.java      # 商品详情 DTO
│       ├── config/                  # 配置
│       │   ├── AppConfig.java             # 业务配置 (缓存TTL/爬虫URL/LLM参数)
│       │   ├── RedisConfig.java           # Redis 序列化配置
│       │   ├── CorsConfig.java            # 跨域配置
│       │   └── GlobalExceptionHandler.java # 全局异常处理
│       ├── service/                 # 业务服务
│       │   ├── ProductService.java        # 商品CRUD + 分页搜索 + 过期检测
│       │   ├── AnalysisService.java       # MongoDB 聚合管道 (KPI/趋势/品类/价格)
│       │   ├── CacheService.java          # Redis 多级缓存封装
│       │   ├── LLMService.java            # DeepSeek API 调用 (AI分析)
│       │   └── CrawlerTriggerService.java # WebClient 异步触发爬虫
│       └── controller/              # REST API
│           ├── ProductController.java     # /api/products
│           ├── CategoryController.java    # /api/categories
│           ├── DashboardController.java   # /api/analysis
│           ├── AIController.java          # /api/ai
│           └── ExportController.java      # /api/export
│
├── amazon-analytics-frontend/       # React 前端 (:5173)
│   ├── package.json                 # 依赖配置
│   ├── vite.config.ts               # Vite 配置 + API 代理
│   ├── index.html                   # HTML 入口
│   └── src/
│       ├── main.tsx                 # 应用入口
│       ├── App.tsx                  # 根组件 (QueryClient + Router)
│       ├── api/                     # axios API 层 (client/products/categories/dashboard/ai/export)
│       ├── hooks/                   # React Query hooks (useProducts/useDashboard/useAI 等)
│       ├── pages/                   # 页面组件
│       │   ├── DashboardPage.tsx          # 数据概览 (KPI卡片 + 4类图表)
│       │   ├── ProductListPage.tsx        # 商品列表 (筛选 + 排序 + 分页)
│       │   ├── ProductDetailPage.tsx      # 商品详情 (信息 + 评论 + AI分析)
│       │   ├── CategoryAnalysisPage.tsx   # 品类分析
│       │   ├── AIInsightsPage.tsx         # AI 洞察
│       │   └── DataExportPage.tsx         # 数据导出
│       ├── components/              # 可复用组件
│       │   ├── charts/                    # ECharts 封装 (折线/柱状/饼图/散点)
│       │   ├── common/                    # 通用组件 (KpiCard/EmptyState/Loading 等)
│       │   ├── layout/                    # 布局 (AppLayout/Header/Sider)
│       │   └── product/                   # 商品组件 (Table/FilterBar/InfoCard)
│       ├── types/                   # TypeScript 类型定义 (7个文件，25+接口)
│       ├── router/index.tsx         # 路由配置 (懒加载)
│       └── constants/index.ts       # 常量 (API地址、图表颜色等)
│
├── 文档/                            # 项目文档
│   ├── amazon-analytics-system_项目总览.md    # 系统概览 + 架构图
│   ├── 项目详细设计文档.md                     # 完整设计文档 (数据模型/API/契约)
│   ├── 5人分工-模块检查完善任务书.md           # 团队分工与检查清单
│   ├── amazon_crawler_说明文档.md             # 爬虫模块说明
│   └── amazon-analytics-backend_说明文档.md   # 后端模块说明
│
├── .gitignore                       # Git 忽略规则
└── README.md                        # 本文件
```

## 环境要求

| 组件 | 版本 | 端口 | 用途 |
|---|---|---|---|
| Python | 3.12+ | — | 爬虫运行环境 |
| JDK | 21 | — | 后端编译运行 |
| Maven | 3.8+ | — | 后端构建 |
| Node.js | 18+ | — | 前端构建运行 |
| MongoDB | 4.4+ | 27017 | 数据存储 |
| Redis | 6.0+ | 6379 | 缓存/去重 |

## 快速开始

### 方式一：从种子 JSON 导入数据库（推荐）

如果你只想快速体验后端和前端，无需运行爬虫：

```bash
# 1. 启动 MongoDB 和 Redis
mongod --dbpath /data/db
redis-server

# 2. 导入种子数据到 MongoDB
cd amazon_crawler
pip install -r requirements.txt
python import_data.py
# 默认读取 export_20260507_170810.json (51847 行商品数据)
# 如需指定其他文件: python import_data.py -f <json文件路径>
```

### 方式二：从头运行爬虫采集数据

```bash
# 1. 启动 MongoDB 和 Redis (同上)

# 2. 安装依赖
cd amazon_crawler
pip install -r requirements.txt

# 3. 运行初始爬取 (BSR分类发现 → 关键词搜索 → 详情采集)
python main.py initial

# 4. 启动调度器 (定时更新 + HTTP API)
python main.py schedule --initial
```

### 启动后端

```bash
cd amazon-analytics-backend
mvn spring-boot:run
# 服务启动在 http://localhost:8080

# 可选：启用 AI 功能
# LLM_API_KEY=sk-xxx mvn spring-boot:run
```

### 启动前端

```bash
cd amazon-analytics-frontend
npm install
npm run dev
# 访问 http://localhost:5173
```

## 访问地址

| 服务 | 地址 |
|---|---|
| 前端页面 | http://localhost:5173 |
| 后端 API | http://localhost:8080 |
| 爬虫 API | http://localhost:8081 |

## 环境变量

| 变量 | 默认值 | 说明 |
|---|---|---|
| `MONGO_URI` | `mongodb://localhost:27017/amazon_products` | MongoDB 连接 |
| `REDIS_HOST` | `localhost` | Redis 地址 |
| `REDIS_PORT` | `6379` | Redis 端口 |
| `LLM_API_KEY` | (空) | DeepSeek API Key (不配置时 AI 功能降级) |
| `LLM_MODEL` | `deepseek-chat` | LLM 模型 |
| `CRAWLER_URL` | `http://localhost:8081` | 爬虫服务地址 |

## 前端页面一览

| 路由 | 页面 | 功能 |
|---|---|---|
| `/dashboard` | 数据概览 | KPI 卡片 + 趋势图 + 品类表现 + 价格分布 + 评分关联 |
| `/products` | 商品分析 | 搜索/筛选/排序/分页商品列表 |
| `/products/:asin` | 商品详情 | 完整信息 + 价格历史 + 评论分析 + AI 洞察 |
| `/categories` | 品类分析 | 分类排行与对比 |
| `/ai-insights` | AI 洞察 | 情感分析/趋势预测/定价建议/异常检测/运营报告 |
| `/export` | 数据导出 | CSV 导出下载 |

## API 接口概要

### 商品 `/api/products`
- `GET /api/products` — 分页搜索 (category/keyword/minPrice/maxPrice/minRating/sortBy/page/size)
- `GET /api/products/{asin}` — 商品详情
- `GET /api/products/{asin}/timeline` — 价格历史
- `GET /api/products/{asin}/comments` — 评论详情
- `POST /api/products/refresh` — 批量刷新触发爬虫

### 品类 `/api/categories`
- `GET /api/categories` — 所有分类
- `GET /api/categories/{category}/ranking` — 分类排行

### 分析 `/api/analysis`
- `GET /api/analysis/dashboard` — 看板聚合数据

### AI `/api/ai` (需配置 LLM_API_KEY)
- `GET /api/ai/sentiment/{asin}` — 评论情感分析
- `GET /api/ai/trend/{asin}` — 销量趋势预测
- `GET /api/ai/pricing/{asin}` — 定价策略建议
- `GET /api/ai/anomalies` — 异常检测
- `POST /api/ai/report/generate` — 生成运营周报

### 导出 `/api/export`
- `GET /api/export/csv` — CSV 导出

### 通用响应格式
```json
{ "code": 200, "message": "success", "data": {} }
```

## 技术栈

| 层级 | 技术 |
|---|---|
| 爬虫 | Python 3.12 + BeautifulSoup4 + curl_cffi + Flask + APScheduler |
| 数据存储 | MongoDB (商品数据) + Redis (多级缓存/去重/进度) |
| 后端 | Java 21 + Spring Boot 3.2.5 + Spring Data MongoDB/Redis + WebFlux |
| 前端 | React 18 + TypeScript + Vite + Ant Design 5 + ECharts 5 + React Query |
| AI | DeepSeek API (情感分析/趋势预测/定价建议/异常检测/报告生成) |