# group

**Repository Path**: Tab-Tan/group

## Basic Information

- **Project Name**: group
- **Description**: 分组
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-07-05
- **Last Updated**: 2025-07-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 羽毛球大赛分组摇号系统

一个基于Python Flask + Redis的羽毛球大赛随机分组摇号系统，具有精美的前端界面和智能分组算法。

## 功能特点

- 🎯 **智能分组**: 自动确保A、B、C三组人数均衡
- 🎲 **随机摇号**: 真正的随机分组，公平公正
- 🔒 **防重复**: 每个队长只能摇号一次
- 💾 **数据持久化**: 使用Redis保存摇号结果
- 📱 **响应式设计**: 支持手机、平板、电脑访问
- ✨ **精美界面**: 转盘动画、呼吸按钮、实时更新

## 系统架构

```
├── server/
│   ├── app.py              # Flask后端应用
│   ├── config.json         # 配置文件
│   ├── requirements.txt    # Python依赖
│   ├── start.py           # 启动脚本
│   └── static/
│       ├── index.html     # 前端页面
│       ├── style.css      # 样式文件
│       └── script.js      # JavaScript逻辑
└── README.md              # 说明文档
```

## 快速开始

### 1. 环境要求

- Python 3.8+ (推荐 3.9+)
- Redis 服务器

**Python 3.8 用户特别说明:**
如果您使用的是Python 3.8，请使用专门的兼容性安装脚本：
```bash
cd server
python setup_py38.py
```

### 2. 安装Redis

**Windows:**
1. 下载Redis for Windows
2. 解压并运行 `redis-server.exe`

**Linux/Mac:**
```bash
# Ubuntu/Debian
sudo apt-get install redis-server
sudo systemctl start redis

# CentOS/RHEL
sudo yum install redis
sudo systemctl start redis

# Mac
brew install redis
brew services start redis
```

### 3. 配置系统

#### 方法一：配置文件方式

编辑 `server/config.json` 文件：

```json
{
  "total_participants": 30,    // 总参与人数
  "groups": ["A", "B", "C"],   // 分组名称
  "redis": {
    "host": "47.122.79.98",    // Redis主机
    "port": 6379,             // Redis端口
    "db": 0,                  // Redis数据库
    "password": "your_redis_password"  // Redis密码
  }
}
```

#### 方法二：环境变量方式（推荐，更安全）

1. 复制环境变量模板：
```bash
cp server/.env.example server/.env
```

2. 编辑 `server/.env` 文件：
```bash
REDIS_HOST=47.122.79.98
REDIS_PORT=6379
REDIS_DB=0
REDIS_PASSWORD=your_actual_redis_password
TOTAL_PARTICIPANTS=30
DEBUG=True
```

**注意**: 环境变量配置优先级高于配置文件

### 4. 启动系统

#### 🐍 Python 3.8 用户专用启动方式
```bash
cd server
python setup_py38.py  # 首次运行，自动安装兼容依赖
python app.py
```

#### 启动方式一：使用启动脚本 (Python 3.9+)
```bash
cd server
python start.py
```

#### 启动方式二：手动启动
```bash
cd server

# Python 3.9+ 用户
pip install -r requirements.txt

# Python 3.8 用户
pip install -r requirements_py38.txt

# 使用基础版本（配置文件）
python app.py

# 使用安全版本（支持环境变量）
python app_secure.py

# 使用演示版本（内存存储，无需Redis）
python app_demo.py
```

### 5. 访问系统

打开浏览器访问: http://localhost:5000

## 使用说明

### 队长摇号流程

1. 打开摇号页面
2. 输入队长姓名
3. 点击"开始摇号"按钮
4. 观看转盘动画
5. 查看摇号结果
6. 在下方查看当前分组情况

### 管理功能

- **查看配置**: GET `/api/config`
- **查看分组**: GET `/api/groups`
- **重置数据**: POST `/api/reset` (仅用于测试)

## API接口

### 获取配置信息
```http
GET /api/config
```

响应:
```json
{
  "total_participants": 30,
  "groups": ["A", "B", "C"],
  "total_drawn": 15,
  "remaining": 15
}
```

### 获取分组情况
```http
GET /api/groups
```

响应:
```json
{
  "A": ["张三", "李四"],
  "B": ["王五", "赵六"],
  "C": ["钱七", "孙八"]
}
```

### 摇号
```http
POST /api/draw
Content-Type: application/json

{
  "name": "队长姓名"
}
```

响应:
```json
{
  "success": true,
  "group": "A",
  "name": "张三",
  "groups": {
    "A": ["张三"],
    "B": [],
    "C": []
  }
}
```

## 核心算法

### 智能分组算法

系统采用智能分组算法，确保三组人数尽可能均衡：

1. 统计当前各组人数
2. 找出人数最少的组
3. 从人数最少的组中随机选择一个
4. 将新队长分配到选中的组

这样可以保证：
- 各组人数差距不超过1人
- 在人数均衡的前提下保持随机性

### 防重复机制

- 使用Redis存储已摇号的队长名单
- 每次摇号前检查队长是否已参与
- 确保每个队长只能摇号一次

## 技术栈

- **后端**: Python Flask
- **数据库**: Redis
- **前端**: HTML5 + CSS3 + JavaScript
- **样式**: 响应式设计，支持移动端
- **动画**: CSS3动画 + JavaScript控制

## 部署建议

### 生产环境部署

1. 使用Gunicorn作为WSGI服务器
2. 配置Nginx作为反向代理
3. 使用Redis集群确保高可用
4. 配置SSL证书启用HTTPS

### Docker部署

可以创建Dockerfile进行容器化部署：

```dockerfile
FROM python:3.9-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt
COPY . .
EXPOSE 5000
CMD ["python", "app.py"]
```

## 故障排除

### 常见问题

1. **Redis连接失败**
   - 检查Redis服务是否启动
   - 确认Redis配置正确

2. **端口被占用**
   - 修改app.py中的端口号
   - 或者停止占用5000端口的进程

3. **依赖安装失败**
   - 升级pip: `pip install --upgrade pip`
   - 使用国内镜像: `pip install -i https://pypi.tuna.tsinghua.edu.cn/simple -r requirements.txt`

4. **Python 3.8 兼容性问题**
   - 使用专用安装脚本: `python setup_py38.py`
   - 手动安装兼容版本: `pip install -r requirements_py38.txt`
   - 如果仍有问题，尝试使用虚拟环境:
     ```bash
     python -m venv venv
     # Windows
     venv\Scripts\activate
     # Linux/Mac
     source venv/bin/activate
     python setup_py38.py
     ```

5. **模块导入错误**
   - 确认使用正确的Python版本: `python --version`
   - 检查是否在正确的虚拟环境中
   - 重新安装依赖包

## 许可证

MIT License

## 联系方式

如有问题或建议，请提交Issue或联系开发者。