# eh-shop

**Repository Path**: MISSMYSEIF/eh-shop

## Basic Information

- **Project Name**: eh-shop
- **Description**: 一款前后端分离的多端购物商城平台
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-10
- **Last Updated**: 2026-09-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 🛒 EH-Shop 多端购物商城

> 一款前后端分离的类淘宝多端购物商城平台，支持 SaaS 多租户架构，覆盖 **Web、iOS、Android、PC、HarmonyOS、微信小程序、支付宝小程序** 七大终端。

[English Version](README.en.md) | [📚 文档中心](docs/README.md)

---

## ✨ 核心特性

- 🏢 **SaaS 多租户**：分库隔离（大型租户）+ 字段隔离（小型租户）混合策略
- 🔄 **多端统一**：Monorepo 共享核心包，统一 API/Bridge 接口，各端差异化 UI
- 💳 **支付安全**：策略模式多渠道（支付宝/微信/银行卡）、RSA2 签名验签、幂等回调
- ⚡ **高并发秒杀**：Redis Lua 原子扣减 + 限购联合检查 + MQ 异步下单
- 📡 **事件驱动**：RabbitMQ 消息总线串联全部业务事件
- 🗄️ **多数据库**：默认 SQLite 开发，支持 MySQL/PostgreSQL
- 🔐 **全链路安全**：JWT 双 Token + RBAC + 数据加密脱敏 + 审计日志
- 🎭 **实名认证**：身份证实名认证 + 审核流程
- ⭐ **积分/会员**：积分累积 + 会员等级自动升级（普通/银卡/金卡/钻石）
- 👥 **拼团购**：开团/参团/成团自动检测 + 参团人数实时回减
- 📺 **直播带货**：直播间管理 + 商品挂载 + 弹幕互动 + 点赞
- 📊 **商家看板**：实时销售统计 + 7天趋势
- 📈 **销量数据闭环**：支付成功自动回写商品销量（详情/排序/推荐真实可用）
- 🛡️ **价格保护**：购买后7天内商品降价可申请差价退款
- 📝 **评价闭环**：订单收货后在线发表评价/晒单（星级+文字+多图），支持追加评价
- 📊 **评价统计**：商品好评率/平均分/星级分布聚合展示
- 🔄 **库存双写一致**：商家改库存同步刷新 Redis，与 Lua 原子扣减/对账任务闭环
- ⏱️ **秒杀库存防泄漏**：超时未支付/退款自动回补活动可售名额
- 🔍 **商品对比**：最多5个商品参数并排对比
- 🎁 **积分商城**：积分兑换优惠券/商品
- ⏰ **定时任务**：价格保护自动过期 + 异常订单检测
- 💳 **银行卡支付**：支付宝/微信/银行卡多渠道支付
- 📊 **退款进度跟踪**：退款全流程时间线可视化
- 🎫 **优惠券叠加**：满减券+折扣券可叠加使用
- 🧾 **电子发票**：对已支付订单申请开具电子发票，支持个人/企业抬头
- 📉 **库存预警**：低库存自动通知商家
- 📍 **浏览足迹**：记录用户浏览历史
- ⭐ **每日签到**：连续签到积分翻倍
- 🎬 **商品视频**：商品详情页支持短视频展示（无视频时回退图片轮播）
- 🤖 **智能客服**：支持真实 LLM 接入（OpenAI 兼容，DeepSeek/通义/Ollama），LLM 不可用自动回退内置知识库

---

## 🏗️ 技术架构

### 后端 — Spring Cloud Alibaba 微服务

| 服务 | 端口 | 说明 |
|------|------|------|
| eh-gateway | 8080 | API网关（租户识别/多端标识/JWT鉴权/Sentinel限流） |
| eh-user | 8081 | 用户服务（注册/登录/OAuth/地址管理） |
| eh-product | 8082 | 商品服务（SPU/SKU/类目/品牌/库存管理） |
| eh-search | 8083 | 搜索服务（ES全文检索/索引同步/降级） |
| eh-cart | 8084 | 购物车服务（Redis Hash/跨端同步） |
| eh-shop-service | 8085 | 店铺服务（入驻/审核/评分） |
| eh-order | 8086 | 订单服务（状态机/Seata分布式事务/拆单/退款） |
| eh-pay | 8087 | 支付服务（策略模式/幂等回调/对账） |
| eh-promotion | 8088 | 营销服务（优惠券/秒杀/Lua原子扣减） |
| eh-review | 8089 | 评价服务 |
| eh-notify | 8090 | 通知服务（站内信/推送/短信） |

**核心技术栈**：Java 17 + Spring Boot 3.2 + Spring Cloud 2023 + Spring Cloud Alibaba 2023 + MyBatis-Plus + Sa-Token + RabbitMQ + Redis + Nacos

### 前端 — Vue 3 Monorepo 多端

