164-基于Python的甜点销售数据可视化分析系统

甜点销售数据可视化分析系统 — 技术文档

一、项目概述

1.1 项目简介

本项目是一个基于 Python 的甜点销售数据可视化分析系统，面向甜点零售场景，提供从数据管理到多维度分析、可视化大屏展示的一站式解决方案。系统涵盖用户认证、角色权限、数据 CRUD、多维图表分析及数据大屏等核心功能。

1.2 技术栈

1.3 运行环境

• Python 3.11+
• Windows / Linux / macOS
• 浏览器：Chrome 80+、Edge 80+、Firefox 78+

二、系统架构

2.1 整体架构

┌─────────────────────────────────────────────────────┐ │ 浏览器 (前端) │ │ ECharts 渲染引擎 + Jinja2 模板 + CSS 甜品主题样式 │ └──────────────────────┬──────────────────────────────┘ │ HTTP / Cookie ┌──────────────────────▼──────────────────────────────┐ │ FastAPI (后端) │ │ ┌──────────┐ ┌──────────┐ ┌───────────────────┐ │ │ │ 页面路由 │ │ REST API │ │ 权限中间件 │ │ │ └──────────┘ └──────────┘ └───────────────────┘ │ └──────────────────────┬──────────────────────────────┘ │ SQLite3 ┌──────────────────────▼──────────────────────────────┐ │ sweet.db (SQLite) │ │ users 表 │ sales 表 │ └─────────────────────────────────────────────────────┘

2.2 目录结构

sweet/ ├── run.py # 启动入口 ├── requirements.txt # Python 依赖 ├── 甜点销售数据.csv # 原始数据源 (10000 条) └── app/ ├── __init__.py ├── main.py # FastAPI 应用：路由、API、权限控制 (656 行) ├── database.py # 数据库初始化、CSV 导入、迁移 (87 行) ├── auth.py # JWT 认证、密码哈希 (33 行) ├── static/ │ ├── css/ │ │ └── style.css # 甜品主题粉色风格 (701 行) │ ├── js/ │ │ ├── echarts.min.js # ECharts 核心库 │ │ └── echarts-liquidfill.min.js # 水球图扩展 │ └── img/ └── templates/ ├── login.html # 登录页 ├── register.html # 注册页 ├── dashboard.html # 概览仪表盘 ├── analysis.html # 数据分析 (18 种图表) ├── data.html # 数据管理 (管理员) ├── users.html # 用户管理 (管理员) ├── profile.html # 个人中心 └── bigscreen.html # 可视化大屏

2.3 代码规模

三、数据库设计

3.1 users 表

预置账号：

• 管理员：admin/123456
• 普通用户：user/123456

角色分配规则：系统中第一个注册的用户自动成为管理员，后续注册用户均为普通用户。

3.2 sales 表

3.3 数据集概况

10 种甜点产品：

3.4 数据库初始化流程

启动 → CREATE TABLE IF NOT EXISTS → 检查 is_admin 列是否存在 ↓ 否 ALTER TABLE ADD COLUMN ↓ 检查是否有管理员账号 ↓ 否 INSERT 默认 admin 账号 ↓ 检查 sales 是否为空 ↓ 是 从 CSV 导入 10000 条数据

数据库支持热迁移：如果已有旧版数据库（无 is_admin 字段），系统会自动ALTER TABLE添加该列，无需手动迁移。

四、认证与权限

4.1 JWT 认证流程

用户提交登录表单 ↓ FastAPI 校验用户名密码 ↓ 生成 JWT Token (payload: user_id, username, is_admin, exp) ↓ 设置 HttpOnly Cookie (token=xxx, max_age=86400) ↓ 返回 JSONResponse { msg, is_admin } ↓ 前端 JS 读取响应，成功则跳转 /

JWT Payload 结构：

{"user_id":1,"username":"admin","is_admin":true,"exp":1779724439}

4.2 角色权限矩阵

4.3 权限实现

页面级别：路由函数中检查user.get("is_admin")，非管理员重定向到首页。

