1. 项目背景与核心功能
年会抽奖环节一直是企业活动中最受期待的环节之一。传统的抽奖方式往往缺乏视觉冲击力，难以调动现场气氛。这个基于Windows平台的3D圆球抽奖系统，正是为了解决这个问题而设计的。
核心功能亮点：
- 炫酷的3D球体动态效果，所有参与者的名字在球体表面流动旋转
- 完全可定制的界面元素（背景、音乐、奖品展示等）
- 支持Excel导入参与者名单，导出抽奖结果
- 本地化存储配置数据，无需担心隐私泄露
- 开箱即用的Windows安装包，无需复杂配置
技术提示：系统底层使用Three.js实现3D渲染，Vue3构建用户界面，IndexDB处理本地数据存储，这种技术组合既保证了视觉效果，又确保了流畅的用户体验。
2. 环境准备与安装指南
2.1 系统要求检查
在开始安装前，请确保您的Windows系统满足以下要求：
- 操作系统：Windows 10/11 64位
- 内存：至少4GB可用内存
- 显卡：支持WebGL 2.0的显卡
- 浏览器：最新版Chrome或Edge（用于Web版本）
- .NET Framework 4.7.2或更高版本
2.2 三种安装方式详解
2.2.1 直接使用Web版本
最简单的使用方式是直接访问官方提供的Web版本：
- 打开Chrome或Edge浏览器
- 访问 https://log1997.github.io/log-lottery/
- 首次使用时，建议点击"全局配置"→"界面配置"→"重置所有数据"
2.2.2 Windows安装包方式
对于需要离线使用的场景：
- 前往GitHub Releases页面下载最新.exe安装包
- 双击运行安装程序，按向导完成安装
- 安装完成后，桌面会出现快捷方式
- 首次运行时，系统会自动创建必要的配置文件夹
2.2.3 Docker容器方式
适合技术团队部署到内网环境：
# 拉取最新镜像 docker pull log1997/log-lottery:latest # 运行容器（映射到本地9279端口） docker run -d --name log-lottery -p 9279:80 log1997/log-lottery:latest访问地址：http://localhost:9279/log-lottery/
3. 核心功能配置详解
3.1 人员名单管理
系统支持多种方式导入参与者信息：
Excel模板导入（推荐）：
- 下载系统提供的模板文件
- 按格式填写姓名、部门、工号等信息
- 在"人员配置"界面点击"导入Excel"
手动添加：
- 在界面中直接输入人员信息
- 支持批量粘贴从其他系统复制的名单
临时添加：
- 抽奖过程中可随时添加遗漏人员
- 新增人员会立即加入抽奖池
实战技巧：建议提前准备好两份名单 - 全员名单和各部门名单，这样可以根据不同奖项灵活切换抽奖范围。
3.2 奖项与规则设置
每个奖项都可以独立配置：
- 基础设置：奖项名称、奖品图片、抽取人数
- 高级规则：
- 是否允许重复中奖
- 特定部门/岗位限制
- 中奖后是否从后续抽奖中排除
- 自定义中奖动画效果
// 奖项配置数据结构示例 { "awardName": "特等奖", "quota": 1, "allowRepeat": false, "departments": ["技术部","产品部"], "animation": "explosion" }3.3 界面个性化定制
系统提供丰富的视觉定制选项：
- 主题颜色：预设12种配色方案，支持自定义RGB值
- 3D球体参数：
- 粒子大小
- 旋转速度
- 高亮颜色
- 背景透明度
- 文字效果：
- 中奖字体大小
- 跑马灯速度
- 弹幕显示设置
- 背景音乐：
- 支持多首音乐循环播放
- 可设置不同阶段的背景音乐（准备、抽奖、中奖）
4. 抽奖流程与现场控制
4.1 标准抽奖流程
- 预热阶段：播放背景音乐，3D球体展示所有参与者名字
- 开始抽奖：点击"开始"按钮，球体加速旋转
- 抽取结果：点击"停止"，系统通过物理引擎模拟球体减速过程
- 结果展示：中奖者名字高亮显示，伴有动画和音效
- 记录保存：自动记录到历史记录，可随时导出
4.2 高级控制技巧
- 节奏控制：通过空格键快速开始/停止，比鼠标操作更流畅
- 多屏支持：可将结果输出到投影仪，操作界面留在控制台
- 紧急预案：
- 突然断电：数据会自动保存，恢复后可继续
- 误操作：提供"撤销上一步"功能
- 系统卡顿：备用的简化模式（关闭3D效果）
4.3 数据管理与备份
所有配置和数据都存储在本地：
- 位置：C:\Users[用户名]\AppData\Roaming\log-lottery
- 备份建议：
- 定期复制整个文件夹到安全位置
- 使用"导出配置"功能生成.json备份文件
- 重要活动前，保存系统快照
5. 技术原理与性能优化
5.1 3D渲染核心机制
系统采用Three.js实现3D效果：
- 粒子系统：每个名字对应一个3D粒子
- 物理引擎：模拟球体旋转的物理效果
- 着色器：自定义GLSL着色器实现流光效果
- 性能优化：
- 视锥体裁剪
- 实例化渲染
- 按需加载
5.2 数据存储方案
- IndexDB：存储配置和人员数据
- 本地文件：保存图片、音乐等大文件
- 内存缓存：抽奖过程中的高频访问数据
5.3 常见问题解决方案
3D显示异常：
- 更新显卡驱动
- 在chrome://flags中启用"Override software rendering list"
- 降低画质设置
导入失败处理：
- 检查Excel是否使用模板格式
- 确保没有特殊字符
- 尝试将文件另存为.csv格式再导入
性能优化建议：
- 超过500人时，启用"简化模式"
- 关闭不必要的后台程序
- 使用有线网络连接（对于Web版）
6. 扩展应用与二次开发
6.1 企业定制化方向
- 集成企业OA系统，自动同步人员信息
- 添加LDAP/AD域认证
- 开发微信小程序联动功能
- 定制企业VI主题包
6.2 开发者指南
项目采用前后端分离架构：
- 前端：Vue3 + TypeScript + Three.js
- 打包：Vite
- 样式：DaisyUI
# 开发环境搭建 git clone https://github.com/LOG1997/log-lottery.git cd log-lottery pnpm install pnpm dev # 构建生产版本 pnpm build6.3 插件开发
系统支持通过插件扩展功能：
- 在src/plugins目录下创建新插件
- 实现核心接口：
interface LotteryPlugin { name: string; init(): Promise<void>; onEvent(event: string, data: any): void; } - 在main.ts中注册插件
我在实际使用中发现，这套系统最出色的地方在于它的灵活性。去年我们公司年会时，临时需要增加一个"最佳着装奖"，通过系统的"快速奖项"功能，5分钟就完成了设置，而且效果丝毫不打折扣。对于技术团队来说，它的开源特性也让我们能够根据公司需求进行深度定制，比如我们集成了员工照片自动显示功能，当中奖时不仅显示名字，还会显示员工照片，现场效果非常好。
