PDF Email Processor

Система автоматизации обработки входящих отчётов о теплопотреблении.

Решает задачу полного цикла: от получения писем с PDF-вложениями до валидации данных и автоматической рассылки.

Задача

Автоматизировать обработку отчётов с узлов учета и снизить ручную проверку документов. Система заменяет ручной разбор писем, проверку данных и рассылку.

Возможности

• Автоматическое получение писем с PDF-отчётами (IMAP, раз в 2 мин)
• Валидация данных в PDF (пустые ячейки, непрерывность дат, извлечение номера теплосчётчика)
• Привязка к объекту по номеру вычислителя
• Автоматическая отправка клиентам (отдельное SMTP-соединение на каждого получателя)
• Rejected — только админу, с описанием причины
• Recovery — автоматическое восстановление отправок после краша воркера
• Веб-интерфейс для управления объектами и документами
• Разграничение прав (admin/operator)

Архитектура

Элдис (почта) → IMAP → Worker (Celery) → PostgreSQL → Backend (API) → UI

Компоненты

Worker (Celery) — фоновые задачи:

• Получение писем по IMAP (email_client.py)
• Валидация PDF (pdf_validator.py)
• Отправка писем получателям (email_sender.py)
• Recovery зависших отправок (recovery.py, beat, каждые 10 мин)

Backend (FastAPI) — REST API:

• Управление объектами и документами
• Настройки системы
• Пользователи и права доступа

UI (Веб-интерфейс):

• Объекты — список и управление
• Документы — статусы и отправка
• Отчёты — отклонённые документы
• Настройки (только admin)

Pipeline обработки

fetch_emails_task (каждые 2 мин)
  validate_pdf_attachment()
    если даты + таблицы OK -> approved -> finalize_validation -> validated
      -> send_pdf_attachment() -> клиентам из Object.email
    если пустые ячейки / нет дат -> rejected
      -> send_pdf_attachment() -> только админу

recover_stuck_attachments (beat, каждые 10 мин):
  находит validated/rejected/approved без sent_to_email, старше 10 мин
  перезапускает send_pdf_attachment()

Статусы документов

• new — новый документ
• processing — в обработке
• approved — данные полные (детерминированная проверка пройдена)
• validated — финализирован, готов к отправке
• rejected — есть пустые ячейки / ошибки дат
• sent — отправлен получателю

Валидация PDF

1. Извлечение таблиц из PDF (pdfplumber)
2. Проверка каждой ячейки на пустоту: None, пустая строка, тире, "---", "нд"
3. Проверка непрерывности дат в строках таблицы (gap detection)
4. Извлечение номера вычислителя из текста (приоритетные и резервные паттерны)
5. Если даты валидны И все ячейки заполнены И нет пропусков дат — документ approved
6. Иначе — rejected с указанием причины

Требования

• Docker и Docker Compose
• PostgreSQL 15+
• Redis 7+

Запуск

git clone <repo>
cd pdf-validator
docker compose up -d

Сервисы:

• Backend: http://localhost:8001
• UI: https://localhost:4321
• PostgreSQL: localhost:5432
• Redis: localhost:6379

Первый вход

1. Открыть https://localhost:4321
2. Войти под admin (пароль по умолчанию: admin)
3. Сменить пароль в разделе "Settings" > "Users"

Настройка объектов

Для каждого объекта заполняется:

• Name — название (ТСЖ, ЖСК, ООО)
• Calculator Number — номер теплосчётчика (для привязки PDF)
• Address — адрес объекта
• Email — получатели отчётов (несколько через запятую)
• Period — отчётный период ("01-31")
• Active — флаг активности (неактивные объекты не получают отчёты)

Настройка почты

В разделе "Settings" > "Mail":

• IMAP — сервер входящей почты
• SMTP — сервер исходящей почты
• Email — email отправителя
• Password — пароль или App Password

Структура проекта

worker/             - Celery воркеры
  email_client.py   - получение почты (IMAP)
  pdf_validator.py   - валидация PDF
  email_sender.py   - отправка писем (SMTP)
  recovery.py       - восстановление зависших отправок
  models.py         - SQLAlchemy модели
  celery_app.py     - конфигурация Celery

backend/            - FastAPI приложение
  main.py           - точка входа
  models.py         - модели БД
  routers/          - API endpoints

ui/                 - веб-интерфейс
  index.html        - HTML
  app.js            - JavaScript

docker-compose.yml
AGENTS.md           - заметки для агента
history.log         - история изменений (локально)