113-基于Python的国际超市电商销售数据可视化分析系统

International SuperStore Insight Hub

MVP 项目技术文档

1. 项目概述

1.1 项目名称

International SuperStore Insight Hub

中文名称：国际超市电商销售数据可视化分析系统

1.2 项目定位

本项目是一个基于 FastAPI + Vue 3 + ECharts + MySQL 的国际超市经营分析 MVP 系统。它围绕 data/SuperStore.xlsx 数据集构建，通过将 Excel 业务明细导入 MySQL，再由后端实时执行聚合查询，为前端提供经营驾驶舱、分析中心、用户管理和数据管理能力。

该 MVP 不是一个通用 ERP，也不是完整的 BI 平台，而是一个聚焦于以下目标的最小可用产品：

让业务数据从 Excel 快速落库
让用户完成登录、查看分析、维护个人资料
让管理员能够管理账号与业务数据
让经营分析从单一大屏扩展为多模块专题分析
用真实数据库聚合结果驱动可视化，而不是使用前端硬编码数据

1.3 MVP 目标

快速验证国际超市销售数据可视化方案是否可行
用较低的实现复杂度支撑真实数据分析
建立一个后续可扩展为完整分析平台的基础工程
以单体应用形式完整覆盖"认证 + 导入 + 分析 + 管理"闭环

1.4 当前 MVP 能力边界

当前版本已经覆盖：

认证：注册、登录、登出、当前用户信息读取
个人中心：用户资料查看与更新
数据底座：Excel 导入 MySQL、导入状态查看
经营驾驶舱：大屏总览
分析中心：地理、商品、客户、运营四大专题分析
管理后台：用户管理、订单明细管理
权限控制：普通用户与管理员可见模块隔离

当前版本仍然保留典型 MVP 特征：

业务明细表采用单表宽表设计，而非完整星型模型
数据来源以单一 Excel 为主，暂不接第三方业务系统
未引入消息队列、缓存中间件、任务调度器
未拆分微服务，仍采用单体后端 + 单页前端模式

2. 系统整体架构

2.1 架构形式

项目采用典型的 前后端一体式单体架构：

前端静态资源位于 static/
后端 API 位于 app/routers/
数据模型位于 app/models.py
数据导入逻辑位于 app/importer.py
FastAPI 同时提供 API 和前端静态页面访问

2.2 运行链路

