🤖 EXPORTUM Bot - Документация

🚀 Быстрый старт

cp .env.example .env
# заполнить .env своими значениями
python3 -m venv .venv
./.venv/bin/python -m pip install -r requirements.txt
./run.sh

📋 Описание

EXPORTUM — Telegram-бот для агропромышленной платформы, объединяющий фермеров, экспортёров, логистов и экспедиторов для эффективной организации поставок зерна.

Основные функции:

• Создание и управление пулами зерна
• Поиск и подбор партий
• Организация логистики и экспедирования
• Управление сделками и доставками
• Административная панель для мониторинга и управления

---

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

🌾 Фермер

• Создание партий зерна (культура, объём, цена, качество)
• Присоединение к пулам экспортёров
• Просмотр доступных пулов и совпадений
• Управление своими партиями

📦 Экспортёр

• Создание пулов (культура, объём, порт, цена FOB)
• Выбор логистов и экспедиторов
• Управление пулами (закрытие, завершение)
• Просмотр участников и статистики

🚚 Логист

• Создание карточки логиста (транспорт, маршруты, цены)
• Просмотр доступных заявок на логистику
• Подача предложений по доставке
• Управление своими перевозками

🚛 Экспедитор

• Создание карточки экспедитора (услуги, порты, опыт)
• Просмотр доступных сделок
• Подача предложений по экспедированию
• Управление своими заявками

🔐 Администратор

• Статистика системы
• Аналитика (регионы, культуры, порты)
• Экспорт данных (CSV, JSON)
• Управление пользователями
• Рассылка сообщений

---

📊 Структура данных

users (dict)

{
    user_id: {
        "id": int,
        "role": str,  # "farmer", "exporter", "logistic", "expeditor"
        "name": str,
        "phone": str,
        "email": str,
        "region": str,
        "inn": str,
        "ogrn": str,
        "company_name": str,
        "company_details": str,
        "registered_at": str,
        ...
    }
}

pools (dict)

{
    pool_id: {
        "id": int,
        "exporter_id": int,
        "culture": str,
        "target_volume": float,
        "current_volume": float,
        "price": float,
        "port": str,
        "status": str,  # "active", "filled", "closed", "completed"
        "selected_logistic_id": int | None,
        "selected_expeditor_id": int | None,
        "batch_ids": list[int],
        "farmer_ids": list[int],
        "created_at": str,
        "completed_at": str | None,
        ...
    }
}

batches (dict)

{
    farmer_id: [
        {
            "id": int,
            "culture": str,
            "volume": float,
            "price": float,
            "status": str,  # "Активна", "Зарезервирована", "sold"
            "region": str,
            "moisture": float,
            "impurity": float,
            "quality_class": str,
            "pool_id": int | None,
            ...
        }
    ]
}

logistics_cards (dict)

{
    user_id: {
        "vehicle_type": str,  # "truck", "grain", "wagon"
        "capacity": float,
        "regions": list[str],
        "ports": list[str],
        "price_per_km": float,
        "description": str,
        ...
    }
}

expeditor_cards (dict)

{
    user_id: {
        "services": str,
        "dt_price": float,
        "ports": list[str],
        "experience": str,
        ...
    }
}

---

🔄 Основные E2E-сценарии

Фермер

1. Регистрация → /start → Выбор роли "Фермер" → Заполнение данных
2. Создание партии → "➕ Добавить партию" → Ввод данных (культура, объём, цена, качество)
3. Поиск пулов → "🔍 Найти пулы" → Просмотр доступных пулов → Присоединение к пулу
4. Управление партиями → "📦 Мои партии" → Просмотр/редактирование/удаление

Экспортёр

1. Регистрация → /start → Выбор роли "Экспортёр" → Заполнение данных
2. Создание пула → "➕ Создать пул" → Ввод данных (культура, объём, порт, цена) → Выбор типа документов
3. Выбор логиста → Просмотр карточек логистов → Выбор логиста → Уведомление логисту
4. Выбор экспедитора → Просмотр карточек экспедиторов → Выбор экспедитора → Уведомление экспедитору
5. Завершение пула → "🎉 Завершить пул" → Подтверждение → Уведомления всем участникам

Логист

1. Регистрация → /start → Выбор роли "Логист" → Заполнение данных
2. Создание карточки → "💳 Моя карточка" → "➕ Создать карточку" → Ввод данных (транспорт, маршруты, цены)
3. Просмотр заявок → "📋 Доступные заявки" → Просмотр заявок → Подача предложения
4. Управление перевозками → "🚚 Мои перевозки" → Просмотр активных доставок

