# ecommerce_analysis

**Repository Path**: yang-wu-di/ecommerce_analysis

## Basic Information

- **Project Name**: ecommerce_analysis
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-29
- **Last Updated**: 2026-05-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 大数据驱动的电商用户行为分析与可视化系统

本项目已重构为纯真实电商 V2 系统，业务对象全部切换为真实平台字段和真实分析口径。系统围绕平台店铺、商品、SKU、订单、订单明细、退款、评价、客户、流量日报、RFM 和经营报表构建。

## 当前定位

系统支持两种真实数据进入方式：

- 平台授权同步：通过店铺数据源、Token、同步任务、原始 API 响应表对接淘宝等电商平台。
- 文件导入兜底：没有正式平台授权时，可使用平台导出的 CSV/Excel，按真实字段导入商品、订单、订单明细、退款、评价、店铺流量和商品流量。

淘宝等平台通常不会稳定开放完整的用户级浏览、收藏、加购点击明细。因此系统不伪造用户级点击路径：购买行为来自订单表，曝光、浏览、点击、收藏、加购来自店铺或商品维度的聚合流量日报。

## 核心模块

- 经营概览：GMV、支付订单数、买家数、客单价、转化率、商品数、类目数。
- 客户分析：地域分布、消费能力、活跃度、RFM 客户价值分层。
- 商品分析：销量排行、浏览排行、类目销售分布、商品关联购买、退款和流量表现。
- 流量转化：订单转化漏斗、平台聚合流量漏斗、支付时段分布。
- 数据源管理：店铺信息、Token、同步任务、原始 API 响应、清洗入库。
- 数据导入导出：真实字段 CSV/Excel 模板、预览、导出。
- 数据质量：真实业务规则检查，不对业务数据做危险自动修复。
- 经营报表：销售、客户、商品、流量、退款、RFM 和综合多 sheet 报表。

## 数据模型

唯一初始化脚本：

```text
backend/src/main/resources/schema_real_v2.sql
```

核心表包括：

- 系统基础：`admin_user`、`role`、`permission`、`user_role`、`role_permission`、`import_task`、`export_task`、`data_quality_check`
- 平台接入：`platform_shop`、`platform_token`、`sync_task`、`raw_api_record`
- 业务明细：`customer`、`category`、`product`、`product_sku`、`trade_order`、`trade_order_item`、`refund_order`、`trade_rate`
- 流量日报：`shop_traffic_daily`、`product_traffic_daily`
- 分析宽表：`dws_shop_daily`、`dws_product_daily`、`rfm_customer_snapshot`

## 指标口径

- GMV：`trade_order.payment`
- 订单数：已支付且未关闭的 `trade_order`
- 买家数：去重 `buyer_open_uid`
- 客单价：GMV / 支付订单数
- 商品排行：`trade_order_item.quantity` 和 `trade_order_item.payment`
- 退款率：`refund_order.refund_fee / trade_order.payment`
- RFM：最近支付时间、支付订单次数、支付金额
- 转化漏斗：曝光、浏览、加购来自 `product_traffic_daily`，支付订单来自 `trade_order`

## 快速开始

1. 创建数据库并执行真实 V2 初始化脚本。

```sql
CREATE DATABASE IF NOT EXISTS ecommerce_analysis_dev DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
USE ecommerce_analysis_dev;
SOURCE backend/src/main/resources/schema_real_v2.sql;
```

2. 配置环境变量。

```bash
DB_URL=jdbc:mysql://localhost:3306/ecommerce_analysis_dev?useUnicode=true&characterEncoding=utf-8&serverTimezone=Asia/Shanghai&useSSL=false&allowPublicKeyRetrieval=true
DB_USERNAME=root
DB_PASSWORD=root
JWT_SECRET=change-me
FIELD_ENCRYPTION_KEY=change-me-too
TAOBAO_ENABLED=false
```

3. 启动后端。

```bash
cd backend
mvn spring-boot:run
```

4. 启动前端。

```bash
cd frontend
npm install
npm run dev
```

## 淘宝接入配置

默认不启用真实网络同步：

```yaml
taobao:
  enabled: ${TAOBAO_ENABLED:false}
  app-key: ${TAOBAO_APP_KEY:}
  app-secret: ${TAOBAO_APP_SECRET:}
  gateway-url: ${TAOBAO_GATEWAY_URL:https://eco.taobao.com/router/rest}
  max-pages: ${TAOBAO_MAX_PAGES:20}
  retry-count: ${TAOBAO_RETRY_COUNT:2}
```

启用后，在“数据源管理”页面保存店铺和 Access Token，再创建同步任务。同步接口会先写入 `raw_api_record`，然后清洗入真实业务表；也可以在历史同步任务中重新执行“清洗入库”。

同步任务支持分页拉取和订单详情补全：订单列表会按页调用淘宝接口，并按 `tid` 尝试补充交易详情；遇到 API 权限不足、Token 缺失或淘宝未启用时，会在同步任务和数据源管理页展示明确提示。没有正式淘宝授权时，可使用 `samples/raw_api/` 中的原始响应示例演示清洗链路。

## DWS/RFM 汇总层

导入或同步真实明细数据后，可在“数据源管理”页面点击“重建DWS/RFM”，或调用：

```http
POST /api/dws/rebuild?startTime=2026-05-01&endTime=2026-05-20
```

该操作会重建：

- `dws_shop_daily`：店铺日 GMV、订单数、买家数、退款和转化率。
- `dws_product_daily`：商品日流量、支付、退款和转化率。
- `rfm_customer_snapshot`：客户最近消费、频次、金额和价值分层快照。

## 当前验收状态

- 后端构建：`mvn clean -DskipTests package` 已通过。
- 前端构建：`npm run build` 已通过，当前仅存在 Vite chunk size 体积提示，不影响运行。
- 旧模拟链路：主业务代码、模板和 README 中已移除模拟数据服务、模拟接口、旧行为事实表、旧用户/行为模板等残留。
- 真实演示链路：支持平台授权同步、真实字段模板导入、raw API 示例清洗、DWS/RFM 汇总、经营报表导出和数据质量检查。
- 答辩口径：系统不承诺淘宝标准接口无法稳定提供的用户级浏览路径；“用户行为分析”解释为订单购买行为与平台聚合流量行为分析。

## 导入模板

真实字段模板位于 `templates/`：

- `product_template.csv`
- `trade_order_template.csv`
- `trade_order_item_template.csv`
- `refund_order_template.csv`
- `trade_rate_template.csv`
- `shop_traffic_daily_template.csv`
- `product_traffic_daily_template.csv`

建议导入顺序：商品 -> 订单主表 -> 订单明细 -> 退款 -> 评价 -> 店铺流量日报 -> 商品流量日报。

## 默认账号

- `admin / admin123`
- `analyst / admin123`
- `viewer / admin123`