You've already forked rollingDraw
389 lines
10 KiB
Markdown
389 lines
10 KiB
Markdown
# Rolling Draw 抽奖系统
|
||
|
||
<div align="center">
|
||
|
||
|
||
|
||
|
||
|
||
|
||
一个功能强大、界面美观的现代化抽奖系统
|
||
|
||
[在线演示](#) · [功能特性](#功能特性) · [快速开始](#快速开始) · [使用文档](#使用文档)
|
||
|
||
</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** - 每行列数
|
||
- **lottery_displayFontColor** - 大屏端字体颜色
|
||
- **lottery_prizeNameFontColor** - 奖品名称字体颜色
|
||
- **lottery_roundNameFontSize** - 轮次名称字体大小
|
||
- **lottery_prizeNameFontSize** - 奖品名称字体大小
|
||
- **lottery_participantFontSize** - 人名字体大小
|
||
- **lottery_displayFields** - 大屏端显示的字段列表
|
||
- **lottery_showFieldLabels** - 是否显示字段标签
|
||
|
||
---
|
||
|
||
## 🔧 开发指南
|
||
|
||
### 代码规范
|
||
|
||
- 使用 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-10 人）
|
||
- 字体颜色（轮次名称、人名、奖品名称）
|
||
- 字体大小（轮次名称、奖品名称、人名）
|
||
- 显示字段选择
|
||
- 字段标签显示/隐藏
|
||
|
||
---
|
||
|
||
## ⚠️ 注意事项
|
||
|
||
1. **数据备份**：建议定期导出参与者名单和中奖记录进行备份
|
||
2. **浏览器兼容性**：需要支持 IndexedDB 的现代浏览器（Chrome、Firefox、Edge、Safari）
|
||
3. **图片限制**：背景图片最大支持 10MB
|
||
4. **CSV 格式**：导入文件第一行为字段名，后续行为数据
|
||
5. **数据清理**：使用浏览器清除缓存会删除所有数据
|
||
6. **性能建议**：单次导入建议不超过 1000 人，大量数据请分批导入
|
||
|
||
---
|
||
|
||
## 🐛 常见问题
|
||
|
||
### Q: 数据会丢失吗？
|
||
A: 数据存储在浏览器的 IndexedDB 中，清除浏览器缓存会丢失数据，建议定期导出备份。
|
||
|
||
### Q: 支持哪些浏览器？
|
||
A: 支持所有现代浏览器（Chrome、Firefox、Edge、Safari）的最新版本。
|
||
|
||
### Q: 可以同时打开多个标签页吗？
|
||
A: 可以，系统支持跨标签页数据同步。
|
||
|
||
### Q: 如何清空所有数据？
|
||
A: 在管理后台的"中奖记录"页面点击"清空"按钮。
|
||
|
||
### Q: 抽奖算法公平吗？
|
||
A: 采用 Fisher-Yates 洗牌算法，确保每个参与者被抽中的概率相同。
|
||
|
||
### Q: 如何自定义大屏显示效果？
|
||
A: 在管理后台点击"显示设置"按钮，可以调整字体颜色、大小、显示字段等。
|
||
|
||
### Q: 大量数据导入会卡顿吗？
|
||
A: 系统已实现分页显示，单页默认显示 20 条数据，支持大数据量操作。
|
||
|
||
---
|
||
|
||
## 📄 许可证
|
||
|
||
版权所有 © 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> |