FSM Swarm (Рой)

FSM Swarm — это кроссплатформенная контейнеризированная экосистема автоматизации выездного сервиса полного цикла, оснащенная динамическим решателем транспортных задач с временными окнами (VRPTW).

🎯 Назначение и функциональные возможности

Система автоматизирует операционную логистику диспетчерских служб и работу мобильных инженеров на основе парадигмы «динамического расписания»:

• Автоматическое планирование: Математический расчет оптимальных маршрутов и графиков для всей сетки сотрудников на основе входящего пула заявок.
• Реактивность в реальном времени: Мгновенный адаптивный пересчет текущих планов при возникновении триггеров: отмена или перенос встреч клиентами, появление экстренных (SOS) аварийных заявок, задержки инженеров в пути.
• Многокритериальная фильтрация: Решатель сопоставляет параметры заявок со свойствами инженеров по жестким критериям:
  • Временные окна: Соблюдение SLA и интервалов доступности клиентов.
  • Матрица компетенций: Соответствие навыков, допусков и наличия инструментов у сотрудника профилю задачи.
  • Ресурсные ограничения: Учет типа транспорта (пеший, общественный, автомобиль или велосипед).

🛠️ Технологический стек

• Frontend: React 19, TypeScript, Tauri (десктопная платформа), Vite 8, TailwindCSS v4, React Router v7.
• Дизайн-система & UI: Собственная UI-библиотека (@beeline/ui), интерактивные гиды (@beeline/onboarding на базе Driver.js) и утилиты общего назначения (@beeline/shared).
• Картография & Визуализация: Leaflet, React Leaflet, Leaflet.heat (тепловые карты плотности заявок), Mermaid (диаграммы архитектуры), KaTeX (математические формулы), React Markdown.
• State Management: Zustand, TanStack React Query v5.
• Работа с формами & Валидация: React Hook Form, Zod.
• Backend: HonoJS (Node server шлюз), Better-Auth (включая работу по API-ключам), Pino (логирование с pino-pretty), @hono/zod-openapi, Scalar (генерация интерактивной документации API).
• База данных & ORM: PostgreSQL 17 + PostGIS 3.5 (географическое расширение), Drizzle ORM (релиз-кандидат v1.0), Drizzle Kit (управление схемой и генерация миграций), драйвер pg (node-postgres).
• Брокер сообщений: PostgreSQL 17 (высокопроизводительная асинхронная очередь задач на базе транзакций через драйвер asyncpg без использования внешних брокеров вроде Redis).
• Микросервис оптимизации (Solver): Python >=3.12 (под управлением менеджера пакетов uv), Google OR-Tools (VRPTW-решатель), SQLAlchemy Asyncio v2, драйверы asyncpg и psycopg3, валидация данных Pydantic v2, асинхронный HTTP-клиент httpx.
• Интеграции & Инфраструктура:
  • Docker Compose (оркестрация контейнеров со сложными межсервисными healthcheck-зависимостями).
  • Valhalla (локальный независимый гео-движок маршрутизации на основе карт OpenStreetMap).
  • Подключение к внутренним системам Мос.Хаб (GitLab) и внешним источникам гео-данных.
• Тестирование, Менеджмент & Разработка:
  • pnpm (управление монорепозиторием, workspaces, переопределение зависимостей).
  • Ruff (молниеносный линтинг и форматирование Python-кода).
  • Playwright (E2E-тестирование), Vitest (компонентное и юнит-тестирование).
  • Tsx / Tsc-alias (сборка и быстрый запуск TS скриптов/миграций на лету).
  • Falso (генерация реалистичных сид-данных для ручного тестирования и ETL).

📦 Структура монорепозитория

