# CHOUJIANG

**Repository Path**: wujunyu111/choujiang

## Basic Information

- **Project Name**: CHOUJIANG
- **Description**: 抽奖小程序
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-06-27
- **Last Updated**: 2025-06-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 🎲 两两分组抽奖系统

一个基于 Vue 3 + Electron 的炫酷两两分组抽奖桌面应用，支持奇数偶数人数的公平分组，具有精美的动画效果和音效体验。

## ✨ 功能特色

### 🎯 核心功能
- **智能分组**: 支持任意人数的两两分组
- **奇数处理**: 提供观察员模式、三人组模式、跳过模式三种奇数处理方案
- **公平随机**: 基于加密安全的随机算法，确保抽奖公平性
- **历史记录**: 自动保存抽奖历史，支持查看和回溯
- **桌面应用**: 基于 Electron 的跨平台桌面应用

### 🎨 视觉体验
- **炫酷动画**: 基于 GSAP 的专业级动画效果
- **多主题支持**: 内置 6 种精美主题（默认、日落、海洋、森林、紫色、深色）
- **响应式设计**: 完美适配桌面端、平板和移动设备
- **毛玻璃效果**: 现代化的 UI 设计语言

### 🔊 音效系统
- **动态音效**: Web Audio API 生成的实时音效
- **音效序列**: 抽奖过程配备完整的音效体验
- **音量控制**: 支持音效开关和音量调节

### ⚙️ 个性化设置
- **动画速度**: 三档速度可调（慢速、正常、快速）
- **主题切换**: 实时主题切换，支持自定义主题
- **数据持久化**: 本地存储用户设置和历史记录
- **导出功能**: 支持结果导出和设置备份

## 🚀 快速开始

### 环境要求
- Node.js 18.16.1 或更高版本
- npm 9.5.1 或更高版本

### 安装步骤

1. **克隆项目**
```bash
git clone <repository-url>
cd choujiang
```

2. **安装依赖**
```bash
# 推荐使用 cnpm 以获得更好的网络体验（国内用户）
npm install -g cnpm --registry=https://registry.npmmirror.com
cnpm install

# 或使用 npm（可能需要配置镜像源）
npm install
```

3. **启动开发服务器**
```bash
# 启动 Web 开发服务器
npm run dev

# 启动 Electron 开发模式
npm run electron:dev
```

4. **构建生产版本**
```bash
# 构建 Web 版本
npm run build

# 构建 Electron 桌面应用
npm run build:electron
```

## 📦 安装包下载

### Windows 用户
- 下载地址：`release/win-unpacked/抽奖系统.exe`
- 文件大小：约 196MB
- 系统要求：Windows 10/11 x64

### 使用方法
1. 下载并解压 `win-unpacked` 文件夹
2. 双击运行 `抽奖系统.exe`
3. 无需安装，即开即用
4. 可将整个文件夹复制到其他电脑使用

## 🎮 使用指南

### 基本操作流程

1. **添加参与者**
   - 在输入框中输入姓名，按回车或点击添加
   - 支持批量输入：点击"批量输入"按钮，每行一个姓名或用逗号分隔
   - 可以点击快速建议按钮添加示例姓名

2. **开始抽奖**
   - 添加至少 2 个参与者后，点击底部的"开始抽奖"按钮
   - 观看炫酷的轮盘旋转动画
   - 等待抽奖结果自动显示

3. **查看结果**
   - 结果页面显示所有分组情况
   - 每个组都有清晰的成员标识和类型标记
   - 支持重新抽奖和导出结果

### 高级功能

#### 奇数人数处理
- **观察员模式**: 多出的 1 人作为观察员，不参与分组
- **三人组模式**: 创建一个三人组，其余正常两两分组
- **跳过模式**: 忽略多余的 1 人

#### 主题自定义
1. 点击顶部主题选择器
2. 选择喜欢的主题风格
3. 主题会实时应用到整个界面

#### 设置调整
1. 点击底部设置按钮（⚙️）
2. 可调整：
   - 音效开关和音量
   - 动画速度
   - 奇数处理方式
   - 数据管理