| 端 | 目录 | 技术栈 |
|----|------|--------|
| 共享核心包 | packages/core | Vue 3 + TypeScript + Pinia + Axios |
| Web 端 | packages/web | Vue 3 + Element Plus + Vite |
| 小程序端 | packages/miniprogram | Taro 3 + Vue 3（微信/支付宝） |
| Flutter 移动端 | packages/mobile | Flutter + Riverpod + GoRouter（iOS/Android） |
| Electron PC 端 | packages/pc | Electron + Vue 3（主进程+渲染进程） |
| HarmonyOS 端 | packages/harmony | ArkUI + ArkTS + @ohos.* |

#### 多端功能覆盖矩阵

> 下表说明各端对核心业务功能的覆盖情况（✅ 已实现 / ➖ 不适用，如 Web 自有商家/管理后台）。各端均直连同一套后端微服务 API，功能一一对应。

| 业务功能 | Web | PC | 小程序 | HarmonyOS | Flutter 移动 |
|---------|:---:|:--:|:-----:|:---------:|:----------:|
| 首页 / 搜索 | ✅ | ✅ | ✅ | ✅ | ✅ |
| 商品详情 | ✅ | ✅ | ✅ | ✅ | ✅ |
| 购物车 | ✅ | ✅ | ✅ | ✅ | ✅ |
| 下单 / 支付 | ✅ | ✅ | ✅ | ✅ | ✅ |
| 订单列表 / 详情 | ✅ | ✅ | ✅ | ✅ | ✅ |
| 优惠券 | ✅ | ✅ | ✅ | ✅ | ✅ |
| 秒杀 | ✅ | ✅ | ✅ | ✅ | ✅ |
| 拼团 | ✅ | ✅ | ✅ | ✅ | ✅ |
| 积分中心 / 积分商城 | ✅ | ✅ | ✅ | ✅ | ✅ |
| 个人中心 | ✅ | ✅ | ✅ | ✅ | ✅ |
| 地址管理 | ✅ | ✅ | ✅ | ✅ | ✅ |
| 收藏 / 足迹 | ✅ | ✅ | ✅ | ✅ | ✅ |
| 我的评价 | ✅ | ✅ | ✅ | ✅ | ✅ |
| 售后 / 退款 | ✅ | ✅ | ✅ | ✅ | ✅ |
| 发票 | ✅ | ✅ | ✅ | ✅ | ✅ |
| 实名认证 | ✅ | ✅ | ✅ | ✅ | ✅ |
| 邀请有礼 | ✅ | ✅ | ✅ | ✅ | ✅ |
| 消息通知 | ✅ | ✅ | ✅ | ✅ | ✅ |
| **价格保护** | ✅ | ✅ | ✅ | ✅ | ✅ |
| 商品对比 | ✅ | ✅ | ✅ | ✅ | ✅ |
| 直播 | ✅ | ✅ | ✅ | ✅ | ✅ |
| 在线客服 | ✅ | ✅ | ✅ | ✅ | ✅ |
| 商家管理端 | ✅ | ➖ | ➖ | ➖ | ➖ |
| 平台管理端 | ✅ | ➖ | ➖ | ➖ | ➖ |

> 说明：**商品对比、直播、在线客服、价格保护** 已在 Web、PC、小程序、HarmonyOS、Flutter 五端全面对齐；**商品详情视频展示**、**直播间弹幕+点赞**、**客服 AI 来源标识** 亦已对齐到五端。「商家/平台管理端」为 Web 端特有的运营后台，其余端不适用。

---

## 📁 项目结构

```
eh-shop/
├── backend/                          # 后端微服务
│   ├── eh-common/                    # 公共模块
│   ├── eh-gateway/                   # API网关
│   ├── eh-user/                      # 用户服务
│   ├── eh-product/                   # 商品服务
│   ├── eh-search/                    # 搜索服务
│   ├── eh-cart/                      # 购物车服务
│   ├── eh-shop-service/              # 店铺服务
│   ├── eh-order/                     # 订单服务
│   ├── eh-pay/                       # 支付服务
│   ├── eh-promotion/                 # 营销服务
│   ├── eh-review/                    # 评价服务
│   └── eh-notify/                    # 通知服务
├── frontend/                         # 前端多端
│   ├── packages/
│   │   ├── core/                     # 共享核心包
│   │   ├── web/                      # Web端
│   │   ├── miniprogram/              # 小程序端
│   │   ├── mobile/                   # Flutter移动端
│   │   ├── pc/                       # Electron PC端
│   │   └── harmony/                  # HarmonyOS端
│   ├── pnpm-workspace.yaml
│   └── package.json
├── tests/                           # Python 测试脚本
└── LICENSE                          # MIT 开源协议
```

---

## 🚀 快速开始

### 环境要求

| 工具 | 版本 |
|------|------|
| JDK | 17+ |
| Maven | 3.8+ |
| Node.js | 18+ |
| pnpm | 8+ |
| Python | 3.8+ |

### Windows 一键启动

