Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/StageGuard/SuperCourseTimetableBot

基于 mirai-console 的超级课表上课提醒QQ机器人插件
https://github.com/StageGuard/SuperCourseTimetableBot

Last synced: 3 months ago
JSON representation

基于 mirai-console 的超级课表上课提醒QQ机器人插件

Host: GitHub
URL: https://github.com/StageGuard/SuperCourseTimetableBot
Owner: StageGuard
License: agpl-3.0
Created: 2020-11-11T12:10:08.000Z (about 4 years ago)
Default Branch: main
Last Pushed: 2022-12-15T08:51:27.000Z (almost 2 years ago)
Last Synced: 2024-07-29T10:13:21.316Z (4 months ago)
Language: Kotlin
Homepage:
Size: 698 KB
Stars: 88
Watchers: 2
Forks: 10
Open Issues: 6
Metadata Files:
- Readme: README.md
- License: LICENSE

Awesome Lists containing this project

awesome-mirai - KonnyakuCamp/SuperCourseTimetableBot

README

# SuperCourseTimetableBot

一个基于 [mirai](https://github.com/mamoe/mirai/) 和 [mirai-console](https://github.com/mamoe/mirai-console) 的超级课程表提醒 mirai-console 插件。

![Gradle CI Status](https://github.com/StageGuard/SuperCourseTimetableBot/workflows/Gradle%20CI/badge.svg) [![CodeFactor](https://www.codefactor.io/repository/github/stageguard/supercoursetimetablebot/badge)](https://www.codefactor.io/repository/github/stageguard/supercoursetimetablebot)
## 特性

- #### Interactive Conversation Mode - 交互式聊天模式的用户接口

抛弃了传统的命令式交互，采用了更友好的交互式聊天模式。

- #### 允许用户更方便地修改时间表信息

可能超级课表上的作息时间表与学校不吻合，用户可以发送 **修改时间表** 来修改。

在交互式聊天模式的优势下，修改时间表的步骤变得非常容易。

- #### 允许用户自定义提醒时间

用户发送 **修改提前提醒时间** 即可通过步骤引导修改。

- #### 适配几乎所有使用超级课程表的高校

插件工作时，为每个正在使用的用户的高校分别计算当前周数和时间表，互不冲突。

- #### 数据库存储数据

使用 [MySQL](https://www.mysql.com/), [MariaDB](https://mariadb.org/) 或 [SQLite](https://www.sqlite.org/index.html) 存储用户的数据，当用户数量较多时依然保持良好的数据读取性能。

## 使用

### 立即体验

~~添加 QQ好友：xxxxxxxxx，将会自动同意好友请求并发送提示。~~

不再提供样例账号，请自行部署。

> 我的高校不使用超级课表APP，但是我也想试试这个 BOT：

> - 超级课程表APP 适配了国内大部分高校的教务系统，你可以尝试下载 APP，同步你的高校的课表。
> 若可以获取课表信息，那么恭喜你，这个 BOT 你也可以使用。

### 部署

SuperCourseTimetableBot 是**基于 `mirai-core 2.x` 版本和 `mirai-console 2.x` 版本的插件，不兼容 1.x 版本**。

1. 运行一个新的或使用现有的 MySQL, MariaDB 或 SQLite 数据库。
2. 在 [Releases](https://github.com/StageGuard/SuperCourseTimetableBot/releases/) 中下载 `SCTimetableBot-x.x.mirai.jar` 将其放入 mirai-console 的插件文件夹下。
3. 插件默认使用 SQLite 嵌入式数据库，启动 mirai-console，会有如下提示。

```
2021-12-21 11:18:41 I/SuperCourseTimetable: Plugin loaded
2021-12-21 11:18:41 I/SuperCourseTimetable: Database is connected.
2021-12-21 11:18:41 I/SuperCourseTimetable: Waiting target Bot 123456789 goes online...
```

4. 停止运行 mirai-console，进入 SuperCourseTimetableBot 配置文件 `config/SuperCourseTimetable/SG.SCTimeTableBotConfig.yml`，按照如下提示修改配置。

```yaml
# 用于工作的BOT的QQ号
qq: 123456789
# 默认提前多长时间提醒(单位：分钟)。
# 此值会在用户第一次被添加进数据库时设置给这个用户。
# 注意：如果你修改了这个值，在修改之前已经被设置的用户和自己设定值的用户不会受到影响。
advancedTipTime: 15
# 使用的数据库类型，支持 MySQL / MariaDB / SQLite
# 填 `mysql` 表示使用 MySQL 或 MariaDB。
# 填 `sqlite` 表示使用 SQLite。
# 填其他字符为无效选项。
# 当使用其中一个数据库类型时，另一个数据库配置不会生效。
database: sqlite
# MySQL / MariaDB 数据库配置。
# 若使用此数据库类型，请先手动创建数据库：
# create database `sctimetabledb`;
# 或其他你在下方 table 中指定的数据库名称。
mysqlConfig:
address: localhost
user: root
password: ''
table: sctimetabledb
maximumPoolSize: 10
# SQLite 数据库配置。
sqliteConfig:
# SQLite 数据库文件。
file: sctimetable.db
```

5. 重新运行 mirai-console，登录在第四步配置中指定的账号，SuperCourseTimetableBot 会输出如下提示：

```
2020-12-19 12:39:07 I/SuperCourseTimetable: TimeProviderService: Job YearUpdater is executed. (currentYear -> 2020)
2020-12-19 12:39:07 I/SuperCourseTimetable: TimeProviderService: Job SemesterUpdater is executed. (currentSemester -> 1)
2020-12-19 12:39:07 I/SuperCourseTimetable: ScheduleListenerService: Notification distribution job has executed.
2020-12-19 12:39:07 I/SuperCourseTimetable: TimeProviderService: Job SchoolWeekPeriodUpdater is executed.
```

这时 SuperCourseTimetableBot 就已经成功工作了。

> 注意：请确保运行 mirai-console 宿主机的时区和数据库时区是 `Asia/Shanghai` 并已同步北京时间！详见 [#4](https://github.com/StageGuard/SuperCourseTimetableBot/issues/4) 。

## 稳定性

SuperCourseTimetableBot 并未经过长期运行测试，对于其 `Quartz` 任务触发是否错误，我们暂时无法得知。

建议将 mirai-console 的日志等级调整为 `ALL`，以便捕获问题。

> 在调整日志等级为 `ALL` 后 HikariCP 和 Quartz 库在每10秒就输出一次日志：
>
> ```
> 2020-xx-xx xx:xx:Xx D/com.zaxxer.hikari.pool.HikariPool: HikariPool-1 - Pool stats (total=10, active=0, idle=10, waiting=0)
> 2020-xx-xx xx:xx:Xx D/com.zaxxer.hikari.pool.HikariPool: HikariPool-1 - Fill pool skipped, pool is at sufficient level.
> 2020-xx-xx xx:xx:Xx D/org.quartz.core.QuartzSchedulerThread: batch acquisition of 0 triggers
> ```
>
> 它的输出过于频繁，会遮盖住 `SuperCourseTimetableBot` 的输出，你可以在 console 的配置文件添加如下配置：
>
> ```yaml
> loggers:
> org.quartz.core.QuartzSchedulerThread: NONE
> com.zaxxer.hikari.pool.HikariPool: NONE
> ```
>
> 来禁用它们的输出。

如有任何问题，请立即新建一个 ISSUE 来反馈，我们非常需要知道是否有稳定性问题。

## 工作原理 & 源码解析

如果你想了解 SuperCourseTimetableBot 是如何工作的，请阅读 [SuperCourseTimetableBot 代码结构解析](source-analyze.md)。

## TODO("")

- [x] 手动修改时间表
- [x] 在时间表被修改时通知本校其他用户
- [ ] 支持手动添加课程(补课或永久调整的课程)
- [ ] ~~使用 `Mozilla Rhino` 通过动态 `JavaScript` 来适配不同的教务系统~~

## 开发计划

SuperCourseTimetableBot 插件将会在 `1.0` 版本允许动态适配不同教务系统(详见上方 `TODO` 第四条)，完全重构 `RequestHandlerService` 和 `BotRouteEventService`，并实现自定义文本/自定义语音/自定义图片提醒。

## 贡献

欢迎任何~~使用者~~大佬们贡献这个项目，你可以通过**反馈 BUG**，**提出 Pull Request** 申请，~~或修改文档错别字~~来贡献这个项目。

> 如果你有贡献这个项目的想法，建议你先浏览一下上面的代码结构解析。

## 使用的开源库

- [mirai](https://github.com/mamoe/mirai/) - 高效率 QQ 机器人框架 / High-performance bot framework for Tencent QQ.
- [mirai-console](https://github.com/mamoe/mirai-console) - mirai 的高效率 QQ 机器人控制台.
- [Exposed](https://github.com/JetBrains/Exposed) - A Kotlin SQL Framework.
- [HikariCP](https://github.com/brettwooldridge/HikariCP) - 光 HikariCP・A solid, high-performance, JDBC connection pool at last.
- [Quartz](https://github.com/quartz-scheduler/quartz) - A richly featured, open source job scheduling library.
- [yamlkt](https://github.com/Him188/yamlkt) - Multiplatform YAML parser & serializer for kotlinx.serialization written in pure Kotlin.

## 许可证协议

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU Affero General Public License as published
by the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU Affero General Public License for more details.

You should have received a copy of the GNU Affero General Public License
along with this program. If not, see .
```