ozone-tech_owl_prime/docs/INPUT_INFO_ANALYSIS.md

# INPUT_INFO_ANALYSIS

Анализ материалов из папки `input_info` для приведения проекта в соответствие с официальной постановкой задачи OZON Tech Track 3.

## 1. Что найдено в input_info

| Путь файла | Тип | Содержит | Важность | Как использовать |
|------------|-----|----------|----------|------------------|
| `doc-1783009063.pdf` | PDF | Перечень допустимого ПО | Средняя | Подтверждение стека (React, Docker, open-source инструменты) |
| `doc-1783009942.pdf` | PDF | Схема рабочей зоны с размерами | Высокая | Размеры зон A/B/C/D, ролл-кейджей; добавить в документацию |
| `doc-1783011400.pdf` | PDF | Критерии оценки Track 3 | **Критическая** | Матрица баллов, детальные требования к презентации/УГТ/корректности |
| `extracted/Постановка_Задача_3_сжато_2.pdf` | PDF | Полная постановка задачи (17 стр) | **Критическая** | Официальные параметры классификации, правила, глоссарий, требования к сдаче |
| `doc-1782987706.zip` → `Step/*.stp` | STEP | 11 3D-моделей товаров | Высокая | Тестовый набор для проверки классификации |
| `doc-1782987733.zip` → `Stl/*.stl` | STL | 11 3D-моделей товаров (дубликат) | Средняя | Альтернативный формат моделей для симуляций |
| `ozone-tech_owl_prime_170-main.zip` | ZIP | Пустой README.md | Низкая | Не содержит полезных материалов |

**Тестовый набор товаров (STEP/STL):**
1. Бутылка
2. Короб 300×200×200
3. Короб 400×400×300
4. ЛанчБокс
5. Мешок
6. Моющее средство
7. Пуфик
8. Ручка
9. Тарелка
10. Цилиндр
11. Шлем

## 2. Ключевые требования из input_info

### 2.1. Параметры классификации (КРИТИЧЕСКИЕ ИСПРАВЛЕНИЯ)

Из `Постановка_Задача_3_сжато_2.pdf`:

#### Минимальные габариты:
- **Официально:** 10×10×**2 мм**
- **Источник:** `Постановка_Задача_3_сжато_2.pdf`, стр. 2/17, раздел "Термины задачи", строка 81
- **Цитата:** "его габариты больше минимально допустимых 10 × 10 × 2 мм"
- **В текущем коде:** 10×10×**10 мм** ❌ → **ИСПРАВЛЕНО** ✅

#### Максимальные габариты:
- **Официально:** 450×320×320 мм
- **Источник:** `Постановка_Задача_3_сжато_2.pdf`, стр. 2/17, раздел "Термины задачи", строка 82
- **Цитата:** "меньше максимально допустимых 450 × 320 × 320 мм"
- **В текущем коде:** 450×320×320 мм ✅

#### Порог круглости:
- **Официально:** K = r_in / r_out ≥ **0.7**
- **Источник:** `Постановка_Задача_3_сжато_2.pdf`, стр. 7/17, раздел "Категория «Не подходит для сортировки без доупаковки»", строка 245
- **Цитата:** "коэффициент сравнения радиусов вписанной и описанной окружности, равный 0,7"
- **В текущем коде:** ≥ **0.8** ❌ → **ИСПРАВЛЕНО** ✅

#### Скорость конвейера:
- **Официально:** 1.0 м/с
- **Источник:** `Постановка_Задача_3_сжато_2.pdf`, стр. 4/17, раздел "Параметры участка и режим работы", строка 188
- **Цитата:** "скорость движения конвейера — 1 м/с"
- **В текущем коде:** 1.0 м/с ✅

### 2.2. Правила классификации

**Категория B "Подходит для сортировки":**
- Габариты: 10×10×**2** мм ≤ размеры ≤ 450×320×320 мм
- НЕТ круга в сечении (K < 0.7)

**Категория C "Не подходит по габаритам":**
- Размеры < 10×10×**2** мм ИЛИ > 450×320×320 мм
- **C имеет приоритет над D** (проверка габаритов идёт первой)

**Категория D "Не подходит без доупаковки":**
- Габариты проходят
- Есть круг в сечении (K ≥ 0.7)

**Порядок проверки:**
1. Сначала габариты → если не прошли, категория **C**
2. Затем форма → если круг, категория **D**
3. Иначе категория **B**

