mirror of
https://github.com/HChaZZY/Random-Picker.git
synced 2025-12-06 10:33:50 +08:00
186 lines
11 KiB
Markdown
186 lines
11 KiB
Markdown
# 随机点名器 README
|
||
|
||
> 当前`README.md`以 `点名器 v1.2.3` 为最新版，会与最新版本持续更新。
|
||
|
||
## 基本结构
|
||
|
||
当运行来自最新版安装包时，安装包将把内容解压至目标目录，目录结构如下：
|
||
|
||
```
|
||
解压目录.
|
||
| 点名器.exe
|
||
|
|
||
+---assets
|
||
| LICENCE
|
||
| proc.wav
|
||
| sel.wav
|
||
| 点名器.ico
|
||
|
|
||
+---log
|
||
| *.log
|
||
|
|
||
\---data
|
||
* config.data
|
||
names.xls
|
||
```
|
||
|
||
## 文件功能
|
||
* 点名器.exe
|
||
- 点名器主程序
|
||
- 若要使用点名器，请双击此文件以启动点名器
|
||
* assets文件夹
|
||
- 存放软件静态资源文件
|
||
- 删除其中文件，乃至删除整个assets文件夹**均不会**导致软件彻底无法使用，部分功能可能失效，但主要点名功能不受影响
|
||
- LICENCE
|
||
+ 许可证文件
|
||
+ 在分发本软件的编译版本时，请随附此文件
|
||
- proc.wav
|
||
+ 选择中音效
|
||
+ 该音效当前未实装
|
||
+ 欲更改选择中音效，请将目标音效转化为`*.wav`格式，并重命名为`proc.wav`，将老音效文件覆盖。
|
||
+ 对本文件的删除、重命名、更改格式等操作将会导致程序在启动时提示`资源文件错误`，继续进入软件会导致不会出现任何音效（包括选择中音效和选中音效）
|
||
- sel.wav
|
||
+ 选中音效
|
||
+ 欲更改选中音效，请将目标音效转化为`*.wav`格式，并重命名为`sel.wav`，将老音效文件覆盖。
|
||
+ 对本文件的删除、重命名、更改格式等操作将会导致程序在启动时提示`资源文件错误`，继续进入软件会导致不会出现任何音效（包括选择中音效和选中音效）
|
||
- 点名器.ico
|
||
+ 软件图标
|
||
+ 虽然应用程序图标，软件左上角图标与Windows底部的任务栏图标一致，但是该点名器.ico仅影响软件左上角图标。
|
||
+ 欲更改软件左上角图标，请将目标图标转化为`*.ico`格式，并重命名为`点名器.ico`，将老图标文件覆盖
|
||
+ 本文件的删除、重命名、更改格式等操作将会导致程序在启动时提示`资源文件错误`，继续进入软件会在应用左上角加载默认图标
|
||
* log文件夹
|
||
+ 内部存放软件生成的所有日志文件
|
||
+ 日志命名方式：YYYY-MM-DD [HH:MM:SS]，时间以应用运行时的系统本地时间为准。
|
||
+ 可以通过传入 `--log-level-**DEBUG/INFO/WARN/ERROR/FATAL/SILENT**` 更改日志等级
|
||
+ `DEBUG`日志等级仅供排障使用，不在log文件内提示。
|
||
+ 可以通过传入 `--disable-logging` 关闭日志记录。
|
||
* data文件夹
|
||
- 存放软件使用所需的数据库文件
|
||
- 删除其中的`names.xls`文件，会导致软件**报错并退出**
|
||
- names.xls
|
||
+ 该文件存放点名所使用的所有数据
|
||
+ 该文件的格式为`*.xls`，如果使用的是Excel 2007及以后版本生成数据库，请注意此时Excel的默认保存格式为`*.xlsx`，该文件**无法被软件识别**
|
||
+ 表格文件的格式如下：
|
||
|
||
|序号|班级|学科|姓名|
|
||
|:---:|:---:|:---:|:---:|
|
||
|......|......|......|......|
|
||
|......|......|......|......|
|
||
|
||
+ 请保证除了首行以外，至少有一行的有效数据，否则软件将**报错并退出**
|
||
- config.data
|
||
+ 该文件是**可选**的，删除该文件不会对软件产生任何`表面上的`影响
|
||
+ 该文件操控本软件的一个隐藏功能：概率隐藏修改
|
||
+ 提供三大功能：移除，概率减少，概率增加：
|
||
- 移除功能
|
||
+ 移除功能将将指定序号的数据列为禁止录入的列表中，即该序号所代表的人即使存在于数据库中，仍然不会录入至软件的数据库中，也不会被选中。
|
||
- 概率减少功能
|
||
+ 被列为概率减少的序号，将会触发以下机制：
|
||
+ 每次随机选取，均会有`(8 * 被列为概率减少的序号人数)%`的概率不抽取他们
|
||
+ 这个概率的上限是40%，当人数大于5人时，所有人共享40%的概率
|
||
- 概率增加功能
|
||
+ 被列为概率增加的序号，将会触发以下机制：
|
||
+ 每次随机抽取，均会有`(5 * 被列为概率增加的序号人数)%`的概率抽取他们
|
||
+ 这个概率的上限是30%，当人数大于6人时，所有人共享30%的概率
|
||
+ 由于以上机制被随机抽到的情况，将不受适用于一般人的`防反复抽取机制`的影响，即有可能出现连续两次都是标记为概率增加的序号的情况
|
||
+ 通过编辑`config.data`文件来执行修改概率功能
|
||
- `config.data`文件由`N`行组成，`N`为需要修改概率的总人数
|
||
- 每一行由`X,P`组成，`X`为需要修改概率的序号，`P`为`+`/`-`/`0`中的任意一个
|
||
+ 当`P`为`+`时，该行对应的X序号将被列入概率增加的列表中
|
||
+ 当`P`为`-`时，该行对应的X序号将被列入概率减少的列表中
|
||
+ 当`P`为`0`时，该行对应的X序号将被列入移除列表中
|
||
- 全程请务必使用**英文符号**，并严格按照语法编写
|
||
- 如果出现语法不合法的情况，预期的软件反应是拒绝读取`config.data`文件，但由于概率修改是隐藏功能，如果出现任何bug没有任何日志可以记录，也不保证软件一定按期望进行操作，请在编辑该文件的时候谨慎操作
|
||
|
||
## 软件使用方法
|
||
欲使用本点名器软件来进行随机点名，请双击安装目录下的`点名器.exe`文件
|
||
|
||
如果正常启动，软件应打开此页面
|
||
|
||
|
||
|
||
如果未能正常启动，请参阅本文档[可能出现的错误和解决方法](#可能出现的错误和解决方法)章节
|
||
|
||
正常启动后，右侧为班级选择器，班级列表是由数据库中的数据自动生成的
|
||
|
||
点击对应班级，可以选择仅抽取指定班级的人，这个选择可以多选
|
||
|
||
|
||
|
||
如果不进行选择，则默认在所有班级中挑选
|
||
|
||
点击`立即摇人！`，即可按照当前选择的班级中随机挑选一名，并显示在软件主页面上并播放一段音效
|
||
|
||
|
||
|
||
会默认播放游戏《只狼·影逝二度》中，对方使出不可振刀攻击时的「危」的音效
|
||
|
||
点击`应用班级选用`，即可应用当前选中的班级筛选，并进行弹窗提示
|
||
|
||
|
||
|
||
如果没有选择任何班级，软件会选中所有班级，并提示用户
|
||
|
||
|
||
|
||
> 对隐藏功能的影响：按下这个按钮同时会导致本次启动被标记为概率增加的人和概率减少的人的概率更改失效，这个失效对被标记为移除的人无效。重启本软件即可恢复概率调整功能
|
||
|
||
## 可能出现的错误和解决方法
|
||
|
||
* 提示类
|
||
- 资源文件错误
|
||
|
||
|
||
> 如图，当软件未能检测到assets文件夹中的某些内容时，会弹出的提示
|
||
|
||
+ 当软件未能检测到assets文件夹中的内容时，会提醒用户资源文件错误
|
||
+ 点击`确定`可继续使用软件，点击`取消`会关闭软件
|
||
+ 如果继续使用软件，某些软件功能，包括但不限于`图标显示/音效文件播放`可能无法使用
|
||
+ 可能的解决方法
|
||
- 检查assets文件夹是否存在，如果不存在，请重新安装本软件
|
||
- 检查assets文件夹是否拼写正确，是否与`点名器.exe`在相同的路径，如果不正确，请人工恢复
|
||
- 检查assets文件夹内内容是否拼写正确，格式正确，如果不正确，请人工恢复
|
||
* 错误类
|
||
- 找不到数据库文件
|
||
|
||
|
||
>如图，当软件未能找到数据库文件时，会弹出的错误信息
|
||
|
||
+ 当软件未能检测到`names.xls`数据库文件时，会弹出错误信息，此时软件将**无法运行**
|
||
+ 可能的解决方法
|
||
- 检查`names.xls`文件是否存在，是否拼写正确，格式正确，如果不正确，请人工恢复
|
||
- 检查`names.xls`文件是否在正确的路径下(点名器根目录/data/names.xls)，如果不正确，请人工恢复
|
||
- 数据库文件格式不正确
|
||
|
||
|
||
>如图，当软件识别到数据库文件格式不正确时，会弹出的错误信息
|
||
|
||
+ 当软件识别的`names.xls`数据库文件格式不正确时，会弹出的错误信息，此时软件将**无法运行**
|
||
+ 数据库文件要求至少两行（包括首行）与正好四列的数据，如果不符合则会弹出此错误信息
|
||
+ 可能的解决方法
|
||
- 检查`names.xls`文件是否有多余的数据干扰软件，如果存在，请人工排除（可以查看错误信息中的软件访问的行列数据辅助排查）
|
||
- 其他错误/可能的解决方案无效
|
||
+ 请在[gitee仓库](https://gitee.com/hchazzy/random_picker)中检查是否有新版本，如果有，请删除本软件，并重新安装最新版本
|
||
+ 如果仍未解决问题，请将`/log`目录打包并发送至作者邮箱<peter13632530821@163.com>
|
||
|
||
## 可选的传参
|
||
* --help 查看帮助对话框
|
||
* --licence 查看许可证信息
|
||
* --version 查看版本信息
|
||
* --path 查看程序运行路径
|
||
* --top-most 使用置顶运行方式
|
||
* --disable-logging 关闭日志记录
|
||
* --log-level-*INFO/WARN/ERROR/FATAL/SILENT* 调整日志等级为`INFO/WARN/ERROR/FATAL/SILENT`
|
||
|
||
## 关于本软件
|
||
本软件受`GNU General Public License v3.0`开源协议保护，任何人均可在遵守[本协议](https://www.gnu.org/licenses/)的前提下随意使用/修改本软件，任何对本软件的分发需随附源码与许可证，如果对本软件进行了修改并二次分发，请注明修改部分及修改时间，详细内容请参阅[GPL v3协议](https://www.gnu.org/licenses/)。
|
||
|
||
你可以在[这里](https://gitee.com/hchazzy/random_picker/blob/master/LICENCE)查看随源码附带的LICENCE文件，如果需要分发本软件，请随附此许可证。
|
||
|
||
如果需要分发软件的编译版本，也请随附LICENCE文件，如果不便附加文件，请告知[查看LICENCE文件的方法](#推荐的在编译版本中查看licence的方法)。
|
||
|
||
#### 推荐的在编译版本中查看LICENCE的方法：
|
||
运行本程序时，传入`--licence`参数，程序将打开许可证信息并提示用户访问LICENCE文件。可以通过`命令提示符`或`快捷方式`来运行程序以传入参数。
|
||
|
||
> The actual science of logic is conversant at present only with things either certain, impossible, or entirely doubtful, none of which (fortunately) we have to reason on. Therefore the true logic for this world is the calculus of probabilities, which takes account of the magnitude of the probability which is, or ought to be, in a reasonable man’s mind.
|
||
> <p align="right">----James Clerk Maxwell (1850)</p> |