papayu/docs/ОЦЕНКА_И_СЦЕНАРИЙ_РАССКАЗА.md

PAPA YU: оценка обновлений и сценарий рассказа о программе

---

Часть 1. Нуждается ли программа в обновлении или улучшении?

Текущее состояние (после внедрённых улучшений)

Уже сделано:

• Архитектура: типы вынесены в src/lib/types.ts, единый API-слой в src/lib/tauri.ts; страница Tasks разбита на компоненты PathSelector, AgenticResult и хук useUndoRedo.
• Безопасность (v2.4.4): лимиты профиля (max_actions_per_tx, timeout_sec) применяются в apply_actions_tx и run_batch; в verify_project добавлен таймаут на выполнение проверок (cargo check, npm run build и т.д.).
• Иконка: используется RGBA-иконка из папки «папа-ю», сборка Tauri проходит успешно.

Программа работоспособна и готова к использованию. При этом остаются направления для развития.

Что имеет смысл улучшить (по приоритету)

Область	Рекомендация	Зачем
UX	История сессий в UI, отображение профиля и лимитов в форме, фильтр расширений при «Прикрепить файл», горячие клавиши (Ctrl+Enter, Escape)	Удобство и прозрачность для пользователя
Тестирование	Юнит-тесты для detect_project_type, is_protected_file, build_plan; E2E-сценарии (анализ → применение → undo)	Надёжность и уверенность при изменениях
Документация	Обновить README до актуальной версии (2.4.x), вести CHANGELOG	Проще онбординг и откат версий
Дальнейшие фичи	LLM-планировщик вместо чисто эвристического плана; контекст прикреплённых файлов при анализе; allowlist команд verify в конфиге	Расширение возможностей и гибкость

Вывод: программа не «сломана» и не требует срочного обновления для базового сценария. Улучшения из списка выше повысят удобство, предсказуемость и расширяемость — их можно планировать поэтапно.

---

Часть 2. Сценарий рассказа о программе (по модулям, технологиям, защите и уникальности)

Ниже — готовый сценарий для устного или письменного рассказа о PAPA YU: модули, достоинства, технологии, защищённость, возможности и уникальность.

---

Введение

PAPA YU — это десктопное приложение для анализа кодовой базы и безопасного автоматического улучшения проектов: добавление README, .gitignore, тестов, приведение структуры к принятым практикам. Всё это делается с полным контролем пользователя: предпросмотр изменений, подтверждение применения и возможность отката одной кнопкой.

Рассказ удобно строить по слоям: интерфейс, единый слой работы с бэкендом, бэкенд по модулям, безопасность и уникальность.

---

Модуль 1. Интерфейс (React + Vite)

Что это: одностраничное приложение на React 18 и Vite 5. Одна основная страница — «Задачи» (Tasks): выбор папок и файлов, поле ввода пути, лента сообщений (чат с системой и ассистентом), блоки с отчётом, превью изменений и результатами автоматического прогона.

Модульная структура фронта:

• PathSelector — блок выбора папок и прикреплённых файлов, кнопки «Выбрать папку» и «Прикрепить файл», список выбранных путей.
• AgenticResult — блок результата «исправить автоматически»: таблица попыток, статусы проверок, кнопки «Скачать отчёт», «Скачать diff», «Откатить».
• useUndoRedo — хук для состояния отката/повтора и вызова команд undo/redo через единый API-слой.
• Единая точка типов и API: все типы (Action, AnalyzeReport, AgenticRunResult и др.) лежат в src/lib/types.ts; все вызовы бэкенда идут через src/lib/tauri.ts, без прямых invoke в компонентах.

Достоинства: понятная структура, переиспользуемые компоненты и типы, один слой общения с Tauri — проще поддерживать и тестировать.

Технологии: React 18, Vite 5, TypeScript, React Router, Tauri 2 (плагины: dialog, shell). Алиас @/ для импортов, строгий TypeScript.

---

Модуль 2. Единый слой API (src/lib/tauri.ts)

Что это: все обращения к бэкенду проходят через функции в tauri.ts: getProjectProfile, runBatchCmd, applyActionsTx, agenticRun, generateActionsFromReport, proposeActions, undoLastTx, undoLast, redoLast, работа с папками и сессиями и т.д.

Достоинства: один контракт между UI и Rust; проще менять форматы запросов/ответов, добавлять логирование и обработку ошибок без правок во всех компонентах.

Технологии: @tauri-apps/api/core (invoke), типы из @/lib/types.

---

Модуль 3. Бэкенд: команды и оркестрация (Tauri 2, Rust)

Структура по модулям:

