Learn_System/plans/pet-assistant/PLAN.md

Квантик-ассистент — дизайн-документ

Статус: дизайн (код не пишем). Движок подсказок: правиловый/эвристический (без LLM). Цель: превратить существующего питомца «Квантик» в сквозного ассистента, который помогает работать в системе, подсказывает и проактивно напоминает.

---

1. Цель и принципы

Маленький плавающий компаньон (тот же Квантик) присутствует на всех страницах и:

1. Подсказывает по контексту страницы — что тут можно, неочевидные фичи.
2. Проактивно напоминает — из реальных данных (домашка, карточки, урок, серия, квесты).
3. Радуется успехам — левелап, ачивка, серия, тест на 100%.
4. Ведёт новичка — короткий тур по разделам при первом входе.
5. Отвечает «как сделать X» — поиск по справке/FAQ (LLM — за рамками, точка расширения).

Принципы:

• Единая личность — имя/цвет/настроение из /api/pet, лицо — pet-sprite.js. Никакого второго персонажа.
• Не назойливый — один пузырь за раз, дневной лимит, кулдауны, «понял / не показывать», тихий режим, выключаемость.
• Детерминированный — правила и шаблоны на реальных данных, предсказуемо и офлайн.
• Без эмоджи в коде — только inline SVG .ic (правило проекта). Тексты подсказок — тоже без эмоджи.
• Лёгкий — не грузит страницы, ленивая инициализация, минимум сетевых запросов.

Не-цели (сейчас): свободный диалог/LLM; голос; геймификация поверх (ачивки за общение — позже, Ф4).

---

2. Что уже есть (фундамент)

• Питомец «Квантик»: 8 уровней по XP, настроение (_mood от серии/дней без входа), аксессуары (_accessories: hat/glasses/crown/star), монеты, поглаживание/кормёжка, дневные квесты (_quests), недельный XP, лента активности, прогноз настроения (_moodForecast), цвета, магазин фонов.
• GET /api/pet (petController.getPet) уже отдаёт: petName, petLevel, petColor, mood, daysSinceLogin, accessories, xp, level, streakCurrent, streakBest, coins, quests[], moodForecast, recentActivity[], weeklyXP[], xpForNextLevel. → почти весь контекст для подсказок берётся отсюда.
• pet-sprite.js — window.PetSprite.render(level, mood, accessories, colorKey, streak) → SVG. Переиспользуем как «лицо» ассистента (мини-версия в пузыре).
• Показ: страница /pet + виджет на /dashboard.
• Онбординга/туров/подсказок в системе нет — строим с нуля, конфликтов не будет.
• Точка инъекции: глобальные скрипты подключаются на каждой app-странице (api.js, sidebar.js, search.js, notifications.js, mobile.js). sidebar.js есть везде → он догружает assistant.js одной строкой, HTML страниц не трогаем.
• Питомец — фича за requireFeature('pet') (см. server.js).

---

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

sidebar.js (на каждой странице)
   └─ догружает /js/assistant.js (если фича включена и не отключено юзером)
        ├─ Assistant.boot()
        │    ├─ собирает ctx (page + данные)
        │    ├─ прогоняет реестр правил → выбирает 1 подсказку по приоритету/кулдауну
        │    └─ рисует компаньона + пузырь (лицо = PetSprite.render)
        ├─ assistant-rules.js — реестр правил (данные, не логика)
        └─ состояние/капы — localStorage (+ опц. сервер в Ф1+)

3.1. Компоненты (файлы — создаём в фазах, не сейчас)

• frontend/js/assistant.js — движок + UI (стили инжектит сам, как board-clip.js).
• frontend/js/assistant-rules.js — каталог правил (отдельно, чтобы правила правились без движка).
• js/sidebar.js — +строка ленивой загрузки ассистента.
• frontend/profile.html — настройки (вкл/выкл, частота, сброс подсказок).
• (Ф1) backend/src/routes/assistant.js + controllers/assistantController.js — GET /api/assistant/context.
• (Ф1, опц.) миграция: серверная отметка «видел подсказку» для кросс-девайс (иначе только localStorage).

3.2. Движок: контекст и правила

Контекст ctx (собирается при загрузке страницы):

{
  path, page,            // page — нормализованный id ('textbook','classroom','exam-prep',...)
  role,                  // student | teacher | admin
  isFirstVisit,          // нет ни одной отметки о показе
  pet,                   // кэш /api/pet (мин. TTL, чтобы не дёргать на каждой странице)
  data: {                // лениво/из /api/assistant/context (Ф1)
    homeworkDue: [{title, deadline, status}],
    dueCards: <int>,     // карточек к повторению
    activeLesson: {courseId, title, pct} | null,
    weakTopics: [...],
    quests: [...]        // из /api/pet
  },
  events: [...],         // свежие левелап/ачивка (детект по дельте)
  now
}

