Схема потока данных от Telegram до Google Sheets

Общий процесс обработки данных

Данный документ описывает полный цикл движения данных от момента отправки изображения в Telegram-чат до записи обработанных данных в Google Sheets с учетом пассивного мониторинга и автоматической обработки.

+----------------+     +----------------+     +----------------+     +----------------+
|                |     |                |     |                |     |                |
| Telegram Chat  | --> | Telegram Bot   | --> | Image          | --> | OCR            |
| (Изображение   |     | (Мониторинг и  |     | Preprocessing  |     | Processing     |
|  накладной)    |     |  фильтрация)   |     | (OpenCV)       |     | (Google Vision)|
|                |     |                |     |                |     |                |
+----------------+     +----------------+     +----------------+     +----------------+
                                                                            |
                                                                            v
+----------------+     +----------------+     +----------------+     +----------------+
|                |     |                |     |                |     |                |
| Google Sheets  | <-- | Data           | <-- | Data           | <-- | Text           |
| (Запись        |     | Validation     |     | Extraction     |     | Processing     |
|  данных)       |     | (Проверка)     |     | (Парсинг)      |     | (Распознанный  |
|                |     |                |     |                |     |  текст)        |
+----------------+     +----------------+     +----------------+     +----------------+

Детальное описание этапов

1. Получение изображения из Telegram-чата

Входные данные:

• Изображение товарной накладной, отправленное в групповой чат
• Метаданные сообщения (отправитель, дата и время отправки, идентификатор сообщения)

Процесс:

1. Бот постоянно мониторит все сообщения в групповом чате
2. При получении сообщения с изображением, бот извлекает:
   • Идентификатор отправителя (водителя)
   • Дату и время отправки сообщения (используется как дата загрузки/выгрузки ТС)
   • Само изображение в виде файла
3. Бот проверяет, не было ли это изображение уже обработано ранее (по хешу или другим признакам)
4. Если изображение новое, оно передается на следующий этап обработки

Выходные данные:

• Файл изображения
• Метаданные (ID водителя, дата и время отправки, ID сообщения)

2. Предобработка изображения

Входные данные:

• Файл изображения из предыдущего этапа
• Метаданные сообщения

Процесс:

1. Применение фильтров для улучшения качества изображения:
   • Нормализация яркости и контраста
   • Удаление шумов
   • Выравнивание перспективы (если необходимо)
2. Определение области интереса (ROI) - поиск области, где находится накладная
3. Оптимизация изображения для OCR (изменение размера, преобразование в оттенки серого и т.д.)

Выходные данные:

• Обработанное изображение, оптимизированное для OCR
• Метаданные (сохраняются и передаются дальше)

3. OCR-обработка

Входные данные:

• Обработанное изображение
• Метаданные

Процесс:

1. Отправка изображения в Google Vision API
2. Настройка параметров распознавания для оптимальной работы с рукописными цифрами
3. Получение результатов распознавания
4. Сохранение распознанного текста вместе с уровнем достоверности

Выходные данные:

• Распознанный текст в структурированном формате
• Уровень достоверности распознавания
• Метаданные (сохраняются и передаются дальше)

4. Обработка распознанного текста

Входные данные:

• Распознанный текст
• Уровень достоверности
• Метаданные

Процесс:

1. Анализ структуры распознанного текста
2. Применение регулярных выражений и других методов для поиска ключевых данных
3. Обработка возможных ошибок распознавания
4. Форматирование текста для дальнейшей обработки

Выходные данные:

• Структурированный текст, подготовленный для извлечения данных
• Метаданные (сохраняются и передаются дальше)

5. Извлечение данных

Входные данные:

• Структурированный текст
• Метаданные

Процесс:

1. Поиск и извлечение значений НЕТТО
2. Поиск и извлечение значений БРУТТО и ТАРА (если НЕТТО не найдено или имеет низкую достоверность)
3. Вычисление НЕТТО как БРУТТО - ТАРА (если прямое распознавание НЕТТО не удалось)
4. Структурирование извлеченных данных в формат, готовый для валидации

Выходные данные:

• Извлеченные данные (НЕТТО, БРУТТО, ТАРА)
• Дата и время отправки изображения (из метаданных)
• Идентификатор водителя (из метаданных)
• Дополнительная информация (если доступна)

6. Валидация данных

Входные данные:

• Извлеченные данные
• Метаданные

Процесс:

1. Проверка корректности извлеченных числовых значений
2. Валидация соответствия БРУТТО - ТАРА = НЕТТО (с допустимой погрешностью)
3. Проверка на аномальные значения (слишком большие или маленькие)
4. Принятие решения о достоверности данных

Выходные данные:

• Валидированные данные, готовые для записи
• Флаг достоверности данных
• Метаданные (сохраняются и передаются дальше)

7. Запись в Google Sheets

Входные данные:

• Валидированные данные
• Флаг достоверности
• Метаданные

Процесс:

1. Подключение к Google Sheets API с использованием учетных данных
2. Определение целевого листа и позиции для записи
3. Форматирование данных в соответствии с структурой таблицы
4. Запись данных:
   • НЕТТО погрузки/выгрузки
   • Дата и время отправки изображения (используется как дата загрузки/выгрузки)
   • Идентификатор водителя
   • Дополнительная информация
5. Обновление статуса обработки в базе данных

Выходные данные:

• Подтверждение успешной записи
• Ссылка на обновленную строку в таблице (для логирования)

8. Обратная связь в Telegram

Входные данные:

• Результат записи в Google Sheets
• Флаг достоверности данных
• Метаданные

Процесс:

1. Формирование краткого сообщения о результате обработки
2. В случае успешной обработки - отправка краткого подтверждения в чат или реакции на сообщение
3. В случае проблем с распознаванием или валидацией - отправка уведомления администратору
4. Логирование результата обработки в базе данных

Выходные данные:

• Сообщение в Telegram-чат (подтверждение или уведомление о проблеме)
• Запись в логе системы

Обработка текстовых сообщений

Помимо изображений, система также обрабатывает текстовые сообщения о загрузке/выгрузке и готовности к работе.

Процесс обработки текстовых сообщений:

1. Получение текстового сообщения

   • Бот мониторит все текстовые сообщения в чате
   • Извлекает текст сообщения, ID отправителя, дату и время

2. Анализ текста с помощью NLP

   • Определение типа сообщения (загрузка, выгрузка, готовность к работе)
   • Извлечение ключевой информации (местоположение, статус и т.д.)

3. Обработка данных

   • Структурирование извлеченной информации
   • Валидация данных

4. Запись в Google Sheets

   • Обновление соответствующих полей в таблице
   • Запись даты и времени сообщения
   • Обновление статуса водителя

5. Обратная связь

   • Отправка краткого подтверждения (реакции) на сообщение
   • Логирование результата обработки

Особенности использования даты и времени

Согласно требованиям, дата в товарно-транспортной накладной (ТТН) обычно не присутствует или не используется. Вместо этого система использует дату и время отправки изображения в чат как дату загрузки/выгрузки транспортного средства.

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

1. Извлечение временной метки

   • При получении сообщения с изображением, бот сохраняет точную дату и время отправки
   • Временная метка сохраняется в формате UTC для исключения проблем с часовыми поясами

2. Преобразование формата

   • Временная метка преобразуется в требуемый формат для записи в Google Sheets
   • Учитывается часовой пояс, если это необходимо для бизнес-логики

3. Запись в Google Sheets

   • Дата и время отправки изображения записываются в соответствующее поле таблицы
   • При необходимости могут быть разделены на отдельные поля (дата и время)

4. Использование для аналитики

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

Обработка ошибок и исключительных ситуаций

1. Ошибки распознавания

Сценарий: OCR не может распознать текст с достаточной точностью

Обработка:

1. Система делает несколько попыток распознавания с разными параметрами
2. Если все попытки неудачны, система:
   • Сохраняет изображение в специальную папку для ручной обработки
   • Отправляет уведомление администратору
   • Делает запись в лог с указанием проблемы
   • Отправляет краткое уведомление в чат о проблеме с распознаванием

2. Ошибки валидации данных

Сценарий: Распознанные данные не проходят валидацию (например, БРУТТО - ТАРА ≠ НЕТТО)

Обработка:

1. Система пытается применить корректирующие алгоритмы
2. Если корректировка невозможна, система:
   • Записывает данные с пометкой о низкой достоверности
   • Отправляет уведомление администратору
   • Делает запись в лог с указанием проблемы

3. Проблемы с подключением к Google Sheets

Сценарий: Невозможно подключиться к Google Sheets API или записать данные

Обработка:

1. Система сохраняет данные локально в очередь
2. Периодически пытается повторить запись
3. После восстановления подключения, все накопленные данные записываются в таблицу
4. Администратор получает уведомление о проблеме и ее решении

4. Дублирование изображений

Сценарий: Водитель отправляет одно и то же изображение несколько раз

Обработка:

1. Система вычисляет хеш изображения и сравнивает с уже обработанными
2. Если изображение уже было обработано, система:
   • Игнорирует повторную обработку
   • Отправляет краткое уведомление о том, что данное изображение уже обработано
   • Делает запись в лог о попытке повторной обработки

Оптимизация производительности

1. Асинхронная обработка

Для обеспечения быстрой реакции бота и обработки большого количества изображений, система использует асинхронную обработку:

1. Получение изображения и первичная проверка выполняются немедленно
2. Ресурсоемкие операции (предобработка, OCR, валидация) выполняются асинхронно
3. Запись в Google Sheets также выполняется асинхронно

2. Очереди сообщений

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

1. Все полученные изображения помещаются в очередь на обработку
2. Обработчики извлекают задания из очереди по мере освобождения ресурсов
3. Приоритет в очереди может определяться на основе бизнес-логики

3. Кэширование

Для оптимизации работы с Google Sheets система использует кэширование:

1. Кэширование структуры таблицы для минимизации запросов к API
2. Пакетная запись данных вместо отдельных запросов для каждой строки
3. Локальное кэширование данных при проблемах с подключением

Безопасность и конфиденциальность

1. Защита данных

1. Все взаимодействие с API (Telegram, Google) происходит по защищенным каналам (HTTPS)
2. Учетные данные хранятся в защищенном виде и не включаются в код
3. Доступ к базе данных и логам ограничен и защищен

2. Разграничение доступа

1. Административные команды доступны только авторизованным пользователям
2. Доступ к Google Sheets ограничен только необходимыми разрешениями
3. Логирование всех административных действий

Мониторинг и логирование

1. Логирование операций

Система ведет подробное логирование всех этапов обработки:

1. Получение изображения (ID сообщения, отправитель, время)
2. Результаты OCR (уровень достоверности, извлеченные данные)
3. Результаты валидации
4. Запись в Google Sheets (успех/неудача)
5. Отправка уведомлений

2. Мониторинг производительности

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

1. Время обработки изображений на каждом этапе
2. Количество успешно обработанных изображений
3. Количество ошибок распознавания и валидации
4. Время отклика Google Sheets API

3. Оповещения

Система настроена на отправку оповещений при возникновении проблем:

1. Критические ошибки отправляются администратору немедленно
2. Некритические проблемы агрегируются в ежедневные отчеты
3. Статистика использования отправляется в виде регулярных отчетов