Compoly bot - бот для чата потока ИВТ в Санкт-Петербургском Политехническом Университете Петра Великого (СПбПУ).

Данный бот может быть использован для Ваших разработок в этой области в качестве платформы с указанием авторства.

Ниже представлены основные положения по разработке, а так же некоторая документация.

Данный бот имеет гибкую модульную систему для обработки любой логики чата.

Модуль -- object, помеченный аннотацией, который может содержать функции-обработчики различных событий.

Событие -- то, что происходит в чате. Примером такого ивента является LongPoolNewMessageEvent. Он содержит некоторые параметры (такие, как текст сообщения, id чата, ...). Они должны быть использованы для обработки события и реакции на него.

Функция обработчик должна быть помечена одной из возможных аннотаций, таких как OnCommand (обработчик будет вызван, если пользователь отправит команду, переданную в аннотации) или OnMessage (обработчик будет вызван на любое сообщение). Пример модуля с двумя обработчиками представлен ниже.

@ModuleObject
object Example {
    @OnCommand(["команда", "аллиас1", "аллиас2"], "Описание команды")
    fun onCommandExample(event: LongPollNewMessageEvent) {
        // example of using TextMessageParser class
        // it allows to parse text, for example, to find user mentions 
        val userTarget = parsed.get<Mention>(1)
        val api = event.api
        val chatId = event.chatId
        api.send("Вы упомянули пользователя: $targetUser", chatId)
    }
    
    @OnMessage
    fun onMessageExample(event: LongPollNewMessageEvent) {
        val api = event.api
        val text = event.text
        api.send("Текст сообщения: $text")
    }
}

Больше примеров может быть найдено в пакете chatbot.chatModules.

Тесты являются основой для разработки. Для каждого модуля они должны быть написаны.

Для каждой группы тестов необходимо создать отдельную директорию в tests/kotlin/testData. В ней необходимо создать файл messages.txt в json-списком, содержащим объекты сообщений. Каждое сообщение по-очереди будет передано боту, а его вывод будет представлен в файле send-out.txt.

Для эмуляции VK API используется mock-заглушка. Для того чтобы эмулировать API, необходимо создать txt-файл с именем apiName-in.txt, например, isUserAdmin-in.txt. Внутри идут строки, для каждого результата вызова функции своя строка. Эти значения будут возвращаться по-очереди для каждого вызова функции. После возвращения значения с последней строки будет возвращено значение на первой строке.

Каждый вызов API записывается в файл с именем apiName-out.txt, например, в isUserAdmin-out.txt. Туда записываются аргументы вызова.

Для эмуляции таблиц базы данных с заранее известными значениями используются файлы с именем tablename.sql, например, userscore.sql. Каждый из них содержит sql запросы, которые выполняются перед каждым тестом. После каждого теста создаётся дамп таблиц БД в файл с именем PUBLIC.TABLE_NAME.sql.dump, например, PUBLIC>USERSCORE.sql.dump

В конце каждого теста происходит сравнение того, что фактически было получено во время теста с текущим содержимым каждого описанного выше файла.

Для создания кода для запуска теста необходимо запустить main-функцию в файле test/kotlin/chatbot/base/GenerateAllTests.kt. После, будут созданы нужные функции в файле test/kotlin/chatbot/codegen/TestsGenerated.kt

Для первичной настройки бота запустите его. В корневой директории создастся файл config.properties. В него необходимо внести значения, такие как vkApiToken (ключ для доступа к VK API, для его получения необходимо создать группу ВКонтакте и создать ключ в настройках этой группы), weatherKey (ключ с сайта openweathermap), botId (ID созданной группы ВКонтакте), mainChatPeerId (id основного чата). Параметр useDebugTime включает режим фиктивного времени. Это значит, что в модулях, которые это поддерживают, будет использоваться время, указанное в коде, а не системное.

Важно: не сообщайте другим людям вписанные значения и не допускайте попадание файла config.properties в PR.

Они позволяют осуществлять действия по расписанию. Например, делать рассылки с прогнозом погоды (modules/events/weather), поздравлениями с днями рождений (modules/events/happyBirthday) или отсчитывать время до даты (modules/events/daysUntil).

Каждый из таких модулей должен представлять собой класс, реализующий интерфейс Event и отмеченный аннотацией @Active. Аннотация (ее отсутствие) позволяет отключать модуль.

Отдельным типом автоматических модулей являются модули, которые выполняются по периоду времени. Например, модуль modules/loops/pageChecking. Каждый из них это класс, реализующий интерфейс Loop и отмеченный аннотацией @Active.

1. Для каждого изменения создаётся ветка вида ник/короткое-имя. Например, vldf/tests.
2. Для предложения переноса правки из ветки в master ветку должен быть создан pull request.
3. Изменения могут быть отвергнуты в связи с некоторым рядом внутренних, непрозрачных причин.

По любым вопросам, относящимся к проекту, Вы можете писать в:

1. VK: https://vk.com/mrvladf
2. TG: @vldfx