Collab Management Telegram Bot

Телеграм бот для коллаб-менеджеров.

Запуск на Windows

Установите Python 3.11.2. Не забудьте поставить галочку напротив "Add Python to PATH".
Установите пакетный менеджер Poetry.
Установите PostgreSQL.
Скачайте или склонируйте этот репозиторий.
В файле .env:
1. Установите BOT_TOKEN, взятый из BotFather.
2. Установите DATABASE_URL в формате postgresql+psycopg://user:password@server/db
В папке проекта пропишите следующие команды:

poetry update
alembic upgrade head

Добавьте администратора в бота
Для запуска бота пропишите следующую команду:

poetry run python -m bot

Добавление администратора

Добавить администратора в базу данных можно напрямую SQL запросом, например, через pgAdmin:

INSERT INTO manager (telegram_id, is_admin, created_at)
VALUES (10000000000, TRUE, (now() at time zone 'utc'));
--      ┗━ Telegram ID администратора

Либо с помощью команды из папки проекта:

python addadmin.py 10000000000

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

После добавления администратора рекомендуется зайти с аккаунта администратора в бота и прописать команду /set_username

Администратор может удалить администратора через бота командой /delete_manager

Детали реализации

Язык: Python 3.11
База данных: PostgreSQL
Менеджер пакетов: Poetry
Пакеты:
- Телеграм: aiogram 3.0
- Логирование: loguru
- База данных: psycopg 3 + SQLAlchemy 2.0 (ORM) + Alembic (Миграции)

Ход реализации

Терминология

TSS — TweetScout Score.
Представитель — человек, представляющий интересы проекта (чаще всего это коллаб-менеджер или администратор).
Оценка — лайк или дизлайк.

База данных

Описание таблиц и логики базы данных.

База данных обязана делать резервное копирование, чтобы в случае непредвиденных обстоятельств можно было откатиться.

[manager] Таблица с данными о менеджерах

Поле	Описание
telegram_id (Первичный ключ)	Telegram ID
created_at	Дата и время внесения в таблицу
telegram_handle	Telegram Handle
is_admin	Является ли администратором

При удалении менеджера (manager) также должны удаляться все относящиеся к нему записи из таблицы оценок (vote).

[project] Таблица с данными о проектах

Поле	Описание
twitter_handle (Первичный ключ)	Twitter Handle
created_at	Дата и время внесения в таблицу
tss	TSS (TweetScout Score)
tss_requested_at	Дата и время последнего запроса TSS
manager.telegram_id (Внешний ключ)	Telegram ID ведущего проект менеджера
likes	Количество лайков
dislikes	Количество дизлайков

При удалении проекта (project) также должны удаляться все относящиеся к нему записи из таблицы (vote).
При обновлении значения tss должно обновляться tss_requested_at.
twitter_handle должен быть либо нечувствительным к регистру, либо только в определенном (нижнем) регистре.

[vote] Таблица с оценками (лайками и дизлайками)

Поле	Описание
manager.telegram_id (Внешний ключ)	Telegram ID менеджера
project.twitter_handle (Внешний ключ)	Twiiter Handle проекта
vote_type	Оценка: лайк или дизлайк

При внесении в таблицу новой оценки (vote) счетчик лайков (project.likes) или дизлайков (project.dislikes) проекта должен инкрементироваться (увеличиваться на один). При удалении, наоборот — декрементироваться (уменьшаться на один).

Доступные форматы ссылок на твиттер

Доступные форматы ссылки на твиттер:

https://twitter.com/elonmusk
https://twitter.com/@elonmusk
https://twitter.com/elonmusk?lang=en
https://twitter.com/@elonmusk?lang=en
@elonmusk
elonmusk

Длина Twitter Handle без @ не может превышать 15 символов.

Менеджер: роли

Существует три роли: пользователь, менеджер и администратор.

Роль менеджера пользователю можно назначить с помощью команды /add_manager, доступной только администраторам.