• analyze_project — сканирование выбранных путей, эвристики (README, .gitignore, tests, структура), формирование отчёта с findings, recommendations, actions, action_groups, fix_packs.
• get_project_profile — определение типа проекта (React/Vite, Next.js, Node, Rust, Python, unknown) по файлам в корне; возврат профиля с лимитами (max_actions_per_tx, timeout_sec, max_files), шаблоном цели и флагом safe_mode.
• run_batch — единый сценарий: анализ → превью (если есть действия) → при необходимости применение с проверками. Перед применением проверяется лимит max_actions_per_tx из профиля; при превышении возвращается ошибка.
• apply_actions_tx — транзакционное применение: снимок состояния до изменений, применение действий, при включённом auto_check — запуск проверок (cargo check / npm run build и т.д.) с таймаутом из профиля; при падении проверки — автоматический откат. Проверка числа действий против max_actions_per_tx.
• preview_actions — расчёт diff без записи на диск.
• undo_last_tx / undo_last / redo_last, get_undo_redo_state_cmd, undo_status — откат и повтор последней транзакции, состояние undo/redo для UI.
• generate_actions_from_report — генерация списка безопасных действий по отчёту (например, только создание файлов/папок) без LLM.
• propose_actions — план исправлений по отчёту и цели пользователя (эвристический планировщик).
• agentic_run — цикл: анализ → план → превью → применение → проверка (verify); при неудаче проверки — откат и повтор в пределах max_attempts.
• verify — проверка проекта после изменений (cargo check, npm run build/test и т.д.) по allowlist команд, с таймаутом на каждый запуск.
• projects / store — проекты и сессии (list_projects, add_project, append_session_event, list_sessions), хранение в userData.

Достоинства: чёткое разделение по командам, переиспользование типов и лимитов профиля, единый контур «превью → применение → проверка → откат при ошибке».

Технологии: Rust, Tauri 2, serde, uuid, стандартная библиотека (fs, path, process, thread, time), allowlist команд и таймауты для внешних процессов.

---

Модуль 4. Транзакции и откат (tx/)

Что это: снимки состояния файлов до применения, запись манифестов транзакций, откат к снимку при падении проверок или по запросу пользователя, стек undo/redo.

Достоинства: пользователь и система всегда могут откатить последнее применение; данные на диске остаются консистентными после отката.

Технологии: копирование/восстановление файлов и директорий, манифесты в JSON, привязка к AppHandle и путям проекта.

---

Защищённость и ограничения рисков

• Защита путей: запрет изменения системных и служебных путей (например, .git, node_modules, target, dist); проверка, что изменяются только допустимые текстовые файлы (is_protected_file, is_text_allowed).
• Подтверждение пользователя: применение изменений только при явном user_confirmed; в UI — кнопки «Применить» и при необходимости диалог подтверждения.
• Лимиты из профиля: ограничение числа действий в одной транзакции (max_actions_per_tx) и таймауты на проверки (timeout_sec) снижают риск «зависания» и перегрузки.
• Allowlist команд в verify: запускаются только заранее разрешённые команды (cargo check, npm run build и т.д.) с фиксированными аргументами, без произвольного shell.
• Таймауты: проверки (verify, auto_check) выполняются с ограничением по времени; при превышении процесс завершается, пользователь получает сообщение (например, TIMEOUT), откат при необходимости уже выполнен.

В совокупности это даёт контролируемую среду: автоматизация без неограниченного доступа к системе и без «тихого» изменения критичных путей.

---

Возможности для пользователя

• Выбор одной или нескольких папок и прикрепление файлов; ввод пути вручную.
• Один запуск анализа с получением отчёта: проблемы, рекомендации, группы действий и пакеты исправлений.
• Предпросмотр изменений (diff) до применения.
• Применение выбранных или рекомендованных исправлений с автоматической проверкой (сборка/тесты); при падении проверки — автоматический откат.
• Режим «исправить автоматически» (agentic run): несколько попыток с откатом при неудачной проверке.
• Режим «безопасные исправления в один клик»: генерация безопасных действий по отчёту → превью → применение с проверкой.
• Откат последнего применения и повтор (undo/redo).
• Скачивание отчёта и diff для аудита и отладки.
• Определение типа проекта и отображение профиля (в т.ч. лимитов) для прозрачности.

---

Уникальность

• Транзакционность и откат на уровне файловой системы: не «патч и надежда», а снимок → применение → проверка → при ошибке откат к снимку и явное сообщение пользователю.
• Профиль проекта и лимиты: тип и лимиты (число действий, таймауты) задаются по структуре проекта и соблюдаются в apply и run_batch, что снижает риски и предсказуемо ограничивает автоматизацию.
• Единый сценарий от анализа до отката: анализ → план → превью → применение → проверка с таймаутом → откат при неудаче — реализован и в batch, и в agentic run, с одной и той же моделью безопасности.
• Десктоп на Tauri 2: нативный бэкенд на Rust, быстрый и контролируемый доступ к файлам и процессам, без веб-сервера и без открытия кода в браузере.
• Гибрид эвристик и подготовки к LLM: уже есть структура (propose_actions, agentic_run, отчёт с narrative и actions); планировщик можно заменить на LLM без смены контура выполнения.

---

Заключение сценария

PAPA YU — это не просто «генератор README», а инструмент с чёткой архитектурой, контролем рисков и расширяемостью. Модули фронта и бэкенда разделены, типы и API централизованы, применение изменений транзакционно с откатом и проверками по таймауту и лимитам. Защита путей, подтверждение пользователя и allowlist команд делают автоматизацию предсказуемой и безопасной. Уникальность — в сочетании транзакционности, профилей проекта и единого сценария «анализ → превью → применение → проверка → откат при ошибке» в одном десктопном приложении.

При необходимости следующий шаг — улучшения UX (история сессий, горячие клавиши, фильтр файлов), тесты и обновление README/CHANGELOG, а затем — опционально LLM-планировщик и контекст прикреплённых файлов.