# xshop

**Repository Path**: belovedLYC/xshop

## Basic Information

- **Project Name**: xshop
- **Description**: 基于v3+ts的前后端分离轻量在线购物商城
- **Primary Language**: TypeScript
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: http://1.12.229.67:3000
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2025-09-11
- **Last Updated**: 2026-04-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 🛒 在线购物商城

<div align="center">
  <p>基于 Vue 3 + TypeScript + Vite + Element Plus + Pinia 构建的现代化在线购物商城全栈前端项目</p>
  <p>包含用户端（C端）和管理后台（B端）双端系统</p>
</div>

## ✨ 特性

- 🚀 **最新技术栈**：Vue 3.3+、TypeScript 5.3+、Vite 7+、Element Plus 2.4+、Pinia 2.1+
- 🏪 **双端架构**：前台购物商城 + 后台管理系统，独立部署也可合并运行
- 💬 **实时通信**：WebSocket 实现客服聊天、消息推送、订单实时通知
- 🔐 **权限管理**：基于角色的菜单权限、按钮权限控制
- 📊 **数据可视化**：ECharts 图表展示销售数据、用户统计
- 🎨 **主题定制**：支持暗色/亮色模式切换、主题色自定义
- 📱 **响应式设计**：适配桌面端、平板端
- 🧩 **组件自动导入**：自动导入 Vue、VueRouter、Pinia、Element Plus 等常用 API
- 🎯 **TypeScript**：完整的类型定义，提供更好的开发体验
- 🌍 **多环境支持**：开发、测试、生产环境配置

## 📦 技术栈

| 类别             | 技术                       |
| ---------------- | -------------------------- |
| **框架**         | Vue 3.3+ (Composition API) |
| **语言**         | TypeScript 5.3+            |
| **构建工具**     | Vite 7+                    |
| **状态管理**     | Pinia 2.1+                 |
| **路由**         | Vue Router 4.2+            |
| **UI 框架**      | Element Plus 2.4+          |
| **CSS 预处理器** | Sass/SCSS                  |
| **HTTP 客户端**  | Axios 1.6+                 |
| **实时通信**     | WebSocket (原生 API)       |
| **图表**         | ECharts                    |
| **工具库**       | @vueuse/core, dayjs        |

## 📁 项目结构

```
x-online-shopping-mall/
├── 📁 src/                    # 前台 - 用户端（C端）
│   ├── api/                   # API 接口封装
│   ├── assets/                # 静态资源（图片、样式）
│   ├── components/            # 公共组件
│   ├── constants/             # 常量定义
│   ├── directives/            # 自定义指令
│   ├── router/                # 路由配置
│   ├── store/                 # Pinia 状态管理
│   │   ├── user.ts            # 用户状态
│   │   ├── chat.ts            # 聊天/WebSocket 状态
│   │   └── cart.ts            # 购物车状态
│   ├── types/                 # TypeScript 类型定义
│   ├── utils/                 # 工具函数
│   │   ├── websocket.ts       # WebSocket 封装
│   │   └── format.ts          # 日期/时间格式化
│   ├── views/                 # 页面视图
│   │   ├── home/              # 首页
│   │   ├── product/           # 商品详情
│   │   ├── cart/              # 购物车
│   │   ├── order/             # 订单
│   │   ├── user/              # 用户中心
│   │   └── chat/              # 客服聊天
│   ├── App.vue                # 根组件
│   └── main.ts                # 入口文件
│
├── 📁 admin/src/              # 后台 - 管理端（B端）
│   ├── api/                   # API 接口封装
│   ├── assets/                # 静态资源
│   ├── components/            # 公共组件
│   │   ├── ProTable/          # 高级表格组件
│   │   └── Upload/            # 图片上传组件
│   ├── layouts/               # 布局组件
│   │   ├── components/        # 布局子组件
│   │   │   └── Header/        # 顶部导航
│   │   │       └── components/
│   │   │           └── Message.vue  # 消息通知组件
│   ├── routers/               # 路由配置
│   ├── stores/                # Pinia 状态管理
│   │   └── modules/
│   │       ├── message.ts     # 消息/WebSocket 状态
│   │       └── auth.ts        # 认证状态
│   ├── utils/                 # 工具函数
│   │   ├── websocket.ts       # WebSocket 封装
│   │   └── format.ts          # 日期/时间格式化
│   ├── views/                 # 页面视图
│   │   ├── dashboard/         # 数据看板
│   │   ├── dataScreen/        # 数据大屏
│   │   ├── product/           # 商品管理
│   │   ├── order/             # 订单管理
│   │   ├── user/              # 用户管理
│   │   ├── message/           # 消息管理
│   │   │   └── chat/          # 客服聊天
│   │   └── marketing/         # 营销管理
│   ├── App.vue                # 根组件
│   └── main.ts                # 入口文件
│
├── 📁 .vscode/                # VSCode 配置
├── 📁 vite/                   # Vite 插件配置
├── .env                       # 环境变量
├── .env.development           # 开发环境变量
├── .env.production            # 生产环境变量
├── .env.test                  # 测试环境变量
├── vite.config.ts             # Vite 配置
├── tsconfig.json              # TypeScript 配置
├── package.json               # 项目依赖
└── README.md                  # 项目文档
```