### 2.3. Схема участка (из doc-1783009942.pdf)

- **Рабочая зона:** 6000×10000 мм (фиксированная)
- **A (подача):** конвейерная линия 500×700 мм (фикс)
- **B (основной сортировщик):** конвейерная линия 500×700 мм (фикс относительно A)
- **C (негабарит):** ролл-кейдж 1200×800×800 мм (свободное размещение в рабочей зоне)
- **D (неправильная форма):** ролл-кейдж 1200×800×800 мм (свободное размещение в рабочей зоне)

### 2.4. Критерии оценки (из doc-1783011400.pdf)

**Раздел 1. Презентация (0-10 баллов)**
- 0-5: Ясность материалов
- 0-5: Выступление и ответы на вопросы

**Раздел 2. УГТ (0-20 баллов)**
- Матрица 4×4: ось CV (1-4) × ось исполнительной части (1-4)

**Раздел 3. Корректность определения (0-20 баллов)**
- 0-10: Корректность на тестовом наборе
- 0-5: Полнота правил классификации
- 0-5: Устойчивость в пограничных случаях

**Раздел 4. Исполнительная часть (0-30 баллов)**
- 0-10: Корректность физической маршрутизации
- 0-10: Качество манипуляции
- 0-5: Разная геометрия объектов
- 0-5: Безопасность эксплуатации

**Раздел 5. Производительность (0-20 баллов)**
- 0-10: Cycle time и производительность
- 0-5: Синхронизация по времени
- 0-5: Устойчивость к нештатным ситуациям

**Раздел 6. Связность (0-15 баллов)**
- 0-10: Связность CV и исполнительной части
- 0-5: Инженерная реалистичность

**Раздел 7. Отчетность (0-15 баллов)**
- 0-5: Полнота и качество отчета
- 0-5: Воспроизводимость и удобство проверки
- 0-5: Полнота комплекта сдачи

**Итого:** 130 баллов

### 2.5. Требования к сдаче (из Постановки задачи)

**Обязательный состав:**
- Описание подхода к классификации ✅
- Исходный код алгоритмической части ✅
- Проектные материалы по исполнительной части ✅
- Цифровая модель / симуляция / расчётное обоснование ✅ (3D digital twin)
- Описание связи CV → исполнительная часть ✅
- Итоговый отчет команды ✅
- Видеодемонстрация работы ⏳ (TODO)

**Формат презентации:**
- Длительность: не более **7 минут**
- Формат: живая демонстрация / видео / комбинация

**Рекомендуемая структура презентации:**
1. О команде
2. Постановка задачи и подход
3. Логика классификации
4. Схема маршрутизации A/B/C/D
5. Исполнительная часть и автоматическая перекладка
6. Подтверждение: метрики, симуляция, расчёты, цифровой прототип
7. Используемые инструменты и выбор
8. Ограничения и развитие

## 3. Что уже реализовано

✅ **Архитектура:** React + Vite + TypeScript + Three.js  
✅ **Классификация:** Чистая функция `classifyItem` с габаритами и roundness  
✅ **State machine:** IDLE → DETECTING → CLASSIFYING → ROUTE_TO_* → RETURN_HOME  
✅ **Исполнительная часть:** Stop-gate, pusher C, pusher D, физическая маршрутизация  
✅ **3D Digital Twin:** React Three Fiber, labels A/B/C/D, route beams, roll-cages  
✅ **2D Fallback:** SVG для mobile и WebGL unavailable  
✅ **Сценарии:** normal_flow, oversized_item, round_object, c_priority, boundary_dimensions, close_items, low_confidence, jam, emergency_stop  
✅ **Criteria Cards:** Покрытие критериев OZON с привязкой к сценариям  
✅ **Engineering Details:** Sensors, PID, Timeline, Event Log, 3D capability check  
✅ **Документация:** README, ARCHITECTURE, DEMO_SCRIPT, SCENARIOS, JURY_QA, SUBMISSION_CHECKLIST, UI_UX_REDESIGN_AUDIT, THREE_D_FEASIBILITY  
✅ **Тесты:** 16/16 passed (classifier, scenarios, demo steps, criteria)  
✅ **Docker:** compose project `owl`, nginx, domain checks OK  
✅ **C-priority:** Габариты проверяются первыми, oversized + round → C

## 4. Что нужно добавить/исправить

### 4.1. КРИТИЧЕСКИЕ исправления параметров

