985f7c327d
Wire live classifyItem into continuous playback, add jam/E-stop cases, presenter controls (seek/speed/hotkeys), quality modes, demo scripts, audit docs, and a verify-only autonomous agent CLI with hard safety limits. Co-authored-by: Cursor <cursoragent@cursor.com>
163 lines
8.1 KiB
Markdown
163 lines
8.1 KiB
Markdown
# План максимизации демонстрации
|
||
|
||
**Проект:** OZON Tech Sorter Simulation
|
||
**Ветка реализации:** `feature/maximum-demo-realism`
|
||
**Дата:** 2026-07-15
|
||
|
||
Документ фиксирует целевое состояние демо, этапы и критерии приёмки. Статус этапов: **Done** = реализовано в этой итерации; **Open** = остаётся.
|
||
|
||
---
|
||
|
||
## 1. Текущее состояние (as-is)
|
||
|
||
| Аспект | Состояние | Тип |
|
||
| ------ | --------- | --- |
|
||
| Движки | Continuous `/` + FSM `/details` | Измерено |
|
||
| Классификация на `/` | `classifyItem` wired (live) | Измерено (код) |
|
||
| Playlist | 10 кейсов вкл. jam + e-stop | Измерено |
|
||
| Proof | HUD DIM/K/reason + CV RULE | Измерено |
|
||
| Управление | seek, 0.5–2×, hotkeys, presentation | Измерено |
|
||
| Quality | low/medium/high/demo | Измерено |
|
||
| Physics | Детерминированная кинематика + jitter | Измерено |
|
||
| CV | Pseudo | Измерено |
|
||
| Twin parity `/` vs `/details` | Расходятся визуально | Измерено |
|
||
| Prod sync | :3100 может быть старым | Измерено (риск) |
|
||
| Tests | 153 / 16 files | Измерено |
|
||
| Agent | MVP verify-only | Измерено |
|
||
|
||
---
|
||
|
||
## 2. Целевое состояние (to-be)
|
||
|
||
Демонстрация должна за 5–10 секунд отвечать зрителю:
|
||
|
||
1. Что это за система (промышленная сортировка OZON Tech).
|
||
2. Откуда берётся решение (измерения → правила → B/C/D).
|
||
3. Что делают механизмы (gate/pusher/маршрут).
|
||
4. Что происходит при аварии (jam / e-stop + recover).
|
||
5. Что это не «мультфильм»: proof HUD, журнал, метрики.
|
||
|
||
Целевые свойства:
|
||
|
||
- визуально реалистичный industrial twin;
|
||
- физически правдоподобное (хотя бы кинематически согласованное) движение;
|
||
- стабильные 30–60 FPS в режиме demo;
|
||
- one-command start + health;
|
||
- откат через git tag;
|
||
- production = тот же билд, что прошёл тесты.
|
||
|
||
---
|
||
|
||
## 3. Этапы
|
||
|
||
| # | Этап | Приоритет | Сложность | Статус | Ожидаемый эффект |
|
||
| - | ---- | --------- | --------- | ------ | ---------------- |
|
||
| E1 | Wire `classifyItem` в continuous | P0 | Низкая | **Done** | Доверие к алгоритму |
|
||
| E2 | Measurement + DIMENSION_LIMITS + confidence | P0 | Средняя | **Done** | Корректные min dims, reason |
|
||
| E3 | Playlist 8→10 + fault timelines | P0 | Средняя | **Done** | Safety story для жюри |
|
||
| E4 | Fault freeze/recover + seeded jitter | P1 | Средняя | **Done** | Правдоподобие / воспроизводимость |
|
||
| E5 | Demo controls + presentation + journal | P0 | Средняя | **Done** | Управление показом |
|
||
| E6 | Quality modes | P1 | Низкая | **Done** | FPS на слабых клиентах |
|
||
| E7 | Proof HUD + CV RULE overlay | P0 | Средняя | **Done** | «Видно почему» |
|
||
| E8 | simulation tests jam/estop/c_priority | P1 | Низкая | **Done** | Регрессионная защита |
|
||
| E9 | Agent MVP + scripts | P1 | Средняя | **Done** | Ops / future autonomy |
|
||
| E10 | resolveItem SKU-*-LC | P2 | Низкая | **Done** | Стабильность данных |
|
||
| E11 | Унификация визуала `/` и `/details` | P1 | Высокая | **Open** | Единый образ системы |
|
||
| E12 | Redeploy prod dist на :3100 | P0 | Низкая (ops) | **Open** | Публичная демо актуальна |
|
||
| E13 | Playwright в CI (1 worker) | P2 | Средняя | **Open** | Авто-регрессия UI |
|
||
| E14 | Опциональный physics (Rapier lite) | P3 | Высокая | **Open** | Доп. fidelity (не блокер) |
|
||
| E15 | Agent auto-patch за human gate | P3 | Высокая | **Open** | Автономия уровня 2 |
|
||
|
||
---
|
||
|
||
## 4. Приоритет (матрица)
|
||
|
||
| Приоритет | Фокус |
|
||
| --------- | ----- |
|
||
| P0 | То, без чего живой показ врёт или ломается: классификация, proof, faults, controls, prod sync |
|
||
| P1 | Убедительность и стабильность: quality, tests, twin unify, agent ops |
|
||
| P2 | Удобство и покрытие: e2e CI, data edge cases |
|
||
| P3 | Исследования: real physics, full autonomous implementer |
|
||
|
||
---
|
||
|
||
## 5. Ожидаемый эффект по направлениям
|
||
|
||
| Направление | Эффект Done-этапов | Остаточный разрыв |
|
||
| ----------- | ------------------ | ----------------- |
|
||
| Demo clarity | Высокий — seek/hotkeys/presentation | — |
|
||
| Algorithm proof | Высокий — live classify + HUD | Pseudo-CV всё ещё |
|
||
| Fault story | Высокий — jam/e-stop в playlist | — |
|
||
| Visual realism | Средний+ | Dual twin, нет AO/heavy PBR |
|
||
| Physics fidelity | Средний | Нет rigid body |
|
||
| Ops | Высокий — scripts + agent | Redeploy path вне docker CLI |
|
||
|
||
---
|
||
|
||
## 6. Сложность оставшихся работ
|
||
|
||
| Работа | Сложность | Зависимости | Риск |
|
||
| ------ | --------- | ----------- | ---- |
|
||
| Unify twins | Высокая | Общий scene kit, не ломая оба маршрута | Регрессия `/details` |
|
||
| Prod redeploy | Низкая | Доступ к docker/host вне среды | Забыть обновить tunnel cache |
|
||
| e2e CI | Средняя | 1 worker, артефакты | Flaky screenshots |
|
||
| Rapier | Высокая | Performance budget | FPS падение |
|
||
| Agent patcher | Высокая | Safety limits, staging | Порча ветки |
|
||
|
||
---
|
||
|
||
## 7. Риски плана
|
||
|
||
| Риск | Митигация |
|
||
| ---- | --------- |
|
||
| Погоня за «настоящей физикой» убивает FPS | Держать кинематику; physics только opt-in |
|
||
| Унификация twin ломает details UX | Feature flag / поэтапный shared module |
|
||
| Агент без лимитов | Kill switch + forbid deploy |
|
||
| Показ со старым prod | `demo:health` + явный checklist redeploy |
|
||
|
||
---
|
||
|
||
## 8. Зависимости
|
||
|
||
```text
|
||
E12 (redeploy) зависит от зелёных tests/build на feature-ветке
|
||
E11 (unify) зависит от стабильного continuous twin (E1–E7 Done)
|
||
E13 (e2e CI) зависит от ёмкости (1 worker) и стабильных селекторов
|
||
E15 (agent patch) зависит от E9 + AI_AGENT_SAFETY_LIMITS
|
||
```
|
||
|
||
---
|
||
|
||
## 9. Критерии приёмки
|
||
|
||
### Must (для «максимальной демо» итерации)
|
||
|
||
- [x] Continuous использует `classifyItem` (не только playlist label).
|
||
- [x] Playlist ≥10 с jam и emergency_stop.
|
||
- [x] Proof HUD показывает DIM, K, reason.
|
||
- [x] Hotkeys + speed + seek + presentation работают.
|
||
- [x] Quality modes существуют и покрыты тестами.
|
||
- [x] Vitest зелёный (≥153).
|
||
- [x] Build OK.
|
||
- [x] Backup tag существует.
|
||
- [ ] Production https://arhipovdan.ru/ отдаёт новый dist (**Open**).
|
||
|
||
### Should
|
||
|
||
- [ ] Визуальный parity ключевых элементов `/` и `/details`.
|
||
- [ ] Playwright smoke в CI (1 worker).
|
||
|
||
### Could
|
||
|
||
- [ ] Лёгкий physics layer.
|
||
- [ ] Agent auto-patch с обязательным human merge.
|
||
|
||
---
|
||
|
||
## 10. Рекомендуемый порядок дожима
|
||
|
||
1. Redeploy production (E12) — максимальный ROI для жюри.
|
||
2. Visual unify twin (E11) — доверие «одной системы».
|
||
3. e2e smoke (E13).
|
||
4. Остальное — по необходимости.
|