Роль администратора можно назначить только напрямую через базу данных установкой флага is_admin в состояние True.

Менеджер: формат вывода информации

Формат вывода информации о менеджере включает в себя следующую информацию:

Роль менеджера.
Telegram Handle менеджера.
Telegram ID менеджера.

Вся информация умещается в одну строчку.

Пример вывода информации о менеджере:

# ┏━ Роль
# ┃      ┏━ Telegram Handle
# ┃      ┃          ┏━ Telegram ID
[Admin] @AlenKimov (123456789)

Команды бота

Команды для обычных пользователей (не менеджеров):

/start — содержит в себе приветственное сообщение и инструкцию, как стать менеджером.
/help — содержит в себе инструкцию, как стать менеджером.
Если пользователь попробует ввести команду для менеджеров, выведется сообщение с информацией о том, что это команда доступна только менеджерам, и с отсылкой на команду /help.

Команды для менеджеров:

/help — содержит в себе описания всех команд для менеджеров.
/my (/me) — выводит список всех взятых менеджером проектов, отсортированных по дате взятия.
/best — выводит список из 5-ти никем не взятых проектов в порядке убывания лайков и в порядке убывания TSS. Не выводит проекты, добавленные менее 5 минут назад.
/new — выводит список из 5-ти никем не взятых проектов без оценок, отсортированных по новизне и в порядке убывания TSS. Не выводит проекты, добавленные менее 5 минут назад.
/set_username — заносит Telegram Handle менеджера в базу.

Команды для администраторов:

/help — содержит в себе описания всех команд для менеджеров и администраторов.
/managers — выводит список всех менеджеров и администраторов.
/add_manager [telegram_id] — добавляет менеджера с указанным Telegram ID.
/delete_managers [telegram_id] (/delete_manager) — удаляет менеджеров с указанными Telegram ID.
/delete_projects [twitter_handle] (/delete_project) — удаляет проекты с указанными Twitter handle.
(не реализовано) /top_managers_day — выводит список менеджеров в порядке убывания количества поставленных оценок за день.
(не реализовано) /top_managers_week — выводит список менеджеров в порядке убывания количества поставленных оценок за неделю.
(не реализовано) /top_managers_month — выводит список менеджеров в порядке убывания количества поставленных оценок за месяц.
(не реализовано) /download_excell — возвращает базу данных в виде файла excell-таблицы.

Проект: форматы вывода информации

Выводить информацию о проекте можно в двух форматах:

Краткий формат
Полный формат

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

Краткий формат

Краткий формат вывода включает в себя лишь базовую информацию о проекте:

Оценка проекта.
TSS проекта.
Ссылка на твиттер проекта.
Telegram handle ведущего.

Краткая информация о проекте должна умещаться в одну строчку.

Примеры вывода базовой информации о проекте без ведущего:

# ┏━ Лайки
# ┃  ┏━ Дизлайки
# ┃  ┃   ┏━ TSS
# ┃  ┃   ┃     ┏━ Затекстовая ссылка на твиттер проекта
# ┃  ┃   ┃     ┃                 ┏━ Никнейм ведущего
[+1/-0] (0227) TweetScout_io  -> @AlenKimov
#              |<- - - - - ->| Фиксированный размер в 15 символов

Если проект добавлен менее 5-ти минут назад, не имеет оценок и ведущего, то в информации о проекте на месте оценок будет плашка NEW!:

[NEW!] (0227) TweetScout_io

Полный формат

Полная формат вывода помимо базовой информации включает в себя следующие поля:

(не реализовано) Ссылка на дискорд проекта.
(не реализовано) Никнейм представителя в дискорде.
Дата и время добавления проекта.

Пример вывода полной информации (базовая + дополнительная) о проекте:

