ozone-tech_owl_prime/docs/3D_REBUILD_SPEC.md

3D REBUILD SPEC — Главная страница как Full-Screen Demo

Дата: 2026-07-06
Цель: Очистить главную, оставить только Play + непрерывное 3D demo. Детали в /details.

---

1. Target UX

Главная страница (/):

• Full-screen 3D demo viewport
• Одна кнопка Play (крупная, центр/низ экрана)
• 8 сценариев проигрываются автоматически подряд без ручного вмешательства
• Минимальный overlay: текущий сценарий, категория, прогресс
• Ссылка "Details" → /details

Цель восприятия:

• Пользователь за 5 секунд понимает: это 3D demo сортировки
• За 60 секунд видит все 8 сценариев без клика
• Жюри сразу видит физическую маршрутизацию B/C/D

---

2. Main Page Scope

Что остаётся на главной:

Компонент	Назначение
SorterDigitalTwin	Full-screen 3D canvas
Play/Pause кнопка	Запуск/пауза автодемо
Mini HUD overlay	Сценарий, категория, step, progress bar
"Details" link	Переход на /details

Что удаляется с главной:

Компонент	Куда идёт
Header	Упрощённый вариант (только logo + Details link)
HeroSection	Удаляется полностью (контекст понятен из 3D)
ProductDemoSection	Интегрируется в full-screen режим
StorylineStepper	→ /details
ScenarioCards	→ /details
CPriorityExplanation	→ /details
CriteriaCards	→ /details
EngineeringDetails	→ /details
Footer	Минимизируется или удаляется

---

3. Details Page Scope

Новая страница /details содержит:

• HeroSection (адаптированная, короткая)
• ScenarioCards (все 9 сценариев)
• CPriorityExplanation
• CriteriaCards
• EngineeringDetails (полные панели)
• StorylineStepper
• Оригинальный демо-режим со step-by-step управлением

Это "документация для жюри":

• Таблицы критериев
• Пояснения правил классификации
• Ручной просмотр отдельных сценариев
• Timeline, PID, Event Log

---

4. 8-Scenario Playback Sequence

Рекомендуемый порядок показа (без jam и emergency для чистого потока):

#	Scenario ID	Название	Категория	Что показывает	Длительность
1	normal_flow	Normal flow	B/C/D mix	Базовый поток, все маршруты	~12s
2	oversized_item	Oversized	C	Габариты FAIL → C	~6s
3	round_object	Round object	D	Roundness K≥0.7 → D	~8s
4	c_priority	C priority	C	Негабарит + круглый = C	~5s
5	boundary_dimensions	Boundary	B/C	Граничные размеры	~8s
6	close_items	Close items	B/B/D	Очередь, spacing warning	~10s
7	low_confidence	Low confidence	B/D	CV fallback, warning	~6s
8	normal_flow	Final loop	B/C/D	Повтор normal для loop	~12s

Общее время: ~67 секунд на полный цикл

Альтернатива с fault/emergency (если жюри хочет видеть):

• Заменить #8 на jam или emergency_stop
• Добавить визуальную индикацию FAULT

---

5. 3D Scene Composition

Что уже есть и работает:

├── SorterDigitalTwin.tsx (главная сцена)
│   ├── Conveyor3D.tsx (лента конвейера)
│   ├── SensorRig3D.tsx (камера, лазер, ultrasonic)
│   ├── Actuator3D.tsx (gate, pusher C, pusher D)
│   ├── SortingZones3D.tsx (зоны B/C/D, roll-cages)
│   ├── Item3D.tsx (товар с реальными STL)
│   ├── RouteArrows3D.tsx (стрелки маршрутов)
│   └── SceneLabels3D.tsx (метки A/B/C/D)

Реальные STL модели (6 шт, ~1.2 MB total):

Файл	Размер	Категория	SKU
bottle.stl	319 KB	D	SKU-007
box-300.stl	29 KB	B	SKU-001
box-400.stl	27 KB	C	SKU-004
cylinder.stl	108 KB	D	SKU-008
lunchbox.stl	566 KB	B	SKU-002
plate.stl	125 KB	D	SKU-006

Procedural fallback (без STL):

• SKU-003 (Detergent) → box primitive
• SKU-005 (Pouf) → cylinder primitive
• SKU-009 (Pen) → thin box primitive
• SKU-010, SKU-011 → box/cylinder primitives

---

6. Camera Storyboard

Использовать существующие presets из demoDirector.ts:

Demo Step	Camera Preset	Что видно
intro	overview	Вся сцена A/B/C/D
spawn_item	overview	Товар появляется в A
move_to_detection	detectionCloseup	Движение к камере
detection_scan	detectionCloseup	Bbox, CV scan
dimensions_check	gateCloseup	Накопитель, stop-gate
roundness_check	gateCloseup	Проверка формы
decision	gateCloseup	Решение B/C/D
command_sent	gateCloseup	ROUTE_TO_*
actuator_move	по категории	Gate/Pusher движение
route_item	routingB/C/D	Товар уходит в зону
result	resultB/C/D	Товар в целевой зоне
reset_or_next	overview	Подготовка к следующему

