# Rolling Draw 抽奖系统

<div align="center">

![Vue 3](https://img.shields.io/badge/Vue-3.4.0-4FC08D?style=flat&logo=vue.js&logoColor=white)
![Vite](https://img.shields.io/badge/Vite-5.0.0-646CFF?style=flat&logo=vite&logoColor=white)
![Element Plus](https://img.shields.io/badge/Element%20Plus-2.5.0-409EFF?style=flat&logo=element&logoColor=white)
![License](https://img.shields.io/badge/License-Proprietary-ff69b4)

一个功能强大、界面美观的现代化抽奖系统

[在线演示](#) · [功能特性](#功能特性) · [快速开始](#快速开始) · [使用文档](#使用文档)

</div>

---

## 📖 项目简介

Rolling Draw 是一个基于 Vue 3 + Vite 开发的现代化抽奖系统，提供完整的管理后台和大屏展示功能。系统支持自定义字段、批量导入、多轮次抽奖、中奖记录导出等功能，适用于年会抽奖、活动抽奖等各类场景。

### ✨ 核心特点

- 🎨 **现代化界面** - 基于 Element Plus 的精美 UI 设计
- 📱 **响应式设计** - 完美适配桌面端和大屏展示
- 💾 **本地存储** - 基于 IndexedDB 的数据持久化
- 🔄 **实时同步** - 支持跨标签页数据同步
- 🎯 **公平抽奖** - 采用 Fisher-Yates 洗牌算法
- 📊 **数据管理** - 支持导入导出，方便数据管理
- ⌨️ **快捷操作** - 大屏端支持快捷键控制

---

## 🚀 功能特性

### 参与者管理
- ✅ 单个添加参与者
- ✅ 批量导入（支持 CSV 格式）
- ✅ 导出参与者名单
- ✅ 自定义字段配置
- ✅ 删除参与者
- ✅ 清空名单

### 奖品管理
- ✅ 添加奖品
- ✅ 设置库存数量
- ✅ 实时库存管理
- ✅ 删除奖品

### 轮次管理
- ✅ 创建抽奖轮次
- ✅ 关联奖品
- ✅ 设置抽取人数
- ✅ 轮次状态跟踪

### 抽奖控制
- ✅ 开始/停止抽奖
- ✅ Fisher-Yates 洗牌算法
- ✅ 防重复中奖
- ✅ 库存自动扣减
- ✅ 重置抽奖数据

### 中奖记录
- ✅ 实时记录中奖信息
- ✅ 导出中奖名单
- ✅ 按轮次筛选

### 大屏展示
- ✅ 滚动动画效果
- ✅ 结果展示模式
- ✅ 自定义背景图片
- ✅ 快捷键控制（← → 切换轮次，Space 开始/停止）
- ✅ 多列布局支持（可配置每行列数）

---

## 🛠️ 技术栈

### 核心框架
- **Vue 3** (v3.4.0) - 渐进式 JavaScript 框架
- **Vite** (v5.0.0) - 下一代前端构建工具
- **Vue Router** (v4.2.5) - 官方路由管理器
- **Pinia** (v2.1.7) - Vue 状态管理库

### UI 组件库
- **Element Plus** (v2.5.0) - Vue 3 组件库
- **@element-plus/icons-vue** (v2.3.1) - Element Plus 图标库

### 数据持久化
- **IndexedDB** - 浏览器本地数据库
- **localStorage** - 跨标签页通信

---

## 📦 安装

### 环境要求

- Node.js >= 16.0.0
- npm >= 8.0.0

### 安装依赖

```bash
# 克隆项目
git clone https://git.pandorastudio.cn/product/rollingDraw.git

# 进入项目目录
cd rollingDraw

# 安装依赖
npm install
```

---

## 🎬 快速开始

### 开发模式

```bash
npm run dev
```

访问 [http://localhost:5173](http://localhost:5173) 查看应用

### 构建生产版本

```bash
npm run build
```

构建产物将生成在 `dist` 目录

### 预览生产构建

```bash
npm run preview
```

---

## 📂 项目结构

```
rollingDraw/
├── src/
│   ├── views/
│   │   ├── Admin.vue              # 管理后台布局
│   │   ├── Display.vue            # 大屏展示页面
│   │   └── admin/
│   │       ├── Participants.vue   # 参与者管理
│   │       ├── Prizes.vue         # 奖品管理
│   │       ├── Rounds.vue         # 轮次管理
│   │       └── Winners.vue        # 中奖记录
│   ├── router/
│   │   └── index.js               # 路由配置
│   ├── store/
│   │   └── index.js               # Pinia 状态管理
│   ├── styles/
│   │   ├── element-plus.css       # Element Plus 样式覆盖
│   │   ├── global.css             # 全局样式
│   │   └── variables.css          # CSS 变量定义
│   ├── App.vue                    # 主应用组件
│   └── main.js                    # 应用入口
├── utils/
│   └── indexedDB.js               # IndexedDB 工具封装
├── index.html                     # HTML 模板
├── package.json                   # 项目配置
├── vite.config.js                 # Vite 配置
└── README.md                      # 项目文档
```

---

## 📖 使用文档

### 路由说明

| 路径 | 组件 | 说明 |
|------|------|------|
| `/` | 重定向 | 默认重定向到参与者管理 |
| `/admin/participants` | Participants | 参与者管理页面 |
| `/admin/prizes` | Prizes | 奖品管理页面 |
| `/admin/rounds` | Rounds | 轮次管理页面 |
| `/admin/winners` | Winners | 中奖记录页面 |
| `/display` | Display | 大屏展示页面 |

### 快捷键

#### 大屏展示端
- **← →** - 切换轮次
- **Space** - 开始/停止抽奖

### CSV 导入格式

```
姓名,部门,工号
张三,技术部,1001
李四,市场部,1002
王五,财务部,1003
```

**注意：**
- 第一行为字段名
- 后续行为数据
- 支持中文字段名
- 使用逗号分隔

### 数据存储

系统使用 IndexedDB 存储所有数据，包括：

- **lottery_fields** - 字段配置
- **lottery_participants** - 参与者列表
- **lottery_prizes** - 奖品列表
- **lottery_rounds** - 轮次列表
- **lottery_winners** - 中奖记录
- **lottery_isRolling** - 抽奖状态
- **lottery_currentRound** - 当前轮次
- **lottery_displayMode** - 显示模式
- **lottery_backgroundImage** - 背景图片
- **lottery_columnsPerRow** - 每行列数

---

## 🔧 开发指南

### 代码规范

- 使用 Vue 3 Composition API
- 使用 `<script setup>` 语法糖
- 遵循 ESLint 规则
- 组件命名使用 PascalCase

### 命名规范

- 文件名：PascalCase (组件) / kebab-case (工具)
- 变量名：camelCase
- 常量名：UPPER_SNAKE_CASE
- 函数名：camelCase

### 添加新功能

1. 在 `src/views/` 创建新组件
2. 在 `src/router/index.js` 添加路由
3. 在 `src/store/index.js` 添加状态管理
4. 在相应页面添加入口

---

## 🎨 自定义样式

### CSS 变量

在 `src/styles/variables.css` 中定义了全局 CSS 变量：

```css
:root {
  /* 颜色 */
  --color-primary: #409EFF;
  --color-secondary: #67C23A;
  --color-accent: #E6A23C;
  
  /* 间距 */
  --spacing-sm: 8px;
  --spacing-md: 12px;
  --spacing-lg: 16px;
  
  /* 字体 */
  --font-family-primary: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
}
```

### 主题定制

修改 `src/styles/variables.css` 中的 CSS 变量即可自定义主题。

---

## ⚠️ 注意事项

1. **数据备份**：建议定期导出参与者名单和中奖记录进行备份
2. **浏览器兼容性**：需要支持 IndexedDB 的现代浏览器（Chrome、Firefox、Edge、Safari）
3. **图片限制**：背景图片最大支持 10MB
4. **CSV 格式**：导入文件第一行为字段名，后续行为数据
5. **数据清理**：使用浏览器清除缓存会删除所有数据

---

## 🐛 常见问题

### Q: 数据会丢失吗？
A: 数据存储在浏览器的 IndexedDB 中，清除浏览器缓存会丢失数据，建议定期导出备份。

### Q: 支持哪些浏览器？
A: 支持所有现代浏览器（Chrome、Firefox、Edge、Safari）的最新版本。

### Q: 可以同时打开多个标签页吗？
A: 可以，系统支持跨标签页数据同步。

### Q: 如何清空所有数据？
A: 在管理后台的"中奖记录"页面点击"清空"按钮。

### Q: 抽奖算法公平吗？
A: 采用 Fisher-Yates 洗牌算法，确保每个参与者被抽中的概率相同。

---

## 📄 许可证

版权所有 © 2025 上海潘哆呐科技有限公司

---

## 📞 联系方式

- **公司**: 上海潘哆呐科技有限公司
- **邮箱**: work@pandorastudio.cn
- **项目地址**: https://git.pandorastudio.cn/product/rollingDraw.git

---

## 🙏 致谢

感谢以下开源项目：

- [Vue.js](https://vuejs.org/)
- [Vite](https://vitejs.dev/)
- [Element Plus](https://element-plus.org/)
- [Pinia](https://pinia.vuejs.org/)

---

<div align="center">

**如果这个项目对你有帮助，请给一个 ⭐️**

Made with ❤️ by Pandora Studio

</div>