[+1/-0] (0227) TweetScout_io  -> @AlenKimov
#        ┏━ Ссылка на дискорд
#        ┃                               ┏━ Никнейм представителя в дискорде
discord: https://discord.gg/uwAefKCj7X | keksich13#1242
#                    ┏━ Дата и время добавления проекта
Проект был добавлен: 2023-03-24 14:55:59

Проект: меню работы

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

Бот вернет сообщение с полной информацией о проекте.

Бот предложит следующий выбор действий:

Лайк
Дизлайк
Стать ведущим/Отказаться от ведения — эта функция доступна, если проект еще не взят на ведение другим менеджером.
Запросить TSS — запрашивает TSS через API TweetScout и присваивает его проекту. TSS можно запрашивать лишь раз в 2 минуты.
(не реализовано) Дискорд — позволяет внести в базу ссылку на дискорд и ник представителя проекта.

(не реализовано) Список проектов: формат вывода

Список проектов выводится только в кратком формате:

[+1/-0] (5286) elonmusk       -> @AlenKimov
[+1/-0] (0227) TweetScout_io
[+0/-0] VitalikButerin

(не реализовано) Список проектов: меню работы

Запросить TSS — запрашивает TSS проектов из списка.
Пройтись по проектам — позволяет пройтись по каждому из новых проектов по очереди. Это открывает особое меню работы с проектом с клавиатурой следующего содержания:
- Верхний слой:
  - Меню работы с проектом
- Нижний слой:
  - Назад — возвращает к предыдущему проекту.
  - Стоп — возвращает к списку проектов.
  - Вперед — переходит к следующем проекту.

Запрос и внесение проектов

Дроп в бота / Запрос проекта(ов) / Внесение проекта(ов) — отправка боту одной или нескольких ссылок на проект в любом из доступных форматов.

Если менеджер дропает один проект:

Бот возвращает меню работы с проектом как для нового, так и для уже известного проекта.

Если менеджер дропает несколько проектов, то бот разбивает дроп на три списка:

Проекты с ведущими:

[+1/-0] (5286) elonmusk       -> @AlenKimov
[+1/-0] (0227) TweetScout_io  -> @AlenKimov
[+0/-0] (0010) VitalikButerin -> @AlenKimov

Проекты без ведущих:

[+0/-0] (5286) elonmusk
[+0/-0] (0227) TweetScout_io
[+0/-0] VitalikButerin

Новые проекты:

[NEW!] (5286) elonmusk
[NEW!] (0227) TweetScout_io
[NEW!] VitalikButerin

Name		Name	Last commit message	Last commit date
Latest commit History 74 Commits
alembic		alembic
bot		bot
.env		.env
.gitignore		.gitignore
.gitmessage		.gitmessage
README.md		README.md
addadmin.py		addadmin.py
alembic.ini		alembic.ini
poetry.lock		poetry.lock
pyproject.toml		pyproject.toml

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

Collab Management Telegram Bot

Запуск на Windows

Добавление администратора

Детали реализации

Ход реализации

Терминология

База данных

Доступные форматы ссылок на твиттер

Менеджер: роли

Менеджер: формат вывода информации

Команды бота

Проект: форматы вывода информации

Краткий формат

Полный формат

Проект: меню работы

(не реализовано) Список проектов: формат вывода

(не реализовано) Список проектов: меню работы

Запрос и внесение проектов

About

Languages

alenkimov/collab_management_bot

Folders and files

Latest commit

History

Repository files navigation

Collab Management Telegram Bot

Запуск на Windows

Добавление администратора

Детали реализации

Ход реализации

Терминология

База данных

Доступные форматы ссылок на твиттер

Менеджер: роли

Менеджер: формат вывода информации

Команды бота

Проект: форматы вывода информации

Краткий формат

Полный формат

Проект: меню работы

(не реализовано) Список проектов: формат вывода

(не реализовано) Список проектов: меню работы

Запрос и внесение проектов

About

Topics

Resources

Stars

Watchers

Forks

Languages