Этот проект представляет собой интеграционный сервис (хаб) для автоматизации бизнес-процессов между системами «1С: Управление торговлей 11» и «МойСклад».

Для локальной разработки и запуска вам понадобятся:

• Docker и Docker Compose
• Poetry

1. Клонируйте репозиторий:

   git clone <your-repo-url>
   cd bisnesmedia-integration-hub

2. Создайте файл конфигурации: Скопируйте пример файла с переменными окружения и заполните его вашими данными.

   cp .env.example .env

   Важно: файл .env не должен попадать в систему контроля версий.

3. Установите зависимости: Poetry создаст виртуальное окружение и установит все необходимые пакеты.

   poetry install

cp .env.example .env
docker compose -f docker-compose.dev.yml up -d --build
# app: http://localhost:8000, admin: http://localhost:8501

Используйте файл docker-compose.dev.yml (hot-reload, локальная сборка образов):

docker compose -f docker-compose.dev.yml up -d --build

Сервис будет доступен по адресу: http://localhost:8000

Документация API (Swagger UI): http://localhost:8000/docs

Здоровье:

GET /            -> { status: ok }
GET /health/db   -> проверка доступности БД

Подсказки:

• Если после обновления зависимостей видите ошибки импорта при перезагрузке, пересоберите без кэша:

  docker compose -f docker-compose.dev.yml build --no-cache app
  docker compose -f docker-compose.dev.yml build --no-cache admin_panel
  docker compose -f docker-compose.dev.yml up -d

• В dev можно отключить миграции на старте: установите RUN_MIGRATIONS_ON_STARTUP=false в .env.

Проект включает современную админ-панель на базе Streamlit для мониторинга и управления интеграционными процессами.

# В составе полного стека
docker compose -f docker-compose.dev.yml up -d --build admin_panel

# Или отдельно
docker compose -f docker-compose.dev.yml up admin_panel

Панель будет доступна по адресу: http://localhost:8501

🔍 Мониторинг логов:

• Просмотр журнала операций с поддержкой как старой, так и новой схемы логов
• Расширенные фильтры: период времени, уровень логирования, система, статус, шаг, run_id
• Авто-обновление с настраиваемым интервалом (2-30 секунд)
• Настраиваемый размер выборки (100-2000 записей)

📊 Умное отображение:

• JSON-превью с обрезкой длинных значений (до 1500 символов)
• Детальный просмотр выбранной записи
• Раскрывающиеся блоки для raw JSON данных (details, payload)
• Fault-tolerant обработка отсутствующих колонок

📥 Экспорт данных:

• CSV — стандартный табличный формат
• NDJSON — JSON по строке для больших данных

⚙️ Конфигурация:

