rollingDraw/README.md

Rolling Draw 抽奖系统

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

在线演示 · 功能特性 · 快速开始 · 使用文档

---

📖 项目简介

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

安装依赖

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

# 进入项目目录
cd rollingDraw

# 安装依赖
npm install

---

🎬 快速开始

开发模式

npm run dev

访问 http://localhost:5173 查看应用

构建生产版本

npm run build

构建产物将生成在 dist 目录

预览生产构建

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 变量：

: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
• Vite
• Element Plus
• Pinia

---

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

Made with ❤️ by Pandora Studio