API 级别：require_admin()函数校验 JWT 中的is_admin字段，不满足则返回 403。

前端级别：侧边栏导航使用 Jinja2{% if user.is_admin %}条件渲染，管理员才可见数据管理和用户管理入口。

4.4 前端错误提示

登录/注册页面使用 JSfetch提交表单，根据 HTTP 状态码显示中文提示：

五、页面功能详解

5.1 登录页 (/login)

• 甜品风格粉色渐变背景 + 浮动光斑动画
• 毛玻璃卡片效果登录框
• 🧁 图标装饰
• 前端 JS 异步提交，失败时红色错误提示框
• 底部链接跳转注册页

5.2 注册页 (/register)

• 与登录页相同的甜品主题风格
• 🍰 图标装饰
• 前端校验两次密码一致性
• 第一个注册用户自动成为管理员

5.3 概览仪表盘 (/)

核心指标卡片 (5 项)：

图表 (4 个)：

5.4 数据分析 (/analysis)

18 种图表，6 行布局：

第一行 — 时间维度：

第二行 — 产品维度：

第三行 — 客户维度：

第四行 — 交叉维度：

第五行 — 结构维度：

第六行 — 单值维度：

第七行 — 特殊图表：

第八行 — 多维与对比：

第九行 — 流向与趋势：

第十行 — 形象化图表：

5.5 数据管理 (/data) — 仅管理员

• 产品名称 + 日期范围筛选
• 分页表格（每页 20 条）
• 添加/编辑/删除销售记录
• 弹窗表单，Toast 提示
• 写入操作需管理员权限，API 级别校验

5.6 用户管理 (/users) — 仅管理员

• 用户列表表格（ID、用户名、角色、注册时间）
• 切换管理员状态按钮
• 删除用户按钮（不可删除自己）
• Toast 提示操作结果

5.7 个人中心 (/profile)

用户信息卡片：

• 🧁 头像 + 用户名 + 注册时间
• 管理员/活跃用户徽章
• 管理数据量 + 系统用户数

分析图表 (4 个)：

修改密码：

• 原密码 + 新密码 + 确认新密码
• 前端校验密码一致性
• 后端校验原密码正确性

5.8 可视化大屏 (/bigscreen)

• 深色主题全屏布局，无需登录
• 实时时钟显示 + 返回首页按钮
• 5 项核心指标卡片
• 6 个图表：月度趋势、产品占比、销量排行、星期分布、热力图
• Flex 弹性布局自适应屏幕
• 每 5 分钟自动刷新

六、API 接口文档

6.1 认证接口

POST /api/login

用户登录，返回 JWT Cookie。

请求：application/x-www-form-urlencoded

成功响应 (200)：

{"msg":"登录成功","is_admin":true}

Cookie:token=eyJ...; HttpOnly; Max-Age=86400; Path=/

失败响应 (401)：

{"detail":"用户名或密码错误"}

POST /api/register

用户注册，返回 JWT Cookie。

成功响应 (200)：

{"msg":"注册成功","is_admin":false}

失败响应 (400)：

{"detail":"用户名已存在"}

POST /api/logout

退出登录，删除 Cookie，302 重定向到登录页。

6.2 数据 CRUD 接口

GET /api/sales

分页查询销售数据。

响应：

{"total":10000,"page":1,"size":20,"data":[{"id":1,"customer_id":66,"product_name":"提拉米苏",...}]}

POST /api/sales — 🔒 管理员

新增销售记录。

响应：

{"msg":"添加成功"}

PUT /api/sales/{sale_id} — 🔒 管理员

更新销售记录，请求体为 JSON。

DELETE /api/sales/{sale_id} — 🔒 管理员

删除销售记录。

6.3 用户管理接口 — 🔒 管理员

GET /api/users

获取用户列表。

响应：

[{"id":1,"username":"admin","is_admin":1,"created_at":"2026-05-25 00:00:00"},{"id":2,"username":"user","is_admin":0,"created_at":"2026-05-25 00:00:00"}]

DELETE /api/users/{user_id}

