# freshgo-mall **Repository Path**: barql/freshgo-mall ## Basic Information - **Project Name**: freshgo-mall - **Description**: 鲜GO生鲜电商系统 - Java后端 + Vue前端 + Python AI预测服务三栈架构 - **Primary Language**: Java - **License**: MIT - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-11-03 - **Last Updated**: 2026-11-04 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # 鲜GO生鲜电商 · Freshgo-Mall > 一套完整的企业级电商教学项目 · Java + Vue + Python 三栈联合

Java Spring Boot Vue Vite Python FastAPI License

--- ## 📌 项目简介 **鲜GO生鲜** 是一个主打有机生鲜的电商平台。系统拆成三个独立部署、松耦合通信的服务: | 服务 | 端口 | 技术栈 | 职责 | |---|---|---|---| | **Java 后端** | `8080` | Spring Boot 3.4 + MyBatis-Plus + JWT + H2(Redis 依赖已引入,默认不启用) | 主业务闭环、RBAC 权限、统一返回体、事务保障 | | **Python AI 服务** | `8100` | FastAPI + scikit-learn + pandas | 销量预测(移动平均+周末因子)、协同过滤推荐 | | **Vue 前端** | `5173` | Vue 3 + Vite + Element Plus + Pinia + ECharts | C 端商城 + B 端管理后台(双端合一) | ### 为什么拆三个服务? 1. **职责单一**:Java 做事务最稳,Python 做数据科学生态最好,Vue 做交互最灵活 2. **独立部署**:Python 模型升级不影响主业务,Java 发版不影响看板 3. **面试故事**:能讲"微服务拆分的 3 个时机"——业务复杂度、技术栈差异、团队分工 --- ## 📂 目录结构 ``` freshgo-mall/ ├── backend-java/ # Java 主后端 (Spring Boot 3 + MyBatis-Plus) │ ├── pom.xml │ └── src/main/ │ ├── java/com/freshgo/mall/ │ │ ├── FreshgoMallApplication.java │ │ ├── common/ # Result / ResultCode / BizException / GlobalExceptionHandler │ │ ├── config/ # Cors / WebMvc / MP 分页 / AutoFill / RestTemplate │ │ ├── security/ # JWT 无状态鉴权 + ThreadLocal 用户上下文 │ │ ├── integration/ # AiClient:HTTP 调用 Python AI 服务 │ │ ├── dto/{req,resp}/ # 请求响应 DTO(分离设计) │ │ ├── entity/ # 7 张表的 MP 实体 │ │ ├── mapper/ # BaseMapper + ProductMapper 原子扣库存 │ │ ├── service/impl/ # 核心业务实现 │ │ └── controller/ # REST API │ └── resources/ │ ├── application.yml │ └── schema.sql + data.sql │ ├── ai-python/ # Python AI 微服务 (FastAPI + sklearn) │ ├── requirements.txt │ └── app/ │ ├── main.py # FastAPI 入口 + /predict /recommend 接口 │ ├── predictor.py # 移动平均 + 周末因子销量预测 │ ├── java_client.py # 调 Java 拿真实销量(超时/降级策略集中在这里) │ └── recommender.py # 基于用户的 Jaccard 相似度协同过滤 │ ├── frontend-vue/ # Vue 3 前端 (双端合一) │ ├── package.json / vite.config.js │ └── src/ │ ├── main.js / App.vue │ ├── utils/request.js # axios 拦截器:Token + Result 解包 + 401 跳登录 │ ├── api/index.js # 所有后端接口函数 │ ├── stores/user.js # Pinia 用户 store(持久化) │ ├── router/index.js # 路由守卫:登录检查 + 管理员权限 │ └── views/ │ ├── Login / Register │ ├── mall/ # C 端:商品列表 / 详情 / 购物车 / 我的订单 │ └── admin/ # B 端:数据看板(ECharts) / 商品 CRUD / 订单管理 │ └── docs/ └── LEARN.md # 完整学习文档:架构 + DB + 全链路 + 19 个面试考点 ``` --- ## 🚀 快速启动 ### 前置条件 - **JDK 21+**(重要:Spring Boot 3.4.x 的 AspectJ 字节码织入需要 JDK 21,JDK 17 也可用,JDK 25 需要额外升级 AspectJ) - Maven 3.9+ - Python 3.10+ · Node.js 18+ ### Windows 环境特殊说明 > 如果只有 IntelliJ IDEA,自带的 JBR (JetBrains Runtime) 是 JDK 25,无法直接运行。需要单独安装 **JDK 21**(推荐 Microsoft Build 或 Eclipse Temurin),然后设置 `JAVA_HOME`: > ```powershell > $env:JAVA_HOME = "C:\tools\jdk-21.0.4+7" # 替换为你的安装路径 > $env:MAVEN_HOME = "C:\Program Files\JetBrains\IntelliJ IDEA 2026.2.4\plugins\maven-plugin\lib\maven3" > $env:PATH = "$env:JAVA_HOME\bin;$env:MAVEN_HOME\bin;$env:PATH" > ``` > 同样,Node.js 和 Python 如果没装,推荐用 winget 或下载 zip 解压到 `C:\tools` 后手动加到 PATH。 ### 环境变量(可选,部署必看) | 变量 | 默认值 | 作用 | |---|---|---| | `FRESHGO_JWT_SECRET` | 空 | JWT 签名密钥。**不配置时每次启动随机生成,重启后所有 Token 失效(需重新登录)**;生产必须显式设置 | | `FRESHGO_CORS_ORIGINS` | `http://localhost:5173,http://127.0.0.1:5173` | 允许跨域的前端来源,逗号分隔 | | `H2_CONSOLE_ENABLED` | `false` | 是否开启 H2 控制台。仅本机调试用,开启后还需把 `/api/h2-console` 临时加回 `JwtAuthFilter` 白名单 | | `AI_CORS_ORIGINS` | `http://localhost:5173,http://127.0.0.1:5173` | Python AI 服务允许的跨域来源 | | `FRESHGO_INTERNAL_KEY` | 空 | 内部调用密钥。`/api/public/user-interactions` 含全站用户购买记录,默认只允许本机回环调用;AI 服务与 Java 不在同一台机器时,两边配置同一个值,Python 会自动带 `X-Internal-Key` 请求头 | ```powershell # 让本地重启后不用反复登录 $env:FRESHGO_JWT_SECRET = "换成你自己的随机长字符串" ``` ### 1. 启动 Java 后端(端口 8080) ```bash cd backend-java mvn spring-boot:run ``` > H2 内存库零依赖启动。Web 控制台默认**关闭**(它能在无鉴权的情况下执行任意 SQL)。 > 本机想查表:设置 `H2_CONSOLE_ENABLED=true`,并把 `/api/h2-console` 临时加回 `JwtAuthFilter` 白名单 > 想切 MySQL?把 `application.yml` 里注释好的 MySQL 配置打开,改 `DbType.H2` → `DbType.MYSQL` 即可 ### 2. 启动 Python AI 服务(端口 8100,可选) ```bash cd ai-python pip install -r requirements.txt python -m app.main ``` > Swagger UI:`http://localhost:8100/docs` > Java 没它也能跑:预测接口会返回 `dataSource=unavailable`,看板显示「AI 服务不可用」标签,主业务不受影响 ### 3. 启动 Vue 前端(端口 5173) ```bash cd frontend-vue npm install npm run dev ``` > 浏览器打开 `http://localhost:5173` ### 演示账号(自动初始化在 `data.sql`) | 用户名 | 密码 | 角色 | 能做什么 | |---|---|---|---| | `admin` | `123456` | ADMIN | 进 `/admin/dashboard` 管理商品订单 + 看 AI 预测 | | `user01` | `123456` | USER | C 端浏览商品、加购物车、下单支付、评价 | | `user02` ~ `user05` | `123456` | USER | 协同过滤的"不同口味用户",让 AI 推荐能算出相似用户 | --- ## 🎯 核心亮点(面试加分项) ### Java 后端 - **统一返回体 + 全局异常**:所有 Controller 返回 `Result`,`@RestControllerAdvice` 拦截所有异常自动转响应 - **JWT 无状态鉴权**:ThreadLocal 存用户上下文 + 自定义 `@CurrentUser` 参数解析器 + `@RequireAdmin` AOP 切面 - **安全加固**:密钥走环境变量;`token_version` 让禁用账号/重置密码后旧 Token 立即失效;登录 5 次失败锁定 15 分钟;角色以数据库为准;管理端不返回密码哈希;H2 控制台默认关闭;`/public/user-interactions` 只允许本机内部调用(跨机需 `X-Internal-Key`) - **事务下单**:`@Transactional(rollbackFor = Exception.class)` 保证"扣库存 + 写订单 + 清购物车"同生共死 - **库存原子扣减**:`UPDATE product SET stock = stock - ? WHERE id = ? AND stock >= ?` 防并发超卖 - **降级策略**:Python 服务挂了不阻塞主业务,返回 `items=[]` + `dataSource=unavailable`,前端提示「AI 服务不可用」 - **完整业务闭环**:分类树形管理(父分类存在性与自引用校验)、用户禁用/重置密码、订单完成后的商品评价(一单一评,且商品必须在该订单明细中) ### Python AI - **时间序列预测**:移动平均 + 周末因子,小数据集比 ARIMA/LSTM 更稳更可解释 - **真实数据闭环**:预测前先调 Java 的 `/api/public/sales` 拿真实历史销量(按天聚合订单明细,顶级分类自动含子分类),不是拍脑袋的随机数 - **推荐也接真实数据**:调 Java 的 `/api/public/user-interactions` 拿真实用户购买记录算协同过滤,不是随机造的 50 个假用户 - **两级降级**:Java 不可达 / 真实样本不足 → 自动降级到模拟数据,AI 服务永远能出结果;响应里的 `dataSource` 字段标明本次用的是真实数据还是降级数据 - **预测契约**:`/admin/dashboard/predict` 返回 `{items, dataSource, meta}`,看板据此标注「真实订单数据 / 模拟数据 / AI 不可用」;`days` 在后端收敛到 1-60 - **协同过滤推荐**:基于用户的 Jaccard 相似度(二元购买向量下与余弦单调等价,计算更快),冷启动时热门商品兜底 ### Vue 前端 - **Pinia 持久化**:登录态存 localStorage,刷新不丢 - **路由守卫**:`beforeEach` 检查登录 + 管理员权限,支持 `redirect` 登录后回跳 - **ECharts 看板**:前端调 Java `/admin/dashboard/predict`,Java 再转发 Python,响应带 `dataSource` 标明数据来源 - **分类/用户/评价管理**:管理后台独立页面,C 端商品详情页含评价区 + AI「猜你喜欢」推荐 - **axios 拦截器链**:自动加 Token + 自动解包 Result + 401 自动跳登录 ### 系统架构 - **三服务松耦合**:Java → RestTemplate → Python,Vue → axios → Java - **AI 反向取数**:Python → httpx → Java `/api/public/sales` 拿真实销量训练模型(超时 5s + 两级降级,不拖慢主链路) - **跨域白名单**:`CorsConfig` 读 `freshgo.cors.allowed-origins`,默认只放行本地前端,不再通配所有来源(Python 侧同理) - **DB 零环境**:H2 `MODE=MySQL` 让同一份 SQL 兼容 H2 和 MySQL --- ## 📖 学习文档 完整学习材料在 [`docs/LEARN.md`](docs/LEARN.md),包含: 1. 系统架构设计与三端分工 2. 数据库 ER 图 + 表设计亮点 3. Java 后端全链路代码讲解(JWT/事务/原子扣库存/AOP) 4. Python AI 服务算法详解(预测 + 推荐) 5. Vue 前端 Composition API + Pinia + 路由守卫 6. 全链路请求流转图(以下单为例) 7. **19 个面试高频考点清单**(含代码位置对照) 8. Docker Compose / Redis / 单元测试等扩展方向 --- ## 🛠️ 技术栈速查 | 模块 | 技术 | 版本 | |---|---|---| | 后端语言 | Java | 21 | | 后端框架 | Spring Boot | 3.4.1 | | ORM | MyBatis-Plus | 3.5.5 | | 数据库 | H2(开发)/ MySQL(生产) | - | | 缓存 | Redis(可选,未启动不影响运行) | - | | 鉴权 | JWT (jjwt 0.12) | - | | 密码加密 | BCrypt | - | | 前端语言 | JavaScript | ES2023 | | 前端框架 | Vue 3 | 3.4 | | 构建工具 | Vite | 5.2 | | UI 组件库 | Element Plus | 2.7 | | 状态管理 | Pinia | 2.1 | | 图表 | ECharts | 5.5 | | HTTP 客户端 | axios | 1.7 | | AI 语言 | Python | 3.11 | | AI 框架 | FastAPI | 0.115 | | 机器学习 | scikit-learn | 1.5 | | 数据处理 | pandas / numpy | 2.2 / 1.26 | --- ## 📄 License MIT