# class_predict

**Repository Path**: liulaoshi666/class_predict

## Basic Information

- **Project Name**: class_predict
- **Description**: 电商项目
- **Primary Language**: Unknown
- **License**: Zlib
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 8
- **Forks**: 2
- **Created**: 2026-08-13
- **Last Updated**: 2026-09-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# class_predict · AI 智能客服分类系统

> 基于 Vue3 + FastAPI 的前后端分离全栈项目，集「智能客服文本分类」「电商运营后台」「商城前台」于一体。

## 项目简介

本项目面向电商客服场景，提供一套完整的智能分类与运营管理解决方案，由三个独立子项目构成：

| 子项目 | 技术栈 | 说明 |
|--------|--------|------|
| `demo` | Python + FastAPI + SQLAlchemy + MySQL | 后端服务，提供智能分类与各类管理 REST API |
| `web` | Vue3 + Vite + Element Plus | 运营管理后台 |
| `pat` | Vue3 + Vite + Element Plus + Pinia | 趣多多商城前台（京东风格），含在线客服 |

## 功能特性

### 智能客服分类
- 单条文本智能分类，覆盖 7 大类目：账户问题 / 订单问题 / 支付问题 / 物流问题 / 产品问题 / 服务问题 / 其他问题
- 基于关键词规则分类器实现，业务逻辑抽离为独立 Service，预留 TF-IDF + SVM、TextCNN 等机器学习算法接入点
- 分类记录入库留存，支持历史追溯

### 用户与权限
- 图形验证码（PIL 生成）、用户注册、登录
- 用户管理：增删改查、启用 / 禁用（禁用账号禁止登录）
- 密码 SHA256 加密存储，昵称展示

### 商品管理
- 商品增删改查，支持分类 / 关键词 / 状态筛选与分页
- 「为您推荐」随机推荐接口
- 商品图 emoji + 类目渐变底色兜底，预留 MinIO 真实图片字段

### 客服管理
- 客服添加（穿梭框多选）、编辑、移除
- 启用 / 禁用状态控制
- 商城前台动态拉取启用客服列表

### 趣多多商城前台
- 首页、商品列表、商品详情、购物车、订单、个人中心
- 「联系客服」：动态查询启用客服 + 聊天对话组件
- 购物车本地持久化（Pinia + localStorage）

### 实用增强
- 天气实时查询（对接国家气象局）
- 浏览器定位 + 逆地理编码

### 智能客服与投诉审核
- 已支付/已完成订单创建或恢复客服会话，WebSocket 消息 ACK、幂等去重、心跳和断线重连
- 问题分类路由、投诉类型识别和聊天生成 Provider 抽象，默认使用可离线演示的确定性 Mock
- 聊天原始消息持久化、投诉证据关联、受控截图附件、人工领取和乐观锁审核
- 审核记录、不可变投诉报告快照、在线通知与离线恢复
- 审核要求补充材料后，用户可追加说明、聊天证据和截图并重新进入领取审核流程
- **会话内投诉细分类**：用户消息发送后由 FastText 7 类模型（`demo/app/models/model.bin`）自动
  细分类，聊天页高亮最高概率类别并询问"是否属于该分类"；确认后一键提交投诉（自动关联会话/
  订单/证据），后台投诉管理直接展示细分类别与置信度
- 完整契约、状态流转、迁移和演示说明见 [docs/support-complaints.md](docs/support-complaints.md)

## 技术栈

| 层级 | 技术 |
|------|------|
| 后端框架 | Python 3.11+ / FastAPI / SQLAlchemy |
| 数据库 | MySQL（utf8mb4） |
| 管理后台前端 | Vue3 / Vite / Element Plus / Vue Router / Axios |
| 商城前端 | Vue3 / Vite / Element Plus / Pinia / Vue Router |
| 分类算法 | 关键词规则（预留 TF-IDF+SVM / TextCNN） |

## 项目结构

```
class_predict
├── demo/                     # FastAPI 后端
│   ├── app/
│   │   ├── api/              # 认证、商城、客服会话、投诉、审核和通知 API/WS
│   │   ├── models/           # 既有模型及订单、会话、投诉、报告、通知模型
│   │   ├── providers/        # 分类、投诉识别、聊天生成抽象与 Mock/HTTP 适配器
│   │   ├── services/         # 领域服务、鉴权、路由、实时连接和限流
│   │   └── ml/               # 机器学习模块（预留）
│   └── run.py                # 启动入口
├── web/                      # Vue3 运营管理后台
│   └── src/views/            # 登录 / 注册 / 分类 / 历史 / 统计 / 用户 / 商品 / 客服管理
└── pat/                      # Vue3 商城前台（趣多多商城）
    └── src/                  # 首页 / 列表 / 详情 / 购物车 / 订单 / 个人中心 + 客服聊天
```

## 快速开始

### 环境要求
- Python 3.11+
- Node.js 18+
- MySQL