❌ **`src/domain/classifier.ts`:**
```typescript
// БЫЛО:
min: { width: 10, depth: 10, height: 10 },
roundnessThreshold: 0.8,

// ДОЛЖНО БЫТЬ:
min: { width: 10, depth: 10, height: 2 },
roundnessThreshold: 0.7,
```

❌ **`README.md`:**
- Строка 153: "min: width >= 10 мм, depth >= 10 мм, height >= 10 мм" → **height >= 2 мм**
- Строка 155: "roundness threshold: 0.8" → **0.7**
- Строка 132: "roundness >= 0.8" → **>= 0.7**

❌ **`src/data/scenarios.ts`:**
- Строка 26: "roundness >= 0.8" → **>= 0.7**

❌ **`docs/JURY_QA.md`:**
- Строка 45: "10×10×10 mm" → **10×10×2 mm**
- Строка 45: "threshold 0.8" → **threshold 0.7**

❌ **`docs/SUBMISSION_CHECKLIST.md`:**
- Строка 21: "10×10×10 mm" → **10×10×2 mm**

### 4.2. Точечные UX улучшения

⚠️ **Hero Section:**
- Добавить крупный proof-line: `Detection → Classification → ROUTE_TO_* → Actuator → B/C/D`
- Добавить бейджи параметров: `Конвейер 1 м/с`, `Min 10×10×2 мм`, `Max 450×320×320 мм`, `K ≥ 0.7 → D`, `C priority`

⚠️ **Product Demo Section:**
- Сделать крупнее блок текущего решения: **Category / Command / Target / Why**
- Для C-priority явно показать: "dimensions failed, so C has priority even though K = 0.93"

⚠️ **C-priority explanation:**
- Добавить заметную карточку/блок с объяснением приоритета C над D

⚠️ **Mobile fallback:**
- Добавить текст объяснения: "3D Digital Twin доступен на desktop. На узком экране включена 2D-схема с той же логикой."

⚠️ **Engineering Details:**
- Добавить пояснение про physics engine: "Physics engine не включён в production-сцену намеренно: для защиты важна воспроизводимая маршрутизация B/C/D."

### 4.3. Документация

⚠️ **README.md:**
- Добавить раздел "input_info" с описанием использованных материалов
- Добавить упоминание тестового набора товаров (11 STEP/STL моделей)

⚠️ **DEMO_SCRIPT.md:**
- Добавить финальный 7-минутный тайминг:
  - 0:00–0:20 что это
  - 0:20–0:45 полный контур
  - 0:45–1:30 B
  - 1:30–2:15 C
  - 2:15–3:00 D
  - 3:00–3:45 C-priority
  - 3:45–4:30 low confidence/fault
  - 4:30–5:30 Engineering Details
  - 5:30–6:30 критерии и метрики
  - 6:30–7:00 ограничения и развитие

⚠️ **JURY_QA.md:**
- Добавить вопрос про physics engine (уже есть, но дополнить)
- Добавить вопрос про тестовый набор STEP/STL моделей
- Обновить параметры 10×10×2 и 0.7

⚠️ **SUBMISSION_CHECKLIST.md:**
- Обновить параметры
- Добавить пункт про input_info analysis

⚠️ **Новый файл: docs/INPUT_INFO_ANALYSIS.md** ✅ (этот документ)

### 4.4. Тесты

⚠️ **Обновить тесты под новые параметры:**
- classifier.test.ts: проверки min height 2 мм, roundness 0.7
- scenarios.test.ts: обновить ожидаемые результаты если изменились

### 4.5. 3D Scene labels

⚠️ **Проверить метки в 3D:**
- A Input
- Накопитель / Accumulator
- CV Camera
- Stop-gate
- Pusher C
- Pusher D
- B Main sorter
- C Dimensions reject
- D Repack

Убедиться, что labels крупные и понятные.

## 5. Что использовать в UI

### Формулировки для Hero:

**Заголовок:**
> Интеллектуальная система предварительной сортировки товаров

**Подзаголовок:**
> 3D-симуляция ПАК показывает полный цикл: товар поступает из A, определяется CV-модулем, классифицируется в B/C/D и физически маршрутизируется исполнительной частью.

**Proof-line:**
> Detection → Classification → ROUTE_TO_* → Actuator → B/C/D

**Бейджи параметров:**
- Конвейер 1 м/с
- Min 10×10×2 мм
- Max 450×320×320 мм
- K ≥ 0.7 → D
- C priority

### Формулировки для Product Demo:

**Current decision summary (крупно):**
```
Category: B / C / D
Command: ROUTE_TO_B / ROUTE_TO_C / ROUTE_TO_D
Target: Zone B / Zone C / Zone D
Why: [1 короткая строка]
```

**Примеры Why:**
- B: "dimensions pass and round section is not detected"
- C: "dimensions failed (oversized)"
- D: "dimensions pass, but K = 0.92 ≥ 0.7"
- C-priority: "dimensions failed, so C has priority even though K = 0.93"

### Формулировки для C-priority explanation:

**Заголовок:**
> Почему C имеет приоритет?

**Текст:**
> Если товар одновременно негабаритный и имеет круг в сечении, он направляется в C. Сначала проверяются габариты, и только если они проходят — форма. Это предотвращает попадание негабаритных объектов в основной сортировщик.

### Формулировки для mobile fallback:

> 3D Digital Twin доступен на desktop. На узком экране включена 2D-схема с той же логикой классификации и маршрутизации.

### Формулировки для Engineering Details (physics engine):

> В демо используется управляемая 3D state-machine simulation. Physics engine не включён в production-сцену намеренно: для защиты важна воспроизводимая маршрутизация B/C/D. Архитектура допускает подключение physics engine позднее.

## 6. Что использовать в документации

### README.md:

**Новый раздел после "Стек":**

```markdown
## input_info

Проект разработан в соответствии с официальной постановкой задачи OZON Tech Track 3.

**Использованные материалы:**
- `Постановка_Задача_3_сжато_2.pdf` — полная постановка задачи (правила классификации, схема участка, критерии оценки)
- `doc-1783009942.pdf` — схема рабочей зоны с размерами A/B/C/D
- `doc-1783011400.pdf` — критерии оценки Track 3 (матрица баллов)
- `doc-1782987706.zip` → STEP модели тестовых товаров (11 шт)
- `doc-1782987733.zip` → STL модели тестовых товаров (11 шт)

**Тестовый набор товаров:**
Цилиндр, Шлем, Бутылка, Мешок, Тарелка, Короб 400×400×300, ЛанчБокс, Короб 300×200×200, Пуфик, Ручка, Моющее средство.

**Параметры классификации (согласно постановке):**
- Min dimensions: **10×10×2 мм**
- Max dimensions: 450×320×320 мм
- Roundness threshold: K ≥ **0.7**
- Conveyor speed: 1.00 м/с
- C-priority: габариты проверяются первыми

Подробный анализ: `docs/INPUT_INFO_ANALYSIS.md`
```

### DEMO_SCRIPT.md:

**Добавить секцию "7-Minute Structure":**

```markdown
## 7-Minute Structure

Рекомендуемый тайминг для защиты (максимум 7 минут):

- **0:00–0:20** Что это за система? ПАК предварительной сортировки, полный цикл A → CV → B/C/D.
- **0:20–0:45** Полный контур: Detection → Classification → Command → Actuator → Route.
- **0:45–1:30** Категория B: габариты проходят, нет круга, зелёный маршрут в основной сортировщик.
- **1:30–2:15** Категория C: негабаритный товар, оранжевый маршрут в roll-cage C.
- **2:15–3:00** Категория D: габариты проходят, но круг в сечении (K ≥ 0.7), фиолетовый маршрут в roll-cage D.
- **3:00–3:45** C-priority: негабаритный + круглый → всё равно C (приоритет габаритов).
- **3:45–4:30** Low confidence и fault: rule-based fallback, FAULT состояние, EMERGENCY_STOP.
- **4:30–5:30** Engineering Details: timeline, PID, sensors, event log, 3D capability check.
- **5:30–6:30** Критерии OZON и метрики: cycle time, устойчивость, воспроизводимость.
- **6:30–7:00** Ограничения MVP и развитие: real CV, physics engine, WebSocket телеметрия.
```

### JURY_QA.md:

**Обновить вопрос 11:**

```markdown
## 11. How Are Dimensions And Circular Section Handled?

Dimensions are checked first against min/max: **10×10×2 mm** to 450×320×320 mm. If they pass, roundness K = r_in / r_out is checked against threshold **0.7**. Conveyor target speed is 1.00 m/s.
```

**Добавить новый вопрос 22:**

```markdown
## 22. Where Are The Test Object Models From input_info?

The official test set includes 11 STEP/STL models from input_info: Cylinder, Helmet, Bottle, Bag, Plate, Box 400×400×300, Lunchbox, Box 300×200×200, Pouf, Pen, Detergent. These models can be used to validate classification correctness on realistic geometries.
```