Форма правила:

{
  id: 'textbook-clip',
  scope: 'page' | 'proactive' | 'celebration',
  when: (ctx) => boolean,        // условие показа
  priority: 50,                  // больше = важнее (celebration > proactive > page)
  cooldownDays: 7,               // не чаще раза в N дней
  maxShows: 3,                   // пожизненный лимит показов
  suppressOn: ['exam-run','board-draw'], // не мешать в фокусных режимах
  text: (ctx) => 'Можно вырезать кусок страницы в «Мои материалы».',
  action: (ctx) => ({ label: 'Показать', url: null, run: fn }) | null,
  petMood: 'happy'               // настроение лица (опц.)
}

Алгоритм выбора: отфильтровать when && !suppressed && подходит по кулдауну/лимиту, отсортировать по scope-весу + priority, взять одно. Показ — по триггеру (см. 3.3).

3.3. Анти-назойливость (критично)

• 1 пузырь на экране за раз.
• Триггеры показа: page-подсказка — через 6–8 с на странице или по наведению на компаньона; proactive — раз в сессию на категорию; celebration — сразу по событию.
• Дневной лимит проактивных подсказок (по умолчанию 3).
• Кулдаун на правило + пожизненный maxShows.
• Кнопки в пузыре: «Понятно» (скрыть), «Не показывать» (навсегда для этого правила).
• Тихий режим и глобальный выключатель в профиле.
• Не мешать в фокусе: скрывать на странице запущенного теста, во время рисования на доске, на онлайн-уроке (suppressOn).
• prefers-reduced-motion — без анимаций/конфетти.

3.4. Хранение состояния

• localStorage: asst_off (вкл/выкл), asst_freq, asst_seen:{ruleId}={count,lastTs}, asst_mute_until, asst_pet_level/asst_ach_seen (для детекта событий).
• (Опц., Ф1) сервер: таблица assistant_seen(user_id, rule_id, count, last_at) для кросс-девайс — иначе подсказки повторятся на другом устройстве. Решить в Открытых вопросах.

---

4. Каталог правил (черновик)

4.1. Контекстные (scope: page) — «что тут можно»

id	страница	текст (суть)	действие
textbook-clip	/textbook	Вырежи кусок страницы картинкой в «Мои материалы»	подсветить кнопку «Вырезать область»
textbook-deeplink	/textbook	Можно делиться ссылкой прямо на параграф	—
board-tools	/classroom, /board	Лассо, фигуры, формулы KaTeX, линейка — попробуй панель	—
exam-modes	/exam-prep	Режимы: экзамен / тренировка / случайный	—
lab-sims	/lab	Симуляции запускаются прямо тут, без установки	—
flashcards-katex	/flashcards	Формулы вводятся через KaTeX-палитру	—
materials-folders	/my-materials	Раскладывай материалы по папкам и аннотируй фото	—
dashboard-widgets	/dashboard	Виджеты дашборда можно настроить под себя	—

4.2. Проактивные (scope: proactive) — из реальных данных

id	условие	текст	действие
hw-due-soon	есть домашка с дедлайном < 24ч и не сдана	Домашка «X» — дедлайн скоро	→ /homework
hw-overdue	есть просроченная несданная	Просрочена домашка «X»	→ /homework
cards-due	dueCards > 0	К повторению N карточек	→ /flashcards
lesson-continue	есть незаконченный урок	Продолжи «X» (N%)	→ /course?id=...
streak-risk	streakCurrent ≥ 1 и сегодня нет активности (вечер)	Серия N дней под угрозой — закрепи	→ /exam-prep
quest-nudge	есть незакрытый дневной квест	Добей квест: «X»	→ соответствующий раздел
weak-topic	низкий средний по теме	Подтяни тему «X»	→ тест/учебник по теме

4.3. Поздравления (scope: celebration) — по событию

id	триггер	реакция
levelup	pet.level вырос с прошлой проверки	Квантик ecstatic + «Уровень N!»
achievement	новая ачивка	поздравление + название
streak-milestone	серия достигла 3/7/14/30	поздравление + аксессуар-намёк
test-perfect	тест на 100% (из recentActivity)	поздравление

Эмоджи в существующих квестах (⭐📝🔥 в petController._quests) заменить на inline SVG .ic при интеграции — для соответствия правилу проекта.

---

