ozone-tech_owl_prime/docs/FULL_PROJECT_AUDIT.md

Полный аудит проекта — OZON Tech Sorter Simulation

Дата аудита: 2026-07-15
Ветка: feature/maximum-demo-realism (от dan_branch @ e89c728)
Точка отката: тег backup/pre-maximum-demo-realism-20260715
Репозиторий: /home/coder/arhipovdan/app
Публичный URL: https://arhipovdan.ru/

Метка	Значение
Тип данных	Измерено / проверено в репозитории и на сервере
Статус	Frontend-only MVP, Track 3 (цифровой двойник сортировки)

---

1. Описание проекта

OZON Tech Sorter Simulation — React/Vite/Three.js цифровой двойник промышленной сортировки товаров (Track 3). Система демонстрирует полный контур:

Поступление объекта
→ обнаружение (pseudo-CV / сенсоры)
→ измерения и признаки (габариты, K-roundness)
→ classifyItem (детерминированные правила)
→ управляющий сигнал (gate / pusher)
→ кинематическое перемещение
→ маршрут B / C / D или fault
→ журнал событий + метрики

Характер MVP: только frontend. Backend, WebSocket, БД, API-сервер — отсутствуют. Сборка — статический dist, раздача через nginx (Docker-образ или локальный preview).

Два движка демонстрации:

Маршрут	Движок	Назначение
/	Continuous playback + playlist	Основная демо для жюри: непрерывный 3D twin, seek/speed, hotkeys
/details	State-machine simulation	Инженерный разбор: FSM, сенсоры, PID, сценарии

Оба движка используют общий classifyItem и доменные типы, но визуальные 3D-сцены всё ещё различаются (SorterDigitalTwinContinuous vs SorterDigitalTwin).

---

2. Архитектура

src/data/items.ts, scenarios.ts, resolveItem.ts, modelAssets.ts
        |
        v
src/domain/classifier.ts  ← единый источник решения (B/C/D)
        |
        +-- continuousPlayback.ts + demoPlaylist.ts + measurementSystem.ts  → MainPage (/)
        |
        +-- simulation.ts + metrics/pid/sensors                              → DetailsPage (/details)
        |
        v
React UI + R3F (Three.js) + Proof HUD / CV overlay / EventLog

Деплой (production-контур):

Vite build → dist/
    → Docker (node:20-alpine build + nginx:alpine runtime)
    → nginx слушает 127.0.0.1:3100 на хосте OwlPrime
    → cloudflared tunnel → https://arhipovdan.ru/

В текущем окружении нет docker CLI для оператора; Node 20.20.2 используется для локальной сборки. Production-контейнер мог быть поднят вне этой среды — см. риск устаревшего dist на :3100.

---

3. Карта модулей

Область	Путь	Роль
Точка входа	src/main.tsx, src/App.tsx	Router: /, /details
Continuous demo	src/domain/continuousPlayback.ts	Фазы кейса, таймлайн, fault freeze
Playlist	src/domain/demoPlaylist.ts	10 кейсов (классификация + jam + e-stop)
Измерения	src/domain/measurementSystem.ts	Stepper/laser/stereo → classifyItem
Классификатор	src/domain/classifier.ts	DIMENSION_LIMITS, приоритет C над D
Кинематика	src/domain/physicalItemMotion.ts	Путь по сети конвейера, jitter, freeze
Layout	src/domain/physicalLayout.ts, conveyorNetwork.ts	Единицы мм/м, геометрия линий
Качество	src/domain/qualityMode.ts	low / medium / high / demo
FSM sim	src/domain/simulation.ts	State machine для /details
3D continuous	src/components/ThreeD/SorterDigitalTwinContinuous.tsx	Основной twin
3D details	src/components/ThreeD/SorterDigitalTwin.tsx	Инженерный twin
Proof UI	CurrentProofCard, CVInspectionOverlay	DIM / K / reason / RULE
Agent MVP	agent/cli.mjs	dry-run / run-once / status / stop…
Demo scripts	scripts/demo-*.sh, scripts/agent-*.sh	One-command ops

---

4. Текущий стек

Слой	Технология	Примечание
Bundler	Vite	Production build ~сотни ms
UI	React 19 + TypeScript	SPA
3D	Three.js + @react-three/fiber + drei	Клиентский WebGL
Тесты	Vitest	Unit/domain; e2e Playwright — вручную
Контейнер	Docker multi-stage + nginx	Статический хостинг
Runtime на сервере	nginx :3100, cloudflared	Без pm2 в этой среде
Node (build)	20.20.2	Измерено

