Skip to content

CHANGELOG.md

Latest commit

 

History

History
251 lines (177 loc) · 10.3 KB

CHANGELOG.md

File metadata and controls

251 lines (177 loc) · 10.3 KB
Raw

CHANGELOG - WhatsApp Bot Refactoring

Версия 2.0 - Оптимизация для WhatsApp (2024)

🎯 Основные изменения

Полная переработка бота для соответствия ограничениям WhatsApp и улучшения устойчивости системы.

✅ 1. Система пагинации (≤3 кнопки)

Проблема: WhatsApp ограничивает количество кнопок до 3 в одном сообщении.

Решение:

  • ✨ Добавлен универсальный хелпер send_paginated_buttons() для отображения длинных списков
  • 📄 Пагинация применена ко всем длинным спискам:
    • Выбор видов работ (техника/ручная)
    • Выбор локаций (поля)
    • Выбор количества часов (1-24)
    • Редактор записей (по 1 записи на странице)
  • ⬅️➡️ Навигация через кнопки "⬅️" и "➡️"
  • 📊 Отображение текущей страницы (напр. "Страница 2 из 5")

Файлы: bot_polya_whatsapp.py, строки 669-749

✅ 2. Callback с ID вместо названий

Проблема: Длинные названия в callback_data превышают лимиты и могут обрезаться.

Решение:

  • 🔢 Добавлены новые DAO функции:
    • list_activities_with_id(grp) → возвращает [(id, name), ...]
    • list_locations_with_id(grp) → возвращает [(id, name), ...]
    • get_activity_name(id) → возвращает (name, grp) по ID
    • get_location_name(id) → возвращает (name, grp) по ID
  • 🏷️ Новый формат callback:
    • Вид работы: work:act:{kind}:{act_id} (вместо work:act:{kind}:{name})
    • Локация: work:loc:{grp}:{loc_id} (вместо work:loc:{grp}:{name})
  • ✂️ Удалены все срезы строк типа [:20], [:30]

Файлы: bot_polya_whatsapp.py, строки 255-314, 1022-1119

✅ 3. Главное меню (≤3 кнопки)

Проблема: Изначально было 4-5 кнопок в главном меню.

Решение:

  • 📱 Экран 1:
    • 🚜 Работа
    • 📊 Статистика
    • Ещё...
  • 📱 Экран "Ещё...":
    • 📝 Перепись
    • ✏️ Имя
    • ⚙️ Админ (только для администраторов)
  • 🔙 Кнопка "Назад" на втором экране

Файлы: bot_polya_whatsapp.py, строки 751-793

✅ 4. Редактор записей (1 запись + 2 кнопки)

Проблема: При большом количестве записей за 24 часа превышался лимит кнопок.

Решение:

  • 📄 Отображение по 1 записи на странице
  • 🖊 2 кнопки действий: "🖊 Править" и "🗑 Удалить"
  • ⬅️➡️ Навигация между записями через стрелки
  • 📊 Счётчик: "Запись 2 из 5"
  • 🔙 Кнопка "Назад" (если помещается)

Файлы: bot_polya_whatsapp.py, строки 795-842, 960-1002

✅ 5. Универсальная навигация (nav:*)

Проблема: Дублирование логики отрисовки экранов при навигации.

Решение:

  • 🔄 Единый обработчик nav:{state_key}:{page} для всех пагинированных экранов
  • 🗂️ Поддерживаемые экраны:
    • acts - виды работ
    • locs - локации
    • hours - выбор часов
    • edit_hours - редактирование часов записи
    • edit_records - навигация по записям
  • ♻️ Переиспользование функций рендеринга (send_paginated_buttons, render_edit_records_page)

Файлы: bot_polya_whatsapp.py, строки 979-1039

✅ 6. Валидация ENV переменных

Проблема: Использование assert не подходит для production и не даёт корректного завершения процесса.

Решение:

  • ❌ Удалены все assert для проверки ENV переменных
  • ✅ Добавлена явная проверка с логированием: 
    if not WHATSAPP_TOKEN:
    logging.error("❌ Ошибка: WHATSAPP_TOKEN не найден в .env")
    sys.exit(1)
  • 🔄 Процесс завершается с кодом 1, что позволяет супервизору перезапустить сервис
  • 📝 Понятные сообщения об ошибках в логах

