Fair Random Number Generator | 公平隨機抽號器

English | 繁體中文

---

English

Description

A web-based random number generator built with FastAPI. It ensures fairness by picking numbers from a pre-defined pool and removing them until the pool is empty. It features a large, easy-to-read UI suitable for presentations or events.

Features

• Two Draw Modes:
  • Fair Mode (No Repeat): Each number is drawn only once from the specified range.
  • Pure Random Mode: Numbers are drawn randomly and may repeat.
• Repeat Detection: In Pure Random mode, a "Repeat!" badge appears if a number has been drawn before.
• Auto Zero-padding: Numbers are automatically padded with leading zeros based on the maximum value (e.g., 001 to 100).
• Bilingual Support: Supports both English and Traditional Chinese (Default: Traditional Chinese).
• Large & Compact UI: Optimized for high visibility while remaining compact for presentation screens.
• Smart Persistence: Remembers your range and mode settings even when resetting or toggling modes.
• Process Management: Automatically closes existing instances on port 80 when starting to ensure a smooth launch.
• Session-based: Keeps track of drawn numbers and remaining pool within the session.
• Security: Uses cryptographically strong random numbers (Python's secrets module) and limits range to 10,000 to prevent OOM.
• Fairness Verification: Includes a script to verify the uniform distribution of results.

Fairness Mechanism

This app ensures fairness through two layers:

1. Logical Fairness (Pool-based): Instead of just picking a random number, the app creates a "pool" containing all numbers in the specified range. When a number is picked, it is removed from the pool. This guarantees that every number is drawn exactly once, and no number is repeated or skipped.
2. Statistical Fairness (Cryptographic Randomness): The app uses Python's secrets module (secrets.randbelow) to select the index from the pool. Unlike the standard random module, secrets is designed for cryptography and provides high-quality randomness that is resistant to prediction.

You can run the verification script yourself to see the distribution:

uv run python tests/verify_fairness.py

Quick Start (Executable)

If you don't want to install Python, you can download the latest version from GitHub Releases.

1. Download RandomPicker.exe.
2. Verify file integrity immediately after download:
   Use Windows built-in certutil to generate a CRC/SHA256 hash:

   certutil -hashfile RandomPicker.exe SHA256
   

   Compare the output with the hash provided on GitHub Releases.
   ⚠️ If the hash does not match, do NOT run the program. Delete or re-download the file to ensure safety.
3. Double-click to run it.
4. Open your browser and navigate to http://127.0.0.1.

Installation (From Source)

1. Requirement: Python 3.13+ and uv.
2. Install dependencies:

   uv sync
   

Usage (From Source)

1. Run the application:

   uv run python exec.py
   

2. Open your browser and navigate to http://127.0.0.1.

License

This project is licensed under the Apache License 2.0. See the LICENSE file for details.

---

繁體中文

說明

一個基於 FastAPI 開發的網頁版隨機抽號器。它透過從預定義的池中抽取號碼並移除，直到所有號碼都被抽完，從而確保公平性。具備超大字體介面，非常適合在簡報、抽獎或各種活動中使用。

功能特點

• 雙重抽選模式：
  • 公平模式 (不重複)：確保在指定範圍內，每個數字只會被抽中一次。
  • 純隨機模式：每次抽取均為獨立隨機，數字可能會重複出現。
• 重複偵測：在「純隨機模式」下，若抽中已出現過的號碼，會顯示「重複！」標籤提示。
• 自動補零：根據最大值自動補齊前導零（例如：範圍 1-100 時顯示 001）。
• 雙語支持：支援英文與繁體中文（預設為繁體中文）。
• 清晰緊緻 UI：針對高能見度優化的超大字體，同時保持版面緊緻，適配各種簡報螢幕。
• 智慧設定記憶：在重置範圍或切換模式時，系統會自動保留您的輸入數值與模式選擇。
• 行程自動清理：啟動時會自動偵測並關閉舊有佔用 80 端口的行程，確保順利執行。
• 會話管理：在瀏覽器會話中記錄已抽出的號碼與剩餘數量。
• 安全性：使用密碼學等級的隨機數生成器（Python 的 secrets 模組），並限制範圍上限為 10,000 以防止記憶體溢出。
• 公平性驗證：內建驗證腳本，可測試結果的均勻分佈。

公平性機制

本應用程式透過兩個層面確保公平性：

1. 邏輯公平（基於號碼池）：程式並非單純隨機抽號，而是先建立一個包含範圍內所有號碼的「號碼池」。每當抽到一個號碼，就會將其從池中移除。這保證了每個號碼在一個循環內只會被抽中一次，不會重複也不會遺漏。
2. 統計公平（密碼學等級隨機性）：程式使用 Python 的 secrets 模組 (secrets.randbelow) 來從池中挑選索引。與標準的 random 模組不同，secrets 模組是專為密碼學設計的，提供高品質且難以預測的隨機性。

您可以自行執行驗證腳本來查看分佈情況：

uv run python tests/verify_fairness.py

快速開始 (執行檔)

如果您不想安裝 Python，可以從 GitHub Releases 下載最新版本。

1. 下載 RandomPicker.exe。
2. 檢查檔案完整性：
   使用 Windows 內建的 certutil 生成 CRC/SHA256 雜湊值：

   certutil -hashfile RandomPicker.exe SHA256
   

   將輸出與 GitHub Releases下載檔案時所提供的雜湊值比對。
   ⚠️ 如果雜湊值不一致，請不要執行程式。 建議刪除或重新下載檔案，以確保安全。
3. 雙擊執行該程式。
4. 開啟瀏覽器並造訪 http://127.0.0.1。

安裝步驟 (從原始碼)

1. 需求：Python 3.13+ 以及 uv。
2. 安裝依賴：

   uv sync
   

使用方式 (從原始碼)

1. 啟動應用程式：

   uv run python exec.py
   

2. 開啟瀏覽器並造訪 http://127.0.0.1。

授權條款

本專案採用 Apache License 2.0 授權。詳情請參閱 LICENSE 檔案。