用户通过浏览器访问 /
FastAPI 返回 static/index.html
前端 app.js 启动 Vue 单页应用
用户登录后，前端通过 fetch 访问 /api/*
FastAPI 读取 Token，解析当前用户身份
业务路由调用 SQLAlchemy 查询 MySQL
聚合结果以 JSON 返回前端
前端使用 ECharts 将结果渲染为图表

2.3 架构分层

表现层

static/index.html
static/styles.css
static/app.js

接口层

app/main.py
app/routers/auth.py
app/routers/profile.py
app/routers/data.py
app/routers/dashboard.py
app/routers/admin.py

业务与基础设施层

app/importer.py
app/security.py
app/dependencies.py
app/db.py
app/config.py

数据层

MySQL 数据库：design_113_shop
三张核心物理表：users、auth_tokens、superstore_orders

3. 技术栈

3.1 后端技术栈

技术	版本/来源	用途
FastAPI	`requirements.txt`	Web API 框架
Uvicorn	`requirements.txt`	ASGI 服务运行器
SQLAlchemy 2	`requirements.txt`	ORM 与 SQL 查询
PyMySQL	`requirements.txt`	MySQL 驱动
OpenPyXL	`requirements.txt`	读取 Excel 数据
Python	项目运行环境	后端主语言

3.2 前端技术栈

技术	来源	用途
Vue 3	CDN 引入	单页应用框架
Vue Router 4	CDN 引入	路由管理
ECharts 5	CDN 引入	图表可视化
ECharts World Map	CDN 引入	世界地图图层
原生 Fetch API	浏览器内置	调用后端接口
原生 CSS	本地文件	页面样式与布局

3.3 数据库与数据源

技术	用途
MySQL	结构化业务数据存储
SuperStore.xlsx	原始业务数据输入源

3.4 工程特征

前端不依赖打包器，直接使用 CDN 版 Vue / ECharts
后端通过 FastAPI 单体对外提供全部接口
采用 SQLAlchemy 模型定义数据库结构
采用 Excel 批量导入作为 MVP 数据接入方式
采用 Token 表持久化会话，而不是纯 JWT 无状态方案

4. 项目目录结构

text 复制代码

shop/
├─ app/
│  ├─ config.py                # 配置项
│  ├─ db.py                    # 数据库初始化、建库、会话工厂
│  ├─ dependencies.py          # 登录与管理员依赖
│  ├─ importer.py              # Excel -> MySQL 导入逻辑
│  ├─ main.py                  # FastAPI 应用入口
│  ├─ models.py                # ORM 数据模型
│  ├─ security.py              # 密码哈希、Token 生成与注销
│  └─ routers/
│     ├─ auth.py               # 注册/登录/退出/当前用户
│     ├─ profile.py            # 个人资料
│     ├─ data.py               # 数据状态与导入
│     ├─ dashboard.py          # 大屏与分析接口
│     └─ admin.py              # 管理员用户与数据管理
├─ data/
│  └─ SuperStore.xlsx          # 原始业务数据
├─ static/
│  ├─ index.html               # SPA 容器页面
│  ├─ styles.css               # 全局样式
│  └─ app.js                   # Vue SPA 主文件
├─ design_113_shop.sql         # SQL 参考文件
├─ main.py                     # 运行入口代理
├─ README.md
└─ requirements.txt

5. 数据库设计

5.1 数据库基本信息

数据库类型：MySQL
默认数据库名：design_113_shop
编码：utf8mb4
排序规则：utf8mb4_unicode_ci

配置默认值位于 app/config.py：

DB_HOST=localhost
DB_PORT=3306
DB_USER=root
DB_PASSWORD=123456
DB_NAME=design_113_shop

5.2 建库与建表策略

项目启动时执行 app/db.py 中的以下流程：

ensure_database()：若数据库不存在，则自动创建
Base.metadata.create_all()：根据 ORM 自动建表
sync_schema()：执行轻量兼容迁移

当前兼容迁移包括：

若 users 表不存在 is_admin 字段，则自动补列
若系统中没有管理员，则自动将首个用户提升为管理员

这意味着项目具备基础的 MVP 自恢复 schema 能力，但尚未引入 Alembic 这类正式迁移框架。

5.3 数据库表总览

当前项目共有三张核心表：

表名	类型	作用
`users`	主数据表	存储系统用户账户与个人资料
`auth_tokens`	会话表	存储用户登录 Token 与有效期
`superstore_orders`	事实表/业务明细表	存储导入后的国际超市订单明细

6. 数据库表详细设计

6.1 `users` 表

6.1.1 作用

用于存储平台用户账号信息、基础资料和角色属性。

6.1.2 字段说明

字段名	类型	约束	说明
`id`	`Integer`	PK, 自增	用户主键
`username`	`String(50)`	唯一, 索引	登录用户名
`email`	`String(120)`	唯一, 可空, 索引	邮箱
`password_hash`	`String(255)`	非空	哈希后的密码
`is_admin`	`Boolean`	非空, 默认 `False`	是否管理员
`full_name`	`String(80)`	可空	真实姓名
`phone`	`String(30)`	可空	电话
`country`	`String(80)`	可空	所属国家
`city`	`String(80)`	可空	所属城市
`bio`	`Text`	可空	个人简介
`created_at`	`DateTime`	默认当前时间	创建时间
`updated_at`	`DateTime`	默认当前时间, 更新时自动刷新	更新时间

6.1.3 业务规则

用户名唯一
邮箱唯一，但允许为空
第一个注册用户自动成为管理员
系统必须至少保留一个管理员
管理员不能删除自己，也不能把自己降为普通用户

6.2 `auth_tokens` 表

6.2.1 作用

用于实现登录态持久化和服务端会话控制。

6.2.2 字段说明

字段名	类型	约束	说明
`token`	`String(128)`	PK	登录 Token
`user_id`	`Integer`	FK -> `users.id`, 索引	所属用户
`expires_at`	`DateTime`	索引	过期时间
`created_at`	`DateTime`	默认当前时间	Token 创建时间

6.2.3 关系说明

一个 User 可以拥有多个 AuthToken
一个 AuthToken 必须归属于一个 User
删除用户时，相关 Token 级联删除

6.2.4 设计特点

当前项目没有采用纯前端保存的 JWT 无状态鉴权，而是采用：

随机 Token
存数据库
每次请求查表校验

这种方案的优点是：

容易做登出
容易做过期清理
容易后续扩展为多端登录控制

6.3 `superstore_orders` 表

6.3.1 作用

这是整个系统最核心的业务表，用于承载导入后的国际超市订单明细数据，也是所有图表与分析查询的唯一事实表。

该表采用 宽表 + 反规范化 设计，目的是：

简化 Excel 导入逻辑
简化分析 SQL
降低 MVP 数据建模成本
适合围绕一个固定业务数据集快速做可视化

6.3.2 字段说明

字段名	类型	约束	说明
`row_id`	`Integer`	PK	Excel 行唯一编号
`order_id`	`String(40)`	索引	订单编号
`ship_mode`	`String(50)`	非空	运输方式
`customer_id`	`String(30)`	索引	客户编号
`customer_name`	`String(120)`	非空	客户名称
`segment`	`String(40)`	索引	客户群体
`city`	`String(120)`	索引	城市
`state`	`String(120)`	索引	州/省
`country`	`String(120)`	索引	国家
`postal_code`	`String(40)`	可空	邮编
`market`	`String(20)`	索引	市场
`region`	`String(60)`	索引	区域
`product_id`	`String(40)`	索引	商品编号
`category`	`String(60)`	索引	品类
`sub_category`	`String(60)`	索引	子品类
`product_name`	`String(255)`	非空	商品名称
`sales`	`Float`	非空	销售额
`quantity`	`Integer`	非空	销量
`discount`	`Float`	非空	折扣
`profit`	`Float`	非空	利润
`shipping_cost`	`Float`	非空	运费
`order_priority`	`String(20)`	索引	订单优先级
`order_date`	`Date`	索引	下单日期
`month_name`	`String(20)`	索引	月份名称
`month_order`	`Integer`	索引	月份序号
`year`	`Integer`	索引	年份

6.3.3 索引设计

除单列索引外，还定义了两个复合索引：

索引名	字段	目的
`ix_orders_market_region_country`	`market, region, country`	加速多级地理筛选
`ix_orders_year_month`	`year, month_order`	加速时间趋势查询

6.3.4 设计说明

superstore_orders 是一个典型分析型事实表，但当前 MVP 没有拆成：

订单事实表
客户维表
商品维表
地理维表
时间维表

而是选择单表承载全部维度。这种设计适合 MVP 快速落地，但后期若数据量继续增长，建议升级为：

星型模型
维表标准化
预聚合宽表
数据仓库分层

7. E-R 图

7.1 物理 E-R 图（当前实现）

owns
USERS
INT
id
PK
VARCHAR
username
UK
VARCHAR
email
UK
VARCHAR
password_hash
BOOLEAN
is_admin
VARCHAR
full_name
VARCHAR
phone
VARCHAR
country
VARCHAR
city
TEXT
bio
DATETIME
created_at
DATETIME
updated_at
AUTH_TOKENS
VARCHAR
token
PK
INT
user_id
FK
DATETIME
expires_at
DATETIME
created_at
SUPERSTORE_ORDERS
INT
row_id
PK
VARCHAR
order_id
VARCHAR
ship_mode
VARCHAR
customer_id
VARCHAR
customer_name
VARCHAR
segment
VARCHAR
city
VARCHAR
state
VARCHAR
country
VARCHAR
postal_code
VARCHAR
market
VARCHAR
region
VARCHAR
product_id
VARCHAR
category
VARCHAR
sub_category
VARCHAR
product_name
FLOAT
sales
INT
quantity
FLOAT
discount
FLOAT
profit
FLOAT
shipping_cost
VARCHAR
order_priority
DATE
order_date
VARCHAR
month_name
INT
month_order
INT
year

7.2 E-R 图解读

当前物理模型只有一个明确外键关系：

users.id -> auth_tokens.user_id

superstore_orders 没有关联到 users，原因是：

订单数据来自外部 Excel 导入
系统用户是平台使用者，不是业务订单中的客户
因此"平台账号"和"业务客户"是两套不同语义的实体

换句话说：

users：系统操作者
superstore_orders.customer_id：业务客户

这两者在当前 MVP 中没有物理关联。

7.3 业务视角的概念关系

虽然当前数据库没有拆维表，但从分析语义上可以理解为：

一个订单属于一个市场
一个订单属于一个区域
一个订单属于一个国家/城市
一个订单属于一个客户群体
一个订单关联一个商品、品类、子品类
一个订单具有时间属性

因此，superstore_orders 实际上承载了一个简化版的"订单事实 + 多维分析"模型。

8. 结构功能说明

8.1 用户与权限结构

系统采用两级角色：

角色	能力范围
普通用户	登录、查看驾驶舱、查看分析中心、维护个人中心
管理员	拥有普通用户全部能力，外加用户管理、数据管理

权限表现

顶部导航按角色动态显示
路由守卫控制管理员路由访问
后端通过 get_admin_user 进行强校验

8.2 页面结构

游客页

登录页 /login
注册页 /register

普通用户页

驾驶舱 /dashboard
分析中心总览 /analysis
地理分析 /analysis/geo
商品分析 /analysis/product
客户分析 /analysis/customer
运营分析 /analysis/operations
个人中心 /profile

管理员页

用户管理 /admin/users
数据管理 /admin/data

8.3 功能模块说明

8.3.1 认证模块

后端文件：

主要能力：

注册
登录
登出
当前用户读取
Token 过期控制
登录态解析

8.3.2 个人中心模块

后端文件：

app/routers/profile.py

前端页面：

ProfilePage

主要能力：

查看当前资料
修改姓名、邮箱、电话、国家、城市、简介

8.3.3 数据导入模块

后端文件：

主要能力：

查看数据状态
将 Excel 导入 MySQL
支持强制重导
支持批量插入

8.3.4 驾驶舱模块

前端页面：

DashboardPage

后端接口集中在：

app/routers/dashboard.py

主要图表与能力：

核心经营指标卡片
市场结构
月度趋势
国家排行
品类经营
客户矩阵
折扣画像
运费压力
明星商品
订单热力日历
市场流向桑基图
子品类榜单

8.3.5 分析中心模块

前端页面：

AnalysisHubPage
GeoAnalysisPage
ProductAnalysisPage
CustomerAnalysisPage
OperationsAnalysisPage

地理分析

市场表现
区域销售
国家对比
全球销售地图
区域、国家、城市明细

商品分析

商品层级旭日图
商品结构树图
品类表现
市场品类结构
利润气泡散点
子品类排行
明星商品
风险商品

客户分析

客群表现
忠诚度结构
忠诚漏斗
RFM 热力矩阵
RFM 平行坐标
市场客群结构
客群明细
头部客户

运营分析

运输方式表现
年度运营走势
折扣影响
运输方式雷达
利润瀑布图
优先级明细
低利润区域

8.3.6 管理后台模块

后端文件：

app/routers/admin.py

前端页面：

AdminUsersPage
AdminDataPage

用户管理

能力包括：

用户列表查询
搜索用户
创建用户
编辑用户
删除用户
切换管理员权限
管理员保底保护

数据管理

能力包括：

订单明细分页查询
多维筛选
搜索订单/客户/商品/国家/城市
查看单条数据
新增订单明细
编辑订单明细
删除订单明细

9. 核心 API 结构

9.1 认证接口

接口	方法	说明
`/api/auth/register`	POST	注册
`/api/auth/login`	POST	登录
`/api/auth/logout`	POST	退出登录
`/api/auth/me`	GET	当前登录用户

9.2 个人中心接口

接口	方法	说明
`/api/profile/me`	GET	获取个人资料
`/api/profile/me`	PUT	更新个人资料

9.3 数据底座接口

接口	方法	说明
`/api/data/status`	GET	查看导入状态
`/api/data/import`	POST	导入 Excel 数据

9.4 驾驶舱与分析接口

接口	方法	说明
`/api/dashboard/filters`	GET	获取筛选项
`/api/dashboard/summary`	GET	汇总指标
`/api/dashboard/market-distribution`	GET	市场分布
`/api/dashboard/monthly-trend`	GET	月度趋势
`/api/dashboard/category-overview`	GET	品类概览
`/api/dashboard/segment-matrix`	GET	客群矩阵
`/api/dashboard/top-countries`	GET	国家排行
`/api/dashboard/discount-analysis`	GET	折扣分析
`/api/dashboard/shipping-priority`	GET	运费与优先级
`/api/dashboard/top-products`	GET	商品排行
`/api/dashboard/insights`	GET	自动洞察摘要
`/api/dashboard/geo-analysis`	GET	地理分析
`/api/dashboard/product-analysis`	GET	商品分析
`/api/dashboard/customer-analysis`	GET	客户分析
`/api/dashboard/operations-analysis`	GET	运营分析
`/api/dashboard/product-advanced`	GET	树图、旭日图、气泡散点
`/api/dashboard/calendar-analysis`	GET	日历热力数据
`/api/dashboard/geo-map`	GET	世界地图数据
`/api/dashboard/market-flow`	GET	桑基图数据
`/api/dashboard/customer-rfm`	GET	RFM 数据
`/api/dashboard/profit-waterfall`	GET	利润瀑布图数据

上述分析接口统一支持当前 MVP 的核心筛选维度：

year
market
region
country

9.5 管理员接口

用户管理

接口	方法	说明
`/api/admin/users`	GET	用户列表
`/api/admin/users`	POST	新建用户
`/api/admin/users/{user_id}`	PUT	更新用户
`/api/admin/users/{user_id}`	DELETE	删除用户

数据管理

接口	方法	说明
`/api/admin/orders`	GET	订单分页列表
`/api/admin/orders/options`	GET	下拉筛选项
`/api/admin/orders/{row_id}`	GET	单条订单详情
`/api/admin/orders`	POST	新增订单
`/api/admin/orders/{row_id}`	PUT	编辑订单
`/api/admin/orders/{row_id}`	DELETE	删除订单

10. 前端结构说明

10.1 前端路由策略

前端使用 Vue Router 4 的 createWebHashHistory()。

路由特征：

未登录用户访问受保护页面会被重定向到 /login
已登录用户访问游客页会跳回 /dashboard
非管理员访问管理员路由会跳回 /dashboard

10.2 前端组件结构

关键公共组件：

TopNav：顶部导航和角色感知菜单
ScopeSummary：当前筛选范围摘要
AnalysisTabs：分析中心二级导航
AdminTabs：后台管理二级导航

10.3 前端工程特征

所有页面均在 static/app.js 中定义
使用原生 fetch 发请求
内置 GET 请求缓存
内置筛选请求乱序保护
内置 resize 节流
支持 CSV 导出
支持基于角色的导航渲染

11. 数据流与处理流程

11.1 Excel 导入数据流

用户点击"同步 Excel / Import"
前端调用 POST /api/data/import
后端读取 data/SuperStore.xlsx
OpenPyXL 按行遍历工作表
标准化文本、日期、邮编等字段
按 1000 条为一批写入 superstore_orders
返回导入结果和总行数

11.2 分析查询数据流

前端根据筛选条件拼接查询参数
调用 /api/dashboard/*
后端对 superstore_orders 执行聚合查询
将结果组装为图表友好 JSON
前端将 JSON 转为 ECharts option
页面渲染图表

11.3 权限控制数据流

用户登录成功后生成 Token
Token 保存到 auth_tokens 表
前端本地存储 token 和 user
后续请求带 Authorization: Bearer <token>
后端查 auth_tokens 和 users
管理员接口额外校验 is_admin

12. MVP 设计取舍说明

12.1 为什么使用宽表

宽表对当前项目的好处：

导入简单
查询直观
适合单数据集分析
减少维表维护成本

代价是：

冗余较高
数据治理能力弱
不利于大规模扩展

12.2 为什么使用服务端 Token 表

优点：

容易实现登出
易于失效控制
易于后续增加风控策略

代价：

每次请求都需要查数据库
会话状态不完全无状态

12.3 为什么前端不打包

MVP 场景下直接使用 CDN 有明显优势：

搭建速度快
依赖少
结构简单
演示部署成本低

代价：

前端代码集中在单文件中
不利于大型团队协作
不利于类型系统和复杂工程管理

13. 当前 MVP 的优势与不足

13.1 优势

技术栈轻量，部署简单
数据从 Excel 到图表闭环完整
后端结构清晰，职责分离明确
管理员能力已覆盖用户和数据双管理
图表维度丰富，支持多专题分析
普通用户与管理员权限边界清楚

13.2 不足

static/app.js 体积较大，前端模块化不足
数据库迁移机制较弱，尚未接入 Alembic
缺乏自动化测试体系
缺少 Redis 缓存或预聚合层
业务数据仍是单一数据源
尚未形成真正的数据仓库模型

14. 后续演进建议

14.1 数据层

拆分客户、商品、地理、时间维表
建立星型模型
引入 Alembic 迁移
增加物化聚合表或缓存

14.2 后端层

增加服务层抽象
增加统一分页与响应结构
增加自动化测试
增加权限粒度控制

14.3 前端层

将 static/app.js 拆分为模块
引入构建工具
细化图表主题系统
增加浏览器级交互测试

14.4 业务层

增加退货分析
增加库存与周转分析
增加活动与营销维度
增加利润归因与经营预警

15. 结论

从 MVP 视角看，该项目已经形成了一个完整、闭环、可运行的国际超市经营分析系统：

数据有来源：SuperStore.xlsx
数据能落库：MySQL
用户能登录：users + auth_tokens
页面能分析：dashboard + analysis
管理能闭环：admin/users + admin/orders

其最重要的工程价值不在于"技术多复杂"，而在于用较少的基础设施，实现了：

真实数据导入
真实数据库聚合
多维可视化分析
权限分级
管理后台

这正符合一个课程设计、毕业设计或业务验证型 MVP 应有的完整性。

113-基于Python的国际超市电商销售数据可视化分析系统

International SuperStore Insight Hub

MVP 项目技术文档

1. 项目概述

1.1 项目名称

1.2 项目定位

1.3 MVP 目标

1.4 当前 MVP 能力边界

2. 系统整体架构

2.1 架构形式

2.2 运行链路

2.3 架构分层

表现层

接口层

业务与基础设施层

数据层

3. 技术栈

3.1 后端技术栈

3.2 前端技术栈

3.3 数据库与数据源

3.4 工程特征

4. 项目目录结构

5. 数据库设计

5.1 数据库基本信息

5.2 建库与建表策略

5.3 数据库表总览

6. 数据库表详细设计

6.1 users 表

6.1.1 作用

6.1.2 字段说明

6.1.3 业务规则

6.2 auth_tokens 表

6.2.1 作用

6.2.2 字段说明

6.2.3 关系说明

6.2.4 设计特点

6.3 superstore_orders 表

6.3.1 作用

6.3.2 字段说明

6.3.3 索引设计

6.3.4 设计说明

7. E-R 图

7.1 物理 E-R 图（当前实现）

7.2 E-R 图解读

7.3 业务视角的概念关系

8. 结构功能说明

8.1 用户与权限结构

权限表现

8.2 页面结构

游客页

普通用户页

管理员页

8.3 功能模块说明

8.3.1 认证模块

8.3.2 个人中心模块

8.3.3 数据导入模块

8.3.4 驾驶舱模块

8.3.5 分析中心模块

地理分析

商品分析

客户分析

运营分析

8.3.6 管理后台模块

用户管理

数据管理

9. 核心 API 结构

9.1 认证接口

9.2 个人中心接口

9.3 数据底座接口

9.4 驾驶舱与分析接口

9.5 管理员接口

用户管理

数据管理

10. 前端结构说明

10.1 前端路由策略

10.2 前端组件结构

10.3 前端工程特征

11. 数据流与处理流程

11.1 Excel 导入数据流

11.2 分析查询数据流

6.1 `users` 表

6.2 `auth_tokens` 表

6.3 `superstore_orders` 表