feat: add sorter simulation dashboard MVP

README.md

@@ -0,0 +1,131 @@
+# OZON Tech Sorter Simulation
+
+Инженерный frontend MVP для задачи хакатона OZON Tech: «Интеллектуальная роботизированная система сортировки товаров».
+
+Приложение показывает 2D/SVG dashboard сортировочной линии: конвейер, рабочую зону 6000 x 10000 мм, зоны A/B/C/D, датчики, stop-gate, боковые толкатели, движение товаров, классификацию, маршрутизацию, state machine, метрики, PID-виджет и event log.
+
+## Архитектура решения
+
+- Vite + React + TypeScript.
+- Доменная логика вынесена в `src/domain`.
+- Mock-данные товаров и сценариев находятся в `src/data`.
+- UI собран из независимых панелей в `src/components`.
+- Визуализация линии выполнена на SVG без Three.js и тяжелой 3D-графики.
+
+## Логика классификации
+
+Классификация реализована чистой функцией `classifyItem`.
+
+1. Сначала проверяются допустимые габариты.
+2. Если товар нарушает min/max размеры, он относится к C.
+3. Если габариты подходят, проверяется `roundness`.
+4. Если `roundness >= 0.8`, товар относится к D.
+5. Иначе товар относится к B.
+6. Если объект одновременно негабаритный и круглый, приоритет остается у C.
+
+Допустимые габариты MVP:
+
+- min: width >= 10 мм, depth >= 10 мм, height >= 2 мм;
+- max: width <= 450 мм, depth <= 320 мм, height <= 320 мм;
+- roundness threshold: 0.8.
+
+## Исполнительная часть
+
+Симуляция отображает:
+
+- камеру с pseudo-CV, bounding box и confidence;
+- лазерный датчик высоты;
+- ультразвуковой датчик прибытия к stop-gate;
+- stop-gate с состояниями open/closed;
+- pusher C и pusher D со состояниями idle/extended/retracting;
+- маршруты B/C/D с цветовой индикацией;
+- предупреждения для close items и low confidence;
+- fault/emergency сценарии с остановкой конвейера.
+
+## State machine
+
+Состояния MVP:
+
+- IDLE
+- MOVING_TO_CAMERA
+- DETECTING
+- MOVING_TO_GATE
+- WAITING_AT_GATE
+- CLASSIFYING
+- ROUTE_TO_B
+- ROUTE_TO_C
+- ROUTE_TO_D
+- RETURN_HOME
+- FAULT
+- EMERGENCY_STOP
+
+## Сценарии
+
+- `normal_flow` — обычный поток товаров B/C/D.
+- `oversized_item` — товар выходит за max dimensions и уходит в C.
+- `round_object` — товар проходит по габаритам, но имеет roundness >= 0.8 и уходит в D.
+- `boundary_dimensions` — товары на границах допустимых размеров.
+- `close_items` — два товара близко друг к другу, появляется warning queue/spacing.
+- `low_confidence` — confidence ниже 0.65, решение принимается rule-based.
+- `jam` — застревание у stop-gate, state FAULT, conveyor stopped.
+- `emergency_stop` — аварийная остановка, state EMERGENCY_STOP.
+
+## Метрики
+
+Dashboard показывает:
+
+- processed count;
+- success count;
+- error count;
+- avg cycle time;
+- throughput items/min;
+- cv latency;
+- actuator latency;
+- queue length;
+- conveyor speed;
+- PID target speed;
+- PID actual speed.
+
+## Локальный запуск
+
+```bash
+npm install
+npm run dev
+```
+
+Открыть: http://127.0.0.1:3100/
+
+## Запуск на сервере
+
+```bash
+docker compose -p owl -f docker-compose.server.yml up -d --build
+```
+
+Compose публикует только loopback-порт:
+
+```yaml
+127.0.0.1:3100:80
+```
+
+## Как проверить
+
+```bash
+curl -I http://127.0.0.1:3100/
+```
+
+## Ограничения MVP
+
+- Физика движения упрощена до дискретной state-machine симуляции.
+- PID-регулятор имитационный, без точной модели двигателя и нагрузки.
+- CV, laser и ultrasound генерируют псевдоизмерения на основе mock-данных.
+- Нет backend, real-time API и сохранения событий.
+- Нет Three.js и полноценного digital twin в 3D.
+
+## Что улучшить дальше
+
+- Добавить backend с WebSocket-телеметрией.
+- Подключить реальные ML/CV модели или replay датасетов.
+- Сделать режим ручного управления исполнительными механизмами.
+- Добавить тесты доменной логики и сценариев.
+- Расширить физическую модель очереди, зазоров и jam recovery.
+- Добавить экспорт event log и отчеты по SLA сортировки.