🤖 OTSKVMBot — Бот для учёта состояния аудиторий

---

📋 О проекте

OTSKVMBot — Telegram-бот для инженеров технического сопровождения конгрессно-выставочных мероприятий СПбПУ. Бот позволяет быстро отмечать состояние аудиторий, отслеживать проблемы, координировать работу и интегрироваться с Google Calendar.

Проект разработан для автоматизации процессов отдела и перехода от реактивного обслуживания к проактивному управлению инфраструктурой.

---

🎯 Возможности

📊 Учёт статусов аудиторий

• ✅ Быстрая отметка состояния аудиторий (/status)
• ✅ Визуальные статусы: 🟢 green (всё ок), 🟡 yellow (проблемы), 🔴 red (не работает)
• ✅ Комментарии к проблемным статусам
• ✅ Просмотр текущего статуса при выборе аудитории
• ✅ История изменений для аналитики

👥 Командная работа

• ✅ Постоянное меню в отдельном топике
• ✅ Уведомления об изменениях статусов в общий чат
• ✅ Назначение ответственных на мероприятия (/assign)
• ✅ Подтверждение/отказ от назначений
• ✅ Статусы: назначен, подтверждён, выполнен, отменён

📅 Интеграция с Google Calendar

• ✅ Команда /today — мероприятия на сегодня
• ✅ Кнопки навигации: Сегодня / Завтра / Неделя
• ✅ Автоматическая синхронизация каждые 6 часов
• ✅ Привязка событий к аудиториям
• ✅ Поддержка событий на целый день и с конкретным временем

🔔 Система уведомлений и напоминаний (Новое в v0.4.0)

• ✅ Напоминания ответственным за 30 минут до мероприятия
• ✅ Кнопки подтверждения и запроса замены
• ✅ Автоматическое завершение мероприятий через час после окончания
• ✅ Ручное завершение мероприятий инженером
• ✅ Дневной отчёт в 14:00 со статистикой
• ✅ Логирование всех уведомлений в БД

🗣️ Транслитерация

• ✅ Русские названия хранятся в БД в английской транслитерации
• ✅ Автоматическая конвертация в русский при показе пользователю
• ✅ Никаких проблем с кодировками

🛠 Административная панель

Для пользователей с ролью superadmin доступна расширенная панель управления с тестовыми и диагностическими функциями.

🔧 Доступные функции

Команда/Кнопка	Описание
🛠 Админ-панель	Главное меню администратора

📊 Тестирование и диагностика

🔔 Тест напоминаний

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

✅ Тест завершения мероприятий

• Запускает автоматическое завершение прошедших мероприятий
• Показывает последние завершённые мероприятия
• Проверяет корректность обновления статусов

🌅 Тест утренней сводки

• Отправляет тестовую версию утреннего отчёта
• Позволяет проверить формат и содержимое до реальной рассылки

📊 Тест дневного отчёта

• Отправляет тестовый дневной отчёт со статистикой
• Показывает количество подтверждённых, ожидающих и выполненных мероприятий

🔄 Принудительная синхронизация

• Запускает синхронизацию с Google Calendar вне графика
• Полезно после добавления новых событий

📋 Статистика базы данных

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

🔒 Безопасность

Административная панель доступна только пользователям с ролью superadmin. Для всех остальных ролей (admin, manager, engineer, viewer) эта кнопка не отображается.

🚀 Планы по развитию админ-панели

• Управление пользователями (просмотр, изменение ролей)
• Редактирование аудиторий через интерфейс
• Просмотр логов ошибок
• Ручной запуск фоновых задач
• Настройка параметров бота на лету
• Создание бэкапов базы данных

---

🛠 Технологический стек

Компонент	Технология	Версия
Язык программирования	Python	3.14
Telegram Bot API	python-telegram-bot	22.2
База данных	PostgreSQL	18.x
Асинхронный драйвер	asyncpg	0.30.0
Google Calendar API	google-api-python-client	2.150.0
Транслитерация	cyrtranslit	0.9.2
Конфигурация	python-dotenv	1.2.0

---

Детальное описание таблиц

1. users — пользователи системы

Поле	Тип	Описание
telegram_id	BIGINT (PK)	ID пользователя в Telegram
full_name	VARCHAR(100)	Имя для отображения
username	VARCHAR(100)	@username в Telegram
role	VARCHAR(20)	admin / manager / engineer / viewer
created_at	TIMESTAMP	Когда зарегистрировался
last_active	TIMESTAMP	Последняя активность
is_active	BOOLEAN	Не уволен ли

Роли пользователей