Экспедитор

1. Регистрация → /start → Выбор роли "Экспедитор" → Заполнение данных
2. Создание карточки → "💳 Моя карточка" → "➕ Создать карточку" → Ввод данных (услуги, порты, опыт)
3. Просмотр сделок → "📋 Доступные сделки" → Просмотр доступных пулов → Подача предложения

Администратор

1. Вход → /admin → Проверка прав → Админ-панель
2. Статистика → "📊 Статистика" → Просмотр общей статистики системы
3. Аналитика → "📈 Аналитика" → Просмотр аналитики (регионы, культуры, порты)
4. Экспорт данных → "📤 Экспорт данных" → Выбор типа данных → Скачивание файла
5. Управление пользователями → "👥 Пользователи" → Просмотр списка → Детали пользователя
6. Рассылка → "📢 Рассылка" → Ввод сообщения → Подтверждение → Отправка всем пользователям

---

🚀 Команды запуска

Основные команды:

• /start — начало работы, регистрация/вход
• /admin — вход в админ-панель (только для администратора)

Навигация:

• Кнопки главного меню (зависят от роли)
• Callback-кнопки для переходов между разделами
• Кнопки "Назад" для возврата в предыдущее меню

---

⚙️ Настройки

Переменные окружения:

• BOT_TOKEN — токен Telegram-бота (обязательно)
• ADMIN_ID — Telegram ID администратора (обязательно)
• DATA_DIR — директория для хранения данных (по умолчанию: data/)

Файлы данных (pickle):

• users.pkl — пользователи
• pools.pkl — пулы
• batches.pkl — партии
• logistics_cards.pkl — карточки логистов
• expeditor_cards.pkl — карточки экспедиторов
• shipping_requests.pkl — заявки на доставку
• logistic_offers.pkl — предложения логистов
• expeditor_pool_offers.pkl — предложения экспедиторов по пулам
• expeditor_request_offers.pkl — предложения экспедиторов по заявкам

---

📁 Структура кода

Основные секции:

1. Импорты и конфигурация (строки 1-200)

• Импорты библиотек
• Константы и настройки
• Инициализация бота и диспетчера

2. Глобальные структуры данных (строки 100-200)

• users, pools, batches
• logistics_cards, expeditor_cards
• shipping_requests, logistic_offers, expeditor_offers

3. FSM States (строки 1300-1500)

• RegistrationStatesGroup
• CreatePoolStatesGroup
• JoinPoolStatesGroup
• EditProfileStates
• BroadcastStates
• И другие...

4. Вспомогательные функции (строки 200-3000)

• Валидация данных
• Форматирование сообщений
• Построение клавиатур
• Функции уведомлений
• Функции экспорта данных

5. Handlers (строки 4000-33000)

• Admin handlers (строки 4500-6500)
• Registration handlers (строки 6700-8000)
• Pool handlers (строки 10000-13000)
• Batch handlers (строки 10000-12000)
• Logistic handlers (строки 25000-28000)
• Expeditor handlers (строки 18000-20000)
• Notification handlers (строки 3500-4000)

6. Функции сохранения/загрузки (строки 700-900)

• save_data() — сохранение всех данных
• load_data() — загрузка всех данных
• save_*_to_pickle() — сохранение отдельных структур

---

🔧 Известные проблемы / TODO

Помеченные кандидаты на удаление:

• parse_price() — не используется
• get_all_pools_with_format() — не используется
• translate_pool_status() — не используется
• parse_join_pool_callback() — не используется
• validate_batch_volume() — не используется
• migrate_all_existing_pools() — одноразовая миграция
• migrate_old_pools() — одноразовая миграция

Улучшения:

• Добавить больше валидации при создании пулов/партий
• Улучшить обработку ошибок Telegram API
• Добавить rate limiting для массовых операций
• Оптимизировать работу с большими объёмами данных

---

📝 Примечания

• Все данные хранятся в памяти и периодически сохраняются в pickle-файлы
• Для работы с Google Sheets требуется настройка gs объекта
• Логирование ведётся через стандартный модуль logging
• Все функции соответствуют принципам КОНТЕКСТ7 (полный код, обработка ошибок, логирование, docstring)

---

🔗 Связанные документы

• docs/README.md — индекс документации
• docs/reports_2026-02-16.tar.gz — архив отчётов аудита и тестирования