甜点销售数据可视化分析系统 — 技术文档一、项目概述1.1 项目简介本项目是一个基于 Python 的甜点销售数据可视化分析系统面向甜点零售场景提供从数据管理到多维度分析、可视化大屏展示的一站式解决方案。系统涵盖用户认证、角色权限、数据 CRUD、多维图表分析及数据大屏等核心功能。1.2 技术栈层级技术版本后端框架FastAPI0.115.0数据库SQLite3内置模板引擎Jinja23.1.4可视化ECharts5.5.0ECharts 扩展echarts-liquidfill3.1.0用户认证JWT (PyJWT)2.9.0密码加密passlib bcrypt1.7.4 / 4.0.1ASGI 服务器Uvicorn0.30.61.3 运行环境Python 3.11Windows / 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 代码规模文件行数app/main.py656app/static/css/style.css701app/templates/analysis.html586app/templates/profile.html222app/templates/data.html146app/templates/dashboard.html146app/templates/bigscreen.html158app/templates/users.html108app/templates/register.html71app/templates/login.html61app/database.py87app/auth.py33总计3039三、数据库设计3.1 users 表字段类型约束说明idINTEGERPK, AUTO用户 IDusernameTEXTUNIQUE, NOT NULL用户名passwordTEXTNOT NULLbcrypt 哈希密码is_adminINTEGERDEFAULT 01管理员, 0普通用户created_atTEXTDEFAULT datetime注册时间预置账号管理员admin/123456普通用户user/123456角色分配规则系统中第一个注册的用户自动成为管理员后续注册用户均为普通用户。3.2 sales 表字段类型约束说明idINTEGERPK, AUTO记录 IDcustomer_idINTEGERNOT NULL顾客 IDproduct_idINTEGERNOT NULL产品 IDproduct_nameTEXTNOT NULL产品名称quantityINTEGERNOT NULL购买数量priceREALNOT NULL单价purchase_dateTEXTNOT NULL购买日期total_priceREALNOT NULL总价 (数量×单价)3.3 数据集概况指标值记录总数10,000产品种类10客户数量1,000时间范围2024-02-12 ~ 2025-02-11总销售额¥2,763,14510 种甜点产品序号产品名称1巧克力熔岩蛋糕2抹茶红豆蛋糕3提拉米苏4柠檬塔5椰香芒果布丁6焦糖玛奇朵冰淇淋7芒果慕斯8草莓千层蛋糕9蓝莓芝士蛋糕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 (tokenxxx, max_age86400) ↓ 返回 JSONResponse { msg, is_admin } ↓ 前端 JS 读取响应成功则跳转 /JWT Payload 结构{user_id:1,username:admin,is_admin:true,exp:1779724439}4.2 角色权限矩阵功能管理员普通用户概览仪表盘✅✅数据分析✅✅可视化大屏✅✅个人中心✅✅数据管理 (CRUD)✅❌用户管理✅❌数据写入 API✅❌用户管理 API✅❌4.3 权限实现页面级别路由函数中检查user.get(is_admin)非管理员重定向到首页。API 级别require_admin()函数校验 JWT 中的is_admin字段不满足则返回 403。前端级别侧边栏导航使用 Jinja2{% if user.is_admin %}条件渲染管理员才可见数据管理和用户管理入口。4.4 前端错误提示登录/注册页面使用 JSfetch提交表单根据 HTTP 状态码显示中文提示状态码提示信息200跳转首页401用户名或密码错误400用户名已存在前端校验两次密码输入不一致网络异常网络错误请稍后重试五、页面功能详解5.1 登录页 (/login)甜品风格粉色渐变背景 浮动光斑动画毛玻璃卡片效果登录框 图标装饰前端 JS 异步提交失败时红色错误提示框底部链接跳转注册页5.2 注册页 (/register)与登录页相同的甜品主题风格 图标装饰前端校验两次密码一致性第一个注册用户自动成为管理员5.3 概览仪表盘 (/)核心指标卡片 (5 项)图标指标数据源总销售额overview.revenue总销量overview.qty订单总数overview.cnt客户总数overview.customers平均客单价overview.avg_order图表 (4 个)图表类型API月度销售趋势折线柱状混合monthly_trend产品销售额占比环形饼图product_sales产品销量排行横向条形图product_sales订单金额分布饼图price_distribution5.4 数据分析 (/analysis)18 种图表6 行布局第一行 — 时间维度图表类型说明 月度销售趋势折线柱状销售额面积折线 销量柱状双 Y 轴 星期销售分析渐变柱状7 天销售额对比第二行 — 产品维度图表类型说明 产品销售额排行横向渐变条形按销售额降序 产品销量占比玫瑰饼图南丁格尔玫瑰图效果第三行 — 客户维度图表类型说明 TOP10 高消费客户横向条形消费金额前 10 购买数量分布饼图不同购买件数的订单占比第四行 — 交叉维度图表类型说明️ 产品-星期热力图热力图10 产品 × 7 天订单量矩阵 产品多维雷达图雷达图销量/销售额/订单数/均客单价第五行 — 结构维度图表类型说明 产品月度销售堆叠图堆叠柱状各产品月度销售额堆叠 订单金额分布柱状0-50/50-100/100-200/200-500/500第六行 — 单值维度图表类型说明⏱️ 产品平均单价横向条形各产品均价对比 销售漏斗图漏斗图产品销售额漏斗 产品订单量涟漪图涟漪散点effectScatter 动画第七行 — 特殊图表图表类型说明 总销售额仪表盘Gauge 仪表目标 300 万达成率 产品销售矩形树图Treemap面积表示销售占比☀️ 星期×产品旭日图Sunburst层级星期→产品第八行 — 多维与对比图表类型说明∥ 产品多维平行坐标图Parallel均购量/均单价/均客单价/总销售额 产品订单量对比柱状图渐变条形按订单量降序第九行 — 流向与趋势图表类型说明 产品→金额等级桑基图Sankey产品流向小/中/高/大额订单 产品销售主题河流图ThemeRiver时间维度上的销售河流第十行 — 形象化图表图表类型说明 产品销量象形柱图PictorialBar矩形纹理重复填充 销售目标完成率水球图LiquidFillecharts-liquidfill 波浪效果 产品收入结构组合图组合图柱状虚线帕累托累计曲线5.5 数据管理 (/data) — 仅管理员产品名称 日期范围筛选分页表格每页 20 条添加/编辑/删除销售记录弹窗表单Toast 提示写入操作需管理员权限API 级别校验5.6 用户管理 (/users) — 仅管理员用户列表表格ID、用户名、角色、注册时间切换管理员状态按钮删除用户按钮不可删除自己Toast 提示操作结果5.7 个人中心 (/profile)用户信息卡片 头像 用户名 注册时间管理员/活跃用户徽章管理数据量 系统用户数分析图表 (4 个)图表类型说明‍‍ 客户消费等级分布环形饼图低/中/高/超高消费客户数 产品关注度偏好环形饼图TOP5 产品订单占比 月度订单趋势面积折线图月度订单数量变化 单价 vs 销量散点图散点图产品均价与总销量关系修改密码原密码 新密码 确认新密码前端校验密码一致性后端校验原密码正确性5.8 可视化大屏 (/bigscreen)深色主题全屏布局无需登录实时时钟显示 返回首页按钮5 项核心指标卡片6 个图表月度趋势、产品占比、销量排行、星期分布、热力图Flex 弹性布局自适应屏幕每 5 分钟自动刷新六、API 接口文档6.1 认证接口POST /api/login用户登录返回 JWT Cookie。请求application/x-www-form-urlencoded参数类型必填说明usernamestring✅用户名passwordstring✅密码成功响应 (200){msg:登录成功,is_admin:true}Cookie:tokeneyJ...; HttpOnly; Max-Age86400; Path/失败响应 (401){detail:用户名或密码错误}POST /api/register用户注册返回 JWT Cookie。参数类型必填说明usernamestring✅用户名 (唯一)passwordstring✅密码成功响应 (200){msg:注册成功,is_admin:false}失败响应 (400){detail:用户名已存在}POST /api/logout退出登录删除 Cookie302 重定向到登录页。6.2 数据 CRUD 接口GET /api/sales分页查询销售数据。参数类型默认说明pageint1页码sizeint20每页条数 (1-100)productstring-按产品名筛选start_datestring-起始日期 (YYYY-MM-DD)end_datestring-结束日期 (YYYY-MM-DD)响应{total:10000,page:1,size:20,data:[{id:1,customer_id:66,product_name:提拉米苏,...}]}POST /api/sales — 管理员新增销售记录。参数类型必填说明customer_idint✅顾客 IDproduct_idint✅产品 IDproduct_namestring✅产品名称quantityint✅数量pricefloat✅单价purchase_datestring✅购买日期响应{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 分析接口接口说明维度GET /api/analysis/overview核心指标汇总全局GET /api/analysis/product_sales产品销量/销售额/均价/订单数产品GET /api/analysis/monthly_trend月度销售额/销量/订单数时间×指标GET /api/analysis/weekday星期销售额/订单数时间GET /api/analysis/price_distribution订单金额区间分布金额GET /api/analysis/quantity_distribution购买数量分布数量GET /api/analysis/top_customersTOP10 高消费客户客户GET /api/analysis/product_monthly产品月度销售额产品×时间GET /api/analysis/daily_trend日度销售额/订单数时间GET /api/analysis/customer_heatmap产品×星期订单热力矩阵产品×时间GET /api/analysis/revenue_rank产品销售额排名产品GET /api/analysis/sunburst星期×产品层级数据时间×产品GET /api/analysis/parallel产品多维指标 (均购量/均单价/均客单价/总销售额)产品×多维GET /api/analysis/sankey产品→金额等级流向产品→金额GET /api/analysis/theme_river日度产品销售河流时间×产品通用响应格式[{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 — 登录修改密码。参数类型必填说明old_passwordstring✅原密码new_passwordstring✅新密码七、前端设计7.1 设计风格主题甜品风格粉色系主色#ec407a (Pink 500)辅色#ffa726 (Orange 400)、#ab47bc (Purple 400)、#26a69a (Teal 400)背景#fff0f5 (Pink 100) 渐变至 #fff8f0 (Cream)圆角16px (卡片)、10px (按钮/输入框)阴影粉色系半透明投影动画浮动光斑背景、卡片 hover 上浮、按钮点击下沉7.2 响应式断点断点侧边栏图表网格大屏网格1200px240px 固定2列/3列3列768-1200px60px 仅图标1列2列768px60px 仅图标1列1列7.3 ECharts 图表类型汇总图表类型ECharts series.type使用位置折线图line仪表盘、分析、大屏、个人中心柱状图bar仪表盘、分析、大屏饼图pie仪表盘、分析、大屏、个人中心环形饼图pie (radius)仪表盘、分析、个人中心玫瑰图pie (roseType)分析横向条形图bar (横向)仪表盘、分析、大屏雷达图radar分析热力图heatmap分析、大屏堆叠柱状图bar (stack)分析仪表盘gauge分析漏斗图funnel分析涟漪散点图effectScatter分析矩形树图treemap分析旭日图sunburst分析平行坐标图parallel分析桑基图sankey分析主题河流图themeRiver分析象形柱图pictorialBar分析水球图liquidFill分析组合图barline分析散点图scatter个人中心共计 21 种图表类型18 种出现在数据分析页。八、部署与运行8.1 安装依赖pipinstall-rrequirements.txtrequirements.txt 内容fastapi0.115.0 uvicorn0.30.6 jinja23.1.4 python-multipart0.0.9 pyjwt2.9.0 passlib1.7.4 bcrypt4.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 首次运行系统启动时自动执行创建 SQLite 数据库app/sweet.db创建 users / sales 表若无管理员自动创建admin/123456若 sales 为空自动从 CSV 导入 10000 条数据若是旧数据库无 is_admin 字段自动 ALTER TABLE 迁移8.4 访问地址页面URL登录http://localhost:8001/login概览http://localhost:8001/数据分析http://localhost:8001/analysis数据管理http://localhost:8001/data用户管理http://localhost:8001/users个人中心http://localhost:8001/profile可视化大屏http://localhost:8001/bigscreen九、安全设计9.1 认证安全措施说明密码哈希bcrypt (cost factor 12)JWT HttpOnly Cookie防 XSS 窃取 tokenToken 过期24 小时自动失效Cookie Path/ 全站可用9.2 权限安全层级机制页面路由后端检查 is_admin非法访问 302 重定向写入 APIrequire_admin() 装饰器非管理员返回 403前端导航Jinja2 条件渲染非管理员看不到管理入口自保护管理员不可删除自己、不可修改自己的管理员状态十、关键代码说明10.1 database.py — 数据库初始化与迁移init_db(): 幂等初始化支持 CREATE IF NOT EXISTS ALTER TABLE 迁移_import_csv(): 读取 UTF-8 编码的 CSV批量 INSERT 10000 条记录首次无管理员时自动 INSERTadmin/123456(is_admin1)10.2 auth.py — 认证模块create_token(user_id, username, is_admin): 生成 JWTpayload 包含 is_admindecode_token(token): 解码验证过期/无效返回 Nonehash_password()/verify_password(): bcrypt 封装10.3 main.py — 核心路由get_current_user(): 从 Cookie 读取 token 并解码require_admin(): 认证 管理员权限双重校验登录/注册 API成功时JSONResponseset_cookie失败时HTTPException分析 API15 个端点覆盖全局、产品、时间、客户、交叉、流向等维度十一、常见问题Q: 启动报错module bcrypt has no attribute __about__A: bcrypt 版本过高与 passlib 不兼容。执行pip install bcrypt4.0.1。Q: 数据库损坏如何重建A: 删除app/sweet.db文件重启服务即可自动重建并导入数据。Q: 忘记管理员密码A: 删除app/sweet.db重启服务后自动创建admin/123456。Q: 如何新增管理员A: 以 admin 登录进入用户管理点击设为管理员按钮。Q: 大屏页面打不开A: 大屏无需登录直接访问/bigscreen。如仍无法访问检查端口是否正确。Q: 图表数据为空A: 检查甜点销售数据.csv是否在项目根目录首次启动需从此文件导入数据。