ozone-tech_owl_prime/docs/PHYSICAL_CONVEYOR_REPORT.md

Physical Conveyor Report

Summary

Исправлена физическая правдоподобность 3D demo на главной странице.

Проблема

Товар выглядел так, будто "летит" выше конвейера:

• beltY был 0.35м вместо 0.7м
• itemOffsetY добавлял ещё смещение
• Итоговая высота товара: 0.5м — неправильно
• Конвейер не имел реалистичной структуры (без опор до пола)

Root Cause

В conveyorPath.ts были hardcoded значения:

beltY: 0.35,        // Должно быть 0.7м
itemOffsetY: 0.15,  // Добавлялось без учёта размера товара

В SorterDigitalTwinContinuous.tsx belt surface был на 0.32м.

Решение

1. Создан единый файл размеров

src/domain/physicalLayout.ts — единый источник правды:

Параметр	Значение	Описание
CONVEYOR_WIDTH_M	0.5м	Ширина полотна
CONVEYOR_HEIGHT_M	0.7м	Высота верха полотна
CONVEYOR_SPEED_MPS	1.0 м/с	Скорость ленты
BELT_THICKNESS_M	0.015м	Толщина полотна
ROLLER_RADIUS_M	0.04м	Радиус ролика
ROLLER_SPACING_M	0.15м	Шаг роликов

2. Формула высоты товара

// Товар сидит НА ленте: верх полотна + половина высоты товара
itemY = BELT_TOP_Y + itemVisualHeight / 2
// BELT_TOP_Y = 0.7м

3. Реалистичный конвейер

Добавлены компоненты:

• Belt surface — верхняя рабочая поверхность на 0.7м
• Side guards — боковые направляющие выше полотна
• Frame rails — рама под полотном
• Rollers — вращающиеся ролики под лентой
• Drive roller — приводной ролик (увеличенный)
• Tension roller — натяжной ролик
• Support legs — опоры от пола до рамы
• Stepper motor — шаговый двигатель у приводного ролика

4. Позиции зон

ZONES = {
  A: { x: -4.0, z: 0 },      // Spawn
  CAMERA: { x: -1.5, z: 0 }, // Detection
  GATE: { x: 1.5, z: 0 },    // Diverter
  B: { x: 4.0, z: 0 },       // Main exit
  C: { x: 2.0, z: 2.0 },     // Oversized
  D: { x: 2.0, z: -2.0 },    // Round
}

Файлы изменены

Файл	Изменения
src/domain/physicalLayout.ts	Создан — все физические размеры
src/domain/conveyorPath.ts	Импорт из physicalLayout, правильный расчёт itemY
src/components/ThreeD/SorterDigitalTwinContinuous.tsx	Новый ConveyorBelt с правильными размерами

Скриншоты

docs/physical_conveyor_screenshots/:

• conveyor_side_view.png — боковой вид с опорами
• item_on_belt.png — товар на полотне
• running_item_on_belt.png — товар движется
• motor_drive.png — виден stepper motor
• conveyor_top_angle.png — вид сверху
• details_page.png — /details не сломан

Проверки

Проверка	Результат
npm run build	✅ Успешно
npm run test	✅ 59 тестов
Docker rebuild	✅ Успешно
Production QA	✅ Работает
Console errors	✅ Нет ошибок

Что осталось

• Визуально stepper motor небольшой — это правильно для масштаба
• Можно добавить более детальную геометрию роликов (низкий приоритет)
• Roll-cages для C/D зон можно добавить отдельно

Команды для commit/push

git add -A
git commit -m "fix: physical conveyor realism - belt at 0.7m, item rides ON belt

- Create physicalLayout.ts with all dimensions
- Update conveyorPath.ts to use correct belt height
- Rebuild ConveyorBelt with proper structure:
  - Support legs from floor
  - Rollers under belt
  - Drive/tension rollers
  - Stepper motor at drive end
- Item Y = BELT_TOP_Y + itemHeight/2

Closes: item floating above conveyor"
git push origin dan_branch