## 🏗️ 技术架构

### 核心技术栈
- **Vue 3.4+**: 现代化前端框架，使用 Composition API
- **Electron 33.2+**: 跨平台桌面应用框架
- **Pinia**: 状态管理，替代 Vuex
- **GSAP 3.12+**: 专业动画库
- **SCSS**: CSS 预处理器
- **Vite 5+**: 现代化构建工具

### 项目结构
```
choujiang/
├── electron/                # Electron 主进程文件
│   ├── main.cjs            # 主进程入口
│   └── preload.cjs         # 预加载脚本
├── src/
│   ├── assets/
│   │   └── styles/         # 全局样式文件
│   ├── components/         # Vue 组件
│   │   ├── LotteryApp.vue     # 主抽奖应用组件
│   │   ├── NameInput.vue      # 名字输入组件
│   │   ├── ParticipantCard.vue # 参与者卡片
│   │   ├── LotteryWheel.vue   # 抽奖轮盘
│   │   └── GroupResult.vue    # 结果展示
│   ├── composables/        # 组合式函数
│   │   ├── useLottery.js      # 抽奖逻辑
│   │   ├── useAnimation.js    # 动画控制
│   │   └── useSound.js        # 音效管理
│   ├── stores/             # Pinia 状态管理
│   │   └── lottery.js         # 抽奖数据 store
│   ├── utils/              # 工具函数
│   │   └── animation-helpers.js # 动画和主题工具
│   ├── views/              # 路由视图
│   │   └── HomeView.vue       # 主页视图
│   └── App.vue             # 主应用组件
├── release/                # 打包输出目录
│   └── win-unpacked/       # Windows 应用程序
└── package.json            # 项目配置
```

### 核心设计模式
- **组合式 API**: 充分利用 Vue 3 的组合式 API 进行逻辑复用
- **状态管理**: 使用 Pinia 进行全局状态管理
- **响应式设计**: 移动优先的响应式布局
- **组件化**: 高度模块化的组件设计
- **进程间通信**: Electron 主进程与渲染进程的安全通信

## 🔧 开发配置

### 环境变量配置
```bash
# 设置 Electron 镜像源（国内用户推荐）
npm config set electron_mirror https://npmmirror.com/mirrors/electron/
npm config set electron_builder_binaries_mirror https://npmmirror.com/mirrors/electron-builder-binaries/
```

### 开发脚本
```json
{
  "scripts": {
    "dev": "vite",                    // 启动 Web 开发服务器
    "electron:dev": "concurrently \"npm run dev\" \"wait-on http://localhost:5176 && electron .\"",
    "build": "vite build",            // 构建 Web 版本
    "build:electron": "npm run build && electron-builder",
    "electron": "electron ."          // 直接启动 Electron
  }
}
```

## 🎯 主要算法

### 分组算法
```javascript
// 核心分组逻辑
function generateGroups(participants, settings) {
  const shuffled = shuffleArray(participants)
  const groups = []
  
  // 处理奇数情况
  if (participants.length % 2 === 1) {
    if (settings.oddHandling === 'triple') {
      // 创建三人组
      groups.push(createGroup(shuffled.slice(0, 3), 'triple'))
      shuffled = shuffled.slice(3)
    }
  }
  
  // 创建两人组
  for (let i = 0; i < shuffled.length; i += 2) {
    if (i + 1 < shuffled.length) {
      groups.push(createGroup(shuffled.slice(i, i + 2), 'pair'))
    } else if (settings.oddHandling === 'observer') {
      groups.push(createGroup([shuffled[i]], 'observer'))
    }
  }
  
  return groups
}
```

### 随机算法
使用 Fisher-Yates 洗牌算法确保真正的随机性：

```javascript
function shuffleArray(array) {
  const shuffled = [...array]
  for (let i = shuffled.length - 1; i > 0; i--) {
    const j = Math.floor(Math.random() * (i + 1))
    ;[shuffled[i], shuffled[j]] = [shuffled[j], shuffled[i]]
  }
  return shuffled
}
```