5. Источники данных (всё уже в системе)

Нужно	Откуда
настроение/серия/квесты/прогноз/уровень	GET /api/pet
домашка + дедлайны	assignments (как на дашборде: asgn-row urgent/over)
карточки к повторению	flashcards SRS (LS.fc*)
незаконченный урок	/api/courses (doneCount/lessonCount) / lesson_progress
слабые темы	analytics по test_sessions
левелап/ачивки	дельта /api/pet (level, xp) + список ачивок

Рекомендация (Ф1): один эндпоинт GET /api/assistant/context собирает компактный бандл (homeworkDue, dueCards, activeLesson, weakTopics), чтобы не дёргать 4 API с клиента.

---

6. UI / UX

• Компаньон: мини-Квантик (≈48–56px) в правом-нижнем углу (на мобиле — выше mob-bar, не перекрывая). Лёгкое «дыхание»; при наличии подсказки — мягкий пульс/бейдж.
• Пузырь: speech-bubble над компаньоном: текст (1–2 строки) + опц. кнопка действия + «Понятно» + «Не показывать». Закрытие: кнопка, клик вне, Esc.
• Состояния: idle / has-hint / bubble-open / celebrating (конфетти + ecstatic) / hidden.
• Стиль: дизайн-система ls.css (переменные --violet/--text/--text-3), inline SVG .ic, тёмная тема, без эмоджи. Тон: дружелюбный, на «ты», кратко.
• A11y: aria-live="polite" на пузыре, фокус/Esc, уважение prefers-reduced-motion.
• Перетаскивание/сворачивание компаньона (запоминать позицию) — опц., Ф2.

---

7. Настройки и приватность

• Профиль: переключатель «Ассистент Квантик», частота (обычная/низкая), «Сбросить подсказки».
• Фича-флаг: reuse pet или новый assistant (решить — см. Открытые вопросы).
• Роли: ученики — основной сценарий; учителям — отдельный набор подсказок (Ф4); по умолчанию для admin, возможно, выключен.
• Никакой персональной телеметрии наружу; состояние — локально (+опц. своя таблица).

---

8. Фазы

• Ф0 — каркас: assistant.js + assistant-rules.js, плавающий Квантик (лицо из pet-sprite), пузырь, dismissal/кулдауны/лимиты, вкл/выкл, инъекция через sidebar.js, 5–6 правил §4.1.
• Ф1 — проактив: GET /api/assistant/context + правила §4.2 + поздравления §4.3 (детект событий).
• Ф2 — онбординг-тур новичка по разделам + все контекстные подсказки + «не показывать снова» + (опц.) перетаскивание/сворачивание.
• Ф3 — «Спроси Квантика»: окно с поиском по справке/FAQ (использует search.js). Точка расширения под LLM — за рамками этого плана.
• Ф4 — персонализация: частота/тон, режим для учителей, ачивки за взаимодействие, на страницах учебника (серверный inject) тоже.

---

9. Затрагиваемые файлы (при будущей реализации)

• • frontend/js/assistant.js, frontend/js/assistant-rules.js
• ~ js/sidebar.js (одна строка-загрузчик)
• ~ frontend/profile.html (настройки)
• (Ф1) + backend/src/routes/assistant.js, backend/src/controllers/assistantController.js, mount в server.js (+ возможный фича-флаг assistant)
• (Ф1, опц.) + миграция assistant_seen
• ~ petController._quests — заменить эмоджи на .ic при интеграции

---

10. Открытые вопросы (обсудить перед Ф0)

1. Фича-флаг: переиспользуем pet или заводим отдельный assistant? (ассистент шире питомца).
2. Кому по умолчанию вкл: всем ученикам? учителям? admin — выкл?
3. Кросс-девайс «видел»: localStorage достаточно, или нужна серверная таблица assistant_seen?
4. Учебник (серверный рендер): включать ассистента и там (через inject) сразу или в Ф4?
5. Тон/частота по умолчанию: насколько активно напоминать (консервативно vs заметно)?
6. «Спроси Квантика» (Ф3): только справка/FAQ, или сразу закладываем место под локальную модель?

---

11. Риски

• Назойливость — главный риск; смягчается лимитами/кулдаунами/тихим режимом (§3.3).
• Перекрытие UI (особенно мобайл, существующие FAB вроде «Вырезать область», flashcard-fab.js) — согласовать z-index и позиции, не накладываться.
• Лишние запросы — кэш /api/pet, один бандл-эндпоинт, ленивая инициализация.
• Рассинхрон личности — всегда брать имя/цвет/настроение из одного источника (/api/pet).