## 🚀 快速开始

### 环境要求

- Node.js >= 18.0.0
- npm >= 9.0.0 或 pnpm >= 8.0.0

### 安装依赖

```bash
npm install
# 或
pnpm install
```

### 开发环境

```bash
# 启动前台（用户端）- 端口 3000
npm run dev

# 访问前台：http://localhost:3000
# 访问后台：http://localhost:3000/admin
```

### 构建

```bash
# 测试环境构建
npm run build:test

# 生产环境构建
npm run build:prod

# 预览构建结果
npm run preview
```

### 代码规范

```bash
# ESLint 检查
npm run lint

# Prettier 格式化
npm run format

# Stylelint 样式检查
npm run lint:stylelint

# TypeScript 类型检查
npm run type-check
```

## 🌍 环境变量

项目支持多环境配置，通过不同的 `.env` 文件管理：

| 文件               | 说明         |
| ------------------ | ------------ |
| `.env`             | 公共环境变量 |
| `.env.development` | 开发环境     |
| `.env.test`        | 测试环境     |
| `.env.production`  | 生产环境     |

### 主要环境变量

```bash
# 应用标题
VITE_APP_TITLE=在线购物商城

# 端口号
VITE_PORT=3000

# API 基础路径
VITE_API_BASE_URL=/api

# API 目标地址
VITE_API_TARGET_URL=http://localhost:8080

# WebSocket 地址
VITE_WS_URL=ws://localhost:8080

# 是否删除 console
VITE_DROP_CONSOLE=false

# 是否开启 Gzip 压缩
VITE_BUILD_GZIP=false
```

## 📝 Git 提交规范

项目使用 Commitlint 规范 Git 提交信息，格式如下：

```
<type>: <subject>
```

**Type 类型：**

| 类型       | 说明                             |
| ---------- | -------------------------------- |
| `feat`     | 新功能                           |
| `fix`      | 修复 bug                         |
| `docs`     | 文档更新                         |
| `style`    | 代码格式（不影响代码运行的变动） |
| `refactor` | 重构                             |
| `perf`     | 性能优化                         |
| `test`     | 增加测试                         |
| `chore`    | 构建过程或辅助工具的变动         |
| `revert`   | 回退                             |
| `build`    | 打包                             |

**示例：**

```bash
git commit -m "feat: 添加用户登录功能"
git commit -m "fix: 修复购物车数量显示错误"
git commit -m "refactor: 优化商品列表查询性能"
```

## 🛠️ 核心功能模块

### 前台（C端）

| 模块         | 功能                                     |
| ------------ | ---------------------------------------- |
| **首页**     | 商品分类、轮播图、热销商品、新品推荐     |
| **商品**     | 商品列表、商品详情、规格选择、商品评价   |
| **购物车**   | 添加商品、数量修改、批量结算             |
| **订单**     | 下单、支付、订单列表、订单详情、物流跟踪 |
| **用户中心** | 个人信息、地址管理、我的订单、我的收藏   |
| **客服聊天** | WebSocket 实时客服对话                   |

### 后台（B端）

| 模块         | 功能                         |
| ------------ | ---------------------------- |
| **数据中心** | 数据看板、数据大屏           |
| **商品管理** | 商品列表、商品分类、SKU 管理 |
| **订单管理** | 订单列表、退款管理           |
| **用户管理** | 用户列表、会员等级、用户详情 |
| **营销管理** | 优惠券管理、轮播图管理       |
| **消息管理** | 客服会话、工单列表、公告管理 |
| **系统设置** | 主题设置、布局配置           |

## 💬 WebSocket 实时通信

项目使用原生 WebSocket 实现实时通信功能：

- **前台**：用户与客服实时对话
- **后台**：全局消息通知、实时推送新消息提醒

WebSocket 封装在 `src/utils/websocket.ts` 和 `admin/src/utils/websocket.ts`，支持：

- 自动重连（指数退避算法）
- 心跳保活
- 连接状态监听
- 断线恢复

## 💡 VSCode 推荐插件

项目已配置推荐插件列表（`.vscode/extensions.json`）：

- Vue Language Features (Volar)
- TypeScript Vue Plugin (Volar)
- ESLint
- Prettier
- Stylelint
- EditorConfig

## 📄 许可证

[MIT](LICENSE)

---

⭐ 如果这个项目对你有帮助，请给它一个星标！