# mall-admin

**Repository Path**: buxuhunao/mall-admin

## Basic Information

- **Project Name**: mall-admin
- **Description**: Mall 商城后台管理 - Vue3 + Vite + Element Plus，平台 + 商户双角色后台
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-06-16
- **Last Updated**: 2026-06-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Mall Admin

Mall 商城后台管理 - **平台 + 商户双角色一套代码**。

**Vue 3.5 + Vite 6 + Element Plus 2.9 + Pinia + ECharts 5 + xlsx**

对接 [mall-system](https://gitee.com/xrlnewman/mall-system) 后端 200+ API。

> **生产部署看这里**：[`docs/DEPLOY.md`](./docs/DEPLOY.md)

---

## 一、项目简介

运营后台。**平台**和**商户**两个角色一份代码维护，根据当前登录用户的 role 自动切换菜单 / 路由 / API 前缀。

- **平台管理员**（platform-admin）：审核商户、看运营大屏、管会员等级、平台报表、系统配置
- **商户管理员**（merchant-admin）：管自家商品、订单、库存、营销活动、提现

两套互不越权，路由守卫严格校验 role，axios 拦截器根据 role 自动加 `/admin/*` 或 `/merchant/*` 前缀。

---

## 二、双角色架构

| 身份 | 演示账号 | 路由前缀 | 自动 API 前缀 |
|---|---|---|---|
| 平台管理员 | `platform-admin` / `admin123` | `/platform/*` | `/admin/*` |
| 商户管理员 | `demo-merchant` / `admin123` | `/merchant/*` | `/merchant/*` |

**关键**：`utils/request.js` 根据 `user.role` 自动加前缀，同一份 Service 双端复用。**role 缺失时拒绝请求**（防越权）。**路由守卫严格校验** role 匹配。

> **生产上线第一件事就是改 admin123 默认密码**。

---

## 三、三仓库生态

| 仓库 | 角色 |
|---|---|
| [mall-system](https://gitee.com/xrlnewman/mall-system) | 后端 API |
| [mall-h5](https://gitee.com/xrlnewman/mall-h5) | C 端 H5 商城 |
| **mall-admin**（本仓库） | 平台 + 商户双角色后台 |

---

## 四、技术栈

| 类别 | 技术 | 版本 |
|---|---|---|
| 框架 | Vue | 3.5 |
| 构建 | Vite | 6.0 |
| UI | Element Plus | 2.9 |
| 状态 | Pinia | 2.2 |
| 路由 | Vue Router | 4.4 |
| HTTP | axios | 1.7 |
| 图表 | ECharts | 5.5（按需引入） |
| 时间 | dayjs | 1.11 |
| Excel | xlsx (SheetJS) | 0.18 |
| 自动导入 | unplugin-auto-import + unplugin-vue-components | 0.18 / 0.27 |

---

## 五、已升级页面清单

### 通用（2）
- Login.vue 双角色登录
- MainLayout.vue 顶部导航 + 侧栏 + 标签页 + 面包屑

### 平台端（13）

- Dashboard.vue 运营大屏（4 KPI + GMV 趋势 + 漏斗 + Top 排行 + 待办 + 30 秒自动刷新）
- Merchants.vue 商户管理（审核 / 启用封禁 / 新增）
- Withdrawals.vue 提现审核（二次确认 + 流水号必填）
- Settlements.vue 结算管理
- MemberLevels.vue 会员等级（V1-V6 + 全量重算）
- LogisticsCompanies.vue 物流公司（批量启停）
- SystemConfigs.vue 系统配置中心（7 大组 40+ 项 + 连通性测试）
- Brands.vue 品牌库
- Topics.vue 专题落地页（拖拽编辑器 + 10+ block 类型）
- PointsProducts.vue 积分商品
- Lottery.vue 抽奖配置（概率合计 = 1 实时校验）
- Disputes.vue 争议仲裁
- Reconciliations.vue 月度对账单
- Reports.vue 平台报表

### 商户端（17）

- Dashboard 商户概览
- Products.vue 商品列表（批量上下架）
- ProductEdit.vue 商品编辑（SKU 矩阵 / OSS 直传）
- Stocks.vue 库存（含调拨、盘点入口）
- MallOrders.vue 商城订单（发货 / 退款处理）
- MallOrderDetail.vue 订单详情
- BatchShipment.vue 批量发货（Excel 模板下载 + 导入）
- Promotions.vue 营销活动（3 合 1：拼团 / 秒杀 / 砍价）
- Coupons.vue 优惠券
- ShippingTemplates.vue 运费模板（含运费试算）
- ShopDecor.vue 店铺装修（拖拽编辑器 + 375px 预览）
- Withdraw.vue 我要提现
- Purchases.vue 采购单
- Sales.vue 销售单
- Warehouses.vue 仓库 CRUD
- Suppliers.vue 供应商 CRUD
- Customers.vue 客户 CRUD
- Reports.vue 商户报表（销售/库存/利润）

---

## 六、快速开始

```bash
git clone https://gitee.com/xrlnewman/mall-admin.git
cd mall-admin
npm install

cp .env.example .env
# 改 .env 里的 VITE_API_BASE 指向后端

npm run dev       # http://localhost:5174
npm run build     # 产物在 dist/
npm run preview   # 本地预览构建产物
```

演示账号：
- 平台：`platform-admin` / `admin123`
- 商户：`demo-merchant` / `admin123`

---

## 七、开发指南

### 加新页面

```
1. src/views/platform/Xxx.vue 或 merchant/Xxx.vue
2. src/router/index.js 加路由，meta.role 标 'platform' 或 'merchant'
3. 接口走 src/api/platform.js 或 merchant.js
4. 菜单走 stores/menu.js
```

### 接口约定

`src/utils/request.js`：
- 当前 user.role = `platform` → 自动加 `/admin/*` 前缀
- 当前 user.role = `merchant` → 自动加 `/merchant/*` 前缀
- role 为空 → **拒绝请求**（防越权，控制台报错提示开发者）
- 401 自动跳 Login + redirect 回填
- 422 字段错误自动提取首条到 ElMessage
- 5xx 全局 ElMessage error

### 路由守卫

`router.beforeEach`：
1. 检查 token，没有跳 Login
2. 检查 `meta.role` 与当前 user.role 匹配，不匹配跳 404
3. 设置标签页（已访问的页面缓存到 tabs store）

### ECharts 按需

`main.js` 已配按需：

```js
import * as echarts from 'echarts/core'
import { GridComponent, LegendComponent, TooltipComponent, TitleComponent } from 'echarts/components'
import { LineChart, BarChart, PieChart, FunnelChart } from 'echarts/charts'
import { CanvasRenderer } from 'echarts/renderers'

echarts.use([GridComponent, LegendComponent, TooltipComponent, TitleComponent,
             LineChart, BarChart, PieChart, FunnelChart, CanvasRenderer])
```

新加图表类型时记得在这里 `use()`，否则不渲染。

**ECharts 实例必须 `dispose()` 释放**（页面 unmounted 时），否则切页面后内存涨。

### Element Plus 自动按需

`vite.config.js` 已配 `unplugin-vue-components` 的 `ElementPlusResolver`，组件按需引入，不用 `import { ElButton }`。**自定义图标改 `@element-plus/icons-vue`**。

### Excel 模板下载 / 导入

`xlsx` 已封装：

```js
// 下载模板
import * as XLSX from 'xlsx'
const ws = XLSX.utils.aoa_to_sheet([['订单号','物流公司','运单号']])
const wb = XLSX.utils.book_new()
XLSX.utils.book_append_sheet(wb, ws, '批量发货模板')
XLSX.writeFile(wb, '批量发货模板.xlsx')

// 解析上传
const reader = new FileReader()
reader.onload = (e) => {
  const wb = XLSX.read(e.target.result, { type: 'binary' })
  const data = XLSX.utils.sheet_to_json(wb.Sheets[wb.SheetNames[0]])
  // data = [{ 订单号: 'xxx', 物流公司: '顺丰', 运单号: 'SF...' }, ...]
}
```

### 加菜单

`stores/menu.js` 里平台菜单和商户菜单分两个常量。新增项：

```js
{
  path: '/platform/xxx',
  name: 'PlatformXxx',
  meta: { title: '新页面', icon: 'Box', role: 'platform' }
}
```

UI 端会根据 role 自动过滤。

---

## 八、环境变量

`.env.example`：

```env
# 后端 API（dev 走 vite proxy，生产由 Nginx 反代）
VITE_API_BASE=http://localhost:8000
```

**生产**：

```env
VITE_API_BASE=https://api.example.com
```

Vite 的 `VITE_*` 变量在 `npm run build` 时编译进产物，每次改完都要重新 build。

---

## 九、项目结构

```
src/
├── api/
│   ├── index.js              # 通用
│   ├── platform.js           # 平台 API
│   ├── merchant.js           # 商户 API
│   └── common.js
├── utils/
│   ├── request.js            # axios + role 自动前缀 + 越权防护
│   └── permissions.js
├── stores/
│   ├── user.js
│   ├── menu.js               # 平台 / 商户两套菜单
│   └── tabs.js               # 标签页
├── router/index.js           # 30+ 路由 + role 守卫
├── layouts/
│   └── MainLayout.vue
├── views/
│   ├── Login.vue
│   ├── Dashboard.vue
│   ├── platform/             # 13 个平台页
│   └── merchant/             # 17 个商户页
└── main.js                   # Element Plus + ECharts 按需
```

---

## 十、版本历史

| 版本 | 更新 |
|---|---|
| v0.1.0 | 双角色架构 + 16 基础页面 |
| v0.2.0 | 运营大屏 + 系统配置中心 + 批量发货 |
| v0.3.0 | 会员等级 + 物流公司 + 营销活动配置 + 优惠券 |
| **v0.4.0** | 积分商品 + 抽奖配置 + 专题编辑器 + 店铺装修拖拽编辑器 + 双角色越权防护 |

---

## License

MIT © [xrlnewman](https://gitee.com/xrlnewman)