删除用户（不可删除自己）。

失败响应 (400)：

{"detail":"不能删除自己"}

PUT /api/users/{user_id}/toggle_admin

切换用户管理员状态（不可修改自己）。

响应：

{"msg":"更新成功","is_admin":1}

6.4 分析接口

通用响应格式：

[{"product_name":"提拉米苏","total_qty":5764,"total_revenue":292205.0,"avg_price":281.24,"order_count":1039}]

6.5 个人中心接口

GET /api/profile/stats — 🔒 登录

获取个人中心统计数据。

POST /api/profile/change_password — 🔒 登录

修改密码。

七、前端设计

7.1 设计风格

• 主题：甜品风格粉色系
• 主色：#ec407a (Pink 500)
• 辅色：#ffa726 (Orange 400)、#ab47bc (Purple 400)、#26a69a (Teal 400)
• 背景：#fff0f5 (Pink 100) 渐变至 #fff8f0 (Cream)
• 圆角：16px (卡片)、10px (按钮/输入框)
• 阴影：粉色系半透明投影
• 动画：浮动光斑背景、卡片 hover 上浮、按钮点击下沉

7.2 响应式断点

7.3 ECharts 图表类型汇总

共计 21 种图表类型，18 种出现在数据分析页。

八、部署与运行

8.1 安装依赖

pipinstall-rrequirements.txt

requirements.txt 内容：

fastapi==0.115.0 uvicorn==0.30.6 jinja2==3.1.4 python-multipart==0.0.9 pyjwt==2.9.0 passlib==1.7.4 bcrypt==4.0.1

注意：bcrypt 版本锁定为 4.0.1，与 passlib 兼容。4.2+ 版本会导致module 'bcrypt' has no attribute '__about__'错误。

8.2 启动服务

cdsweet python run.py

服务默认运行在http://localhost:8001，支持热重载。

8.3 首次运行

系统启动时自动执行：

1. 创建 SQLite 数据库app/sweet.db
2. 创建 users / sales 表
3. 若无管理员，自动创建admin/123456
4. 若 sales 为空，自动从 CSV 导入 10000 条数据
5. 若是旧数据库（无 is_admin 字段），自动 ALTER TABLE 迁移

8.4 访问地址

九、安全设计

9.1 认证安全

9.2 权限安全

十、关键代码说明

10.1 database.py — 数据库初始化与迁移

• init_db(): 幂等初始化，支持 CREATE IF NOT EXISTS + ALTER TABLE 迁移
• _import_csv(): 读取 UTF-8 编码的 CSV，批量 INSERT 10000 条记录
• 首次无管理员时，自动 INSERTadmin/123456(is_admin=1)

10.2 auth.py — 认证模块

• create_token(user_id, username, is_admin): 生成 JWT，payload 包含 is_admin
• decode_token(token): 解码验证，过期/无效返回 None
• hash_password()/verify_password(): bcrypt 封装

10.3 main.py — 核心路由

• get_current_user(): 从 Cookie 读取 token 并解码
• require_admin(): 认证 + 管理员权限双重校验
• 登录/注册 API：成功时JSONResponse+set_cookie，失败时HTTPException
• 分析 API：15 个端点覆盖全局、产品、时间、客户、交叉、流向等维度

十一、常见问题

Q: 启动报错module 'bcrypt' has no attribute '__about__'

A: bcrypt 版本过高，与 passlib 不兼容。执行pip install bcrypt==4.0.1。

Q: 数据库损坏如何重建

A: 删除app/sweet.db文件，重启服务即可自动重建并导入数据。

Q: 忘记管理员密码

A: 删除app/sweet.db，重启服务后自动创建admin/123456。

Q: 如何新增管理员

A: 以 admin 登录，进入用户管理，点击"设为管理员"按钮。

Q: 大屏页面打不开

A: 大屏无需登录，直接访问/bigscreen。如仍无法访问，检查端口是否正确。

Q: 图表数据为空

A: 检查甜点销售数据.csv是否在项目根目录，首次启动需从此文件导入数据。