backmanagerweb/README.md

# 🍦 蜜雪冰城管理系统 (Mixue Management System)

**蜜雪冰城管理系统**是一个面向企业内部的 Web 管理后台，基于 Vue 3 + Element Plus 构建。用于管理客户、合同、售后、产品、供应商、员工及系统用户等核心业务模块，为蜜雪冰城品牌运营提供一体化管理支持。

> 前端项目地址：`backmanagerweb`  
> 后端项目地址：`backmanager-server`（Express + MySQL）

---

## 目录

- [功能概览](#功能概览)
- [技术栈](#技术栈)
- [快速开始](#快速开始)
- [项目结构](#项目结构)
- [页面与模块说明](#页面与模块说明)
- [权限体系](#权限体系)
- [与后端 API 的关系](#与后端-api-的关系)
- [开发命令](#开发命令)
- [构建部署](#构建部署)

---

## 功能概览

| 模块 | 说明 | 权限标识 |
|------|------|---------|
| 🏠 **首页** | 欢迎页，展示蜜雪冰城品牌视频与雪王简介 | 登录即可访问 |
| 👥 **客户管理** | 客户信息 CRUD、客户列表搜索、详情查看 | `customer:read` / `customer:create` / `customer:update` / `customer:delete` |
| 📄 **合同管理** | 合同 CRUD，关联客户，支持金额与签约日期管理 | `contract:read` / `contract:*` |
| 🔧 **售后管理** | 售后服务记录管理 | `after_sale:read` / `after_sale:*` |
| 🧋 **产品管理** | 产品（饮品）信息管理 | `product:read` / `product:*` |
| 📦 **供应商管理** | 供应商信息管理 | `supplier:read` / `supplier:*` |
| 👤 **员工管理** | 企业员工信息（花名册）管理，含薪资可见范围控制 | `employee:read` / `employee:create` / `employee:update` / `employee:delete` |
| 🔐 **用户管理** | 系统登录用户管理（管理员专有模块） | `user:manage` |

---

## 技术栈

| 技术 | 版本 | 用途 |
|------|------|------|
| **Vue 3** | ^3.5 | 前端框架（Composition API + `<script setup>`） |
| **Vite** | ^8.0 | 构建工具 |
| **Element Plus** | ^2.14 | UI 组件库 |
| **@element-plus/icons-vue** | ^2.3 | 图标库 |
| **Vue Router 4** | ^4.x | 前端路由 |
| **Axios** | ^1.18 | HTTP 请求库 |
| **element-china-area-data** | ^5.0 | 中国省市区数据（合同模块使用） |

---

## 快速开始

### 前置条件

- Node.js >= 18
- 后端项目 `backmanager-server` 已启动运行（默认端口 3000）

### 安装与运行

```bash
# 1. 克隆项目
git clone <repo-url>
cd backmanagerweb

# 2. 安装依赖
npm install

# 3. 启动开发服务器（默认端口 5173）
npm run dev
```

浏览器打开 `http://localhost:5173` 即可访问。

> 开发环境下，`/api` 请求会自动代理到 `http://localhost:3000`（参见 `vite.config.js`）。

### 登录

项目默认对接后端认证系统，使用后端预置的管理员账号登录：

| 用户名 | 密码 | 角色 |
|--------|------|------|
| `admin` | 请联系管理员 | 信息技术部 · 超管 |

具体账号信息由后端 `db.js` 中的种子数据定义。

---

## 项目结构

```
backmanagerweb/
├── public/                          # 静态资源
│   ├── logo.png                     # 系统 Logo
│   ├── mixue.png                    # 雪王头像（首页）
│   ├── 首页顶图.mp4                 # 首页视频横幅
│   └── 登陆界面背景.mp4             # 登录页背景视频
├── src/
│   ├── api/                         # API 请求层
│   │   ├── request.js               # Axios 实例与响应拦截器
│   │   ├── employee.js              # 员工相关 API
│   │   ├── user.js                  # 用户相关 API
│   │   ├── customer.js              # 客户相关 API
│   │   ├── contract.js              # 合同相关 API
│   │   ├── service.js               # 售后相关 API
│   │   ├── products.js              # 产品相关 API
│   │   ├── suppliers.js             # 供应商相关 API
│   │   └── mock/                    # Mock 数据（开发参考）
│   ├── components/                  # 页面组件
│   │   ├── Login.vue                # 登录页
│   │   ├── panel.vue                # 主布局（顶栏 + 侧栏 + 内容区）
│   │   ├── home.vue                 # 首页
│   │   ├── employee.vue             # 员工管理
│   │   ├── user.vue                 # 用户管理
│   │   ├── customer.vue             # 客户管理
│   │   ├── contract.vue             # 合同管理
│   │   ├── service.vue              # 售后管理
│   │   ├── products.vue             # 产品管理
│   │   └── supplier.vue             # 供应商管理
│   ├── constants/                   # 常量定义
│   │   └── departments.js           # 部门列表常量
│   ├── store/
│   │   └── user.js                  # 用户状态管理（登录/登出/权限检查）
│   ├── utils/
│   │   └── date.js                  # 日期格式化工具
│   ├── router.js                    # 路由配置
│   ├── main.js                      # 应用入口
│   ├── App.vue                      # 根组件
│   └── style.css                    # 全局样式
├── index.html                       # HTML 入口
├── vite.config.js                   # Vite 配置
├── package.json
└── README.md
```

---

## 页面与模块说明

### 登录页 (`Login.vue`)

- 背景播放品牌视频，半透明遮罩，右侧展示登录卡片
- 支持用户名/密码表单验证
- "记住我" 复选框（当前为前端状态，可扩展持久化）
- 登录成功后跳转到 `/panel/home`

### 主布局 (`panel.vue`)

- **顶栏**：Logo + 系统名称 + 当前用户信息（姓名 / 部门）+ 退出登录按钮
- **侧栏**：根据当前用户的权限动态展示可访问的菜单项（通过 `hasPermission` 控制）
- **内容区**：嵌套 `<router-view>` 渲染子页面
- 侧栏可收缩

### 首页 (`home.vue`)

- 品牌视频横幅 + 雪王简介卡片
- 展示雪王的基本信息（生日、性格、职位等）

### 员工管理 (`employee.vue`)

- **列表**：支持按 ID、姓名、部门搜索，按在职/离职状态筛选
- **分页**：服务端分页（向后端发送 `page`/`pageSize` 参数）
- **CRUD**：新增、编辑、删除员工信息
- **薪资可见范围**：仅"总经理办公室"和"财务部"用户可见薪资字段
- **创建用户联动**：新增员工后可选择同步创建系统用户
- **部门**：部门列表与后端数据库 6 个部门保持一致

### 用户管理 (`user.vue`)

- **权限**：仅 `user:manage` 权限的用户（信息技术部管理员）可访问
- **列表**：支持按用户名、真实姓名、ID 搜索，按部门/状态筛选
- **分页**：服务端分页
- **CRUD**：系统用户的创建、编辑、启用/禁用、删除
- **关联员工**：创建用户时可关联已有员工（员工下拉列表使用 `/api/employees/simple` 接口，仅展示在职员工基本信息）
- **安全保护**：后端禁止删除自身账号或最后一个超级管理员

### 其它模块

| 模块 | 关键特性 |
|------|---------|
| **客户管理** | 客户信息维护，支持按名称/联系方式搜索 |
| **合同管理** | 合同信息管理，关联客户，支持省市区选择 |
| **售后管理** | 售后服务记录管理 |
| **产品管理** | 产品（饮品）信息管理 |
| **供应商管理** | 供应商基本信息管理 |

---

## 权限体系

### 权限模型

系统采用**基于资源+操作的权限模型**，每个权限表示为 `resource:action` 格式的字符串。用户的权限列表在登录时从后端获取，存储在 Vue Store 中。

### 资源与操作

| 资源 | 操作 | 说明 |
|------|------|------|
| `customer` | `read` / `create` / `update` / `delete` | 客户管理 |
| `contract` | `read` / `create` / `update` / `delete` | 合同管理 |
| `after_sale` | `read` / `create` / `update` / `delete` | 售后管理 |
| `product` | `read` / `create` / `update` / `delete` | 产品管理 |
| `supplier` | `read` / `create` / `update` / `delete` | 供应商管理 |
| `employee` | `read` / `create` / `update` / `delete` | 员工管理 |
| `user` | `manage` | 用户管理（仅超管角色） |

### 权限检查

```javascript
import { hasPermission } from '../store/user'

// 检查当前用户是否拥有某个权限
hasPermission('employee', 'create')  // → true/false
```

### 数据范围

员工列表受**数据范围（data scope）** 控制：
- **信息技术部、总经理办公室**：查看全部员工
- **招商部、运营部、采购部**：仅查看本部门员工
- **财务部**：查看全部员工（同时可查看薪资）

### 菜单可见性

侧栏菜单项根据当前用户的权限动态渲染（在 `panel.vue` 中通过 `v-if="checkPermission(...)"` 控制）。

---

## 与后端 API 的关系

前端通过 Axios 请求后端 RESTful API，所有请求以 `/api` 为前缀。

| 端点 | 方法 | 说明 |
|------|------|------|
| `/api/auth/login` | POST | 登录认证 |
| `/api/auth/userinfo` | GET | 获取当前用户信息与权限 |
| `/api/employees` | GET/POST/PUT/DELETE | 员工 CRUD |
| `/api/employees/simple` | GET | 简易员工列表（下拉专用，仅在职） |
| `/api/users` | GET/POST/PUT/DELETE | 用户 CRUD |
| `/api/user/list` | GET | 简易用户列表（下拉专用） |
| `/api/customers` | GET/POST/PUT/DELETE | 客户 CRUD |
| `/api/contracts` | GET/POST/PUT/DELETE | 合同 CRUD |
| `/api/after-sales` | GET/POST/PUT/DELETE | 售后 CRUD |
| `/api/products` | GET/POST/PUT/DELETE | 产品 CRUD |
| `/api/suppliers` | GET/POST/PUT/DELETE | 供应商 CRUD |

> 详细 API 文档请参见后端项目的 `API.md`。

### 请求配置

基础请求配置在 `src/api/request.js` 中定义，包括：
- 自动附加 `Authorization: Bearer <token>` 请求头
- 响应拦截器统一处理错误（401 跳转登录、403 无权限提示等）
- 自动解析 `res.data` 数据

---

## 开发命令

```bash
# 启动开发服务器（热更新）
npm run dev

# 构建生产版本
npm run build

# 预览生产构建
npm run preview
```

---

## 构建部署

```bash
# 构建
npm run build

# 构建产物在 dist/ 目录
# 将 dist/ 内容部署到任意静态文件服务器或 Nginx
```

### Nginx 反向代理示例

```nginx
server {
    listen 80;
    server_name your-domain.com;

    root /path/to/backmanagerweb/dist;
    index index.html;

    # SPA 路由重写
    location / {
        try_files $uri $uri/ /index.html;
    }

    # API 反向代理到后端
    location /api/ {
        proxy_pass http://localhost:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}
```

---

## 品牌说明

本项目是为 **蜜雪冰城（Mixue Ice Cream & Tea）** 量身定制的管理系统，品牌视觉元素（Logo、雪王 IP、品牌色 `#E60012` 等）均归属蜜雪冰城所有。

> "你爱我，我爱你，蜜雪冰城甜蜜蜜" 🎵