## 🎨 主题系统

系统内置 6 种主题，支持实时切换：

1. **默认主题**: 紫蓝渐变，经典优雅
2. **日落主题**: 橙红渐变，温暖浪漫
3. **海洋主题**: 蓝色渐变，清新自然
4. **森林主题**: 绿色渐变，生机活力
5. **紫色主题**: 粉紫渐变，时尚前卫
6. **深色主题**: 深灰色调，专业商务

每个主题包含：
- 背景渐变色
- 组件配色方案
- 动画风格调整
- 音效特性配置

## 🔧 配置选项

### 动画设置
- **速度等级**: 慢速(3s)、正常(2s)、快速(1s)
- **缓动曲线**: 多种专业缓动效果
- **性能优化**: 硬件加速和帧率优化

### 音效设置
- **音效类型**: 合成音效，无需额外文件
- **音量控制**: 0-100% 精确调节
- **音效序列**: 完整的抽奖音效体验

### 数据设置
- **本地存储**: 自动保存用户数据
- **历史记录**: 最多保存 20 条记录
- **导出格式**: JSON 格式导出

## 📱 跨平台支持

### Windows
- ✅ Windows 10/11 x64
- ✅ 无需安装，绿色版本
- ✅ 完整功能支持

### macOS（开发中）
- 🔄 macOS 10.14+ 支持
- 🔄 Apple Silicon 原生支持

### Linux（开发中）
- 🔄 Ubuntu 18.04+ 支持
- 🔄 AppImage 格式

## 🚀 打包部署

### 本地打包
```bash
# 安装依赖
cnpm install

# 构建 Web 版本
npm run build

# 打包 Electron 应用
npm run build:electron
```

### 打包配置
```json
{
  "build": {
    "appId": "com.choujiang.lottery",
    "productName": "抽奖系统",
    "npmRebuild": false,
    "forceCodeSigning": false,
    "directories": {
      "output": "release"
    },
    "win": {
      "target": [
        {
          "target": "nsis",
          "arch": ["x64"]
        }
      ],
      "sign": false
    }
  }
}
```

## 🛠️ 故障排除

### 常见问题

#### 1. npm install 失败
```bash
# 解决方案：使用国内镜像源
npm config set registry https://registry.npmmirror.com
npm config set electron_mirror https://npmmirror.com/mirrors/electron/
cnpm install
```

#### 2. Electron 启动失败
```bash
# 重新安装 electron
rm -rf node_modules/electron
cnpm install electron --save-dev
```

#### 3. 打包失败
```bash
# 清理缓存
npm cache clean --force
rm -rf node_modules
cnpm install
```

## 🤝 贡献指南

欢迎提交 Issue 和 Pull Request！

### 开发环境设置
1. Fork 项目
2. 创建功能分支: `git checkout -b feature/amazing-feature`
3. 提交更改: `git commit -m 'Add amazing feature'`
4. 推送分支: `git push origin feature/amazing-feature`
5. 创建 Pull Request

### 开发规范
- 使用 Vue 3 Composition API
- 遵循 ESLint 代码规范
- 组件命名使用 PascalCase
- 提交信息使用语义化格式

## 📄 许可证

本项目采用 MIT 许可证。详见 [LICENSE](LICENSE) 文件。

## 🙏 致谢

- [Vue.js](https://vuejs.org/) - 现代化前端框架
- [Electron](https://www.electronjs.org/) - 跨平台桌面应用框架
- [GSAP](https://greensock.com/gsap/) - 专业动画库
- [Pinia](https://pinia.vuejs.org/) - Vue 状态管理
- [Vite](https://vitejs.dev/) - 下一代构建工具

---

如果这个项目对你有帮助，请给一个 ⭐ Star 支持一下！

## 📞 联系方式

如有问题或建议，欢迎通过以下方式联系：

- 📧 邮箱：[your-email@example.com]
- 🐛 问题反馈：[GitHub Issues](https://github.com/your-username/choujiang/issues)
- 💬 讨论：[GitHub Discussions](https://github.com/your-username/choujiang/discussions)