Чего нет (подтверждено аудитом): backend, БД, WebSocket/SSE, PM2, docker CLI в текущем shell-окружении, CI e2e, реальный ML/CV, физический движок (Rapier/Cannon и т.п.).

Секреты: файл .env присутствует (ключи login, password, url). Значения не документируются и в отчёты не включаются.

---

5. Выявленные проблемы

#	Проблема	Критичность	Влияние на демо
P1	Dual 3D twins визуально расходятся (/ vs /details)	Высокая	Зритель может не понять «одну систему»
P2	Нет реального physics engine — детерминированная кинематика	Средняя	При пристальном взгляде нет столкновений/инерции «как в жизни»
P3	Pseudo-CV (измерения из данных SKU, не с камеры)	Средняя	Нужен Proof HUD, иначе «анимация»
P4	Production :3100 может отдавать старый dist до redeploy	Высокая	Публичная демо ≠ локальная сборка
P5	Нет e2e в CI; Playwright только scripts	Средняя	Регрессии UI ловятся вручную
P6	Agent MVP не патчит код автоматически	Низкая (by design)	Автономность ограничена verify-only
P7	GPU на сервере idle; 3D на клиенте	Инфо	Серверный offscreen render не нужен

---

6. Критичность (сводка)

Уровень	Количество	Действие
Критическая для живого показа	1	Синхронизировать/передеплоить prod dist
Высокая (доверие демо)	2	Унификация twin + явный proof алгоритма (уже частично сделано)
Средняя (техдолг)	3	Physics/CV/e2e — план, не блокер MVP
Низкая / by design	1	Agent без auto-merge

---

7. Технический долг

1. Два рендерера сцены — дублирование материалов/освещения/лейаута.
2. Кинематика вместо физики — осознанный trade-off производительности и детерминизма.
3. Pseudo-CV — confidence фиксирован (0.65 в measurement path после фикса min dims); нет модели.
4. Ручные Playwright-скрипты в scripts/ без интеграции в CI.
5. Agent — оркестратор без Implementer-патчей (verify-only).
6. Документация историческая в docs/*_REPORT.md — много итерационных отчётов; этот аудит — актуальная точка истины на 2026-07-15.

---

8. Состояние тестов

Метрика	До изменений	После изменений	Тип данных
Passed	144	153	Измерено
Файлов тестов	14	16	Измерено
Runner	Vitest	Vitest	—

Добавлено/расширено: simulation.test.ts (jam / emergency_stop / c_priority), тесты quality mode и связанные domain-тесты.

E2E: не в CI. Скрипты Playwright/Python в scripts/ — ручной прогон (оценка процесса, не автоматический gate).

---

9. Состояние production build

Метрика	До	После	Тип
npm run build	OK (~391 ms)	OK	Измерено
Main R3F chunk	~881 kB	(сборка OK; детальный breakdown см. PERFORMANCE_BASELINE)	Измерено / частично
CSS	—	39.66 kB (gzip 8.79)	Измерено
Continuous twin chunk	—	51.29 kB (gzip 13.68)	Измерено

Команда: tsc -b && vite build. Typecheck входит в build pipeline.

---

10. Состояние демонстрации

Сильные стороны (после итерации maximum-demo-realism):

• classifyItem встроен в continuous playback — live classification, не только playlist override.
• Playlist 10 кейсов: B/C/D, edge, c_priority, jam, emergency_stop.
• Demo controls: seek, speed 0.5–2×, hotkeys (Space/N/B/R/P/E/F/1–0), presentation mode, event journal.
• Proof HUD: DIM pass/fail, K, classifier reason; CV overlay с RULE.
• Quality modes: low / medium / high / demo.
• Fault freeze/recover в physicalItemMotion + seeded jitter.
• One-command: npm run demo:start / demo:health / agent scripts.

Ограничения для жюри:

• Публичный https://arhipovdan.ru/ может ещё показывать старый билд, пока не пересобран/не перезалит контейнер на :3100.
• Визуальное отличие / и /details.
• Нет настоящего ML-CV и rigid-body physics.

Готовность к показу: высокая для локального preview (127.0.0.1:3101 через demo:start) при зелёных тестах; production — после явного redeploy.

---

11. Вывод аудита

Проект — зрелый frontend digital twin с убедительным демо-контуром и измеримой proof-логикой классификации. Главные остаточные риски для показа: синхронизация production dist и визуальная унификация двух twin. Автономный агент на сервере — возможен с ограничениями (1 worker, hybrid LLM, без auto-deploy). Подробности — в SERVER_CAPACITY_REPORT.md и AUTONOMOUS_AI_AGENT_ARCHITECTURE.md.