Переходы камеры:

• Плавная интерполяция (lerp) между presets
• Длительность перехода: 400-600ms
• OrbitControls отключены во время автодемо

---

7. Asset Readiness

STL модели — готовы ✅

• 6 моделей в /public/models/
• Все протестированы, загружаются
• Fallback primitives для остальных

Items — готовы ✅

• 11 SKU в items.ts
• Параметры соответствуют input_info (10×10×2mm, K≥0.7)

Scenarios — готовы ✅

• 9 сценариев в scenarios.ts
• Все работают с текущей simulation

DemoDirector — готов ✅

• Camera presets определены
• Step sequence есть
• Auto playback реализован

Что нужно доработать:

• Multi-scenario playlist (сейчас один сценарий)
• Camera transitions (lerp между presets)
• Full-screen режим без UI chrome
• Loop mode для 8 сценариев

---

8. File Plan

Новые файлы:

Файл	Назначение
src/pages/MainPage.tsx	Новая главная с full-screen 3D
src/pages/DetailsPage.tsx	Страница деталей
src/components/DemoOverlay.tsx	Минимальный HUD для главной
src/components/PlayButton.tsx	Крупная кнопка Play
src/domain/demoPlaylist.ts	Playlist из 8 сценариев

Изменения в существующих:

Файл	Изменение
src/App.tsx	Роутинг: / → MainPage, /details → DetailsPage
src/main.tsx	Добавить React Router
src/domain/demoDirector.ts	Добавить playlist support, camera lerp
src/components/ThreeD/SorterDigitalTwin.tsx	Full-screen mode prop
src/styles.css	Стили для full-screen, overlay, play button

Удаление/перемещение:

Компонент	Действие
HeroSection.tsx	Перенести в DetailsPage
ScenarioCards.tsx	Перенести в DetailsPage
CriteriaCards.tsx	Перенести в DetailsPage
CPriorityExplanation.tsx	Перенести в DetailsPage
EngineeringDetails.tsx	Перенести в DetailsPage
StorylineStepper.tsx	Перенести в DetailsPage

---

9. Risks / Open Questions

Риски:

Риск	Митигация
WebGL context lost на mobile	2D fallback уже есть (ThreeFallback.tsx)
Тяжёлые STL на слабых устройствах	Fallback primitives, DPR снижение
Камера дёргается при быстрых переходах	Easing функция, плавный lerp
Жюри хочет ручной контроль	Ссылка на /details с полным контролем
React Router добавляет bundle	Минимальный импакт (~10KB gzipped)

Open Questions:

Вопрос	Рекомендация
Включать ли jam/emergency в playlist?	Нет для чистого показа, да для полноты
Показывать ли FPS?	Нет на главной, да в /details
Звук/музыка?	Нет, лишняя зависимость
Автозапуск при загрузке?	Нет, ждать клика Play
Loop бесконечно или остановка?	Loop по умолчанию, стоп по клику

---

10. Step 2 Implementation Checklist

Phase 1: Routing Setup

• Установить react-router-dom
• Создать базовый роутинг в App.tsx
• Создать пустые MainPage.tsx и DetailsPage.tsx

Phase 2: Details Page

• Перенести компоненты из App.tsx в DetailsPage
• Сохранить всю текущую функциональность
• Проверить работоспособность /details

Phase 3: Demo Playlist

• Создать demoPlaylist.ts с 8 сценариями
• Добавить playlist mode в demoDirector.ts
• Автопереключение сценариев по завершении

Phase 4: Main Page

• Создать full-screen layout
• Интегрировать SorterDigitalTwin без HUD
• Добавить PlayButton.tsx
• Добавить DemoOverlay.tsx (минимальный)

Phase 5: Camera Transitions

• Добавить lerp для camera position
• Добавить lerp для camera target
• Синхронизировать с demoDirector steps

Phase 6: Polish

• Стили для full-screen
• Mobile responsive
• Тестирование всех 8 сценариев
• Performance check (target: 30+ FPS)

Phase 7: QA

• Desktop 1920×1080: Play → 8 сценариев → loop
• Laptop 1440×900: То же
• Mobile 390×844: Fallback или simplified 3D
• /details: Полная функциональность

---

Summary

Текущее состояние:

• 3D сцена работает
• Все компоненты готовы
• STL модели загружены
• DemoDirector с camera presets есть

Что нужно сделать:

• Роутинг (/ и /details)
• Playlist из 8 сценариев
• Full-screen режим главной
• Camera lerp transitions
• Минимальный overlay

Оценка трудозатрат:

• Phase 1-2: ~1 час
• Phase 3-4: ~2 часа
• Phase 5-6: ~1 час
• Phase 7: ~30 минут

Total: ~4-5 часов