### 1. 启动后端
```bash
cd demo
python -m venv .venv
.venv\Scripts\pip install -r requirements.txt
# 确认 demo/app/config_local.py 已填写 MySQL 连接信息
.venv\Scripts\python.exe -m alembic -c alembic.ini upgrade head
.venv\Scripts\python.exe run.py
```
后端默认运行于 http://127.0.0.1:8000

### 2. 启动管理后台
```bash
cd web
npm install
npm run dev
```
默认运行于 http://localhost:5173

### 3. 启动商城前台
```bash
cd pat
npm install
npm run dev
```
默认运行于 http://localhost:5174

## 连接 MySQL 后启动完整项目

以下步骤适用于本地 MySQL或云 MySQL。生产/云数据库执行迁移前应先完成数据库备份，并确认
MySQL 服务、3306 端口、安全组、访问白名单和数据库账号的远程权限均已正确配置。

### 1. 配置 MySQL

数据库连接由 `demo/app/config_local.py` 提供，该文件已被 `.gitignore` 排除，不会提交真实密码：

```python
DB_HOST = "<MySQL地址>"
DB_PORT = 3306
DB_USER = "<用户名>"
DB_PASSWORD = "<密码>"
DB_NAME = "<数据库名>"
```

如果该文件不存在，程序会读取系统环境变量 `DB_HOST`、`DB_PORT`、`DB_USER`、`DB_PASSWORD` 和 `DB_NAME`。项目仅使用 MySQL。

生产环境还应通过系统环境变量配置 `APP_ENV=production`、`APP_SECRET_KEY` 和 `CORS_ORIGINS`。

可用以下命令生成 `APP_SECRET_KEY`：

```powershell
python -c "import secrets; print(secrets.token_urlsafe(48))"
```

`config.py` 会对用户名和密码自动进行 URL 编码。不要把数据库密码写回 `demo/app/config.py`、README 或前端代码。

### 2. 安装后端依赖并检查连接

```powershell
cd demo
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements.txt

# 只执行 SELECT 1，不修改数据库
.\.venv\Scripts\python.exe -c "from sqlalchemy import text; from app.models.database import engine; c=engine.connect(); print(c.execute(text('SELECT 1')).scalar()); c.close()"
```

输出 `1` 表示 SQLAlchemy 已成功连接 `config_local.py` 指定的 MySQL。

常见连接错误：

- `2003`：地址、端口、安全组或网络不可达。
- `2013 Lost connection`：TCP 端口可达，但 MySQL 握手被服务、防火墙、白名单或代理中断。
- `1045 Access denied`：用户名、密码或 MySQL `user@host` 授权不正确。

### 3. 执行 Alembic 增量迁移

先在结构一致的预发布库验证，并为目标数据库创建备份。确认无误后执行：

```powershell
cd demo
.\.venv\Scripts\python.exe -m alembic -c alembic.ini current
.\.venv\Scripts\python.exe -m alembic -c alembic.ini upgrade head
.\.venv\Scripts\python.exe -m alembic -c alembic.ini current
```

最终版本应为 `20260815_0005 (head)`。迁移会先检查同名既有表的关键字段和主键；发现结构不兼容时会停止，
不要通过手工 stamp 或删除表绕过检查。

既有云库用户迁移后默认仍为普通 `USER`。需要为某个明确账号授予后台管理权限时执行：

```powershell
cd demo
.\.venv\Scripts\python.exe -m app.bootstrap_admin --username <已存在的准确用户名> --confirm GRANT_COMPLAINT_ADMIN
```

该命令会修改指定用户的角色，请先确认用户名；系统不会自动把“第一个用户”提升为管理员。

### 4. 按顺序启动三个服务

终端一，启动 FastAPI：

```powershell
cd demo
.\.venv\Scripts\python.exe run.py
```

后端地址：http://127.0.0.1:8000

终端二，启动后台管理端：

```powershell
cd web
npm.cmd install
npm.cmd run dev
```

后台地址：http://localhost:5173

终端三，启动趣多多商城：

```powershell
cd pat
npm.cmd install
npm.cmd run dev
```

商城地址：http://localhost:5174

修改 `config_local.py` 或系统环境变量后必须重启后端进程。后台和商城登录使用同一张 `users` 表；云库中不存在本地
`demo_admin` / `demo_user` 演示账号，需注册真实用户或对既有账号执行上述管理员授权。

## 数据库表

| 表名 | 说明 |
|------|------|
| users | 用户表 |
| product | 商品表 |
| customer_service | 客服表 |
| classify_record | 分类记录表 |
| orders / order_items | 权威订单归属与商品快照 |
| support_sessions / support_messages | 客服会话与原始消息 |
| complaints / complaint_reviews / complaint_supplements | 投诉、人工审核与用户补充材料 |
| complaint_reports / complaint_status_history | 不可变报告快照与状态审计 |
| user_notifications | 在线/离线审核结果通知 |

## License