Year-End Lucky Draw (年会幸运抽奖系统)

一个现代化、高颜值、功能强大的年会抽奖系统，支持 Windows 客户端和 Web 网页端。专为企业年会、活动抽奖场景打造，提供多种炫酷动画效果和高度自定义的配置选项。

📚 目录

• 核心功能
• 界面预览
• 安装与使用
• 操作指南
• 键盘快捷键
• 配置说明
• 项目结构
• 开发指南
• 技术栈
• 个人矩阵

✨ 核心功能 (Features)

🎨 极致视觉体验

• 多重动画模式：
  • 📜 名单滚动 (Reel)：经典老虎机式滚动，支持高速模糊与即时停止，性能强劲，适合千人以上大抽奖。
  • 🔮 平面扭蛋 (2D Gashapon)：基于物理引擎的 2D 碰撞球体，支持玻璃拟态 (Glassmorphism) 质感，全屏碰撞，气氛热烈。
  • 🌍 3D 光球 (Sphere)：赛博朋克风格的 3D 旋转水晶球，科技感十足。
• 高级主题系统：内置 6 套精心调配的主题（深空蓝、喜庆红、科技黑、柔粉金、清新绿、极光紫），支持一键切换，UI 全局自动适配。
• 沉浸式特效：全屏烟花庆典 (Fireworks)、粒子特效、流光文字、入场动画。

🛠 强大功能配置

• Excel 数据导入：支持 .xlsx / .xls 格式一键导入，自动识别“姓名”、“部门”列，智能去重。
• 灵活奖项管理：自定义奖项名称（特等奖、一等奖...）、抽取人数、奖品图片（可选）。
• 音频控制：支持背景音乐 (BGM)、滚动音效、中奖音效，支持自定义上传 MP3。
• 数据安全：基于 Electron/Browser 本地存储，防刷新丢失，支持一键重置。

🖼 界面预览 (Preview)

💡 提示：系统支持全屏模式，建议在投影大屏上运行以获得最佳效果。

1. 环境准备

在运行本软件之前，您的电脑需要安装基础的运行环境。

安装 Node.js

Node.js 是本系统的运行基础。

1. 访问 Node.js 官网。
2. 下载 LTS (长期支持版)，例如 v20.x.x。
3. 双击安装包，一路点击 "Next" 完成安装。
4. 验证安装：
   打开终端 (Win+R 输入 cmd)，输入以下命令并回车：

   node -v
   npm -v

   如果出现版本号（如 v20.11.0），说明安装成功。

2. 下载与安装

获取代码

如果您已获得源码包：

1. 将压缩包解压到一个文件夹（例如桌面）。
2. 记住这个文件夹的路径。

cd year-end-lucky-draw

安装依赖

1. 在代码文件夹内，右键选择 "在终端中打开" (Open in Terminal) 或者在地址栏输入 cmd 并回车。
2. 输入以下命令开始安装依赖库：

   npm install

   注意：根据网络情况，这可能需要几分钟时间。如果失败，可以尝试使用镜像：npm config set registry https://registry.npmmirror.com 后重试。

3. 运行系统

本系统支持两种运行模式：网页版 和 桌面客户端版 (Windows)。

模式 A：开发/预览模式 (网页版)

适合快速查看效果或在浏览器中使用，建议使用网页版。（F11全屏即可）

npm run dev
【推荐，按F11全屏即可】

运行后，终端会显示一个地址（通常是 http://localhost:5173），按住 Ctrl 点击该链接即可在浏览器打开。

模式 B：桌面客户端模式 (Electron)

适合正式活动使用，体验更流畅，无浏览器边框。（不推荐）

npm run dev:electron
【不推荐】

系统将自动启动一个独立的应用程序窗口。

模式 C：打包生成 EXE 文件

如果您需要将软件拷贝到其他没有环境的电脑上运行：（不推荐）

npm run electron:build
【不推荐】

打包完成后，在项目目录下的 dist_electron 或 release 文件夹中，会生成一个 .exe 安装包或免安装程序。

📖 操作指南 (User Guide)

1. 导入名单：
   • 点击右下角 ⚙️ 设置 图标。
   • 在“人员管理”中点击“导入 Excel”。
   • 确保 Excel 第一行为表头（包含“姓名”列）。
2. 设置奖项：
   • 在“奖项设置”中添加或修改奖项。
   • 设置当前轮次要抽取的“单次人数”。
3. 选择主题与动画：
   • 在“全局设置”中选择喜欢的主题配色。
   • 选择“动画效果”：推荐使用 2D Gashapon 获得最佳视觉效果。
4. 开始抽奖：
   • 点击主界面 开始抽奖 按钮，或按 空格键。
   • 再次点击或按空格键停止，生成中奖名单。
5. 导出结果：
   • 抽奖结束后，可在设置界面查看并导出中奖记录。

⌨ 键盘快捷键 (Shortcuts)

⚙ 配置说明 (Configuration)

配置文件位于 src/store/luckyDraw.ts (State) 和界面设置面板。

📂 项目结构 (Project Structure)

.
├── electron/               # Electron 主进程代码
│   ├── main.ts             # 窗口创建、系统事件
│   └── preload.ts          # 预加载脚本
├── src/
│   ├── components/         # Vue 组件
│   │   ├── animations/     # 核心动画组件 (Reel, Gashapon, Sphere)
│   │   ├── ControlPanel.vue # 底部控制栏
│   │   ├── LuckyGrid.vue   # 抽奖主区域
│   │   └── Settings.vue    # 设置面板
│   ├── store/              # Pinia 状态管理
│   ├── utils/              # 工具函数 (Excel解析, 音频管理)
│   ├── App.vue             # 根组件
│   └── main.ts             # 入口文件
├── dist-electron/          # Electron 构建产物
├── public/                 # 静态资源
└── package.json            # 依赖配置

🛠 开发指南 (Development)

添加新主题

1. 打开 src/store/luckyDraw.ts。
2. 在 defaultSettings 或主题列表中添加新的颜色配置对象。

修改动画逻辑

• Reel 效果：修改 src/components/animations/ReelAnimation.vue。
• 2D 效果：修改 src/components/animations/FlatGashaponAnimation.vue (基于 Canvas/DOM 物理模拟)。
• 3D 效果：修改 src/components/animations/SphereAnimation.vue (CSS3D)。

� 技术栈 (Tech Stack)

• 核心框架: Vue 3 (Composition API)
• 语言: TypeScript
• 构建工具: Vite 5
• 桌面运行时: Electron
• 样式: Tailwind CSS
• 状态管理: Pinia
• 动画: Native RAF, CSS3 Transitions, Canvas Confetti

个人矩阵

• 抖音账号：从 0 至 1（日常分享实操、效率工具教程）
• 微信公众号：从 0 至 1（可通过该渠道获取完整代码包及EXE程序）
• 博客网站： https://www.from0to1.cn （持续更新实战教程、技术干货内容）
• GitHub账号： https://github.com/mtnljbydd （开源更多实用工具脚本及项目工程）