• ADMIN_DB_URL — URL подключения к БД (по умолчанию: postgresql+psycopg2://user:password@db:5432/bisnesmedia)
• ADMIN_APP_URL — URL FastAPI приложения для триггера (по умолчанию: http://app:8000)
• ADMIN_POLL_SECONDS — интервал авто-обновления (по умолчанию: 5 сек)
• ADMIN_PAGE_SIZE — размер выборки (по умолчанию: 500 записей)
• ADMIN_TRIGGER_TOKEN — токен для защиты ручного триггера (опционально)

Панель предоставляет кнопки для ручного запуска процессов:

• 🔄 Обновить логи — принудительное обновление журнала операций
• 🚀 Запустить оценку дефицита — триггер процесса внутреннего пополнения с возможностью указания warehouse_id

• Graceful degradation при проблемах с подключением к БД
• Информативные сообщения об ошибках вместо падения интерфейса
• Автоматическое восстановление соединения
• Исправлено подключение к БД в Docker: использует db:5432 вместо localhost:5432 для корректной работы в контейнерах

Если при запуске приложения вы видите ошибку:

Multiple head revisions are present for given argument 'head'

Это означает, что в migrations/versions/ появились несколько независимых веток миграций (голов).

1. Проверьте текущие головы миграций:

poetry run alembic heads

2. Посмотрите историю миграций:

poetry run alembic history --verbose | tail -n 20

1. Создайте merge-миграцию для объединения голов:

poetry run alembic merge -m "merge heads: unify branches" <head1> <head2> [<head3>...]

2. Примените миграции:

poetry run alembic upgrade head

3. Проверьте результат:

poetry run alembic heads

Должен остаться только один head.

# 1. Диагностика
poetry run alembic heads
# Вывод: 20240911001000, 20250922000000

# 2. Создание merge-миграции
poetry run alembic merge -m "merge heads: unify 20240911001000 and 20250922000000" 20240911001000 20250922000000

# 3. Применение
poetry run alembic upgrade head

# 4. Проверка
poetry run alembic heads
# Вывод: только один head (новая merge-миграция)

Приложение автоматически проверяет состояние миграций при старте:

• В production: При обнаружении multi-head приложение остановится с подробной ошибкой и инструкциями по исправлению.
• В development: При обнаружении multi-head приложение продолжит работу с предупреждением в логах, но рекомендуется исправить ASAP.

Для принудительной проверки используйте:

poetry run python -c "from app.core.migrations_health import log_migration_status; log_migration_status()"

• Всегда создавайте новые миграции на базе текущего head: down_revision должен указывать на крайнюю ревизию.
• При параллельной разработке используйте последовательный rebase перед созданием новых миграций.
• CI автоматически проверяет и применяет миграции перед тестами.

Для быстрой проверки корректности API-кредов (URL, логин, пароль) из .env файла, можно использовать специальный скрипт.

1. Убедитесь, что ваш .env файл заполнен актуальными данными для API_1C_*.
2. Запустите скрипт из корневой директории проекта:

poetry run python scripts/test_1c_connection.py

Скрипт выведет в консоль подробный отчет об успехе или ошибке подключения.

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

poetry run pytest

Проект имеет строгую многоуровневую архитектуру для обеспечения чистоты и сопровождаемости кода. Подробное описание каждого модуля и его назначения находится в документе PROJECT_STRUCTURE.md.

База данных: приложение использует асинхронный драйвер asyncpg через SQLAlchemy 2.x. Первичная таблица integration_logs создаётся миграцией и предназначена для логирования процесса интеграций в режиме read-only.

• POST /api/v1/trigger/internal-replenishment: Асинхронно запускает процесс внутреннего пополнения.

Система использует фоновый планировщик задач (APScheduler) для выполнения отложенных и регулярных операций:

• Обработчик Outbox: Каждые 30 секунд проверяет наличие новых задач на отправку данных в 1С и выполняет их. Это гарантирует, что даже при кратковременном сбое API, заказ в конечном итоге будет создан.
• Внутреннее пополнение: Каждый будний день в 9:00 по московскому времени автоматически запускает основной процесс анализа дефицита и создания заказов на перемещение.

• API Сервис: http://localhost:8000
• API Документация: http://localhost:8000/docs
• Панель Администратора: http://localhost:8501

В production используется файл docker-compose.yml, который подтягивает готовые образы из GHCR:

docker compose up -d

Перед запуском замените плейсхолдеры образов ghcr.io/your-github-username/your-repo-name/... в docker-compose.yml на реальные пути (например, ghcr.io/<owner>/<repo>/app:latest).

При пуше в ветку main GitHub Actions запускает пайплайн:

• Линтинг (ruff) и статический анализ (mypy).
• Тесты (pytest) с тестовой PostgreSQL.
• Сборка и публикация Docker-образов приложения и админ‑панели в GitHub Container Registry (GHCR) с тегами latest и SHA коммита.

1. Анализ дефицита в 1С: система находит товары, у которых остаток ниже минимального значения.
2. Поиск на складах-донорах: проверяются склады "Бестужевых" и "Контейнер".
3. Создание внутреннего перемещения: если товар найден, создается запись в outbox для создания "Заказа на перемещение" в 1С, затем Outbox-процессор создаёт документ.
4. Создание внешнего заказа: если товар не найден на внутренних складах, создаётся запись в outbox для создания "Заказа покупателя" в МойСклад; процессор отправляет заказ в МойСклад.

• Многоэтапные Dockerfile: оба образа (приложение и админ‑панель) собираются через Poetry с вмонтированным .venv внутри контейнера.
• Локальная сборка в dev: docker-compose.dev.yml убирает image: и использует build с Dockerfile/Dockerfile.admin.
• Команды запуска: используются бинарники Python из .venv внутри контейнера, а для приложения включён --reload.

• Добавить runtime‑зависимость (приложение): docker compose -f docker-compose.dev.yml run --rm app poetry add <package-name>
• Добавить dev‑зависимость (админка/инструменты): docker compose -f docker-compose.dev.yml run --rm admin_panel poetry add -G dev <package-name>
• Обновить lock‑файл локально в активированном .venv (рекомендуется): & .\.venv\Scripts\Activate.ps1; poetry lock
• Пересобрать контейнеры после изменения зависимостей: docker compose -f docker-compose.dev.yml up -d --build

Примечание: выполнение poetry add внутри контейнера меняет файлы зависимостей в контейнере. Чтобы изменения зафиксировались в репозитории, обновляйте lock локально (как выше) или смонтируйте корень проекта в сервис перед выполнением команды.

ERROR: Could not connect to 'http://localhost:8000/admin/init_logs_table'
getaddrinfo failed: Name or service not known

Причина: Админ-панель не может подключиться к приложению из-за неправильного адреса в переменной окружения ADMIN_APP_URL.

Решение:

1. Убедитесь, что в .env файле указан правильный адрес:

   ADMIN_APP_URL=http://app:8000  # Для Docker (НЕ localhost!)

2. Если запускаете локально (не в Docker), используйте:

   ADMIN_APP_URL=http://localhost:8000

sqlalchemy.exc.ProgrammingError: relation "integration_logs" does not exist

Причина: Таблица integration_logs не создана в базе данных.

Решения:

1. Применить миграции (рекомендуется):

   poetry run alembic upgrade head

2. Создать таблицу через админ-панель: Перейдите на http://localhost:8501 и нажмите кнопку "Создать таблицу логов" в боковой панели.

3. Ручная инициализация через API:

   curl -X POST http://localhost:8000/admin/init_logs_table

IntegrationError: 1C API error: Товар не найден в базе

Причина: 1С вернул ошибку в XDTO-формате, что означает проблемы с данными или конфигурацией.

Решения:

1. Проверить подключение к 1С:

   poetry run python scripts/test_1c_connection.py

2. Проверить настройки в .env:

   API_1C_URL=http://84.23.42.102/businessmedia_ut
   API_1C_USER=Программист
   API_1C_PASSWORD=cO7cu4vi

3. Логи приложения: Проверьте логи контейнера для деталей:

   docker compose -f docker-compose.dev.yml logs app

Симптомы: Админ-панель не может подключиться к приложению или базе данных.

Решение: Убедитесь, что используются правильные DNS-имена сервисов в .env:

# Правильно (имена сервисов из docker-compose.dev.yml)
POSTGRES_SERVER=db
ADMIN_APP_URL=http://app:8000
ADMIN_DB_URL=postgresql+psycopg2://user:password@db:5432/bisnesmedia

# Неправильно
POSTGRES_SERVER=localhost  # НЕ работает в контейнерах
ADMIN_APP_URL=http://localhost:8000  # НЕ работает в контейнерах