# 随机抽取工具

**Repository Path**: user_gitee/RandomPick

## Basic Information

- **Project Name**: 随机抽取工具
- **Description**: 随机抽取一个人，随机采取多种方式，包括微秒时间种子以及secrets随机库，双随机机制。
- **Primary Language**: Python
- **License**: AGPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-10
- **Last Updated**: 2026-07-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: 抽签, 抽人, 抽取, 随机, 抽选

## README

# RandomPick — 随机抽选工具

<div align="center">

![RandomPick](https://img.shields.io/badge/版本-1.3.22-blue.svg)
![PyQt6](https://img.shields.io/badge/PyQt6-6.5+-green.svg)
![Python](https://img.shields.io/badge/Python-3.9+-yellow.svg)
![License](https://img.shields.io/badge/license-MIT-orange.svg)

**一款基于 PyQt6 的桌面随机抽取工具，支持人员管理、多模式抽取、动画展示与数据统计。**

</div>

---

## 目录

- [项目简介](#项目简介)
- [功能特性](#功能特性)
- [项目结构](#项目结构)
- [安装指南](#安装指南)
- [使用说明](#使用说明)
- [打包部署](#打包部署)
- [技术架构](#技术架构)
- [版本历史](#版本历史)
- [作者](#作者)
- [许可证](#许可证)

---

## 项目简介

RandomPick 是一款本地化运行的桌面随机抽取工具，适用于活动抽奖、课堂点名、随机分组等场景。程序采用**双随机机制**（安全随机打乱 + 整除取余选区），确保每次抽选结果不可预测且分布均匀。

### 核心特性

- **双随机抽取引擎**：基于 `secrets.SystemRandom()` 的安全随机 + 微秒时间种子混合
- **多种抽取模式**：单次抽取、多次抽取（可配置重复次数）、带动画滚动效果
- **人员管理**：支持增删改查、Excel 批量导入、头像裁剪
- **可视化统计**：表格 + matplotlib 柱状图展示中选概率分布
- **系统托盘**：最小化到托盘，后台持续运行

---

## 功能特性

### 1. 人员管理

| 功能 | 说明 |
|------|------|
| 新增人员 | 填写昵称、真实姓名，选择并裁剪头像 |
| 编辑人员 | 修改已有人员信息及头像 |
| 删除人员 | 删除人员同时清理关联头像文件 |
| 参与开关 | 每人可独立设置是否参与抽取 |
| Excel 导入 | 支持三种模式：单元格内嵌图片、直接路径引用、分批导入后自动匹配 |
| 搜索筛选 | 按昵称/真实姓名实时搜索 |

### 2. 随机抽取

- **单次抽取**：每次抽取 1 人，间隔可调
- **多次抽取**：一次抽取 N 人（可设置人数和重复次数）
- **三阶段动画**：快速 → 中速 → 慢速滚动，营造悬念效果
- **即时/延时显示**：可设置在动画结束时立即显示或结束后再显示结果

### 3. 结果展示

- **非模态弹窗**：渐变背景、大号头像、居中显示
- **自动关闭**：单次和多次结果可独立设置自动关闭时间
- **历史记录**：抽取历史列表，最多保留当前会话记录

### 4. 数据统计

- 按人员统计中选次数及概率
- 柱状图可视化展示（matplotlib）
- 支持清空历史记录

### 5. 个性化设置

- 昵称/真实姓名显示切换（卡片、抽取结果、历史记录独立控制）
- 三阶段动画速度独立调节
- 窗口布局、尺寸自动持久化
- 日志面板可见性控制

---

## 项目结构

```
RandomPick/
├── main.py                      # 主程序入口（单文件，1961 行）
├── RandomPick.spec              # PyInstaller 打包配置文件
├── requirements.txt             # Python 依赖列表
├── pyproject.toml               # 项目元数据配置
├── .gitignore                   # Git 忽略规则
├── MANIFEST.in                  # 打包数据文件清单
│
├── config/                      # 运行时配置
│   ├── settings.json            # 用户设置（自动生成）
│   └── stats.json               # 抽取统计记录（自动生成）
│
├── person/                      # 人员数据
│   ├── persons.json             # 人员列表（自动生成）
│   └── photo/                   # 人员头像（自动生成）
│       ├── 1_20260504194141.png
│       ├── 2_20260504194141.png
│       └── ...
│
├── template/                    # 导入模板
│   └── 人员导入模板.xlsx          # Excel 批量导入模板
│
├── docs/                        # 文档
│   └── README.md                # 本文件
│
├── tests/                       # 测试目录
│   └── __init__.py
│
├── resources/                   # 资源文件
│   └── app.ico (symlink/copy)   # 应用图标
│
└── dist/                        # 打包输出目录
    └── 随机抽取工具_V1.3.22.exe   # 已打包的可执行文件
```

---

## 安装指南

### 环境要求

- Python 3.9 或更高版本
- Windows 7+

### 安装步骤

```bash
# 1. 克隆或进入项目目录
cd RandomPick

# 2. （推荐）创建虚拟环境
python -m venv venv
.\venv\Scripts\Activate.ps1   # Windows PowerShell
# 或 .\venv\Scripts\activate.bat

# 3. 安装依赖
pip install -r requirements.txt
```

### 运行

```bash
# 直接运行
python main.py
```

---

## 使用说明

### 首次启动

1. 运行 `python main.py`
2. 程序自动生成 15-20 个示例人员及配置文件
3. 主界面左侧为人员卡片网格，右侧为操作面板

### 抽取操作

1. 在右侧面板选择**抽取人数**（1 或多人）
2. 设置**抽取次数**（多次模式有效）
3. 点击 **「开始抽取」** 按钮
4. 观看动画过程，结果弹窗自动展示

### 人员管理

- 点击 **「人员维护」** 进入管理界面
- 支持增删改查、批量导入、下载导入模板
- 可在**设置**中对人员参与状态批量控制

---

## 打包部署

使用 PyInstaller 打包为单文件 EXE：

```bash
# 安装 PyInstaller
pip install pyinstaller

# 使用项目 spec 文件打包
pyinstaller RandomPick.spec

# 打包后的 exe 位于 dist/RandomPick/
```

### 打包说明

- `RandomPick.spec` 已配置好隐藏导入（matplotlib、openpyxl）
- 输出为无控制台窗口的 GUI 程序
- 使用 `app.ico` 作为程序图标
- 数据目录（config、person、template）需与 exe 同级放置

---

## 技术架构

### 技术栈

| 组件 | 技术 | 用途 |
|------|------|------|
| UI 框架 | PyQt6 | 桌面窗口、控件、布局管理 |
| 图像处理 | Pillow (PIL) | 头像裁剪、缩放、生成 |
| 数据可视化 | matplotlib | 统计柱状图 |
| Excel 处理 | openpyxl | 人员批量导入模板 |
| 打包工具 | PyInstaller | 单文件 EXE 发布 |
| 随机引擎 | secrets + random | 安全随机打乱与抽取 |

### 核心设计

- **单文件架构**：全部代码集中在 `main.py`（1961 行），无模块拆分，便于快速部署和修改
- **JSON 持久化**：人员数据、设置、统计均以 JSON 文件存储，无需数据库
- **单实例保护**：通过 `QLocalServer` / `QLocalSocket` 确保程序只有一个实例运行
- **窗口状态持久化**：窗口位置、大小、分割条比例等自动保存

### 随机抽取算法

```
参与列表 → secrets.SystemRandom().shuffle() 打乱
       → 打乱后分配序号 → 整除取余选区 → 不放回抽取
       → 微秒时间种子辅助防重
```

### 依赖清单

| 包名 | 最低版本 | 用途 |
|------|---------|------|
| PyQt6 | ≥6.5 | GUI 框架 |
| Pillow | ≥10.0 | 图像处理 |
| matplotlib | ≥3.7 | 数据可视化 |
| openpyxl | ≥3.1 | Excel 导入导出 |

---

## 版本历史

### v1.3.22（当前版本）

- ✨ 多次抽取自动关闭改为独立复选框，默认启用 0.5 秒
- ✨ 单次/多次自动关闭可分开配置
- 🐛 优化了抽取动画逻辑

### v1.3.21

- ✨ 增加窗口状态持久化
- ✨ 优化卡片布局

### v1.3.20

- ✨ 增加三阶段动画速度设置
- ✨ 优化结果弹窗显示效果

### v1.3.x 系列

- 🎯 Excel 批量导入功能完善
- 🎯 头像裁剪功能
- 🎯 数据统计与可视化

### v1.0.x 系列

- 🚀 初始版本
- 🚀 基础随机抽取功能
- 🚀 人员管理基础功能

---

## 作者

**App14345**

- 项目名称：RandomPick（随机抽选工具）
- 原始名称：App14345

---

## 许可证

本项目基于 MIT 许可证开源，详见 LICENSE 文件。

---

*最后更新：2026-06*