feat: maximize sorter demo realism and add safe agent MVP
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>
This commit is contained in:
Даня Архипов
173
docs/IMPLEMENTATION_REPORT.md
Normal file
173
docs/IMPLEMENTATION_REPORT.md
Normal file
@@ -0,0 +1,173 @@
|
||||
# Отчёт о реализации — maximum-demo-realism
|
||||
|
||||
**Ветка:** `feature/maximum-demo-realism`
|
||||
**База:** `dan_branch` @ `e89c728`
|
||||
**Backup tag:** `backup/pre-maximum-demo-realism-20260715`
|
||||
**Дата:** 2026-07-15
|
||||
**Проект:** OZON Tech Sorter Simulation (Track 3)
|
||||
|
||||
---
|
||||
|
||||
## 1. Цель итерации
|
||||
|
||||
Максимально поднять убедительность живой демонстрации: live-классификация, safety-сценарии, proof UI, управление показом, адаптивное качество, ops-скрипты и безопасный MVP агента — без выдуманных секретов и без auto-deploy.
|
||||
|
||||
---
|
||||
|
||||
## 2. Все выполненные изменения (реальные)
|
||||
|
||||
| # | Изменение | Зачем |
|
||||
| - | --------- | ----- |
|
||||
| 1 | `classifyItem` встроен в continuous playback | Live classification, не только подписи playlist |
|
||||
| 2 | `measurementSystem` → `DIMENSION_LIMITS` + `classifyItem`; min dims; confidence 0.65 | Согласованность измерений и правил |
|
||||
| 3 | Playlist 8→10: jam + emergency_stop timelines | Safety story для жюри |
|
||||
| 4 | `physicalItemMotion`: fault freeze/recover + seeded jitter | Правдоподобие и воспроизводимость |
|
||||
| 5 | Demo controls: seek, speed 0.5–2×, hotkeys Space/N/B/R/P/E/F/1–0, presentation, event journal | Управление живым показом |
|
||||
| 6 | Quality modes low/medium/high/demo | FPS на разных клиентах |
|
||||
| 7 | Proof HUD: DIM pass/fail, K, reason; CV overlay RULE | Доказательство работы алгоритма |
|
||||
| 8 | `simulation.test.ts`: jam / estop / c_priority | Регрессия safety/логики |
|
||||
| 9 | Agent MVP `agent/cli.mjs`: dry-run\|run-once\|status\|stop\|resume\|pause\|report | Автономия уровня verify-only |
|
||||
| 10 | Scripts: demo-start/stop/reset/health, agent-dry-run, agent-run-once | One-command ops |
|
||||
| 11 | `resolveItem` для SKU-*-LC | Стабильность данных |
|
||||
|
||||
---
|
||||
|
||||
## 3. Изменённые / затронутые области файлов
|
||||
|
||||
> Точный `git diff` зависит от незакоммиченного состояния рабочей копии. Ниже — карта модулей по смыслу изменений (**проверено по коду репозитория**).
|
||||
|
||||
| Область | Файлы (ключевые) |
|
||||
| ------- | ---------------- |
|
||||
| Continuous / classify | `src/domain/continuousPlayback.ts`, `measurementSystem.ts`, `classifier.ts` |
|
||||
| Playlist / faults | `src/domain/demoPlaylist.ts`, `physicalItemMotion.ts`, `seededRng.ts` |
|
||||
| UI demo | `src/pages/MainPage.tsx`, Proof/CV components, styles |
|
||||
| Quality | `src/domain/qualityMode.ts`, `qualityMode.test.ts` |
|
||||
| Data | `src/data/resolveItem.ts` |
|
||||
| Tests | `src/domain/simulation.test.ts`, связанные domain tests |
|
||||
| Agent | `agent/cli.mjs`, `agent/state/*`, `agent/reports/*` |
|
||||
| Scripts | `scripts/demo-*.sh`, `scripts/agent-*.sh` |
|
||||
| Package scripts | `package.json` (`demo:*`, `agent:*`) |
|
||||
| Docs | этот набор `docs/*.md` аудита |
|
||||
|
||||
---
|
||||
|
||||
## 4. Причины изменений (кратко)
|
||||
|
||||
1. Жюри должно **видеть причинно-следственную связь** измерений → правила → маршрут.
|
||||
2. Без jam/e-stop демо выглядит «идеальной анимацией».
|
||||
3. Без hotkeys/presentation оператор теряет контроль на сцене.
|
||||
4. Без quality modes слабые ноутбуки дают рывки и подрывают доверие.
|
||||
5. Agent/scripts нужны для устойчивой эксплуатации и будущего цикла улучшений **с лимитами**.
|
||||
|
||||
---
|
||||
|
||||
## 5. Результаты тестов
|
||||
|
||||
| Проверка | До | После | Тип |
|
||||
| -------- | -: | ----: | --- |
|
||||
| Vitest passed | 144 | **153** | Измерено |
|
||||
| Test files | 14 | **16** | Измерено |
|
||||
| E2E CI | нет | нет | Измерено |
|
||||
| Lint (отдельный) | не выделен в package | не выделен | Измерено |
|
||||
| Typecheck | через `tsc -b` в build | OK вместе с build | Измерено |
|
||||
|
||||
---
|
||||
|
||||
## 6. Метрики до и после
|
||||
|
||||
| Метрика | До | После | Изменение |
|
||||
| ------- | -: | ----: | --------: |
|
||||
| Tests | 144 | 153 | +9 |
|
||||
| Test files | 14 | 16 | +2 |
|
||||
| Build | OK ~391 ms | OK | стабильно |
|
||||
| CSS | — | 39.66 kB / gzip 8.79 | зафиксировано |
|
||||
| Continuous twin chunk | — | 51.29 kB / gzip 13.68 | зафиксировано |
|
||||
| Playlist size | 8 | 10 | +faults |
|
||||
| Agent | нет | MVP CLI | +ops |
|
||||
| Live classify on `/` | слабо | wired | +proof |
|
||||
|
||||
Main R3F chunk baseline до итерации: ~881 kB (**Измерено** historically).
|
||||
|
||||
---
|
||||
|
||||
## 7. Оставшиеся ограничения
|
||||
|
||||
| Ограничение | Комментарий |
|
||||
| ----------- | ----------- |
|
||||
| Нет real physics engine | Детерминированная кинематика |
|
||||
| Pseudo-CV | Synthetic measurements |
|
||||
| Dual 3D twins diverge | `/` vs `/details` |
|
||||
| Нет e2e в CI | Playwright вручную |
|
||||
| Agent без auto-patch | By design MVP |
|
||||
| Production :3100 | Может служить старый dist до redeploy |
|
||||
| Нет docker CLI в этой среде | Redeploy — внешняя ops-процедура |
|
||||
| GPU idle | Не используется для demo render |
|
||||
|
||||
---
|
||||
|
||||
## 8. Инструкции запуска
|
||||
|
||||
### Демо (preview, не путать с prod :3100)
|
||||
|
||||
```bash
|
||||
cd /home/coder/arhipovdan/app
|
||||
npm run demo:start # build + vite preview 127.0.0.1:3101
|
||||
npm run demo:health # :3100 / :3101 / public + vitest
|
||||
npm run demo:stop # остановить preview
|
||||
# также: bash scripts/demo-reset.sh
|
||||
```
|
||||
|
||||
### Разработка
|
||||
|
||||
```bash
|
||||
npm install # при необходимости
|
||||
npm run dev # 127.0.0.1:3100 (vite dev — не prod nginx)
|
||||
npm test
|
||||
npm run build
|
||||
```
|
||||
|
||||
### Агент
|
||||
|
||||
```bash
|
||||
npm run agent:dry-run
|
||||
npm run agent:run-once
|
||||
npm run agent:status
|
||||
node agent/cli.mjs stop # перед живым показом
|
||||
node agent/cli.mjs resume
|
||||
node agent/cli.mjs report
|
||||
```
|
||||
|
||||
### Откат кода
|
||||
|
||||
```bash
|
||||
git fetch --tags
|
||||
git checkout backup/pre-maximum-demo-realism-20260715
|
||||
# или сброс ветки к e89c728 по необходимости (только осознанно)
|
||||
```
|
||||
|
||||
### Production
|
||||
|
||||
Публичный URL: https://arhipovdan.ru/ (nginx loopback :3100 + cloudflared).
|
||||
После merge/сборки нужен **ручной redeploy** образа/dist — агент этого не делает.
|
||||
|
||||
---
|
||||
|
||||
## 9. Hotkeys (оператору демо)
|
||||
|
||||
| Клавиша | Действие |
|
||||
| ------- | -------- |
|
||||
| Space | Play / pause |
|
||||
| N | Next case |
|
||||
| B | Back / previous |
|
||||
| R | Reset |
|
||||
| P / F | Presentation / fullscreen-related |
|
||||
| E | Event journal focus/toggle (UI) |
|
||||
| 1–0 | Seek/jump по кейсам playlist |
|
||||
|
||||
Speed: 0.5×–2× через demo controls UI.
|
||||
|
||||
---
|
||||
|
||||
## 10. Вывод
|
||||
|
||||
Итерация достигла измеримого улучшения демо-контура (тесты +9, playlist +faults, live classify, proof, controls, agent MVP). Критический остаточный ops-риск — **рассинхрон production dist**. Технический потолок реализма без смены архитектуры — кинематика + pseudo-CV; это задокументировано честно.
|
||||
Reference in New Issue
Block a user