Роль	Описание	Доступ
superadmin	Разработчик, администратор системы	🔥 Полный доступ ко всем функциям, включая админ-панель
admin	Начальник управления, проджект-менеджер	📊 Только просмотр статистики
manager	Начальник отдела	🎯 Полное операционное управление
engineer	Инженеры	🔧 Базовые операции
viewer	Внешние наблюдатели	👁️ Только просмотр

---

2. auditories — аудитории

Поле	Тип	Описание
id	SERIAL (PK)	Внутренний ID
name	VARCHAR(50)	Номер аудитории ('501', '315')
building	VARCHAR(50)	Корпус
floor	INTEGER	Этаж
equipment	TEXT	Описание оборудования
notes	TEXT	Заметки
is_active	BOOLEAN	Не списана ли

---

3. status_log — история статусов (ядро системы)

Поле	Тип	Описание
id	SERIAL (PK)
auditory_id	INTEGER (FK)	Аудитория
status	VARCHAR(10)	green / yellow / red
comment	TEXT	Описание проблемы
reported_by	BIGINT (FK)	Кто отметил
created_at	TIMESTAMP	Когда отметили
equipment_type	VARCHAR(50)	Тип оборудования
problem_category	VARCHAR(50)	Категория проблемы
resolved_at	TIMESTAMP	Когда починили
resolution_comment	TEXT	Как починили

---

4. calendar_events — мероприятия из Google Calendar

Поле	Тип	Описание
id	SERIAL (PK)
google_event_id	VARCHAR(255)	ID из Google Calendar
auditory_id	INTEGER (FK)	Аудитория
title	VARCHAR(255)	Название мероприятия
description	TEXT	Описание
start_time	TIMESTAMP	Начало
end_time	TIMESTAMP	Конец
organizer	VARCHAR(255)	Организатор
status	VARCHAR(20)	confirmed / cancelled / tentative
last_sync	TIMESTAMP	Последняя синхронизация

---

5. event_assignments — кто ответственный за мероприятие

Поле	Тип	Описание
id	SERIAL (PK)
event_id	INTEGER (FK)	Мероприятие
assigned_to	BIGINT (FK)	Инженер
assigned_by	BIGINT (FK)	Начальник
assigned_at	TIMESTAMP	Когда назначили
role	VARCHAR(30)	primary / secondary / trainee / backup
status	VARCHAR(20)	assigned / accepted / done / cancelled
confirmed_at	TIMESTAMP	Когда инженер подтвердил
completed_at	TIMESTAMP	Когда отработал

Уникальность: один инженер не может быть назначен на одно мероприятие дважды

---

6. tasks — задачи от начальника

Поле	Тип	Описание
id	SERIAL (PK)
title	TEXT	Краткое описание
description	TEXT	Подробности
created_by	BIGINT (FK)	Кто создал
assigned_to	BIGINT (FK)	Кому назначено
assigned_group	VARCHAR(50)	Или группа ('all', 'engineers')
auditory_id	INTEGER (FK)	Связанная аудитория
deadline	TIMESTAMP	Срок
priority	VARCHAR(10)	low / medium / high / urgent
status	VARCHAR(20)	new / accepted / in_progress / done / cancelled / overdue
created_at	TIMESTAMP
completed_at	TIMESTAMP

---

7. task_comments — комментарии к задачам

Поле	Тип	Описание
id	SERIAL (PK)
task_id	INTEGER (FK)	Задача
user_id	BIGINT (FK)	Кто написал
comment	TEXT	Текст
created_at	TIMESTAMP

---

8. notifications — лог уведомлений

Поле	Тип	Описание
id	SERIAL (PK)
user_id	BIGINT (FK)	Кому
task_id	INTEGER (FK)	По какой задаче
event_id	INTEGER (FK)	По какому мероприятию
type	VARCHAR(30)	new_task / reminder / deadline / assignment / cancellation
sent_at	TIMESTAMP	Когда отправили
read_at	TIMESTAMP	Когда прочитал
telegram_message_id	BIGINT	ID сообщения в Telegram

---

9. cancellation_log — отмены мероприятий

Поле	Тип	Описание
id	SERIAL (PK)
event_id	INTEGER (FK)	Мероприятие
cancelled_by	BIGINT (FK)	Кто отменил
cancelled_at	TIMESTAMP
source	VARCHAR(20)	bot / calendar_webhook / manual
reason	TEXT	Причина
notification_sent	BOOLEAN	Уведомили ли

---

10. equipment_types — справочник оборудования

Поле	Тип	Описание
id	SERIAL (PK)
name	VARCHAR(50)	projector / sound / hdmi / remote / computer / other
description	TEXT

---

11. problem_categories — справочник категорий проблем

Поле	Тип	Описание
id	SERIAL (PK)
name	VARCHAR(100)	no_power / no_signal / broken_cable / software
equipment_type_id	INTEGER (FK)	Связь с оборудованием
description	TEXT

---