swarm/
├── apps/                      # Исполняемые приложения экосистемы
│   ├── admin/                 # Высокопроизводительный UI диспетчера (React 19 + Vite 8 + Tauri)
│   └── api/                   # Бэкенд-шлюз (Gateway) на HonoJS с автогенерацией OpenAPI
├── packages/                  # Внутренние воркспейсы (pnpm workspaces)
│   ├── api-client/            # Сквозной типобезопасный API-клиент (Hono RPC SDK)
│   ├── db/                    # Слой данных: схемы Drizzle ORM, миграции и сиды
│   ├── ui/                    # Общая дизайн-система компонентов на React 19
│   ├── onboarding/            # Интерактивные гиды на базе Driver.js
│   └── shared/                # Общие TypeScript-типы и утилиты
├── solver/                    # Микросервис асинхронного VRPTW-оптимизатора (Python 3.12 + uv)
├── data/                      # Бинарные файлы и медиа-ресурсы (в т.ч. презентации)
├── docs/                      # Дополнительная проектная и экспертная документация
├── nginx/                     # Конфигурация Nginx для развертывания веб-интерфейса
├── valhalla_tiles/            # Локальные дорожные тайлы карт ЦФО для Valhalla Engine
├── eda/ & .claude/ & .husky/  # Служебные директории окружения, линтеров и агентов разработки
├── docker-compose.yml         # Оркестрация локального стенда (PostgreSQL 17, Valhalla, API, Solver)
├── dump.sql                   # Базовый SQL-дамп структуры и начальных данных БД
├── pnpm-workspace.yaml        # Конфигурация воркспейсов монорепозитория
├── .env / .env.docker         # Конфигурационные файлы переменных окружения
│
├── ALGORITHM.md               # Математическое описание и логика VRPTW-решателя
├── DATASET.md                 # Спецификация используемых датасетов и графов дорог
├── SOLUTION_DIAGRAM.md        # Архитектурные диаграммы взаимодействия компонентов
├── FUTURE.md                  # Дорожная карта развития и план масштабирования
└── CLAUDE.md                  # Инструкции и контекст для AI-ассистентов разработки

🚀 Быстрый старт (Локальное развертывание)

Для запуска полного стенда на локальной машине необходимы Docker (с поддержкой Docker Compose) и менеджер пакетов pnpm.

1. Подготовка окружения

Для успешного клонирования проекта на вашем компьютере должен быть установлен Git LFS (Large File Storage), так как в репозитории хранятся тяжелые бинарные файлы (карты и дорожные графы).

1. Установите Git LFS (если он еще не установлен):

   • Для Windows: Скачайте и запустите установщик с официального сайта Git LFS.
   • Для macOS: Выполните команду brew install git-lfs.
   • Для Ubuntu/Debian: Выполните команду sudo apt install git-lfs.

2. Инициализируйте Git LFS в вашей системе (выполняется один раз):

   git lfs install

3. Склонируйте репозиторий и перейдите в папку проекта:

   git clone https://hub.mos.ru/rus_kadr03/swarm
   cd swarm

Примечание: Перед стартом убедитесь, что файлы дорожных графов для региона (ЦФО) размещены в папке ./valhalla_tiles.

2. Запуск контейнеров

Запустите сборку и развертывание всех сервисов в фоновом режиме. Архитектура настроена таким образом, что веб-сервисы и решатель дождутся полной готовности и прохождения healthcheck-проверок со стороны PostgreSQL и Valhalla:

docker compose up -d --build

После успешного выполнения команды сервисы будут доступны по следующим адресам:

• Административная панель (Диспетчер): http://localhost:9999
• Бэкенд-шлюз (API Gateway): http://localhost:3030
• Документация API (Scalar): http://localhost:3030/reference (генерируется автоматически)

3. Базовые команды управления

# Остановить все сервисы (данные сохраняются в локальной директории ./pgdata)
docker compose down

# Запустить только инфраструктурную часть (для локальной разработки на хосте)
docker compose up -d db valhalla

📖 Сопутствующая документация

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

🔗 Развернутые стенды и демонстрационные материалы

Вы можете протестировать работу экосистемы и ознакомиться с материалами проекта по следующим ссылкам:

• 🖥️ Демо-интерфейс диспетчера (Клиент) — интерактивное веб-приложение для управления выездными службами, мониторинга инженеров и визуализации маршрутов.
• ⚙️ Интерактивная документация API (Сервер) — Scalar-спецификация эндпоинтов бэкенд-шлюза со строгой Zod-валидацией контрактов.
• 🎓 Техническая документация проекта — подробное PDF-руководство по архитектурным решениям.
• 📊 Презентация продукта — презентационные материалы экосистемы FSM Swarm.
• 🎨 Скринкаст — демонстрация работы FSM Swarm.

📥 Ссылки на скачивание FSM Swarm (Версия 0.1.0)

🖥️ Для компьютеров (Windows)

• Скачать инсталлятор (.exe) — рекомендуемый вариант. Обычная установка программы на компьютер в несколько кликов.
• Скачать пакет (.msi) — альтернативный установщик (на английском языке). Обычно используется для автоматической установки сразу на много компьютеров в офисах.

🤖 Для смартфонов (Android)

• Скачать приложение (.apk) — файл для ручной установки приложения на телефоны или планшеты Android.

⚡️ Разработано в рамках хакатона Лидеры Цифровой Трансформации 2026 для решения задачи Билайн Бизнес