```bash
# 启动核心服务
start-all.bat

# 停止所有服务
stop-all.bat
```

### 后端启动

```bash
# 1. 编译
cd backend
mvn clean compile

# 2. 启动服务（默认使用 SQLite，无需额外数据库）
java -jar eh-gateway/target/eh-gateway-1.0.0-SNAPSHOT.jar
java -jar eh-user/target/eh-user-1.0.0-SNAPSHOT.jar
# ... 其他服务同理
```

### 前端启动

```bash
cd frontend
pnpm install

# Web端开发
pnpm dev:web
```

### 默认登录账号

| 角色 | 用户名 | 密码 |
|------|--------|------|
| 管理员 | admin | admin123 |

---

## 🧪 运行测试

项目包含 **Python 集成测试**（API 级）和 **Java 单元测试**（模块级）两套测试体系。

### Python 集成测试

```bash
cd tests
pip install -r requirements.txt

# 运行全部测试
python3 -m pytest -v

# 运行指定模块测试
python3 run_tests.py auth product order

# 运行新功能测试
python3 run_tests.py features

# 运行增强功能测试
python3 run_tests.py improved

# 运行核心交易链路测试（秒杀/退款/拼团/物流/直播/RBAC/导出/看板）
python3 run_tests.py flows
```

### Java 单元测试

覆盖全部后端模块（11 个微服务 + 6 个 common 子模块），包括工具类、枚举、模型、状态机、服务逻辑等。

```bash
cd backend
mvn test

# 运行单个模块
mvn test -pl eh-order

# 运行单个测试类
mvn test -pl eh-cart -Dtest=CartServiceTest
```

### 前端 vitest 单元测试

- **@ehshop/core** 共享包内置 **157 个 vitest 用例**（19 个测试文件），覆盖工具函数、状态管理、composable、API 客户端等核心模块。
- **@ehshop/web** Web 端内置 **32 个 vitest 用例**（5 个测试文件），覆盖省市区级联数据、图片懒加载指令、价格展示/倒计时/空状态等组件逻辑。

```bash
cd frontend

# 运行 core 包全部单测
pnpm --filter @ehshop/core test

# 运行 web 端全部单测
pnpm --filter @ehshop/web test
```

**PC 端（Electron）** 渲染层可通过 `cd frontend/packages/pc && npx vite build --config vite.renderer.config.ts` 进行构建校验。


### 测试覆盖范围

- **Python 集成测试**：认证、用户、商品、购物车、订单、支付、营销、评价、通知、搜索、实名认证、积分、拼团、直播、秒杀、推荐、购物车同步、RBAC、批量操作、数据导出
- **Java 单元测试**：全部 17 个后端模块（11 个微服务 + 6 个 common 子模块）的工具类、枚举、模型、DTO/VO、状态流转、多租户处理器、消息序列化、支付策略、MQ消费者、定时任务等
- **前端 vitest 单元测试**：format/validate/token/constants、cart-store/user-store/order-store、use-auth/use-cart/use-order/use-product/use-search/use-payment/use-favorites/use-points-mall/use-price-protection/use-recommendation/use-notification 等 composable；Web 端 regions 省市区数据、lazyLoad 指令、PriceDisplay/CountdownTimer/EmptyState 组件

---

## 📚 文档

- [📖 文档中心](docs/README.md)
- [🏗️ 架构设计](docs/architecture/architecture.md)
- [🏁 快速上手](docs/development/getting-started.md)
- [💻 开发指南](docs/development/development-guide.md)
- [🔌 第三方服务对接](docs/api/third-party-integration.md)
- [📡 API 接口规范](docs/api/api-spec.md)
- [🚢 部署运维指南](docs/deployment/deployment-guide.md)
- [🗄️ 数据库配置指南](docs/deployment/database-guide.md)
- [📋 变更日志](docs/changelog/CHANGELOG.md)

---

## 🛠️ 数据库配置

项目默认使用 **SQLite**（无需安装，零配置），支持切换到 MySQL、PostgreSQL：

```yaml
# SQLite（默认）
spring:
  datasource:
    driver-class-name: org.sqlite.JDBC
    url: jdbc:sqlite:eh-shop.db

# MySQL
spring:
  datasource:
    driver-class-name: com.mysql.cj.jdbc.Driver
    url: jdbc:mysql://127.0.0.1:3306/eh_shop?useUnicode=true&characterEncoding=utf-8&useSSL=false&serverTimezone=Asia/Shanghai
    username: root
    password: root
```

详见 [数据库配置指南](docs/deployment/database-guide.md)。

---

## 🤝 贡献指南

1. Fork 本仓库
2. 创建功能分支 (`git checkout -b feature/xxx`)
3. 提交代码 (`git commit -m "feat: 添加xxx功能"`)
4. 推送分支 (`git push origin feature/xxx`)
5. 创建 Pull Request

---

## 📄 许可证

安装后执行：File → Invalidate Caches / Restart

## License

本项目使用 [MIT License](LICENSE)。