## 7. Риски

### 7.1. Изменение параметров может сломать тесты

✅ **Митигация:** Сначала обновить `classifier.ts`, затем запустить тесты, исправить ожидаемые результаты где нужно.

### 7.2. Изменение min height с 10 на 2 мм может изменить категории некоторых товаров

✅ **Митигация:** Проверить все товары в `items.ts`:
- SKU-009 (Pen 9×13×148): width 9 < 10, всё равно C ✅
- Остальные товары имеют height > 10 мм, изменение не влияет ✅

### 7.3. Изменение roundness threshold с 0.8 на 0.7 может изменить категории

✅ **Митигация:** Проверить все товары:
- SKU-006 (Plate, roundness 0.95): было D, останется D ✅
- SKU-007 (Bottle, roundness 0.92): было D, останется D ✅
- SKU-008 (Cylinder, roundness 0.88): было D, останется D ✅
- SKU-005 (Pouf, roundness 0.74): было C (oversized), останется C ✅
- Нет товаров с roundness между 0.7 и 0.8, которые меняют категорию ✅

### 7.4. Нет видеодемонстрации

⚠️ **Риск:** Требование к сдаче включает видеодемонстрацию работы решения.

✅ **Митигация:** Указать в SUBMISSION_CHECKLIST и JURY_QA, что live demo на сайте заменяет видео, но при необходимости можно записать screen capture 7-минутного прохода.

### 7.5. Нет реального ML / CV

⚠️ **Риск:** Жюри может спросить про настоящее машинное зрение.

✅ **Митигация:** Уже указано в JURY_QA.md: "The MVP uses pseudo-CV: bbox, dimensions, confidence and latency are derived from mock items. The architecture keeps CV output separate from classification, so a real CV service can replace it later."

## 8. Definition of Done

Проект готов к защите, когда выполнены все пункты:

### 8.1. Параметры классификации

- [ ] `src/domain/classifier.ts`: min height = 2 мм, roundness threshold = 0.7
- [ ] `README.md`: обновлены параметры
- [ ] `src/data/scenarios.ts`: обновлено описание roundness
- [ ] `docs/JURY_QA.md`: обновлены параметры
- [ ] `docs/SUBMISSION_CHECKLIST.md`: обновлены параметры

### 8.2. UX улучшения

- [ ] Hero: добавлен proof-line и бейджи параметров
- [ ] Product Demo: крупный блок Category / Command / Target / Why
- [ ] C-priority: отдельная карточка/блок объяснения
- [ ] Mobile fallback: текст объяснения
- [ ] Engineering Details: пояснение про physics engine

### 8.3. Документация

- [ ] `docs/INPUT_INFO_ANALYSIS.md`: создан ✅
- [ ] `README.md`: добавлен раздел input_info
- [ ] `DEMO_SCRIPT.md`: добавлен 7-минутный тайминг
- [ ] `JURY_QA.md`: обновлены ответы, добавлен вопрос про тестовые модели
- [ ] `SUBMISSION_CHECKLIST.md`: обновлён

### 8.4. Тесты

- [ ] `npm run test` проходит
- [ ] Все 16+ тестов зелёные

### 8.5. Build & Deploy

- [ ] `npm run build` успешно
- [ ] Docker project `owl` перезапущен
- [ ] `https://arhipovdan.ru/` открывается
- [ ] `https://www.arhipovdan.ru/` открывается
- [ ] `https://ai-shorts.ru/` не затронут

### 8.6. Visual QA

- [ ] Desktop 1920×1080: Hero понятен, proof-line виден, бейджи читаемы
- [ ] Laptop 1440×900: Category/Command/Target крупные
- [ ] Mobile 390×844: fallback объяснён, нет horizontal scroll
- [ ] Сценарии: B / C / D / C-priority / low confidence / fault / emergency работают
- [ ] Console: no React errors, no WebGL errors

### 8.7. Git

- [ ] `git status` показывает только изменённые файлы (нет мусора)
- [ ] `git diff` проверен
- [ ] Команды для commit/push подготовлены (но НЕ выполнены)

---

**Дата создания:** 2026-07-04  
**Автор:** Claude Sonnet 4.5  
**Цель:** Привести проект в полное соответствие с официальной постановкой задачи OZON Tech Track 3 перед финальной защитой.