# Physical Motion Fix Report

## Причины предыдущего хаоса
Ранее движение товара рассчитывалось независимо по осям с использованием интерполяции между хардкодными точками, что приводило к телепортации или "зависанию" объектов (в том числе над корзиной). Также отсутствовала система хранения объектов после завершения их этапа маршрутизации. Указанные в `ModelAssets` STL-модели загружались, но отображались некорректно. Из-за отсутствия независимой физической модели каждый фрейм пытался обновлять позиции локально.

## Решение
1. **Создана `physicalItemMotion.ts`** — единая физико-кинематическая модель `getPhysicalItemPose`. Она гарантирует детерминированное вычисление `[x,y,z]` и вращения на основе `elapsedMs`, отсчитанного от момента спавна товара, а также `CONVEYOR_SPEED_MPS` (1 м/с).
2. **Синхронизация ленты и товара**: Время и расстояние на ленте точно соответствуют $d = 1.0 \times t$. Движущаяся текстура ленты использует эту же скорость.
3. **Хранение (settled) элементов**: В `SorterDigitalTwinContinuous.tsx` теперь рендерятся все созданные (spawned) объекты за последние 20 циклов. Объекты попадают в корзину `C` или `D` по желобу (`chute`), меняя высоту, и остаются там (isSettled).
4. **STL модели**: Добавлен единый компонент `PhysicalPlaybackItem.tsx`, который грузит `STLGeometry` или использует `FallbackPrimitive` в случае их отсутствия, применяя при этом корректные материалы с реалистичным `roughness` и `metalness`.

## Подтверждение
- Скорость товара 1 м/с подтверждена тестами в `physicalItemMotion.test.ts`.
- Объекты остаются внутри cage благодаря смещению на базе `slotIndex`.
- Fallback применён только к отсутствующим или "heavy" STL. (Короб 300, 400, Тарелка, Бутылка, Цилиндр, ЛанчБокс — STL).

## Результаты QA и сборка
- `npm run build` — Успешно (0 ошибок).
- `npm run test` — Успешно (117 тестов пройдено).
- `docker-compose` — Контейнеры пересобраны и запущены.
- Production QA Script завершен с 0 ошибок консоли (`NO_CONSOLE_ERRORS`).

Скриншоты лежат в папке `docs/physical_motion_fix_screenshots/`:
- `stl_models_visible.png`
- `belt_sync_t0.png`
- `belt_sync_t1.png`
- `item_on_belt_no_flying.png`
- `route_to_c_chute.png`
- `item_settled_in_c_cage.png`
- `route_to_d_chute.png`
- `item_settled_in_d_cage.png`
- `no_overlay_overlap.png`
- `demo_complete_items_not_chaotic.png`

Ограничения: `slotIndex` использует простую матричную сетку 3xN, что при сильном переполнении корзины может вызвать небольшие наложения (clipping) STL-моделей друг на друга, но это визуально приемлемо и объекты остаются строго внутри корзины.