# 3c

**Repository Path**: hydrogen-elements/3c

## Basic Information

- **Project Name**: 3c
- **Description**: 毕业设计
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-23
- **Last Updated**: 2026-04-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 3C 数码智能比价分析平台

> 基于公开 3C 数码商品数据集，通过多平台差异化价格模拟算法、三大机器学习模型、Flask 后端接口与多角色前端应用，构建从**数据生成 → 智能处理 → 业务应用 → 系统管理**的完整闭环系统。

---

## 目录

- [项目概述](#项目概述)
- [系统架构（闭环说明）](#系统架构闭环说明)
- [技术栈](#技术栈)
- [目录结构](#目录结构)
- [数据库设计](#数据库设计)
- [机器学习模型](#机器学习模型)
- [API 接口一览](#api-接口一览)
- [前端页面说明](#前端页面说明)
- [快速开始](#快速开始)
- [账号说明](#账号说明)
- [配置说明](#配置说明)

---

## 项目概述

本系统以公开 3C 数码商品数据集（37,202 条，涵盖手机、电脑、平板三大品类）为基础数据源，通过算法模拟京东、淘宝、拼多多三平台的差异化实时价格，并利用 XGBoost、随机森林、SnowNLP/BERT 三大模型对商品数据进行智能加工，最终通过 Flask 后端 RESTful 接口支撑三类角色（消费者、商家、管理员）的前端业务应用。

**核心特点：**
- 无需爬虫，价格数据由算法合规生成，可随时动态刷新
- 三大 ML 模型在初始化时自动训练，支持管理员一键重训覆盖
- 三端角色分离，JWT 鉴权，前后端分离架构
- 37K+ 商品数据全量存入 MySQL，支持增删改查、导出、导入

---

## 系统架构（闭环说明）

```
┌─────────────────────────────────────────────────────────────────┐
│                         完整数据闭环                             │
│                                                                   │
│  1. 数据生成  ──→  公开数据集 + 多平台差异化定价算法              │
│       ↓                                                           │
│  2. 数据存储  ──→  MySQL (jd_3c_goods 表，37K 条商品)             │
│       ↓                                                           │
│  3. 智能处理  ──→  XGBoost(价格预测) + RF(推荐) + BERT(情感)      │
│       ↓                                                           │
│  4. 接口服务  ──→  Flask RESTful API (/api/consumer|merchant|admin)│
│       ↓                                                           │
│  5. 业务应用  ──→  消费者端 / 商家端 / 管理员端                   │
│       ↓                                                           │
│  6. 迭代更新  ──→  管理员刷新价格 / 重训模型 / 导入新数据         │
│       └────────────────────────────────────────────────────────→ │
└─────────────────────────────────────────────────────────────────┘
```

| 层级 | 组件 | 说明 |
|------|------|------|
| 数据生成 | `utils/price_generator.py` | JD/TB/PDD 三平台差异化定价算法，含优惠券模拟 |
| 数据存储 | MySQL `db_3c.jd_3c_goods` | 统一商品库，含价格、规格、销量、评论、ML 评分 |
| 智能模型 | `models_ml/` | XGBoost 价格预测、随机森林推荐、SnowNLP 情感分析 |
| 后端服务 | Flask + SQLAlchemy | 标准化 RESTful 接口，JWT 鉴权，CORS 支持 |
| 前端应用 | 原生 HTML/CSS/JS + ECharts | 消费者、商家、管理员三端分离 |
| 迭代更新 | 管理员后台 | 刷新价格、重训模型、CRUD 管理数据，后台异步任务 |

---

## 技术栈

### 后端
| 组件 | 版本 | 用途 |
|------|------|------|
| Python | 3.11 | 运行环境 |
| Flask | 3.0.3 | Web 框架 |
| Flask-SQLAlchemy | 3.1.1 | ORM 数据库映射 |
| Flask-CORS | 4.0.1 | 跨域支持 |
| PyMySQL | 1.1.1 | MySQL 驱动 |
| XGBoost | 2.1.3 | 价格预测模型 |
| scikit-learn | 1.5.2 | 随机森林推荐模型 |
| SnowNLP | 0.12.3 | 中文情感分析（BERT 降级方案） |
| PyJWT | 2.9.0 | JWT 鉴权 |
| openpyxl | 3.1.5 | Excel 数据导出 |
| pandas / numpy | 2.2.3 / 1.26.4 | 数据处理 |

### 前端
| 组件 | 用途 |
|------|------|
| 原生 HTML5 / CSS3 / ES6 | 页面结构与交互 |
| ECharts | 数据可视化图表 |
| Fetch API + JWT | 接口调用与鉴权 |

### 数据库 & 环境
- **MySQL 8.x**，字符集 `utf8mb4`
- **Conda** 虚拟环境（Python 3.11），环境名 `3c`

---

## 目录结构

```
d:\3c\
├── 3c_digital_dataset.txt          # 原始数据集（37,202 条 3C 商品）
├── README.md
├── backend/
│   ├── app.py                      # Flask 应用工厂 & 入口
│   ├── config.py                   # 全局配置（DB、JWT、路径等）
│   ├── init_db.py                  # 数据库初始化脚本（建库建表+训练模型）
│   ├── requirements.txt            # Python 依赖
│   ├── models/                     # 训练后的模型文件
│   │   ├── xgb_price.pkl           # XGBoost 价格预测模型
│   │   ├── xgb_encoders.pkl        # XGBoost 标签编码器
│   │   ├── rf_recommend.pkl        # 随机森林推荐模型
│   │   └── rf_encoders.pkl         # 随机森林标签编码器
│   ├── database/
│   │   └── db.py                   # SQLAlchemy 模型（Product、User）
│   ├── models_ml/
│   │   ├── xgboost_price.py        # XGBoost 价格预测（训练/预测/评分）
│   │   ├── rf_recommend.py         # 随机森林推荐（训练/批量评分）
│   │   └── bert_sentiment.py       # 情感分析（SnowNLP / 真实BERT 自动切换）
│   ├── routes/
│   │   ├── auth.py                 # /api/auth  登录/注册/JWT
│   │   ├── consumer.py             # /api/consumer  消费者接口
│   │   ├── merchant.py             # /api/merchant  商家接口
│   │   └── admin.py                # /api/admin     管理员接口
│   └── utils/
│       ├── data_loader.py          # 数据集解析（TAB 分隔，37K 行）
│       └── price_generator.py      # 三平台价格模拟算法
└── frontend/
    ├── login.html                  # 登录 / 注册页
    ├── role-select.html            # 角色选择页
    ├── consumer.html               # 消费者端（4 功能模块）
    ├── merchant.html               # 商家端（3 功能模块）
    ├── admin.html                  # 管理员端（CRUD + 模型 + 可视化）
    ├── css/
    │   ├── common.css              # 全局公共样式
    │   ├── login.css               # 登录页样式
    │   ├── consumer.css
    │   ├── merchant.css
    │   └── admin.css
    └── js/
        ├── consumer.js
        ├── merchant.js
        └── admin.js
```

---

## 数据库设计

### `jd_3c_goods`（主商品表）

| 字段 | 类型 | 说明 |
|------|------|------|
| `id` | INT PK | 自增主键 |
| `product_id` | VARCHAR(60) | 数据集行 ID（唯一） |
| `title` | VARCHAR(600) | 商品标题 |
| `category` | VARCHAR(60) | 品类（手机 / 电脑 / 平板） |
| `brand` | VARCHAR(100) | 品牌 |
| `color_spec` | VARCHAR(250) | 颜色/规格 |
| `store_name` | VARCHAR(250) | 店铺名称 |
| `original_price` | DECIMAL(12,2) | 官方指导价 MSRP |
| `jd_price` / `tb_price` / `pdd_price` | DECIMAL(12,2) | 三平台模拟售价 |
| `jd_coupon` / `tb_coupon` / `pdd_coupon` | DECIMAL(10,2) | 三平台优惠券金额 |
| `sales_volume` | BIGINT | 销售量 |
| `review_count` | BIGINT | 评论数 |
| `positive_rate` | INT | 好评率（%） |
| `storage_gb` / `memory_gb` / `screen_inch` | INT/FLOAT | 从标题提取的规格 |
| `predicted_price` | DECIMAL(12,2) | XGBoost 预测合理价 |
| `price_score` | FLOAT | 性价比评分（0-10） |
| `sentiment_score` | FLOAT | 情感分析评分（0-1） |
| `recommendation_score` | FLOAT | 随机森林推荐评分（0-1） |

### `users`（用户表）

| 字段 | 类型 | 说明 |
|------|------|------|
| `id` | INT PK | 自增主键 |
| `username` | VARCHAR(50) UNIQUE | 用户名（4-16位字母数字下划线） |
| `phone` | VARCHAR(20) UNIQUE | 手机号 |
| `password_hash` | VARCHAR(256) | Werkzeug 哈希密码 |
| `role` | VARCHAR(20) | 角色（user / admin） |
| `created_at` | DATETIME | 注册时间 |

---

## 机器学习模型

### 1. XGBoost 价格预测模型
- **文件**：`models_ml/xgboost_price.py`
- **输入特征**：品牌、品类、存储容量、内存、屏幕尺寸、log(销量)、log(评论数)、好评率
- **目标**：预测商品合理市场价（log1p 变换后回归）
- **输出**：`predicted_price`（预测合理价）、`price_score`（0-10 性价比评分）
- **评估**：验证集 MAPE（平均绝对百分比误差）
- **用途**：消费者端"价格评估"、商家端"智能定价建议"

### 2. 随机森林推荐模型
- **文件**：`models_ml/rf_recommend.py`
- **标签生成规则**：好评率 ≥ 93% AND 销量 ≥ 1000 AND 最低价 ≤ MSRP×95% → 标签=1（优质推荐）
- **输入特征**：品牌、品类、存储、内存、屏幕、log(销量)、log(评论数)、好评率、折扣比
- **输出**：`recommendation_score`（0-1 推荐置信度）
- **批量推断**：一次 `predict_proba(X)` 处理所有候选商品，避免单条调用性能瓶颈
- **用途**：消费者端"AI 智能选品"

### 3. 情感分析模型（BERT/SnowNLP）
- **文件**：`models_ml/bert_sentiment.py`
- **双引擎自动切换**：若安装 `transformers` 且有缓存模型则使用真实 BERT，否则降级为 SnowNLP
- **融合策略**：`score = 0.6 × 好评率信号 + 0.4 × NLP信号`
- **输出**：`sentiment_score`（0-1，越高越正面）
- **用途**：消费者端"评价情感分析"、商家端"竞品口碑分析"

---

## API 接口一览

### 认证 `/api/auth`
| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/api/auth/login` | 登录（admin 固定账号 / 普通用户数据库验证） |
| POST | `/api/auth/register` | 注册新用户 |
| GET | `/api/auth/me` | 获取当前登录用户信息 |

### 消费者 `/api/consumer`
| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/consumer/products` | 分页商品列表，支持分类/品牌/价格/排序筛选 |
| GET | `/api/consumer/products/<id>` | 单品详情 |
| GET | `/api/consumer/compare/<product_id>` | 三平台价格对比 + 最优惠推荐 |
| GET | `/api/consumer/search` | 全文搜索（标题/品牌/福利标签） |
| GET | `/api/consumer/recommend` | AI 智能推荐（随机森林，支持预算/品类/品牌/规格筛选） |
| GET | `/api/consumer/evaluate/<id>` | XGBoost 价格评估（超值/划算/合理/偏贵/较贵） |
| GET | `/api/consumer/sentiment/<id>` | 情感分析（分数 + 标签 + 关键词） |
| GET | `/api/consumer/categories` | 所有品类及数量 |
| GET | `/api/consumer/brands` | 所有品牌及数量 |

### 商家 `/api/merchant`
| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/merchant/competitor` | 竞品分析（同类目各品牌均价/销量/评分对比） |
| GET | `/api/merchant/pricing` | 智能定价建议（三平台分策略定价区间 + 利润率） |
| GET | `/api/merchant/trends` | 行业价格趋势（均价/折扣率/价格区间） |
| GET | `/api/merchant/market` | 市场份额（品牌销量占比 + TOP5 商品） |
| GET | `/api/merchant/top_products` | 各维度 TOP 商品榜单 |

### 管理员 `/api/admin`（需 JWT）
| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/api/admin/login` | 管理员专属登录 |
| GET | `/api/admin/products` | 商品分页列表（含完整字段） |
| POST | `/api/admin/products` | 新增商品 |
| PUT | `/api/admin/products/<id>` | 编辑商品 |
| DELETE | `/api/admin/products/<id>` | 删除商品 |
| GET | `/api/admin/export` | 导出 Excel |
| POST | `/api/admin/import` | 从数据集导入新商品（后台异步） |
| POST | `/api/admin/refresh_prices` | 重新生成三平台模拟价格（后台异步） |
| POST | `/api/admin/retrain` | 重训 XGBoost + 随机森林并回写评分（后台异步） |
| GET | `/api/admin/task/<task_id>` | 查询后台任务状态 |
| GET | `/api/admin/stats` | 系统统计（商品数/均价/品类分布等） |
| GET | `/api/admin/model_status` | 模型状态（是否加载/训练样本数） |
| GET | `/api/health` | 服务健康检查 |

---

## 前端页面说明

### `login.html` — 登录/注册
- 滑动面板切换登录 / 注册模式
- 表单校验（用户名格式、手机号、密码长度）
- 登录成功后：admin → `/admin.html`，普通用户 → `/role-select.html`

### `role-select.html` — 角色选择
- 普通用户登录后选择以**消费者**或**商家**身份进入对应平台

### `consumer.html` — 消费者端
| 模块 | 功能 |
|------|------|
| 🔍 多平台比价 | 搜索商品，查看京东/淘宝/拼多多三平台售价与优惠券，高亮最优价 |
| 🎯 AI 智能选品 | 输入预算/品类/品牌/内存/存储需求，随机森林批量评分后返回 TOP 推荐卡片 |
| 📊 价格评估 | 选择商品，XGBoost 给出预测合理价与性价比评分（超值→较贵五档） |
| 💬 评价情感分析 | 查看商品的情感分析分数、标签分类、关键福利词 |

### `merchant.html` — 商家端
| 模块 | 功能 |
|------|------|
| 🏆 竞品分析 | 选择品类，查看各品牌均价/销量/好评率/情感分对比，ECharts 柱状图 |
| 💰 智能定价 | 输入商品 ID，获取京东/淘宝/拼多多三平台分策略定价区间与毛利率建议 |
| 📈 行业趋势 | 查看各品类价格趋势、折扣率、价格区间与市场份额饼图 |

### `admin.html` — 管理员端
| 模块 | 功能 |
|------|------|
| 📦 商品管理 | 分页浏览商品，新增/编辑/删除，关键字搜索，实时刷新 |
| 📤 数据导出 | 一键导出全量商品数据为 Excel |
| ⬆️ 数据导入 | 从原始数据集扫描并导入新增商品（增量，不重复插入） |
| 🔄 刷新价格 | 重新运行价格模拟算法，更新全库三平台价格 |
| 🤖 模型重训 | 重新训练 XGBoost + 随机森林，并将新评分批量写回数据库 |
| 📊 系统概览 | ECharts 可视化：品类分布、品牌 TOP10、价格区间分布、模型状态 |

---

## 快速开始

### 前提条件
- MySQL 8.x（已启动，`root` 账号可用）
- Miniconda / Anaconda

### 1. 创建 Conda 环境并安装依赖

```bash
conda create -n 3c python=3.11 -y
conda activate 3c
pip install -r backend/requirements.txt
```

### 2. 创建 MySQL 用户

```sql
-- 以 root 登录 MySQL 执行
CREATE USER IF NOT EXISTS 'admin'@'localhost' IDENTIFIED BY '123456';
GRANT ALL PRIVILEGES ON *.* TO 'admin'@'localhost' WITH GRANT OPTION;
FLUSH PRIVILEGES;
```

### 3. 初始化数据库（首次运行）

```bash
cd backend
python init_db.py
```

此步骤将自动完成：
1. 创建 `db_3c` 数据库及数据表
2. 解析数据集，生成三平台模拟价格，计算情感评分，批量插入 37,202 条商品
3. 训练 XGBoost 价格预测模型 + 随机森林推荐模型，保存至 `backend/models/`
4. 将预测价格、性价比评分、推荐评分批量回写数据库

> ⚠️ 首次初始化约需 **25-30 分钟**（主要耗时在 37K 条评分回写），请耐心等待。

如需**重置**数据库（清空重建）：

```bash
python init_db.py --reset
```

### 4. 启动服务

```bash
python app.py
```

服务默认运行于 `http://localhost:5000`，浏览器访问即进入登录页。

---

## 账号说明

| 角色 | 用户名 | 密码 | 说明 |
|------|--------|------|------|
| 管理员 | `admin` | `123456` | 固定账号，无需注册，直接进入管理后台 |
| 消费者/商家 | 自行注册 | 自定义 | 注册后登录，角色选择页选择身份 |

> 管理员账号在 `config.py` 中通过 `ADMIN_USERNAME` / `ADMIN_PASSWORD` 配置，也可通过环境变量覆盖。

---

## 配置说明

所有配置集中在 `backend/config.py`，支持通过**环境变量**覆盖默认值：

| 配置项 | 环境变量 | 默认值 | 说明 |
|--------|----------|--------|------|
| 数据库主机 | `DB_HOST` | `localhost` | MySQL 地址 |
| 数据库端口 | `DB_PORT` | `3306` | MySQL 端口 |
| 数据库用户 | `DB_USER` | `admin` | |
| 数据库密码 | `DB_PASSWORD` | `123456` | |
| 数据库名 | `DB_NAME` | `db_3c` | |
| JWT 密钥 | `SECRET_KEY` | `3c-price-system-secret-2025` | 生产环境请务必修改 |
| 管理员账号 | `ADMIN_USERNAME` | `admin` | |
| 管理员密码 | `ADMIN_PASSWORD` | `123456` | 生产环境请务必修改 |

---

## 注意事项

1. **评分回写耗时**：首次 `init_db.py` 写回 37K 条评分约需 20 分钟，这是一次性操作。后续重训通过管理员后台"模型重训"按钮触发，为后台异步任务，不阻塞前端。

2. **情感分析后端**：默认使用 SnowNLP（轻量，无需 GPU）。若安装了 `transformers` 库且有 BERT 模型缓存，系统会自动切换至真实 BERT，`/api/health` 接口的 `bert_backend` 字段会反映当前使用的引擎。

3. **价格数据**：三平台价格均为算法模拟，非真实市场价格，仅供演示与学习使用。

4. **数据编码**：原始数据集为 UTF-8 编码，Windows 终端可能显示乱码，实际存入数据库的中文数据完全正常（MySQL 连接串使用 `charset=utf8mb4`）。