Файлы: bot_polya_whatsapp.py, строки 43-52

✅ 7. Улучшенная валидация часов

Проблема: Неинформативное сообщение об ошибке при превышении 24 часов в сутки.

Решение:

  • 📊 Подробное сообщение с разбивкой: 
    ❗ Превышен лимит часов

Сейчас учтено: 22 ч
Попытка добавить: 3 ч
Максимум в сутки: 24 ч

Вы можете добавить не более 2 ч.
  • 🧮 Автоматический расчёт максимально доступного количества часов
  • ✏️ Применено как при добавлении записи, так и при редактировании

Файлы: bot_polya_whatsapp.py, строки 1153-1165, 1220-1232

✅ 8. Админ-панель (≤3 кнопки)

Проблема: 6 кнопок в админ-панели превышали лимит.

Решение:

  • 📱 Главная админ-панель:
    • ➕➖ Работы
    • ➕➖ Локации
    • 📤 Экспорт
  • 📱 Подменю "Работы":
    • ➕ Добавить работу
    • ➖ Удалить работу
    • 🔙 Админ
  • 📱 Подменю "Локации":
    • ➕ Добавить локацию
    • ➖ Удалить локацию
    • 🔙 Админ

Файлы: bot_polya_whatsapp.py, строки 1089-1122

📝 9. Комментарии WhatsApp-специфичных ограничений

Добавлены комментарии # WA: во всех местах, где учитываются ограничения WhatsApp:

  • Лимит 3 кнопки в сообщении
  • Использование ID вместо длинных строк в callback
  • Пагинация длинных списков
  • Ограничение на количество дат в выборе

Примеры:

# WA: WhatsApp ограничивает количество кнопок до 3 в одном сообщении
# WA: Получаем название activity по ID из БД, а не из callback_data
# WA: Показываем по 1 записи на странице с 2 кнопками действий

🔧 Технические улучшения

  1. Структурирование кода:

    • Вынесен хелпер send_paginated_buttons() для переиспользования
    • Создана функция render_edit_records_page() для отрисовки редактора
    • Добавлена функция show_more_menu() для дополнительного меню

  2. Состояния пользователей:

    • Расширено хранение состояний для поддержки пагинации
    • Добавлены ключи: acts, locs, hours_opts, edit_records, edit_hours_opts

  3. Типизация:

    • Добавлен dataclass PaginationButton для структурированных кнопок
    • Улучшена типизация в DAO функциях

📊 Статистика изменений

  • Добавлено:

    • 4 новые DAO функции
    • 1 универсальный хелпер пагинации
    • 2 функции рендеринга экранов
    • 1 обработчик навигации
    • 50+ строк документации

  • Изменено:

    • 12 обработчиков callback
    • Все длинные списки переведены на пагинацию
    • Формат всех callback_data для работ и локаций

  • Удалено:

    • Все срезы строк [:20], [:30]
    • assert для проверки ENV

🚀 Готовность к production

  • ✅ Соблюдены все ограничения WhatsApp API
  • ✅ Корректная обработка ошибок
  • ✅ Устойчивость к перезапускам (через exit code 1)
  • ✅ Улучшенный UX (информативные сообщения об ошибках)
  • ✅ Минимизировано дублирование кода
  • ✅ Добавлены докстринги к новым функциям

🔍 Обратная совместимость

База данных: Полная совместимость. Добавлены только новые функции чтения, схема БД не изменена.

Конфигурация: Не требуется изменений в .env файлах.

Миграция: Обновление не требует миграции данных, просто замените файл и перезапустите бот.

📚 Дополнительная документация

См. также:

  • README_WHATSAPP.md - документация по настройке
  • MIGRATION_GUIDE.md - руководство по миграции
  • requirements_whatsapp.txt - зависимости

Авторы изменений: AI Assistant
Дата: 2024
Версия API: WhatsApp Business API v18+