Avtex/AI_SESSION_PROMPT.md

Системный промпт для AI-ассистента проекта XFlow

Текущая архитектура

Проект реализован на Nuxt 3 PWA.

Стек

• Frontend/Backend: Nuxt 3 (Vue 3 + Nitro SSR)
• Стили: Tailwind CSS
• PWA: @vite-pwa/nuxt (Service Worker, манифест, оффлайн-кэш)
• Аутентификация: Firebase Auth (Google Sign-In), JWT на Nitro
• Визуализация: @vue-flow/core + @vue-flow/background + @vue-flow/controls + @vue-flow/minimap
• Markdown: markdown-it (рендеринг нод)
• Push: Web Push API + Notification API + вибро
• База данных: In-memory (заглушка на Nitro utils/db.ts), миграция на Postgres в планах

Файловая структура

app/
  app.vue              # Корневой компонент
  assets/css/main.css  # Tailwind + кастомные стили для Vue Flow
  components/
    CanvasViewer.vue   # Основной канвас (Vue Flow)
    MarkdownNode.vue   # Рендеринг markdown в нодах
    AchievementOverlay.vue # Всплывающие ачивки
  composables/
    useAuth.ts         # Firebase Google Sign-In + JWT decode
    useCanvas.ts       # Загрузка .canvas JSON, парсинг frontmatter
    usePush.ts         # Подписка/отправка Web Push
    useAchievements.ts # Управление ачивками
  layouts/
    default.vue        # Навигация + AchievementOverlay
  middleware/
    auth.ts            # Проверка JWT (cookie xflow_token)
    admin.ts           # Проверка role === 'admin'
  pages/
    index.vue          # Дашборд (статы задач и ачивок)
    login.vue          # Только Google Sign-In (Firebase)
    canvas.vue         # CanvasViewer страница
    admin.vue          # Панель админа (пуши, скрипты)
    settings.vue       # Настройки пушей и ачивок
  plugins/
    firebase.client.ts # Инициализация Firebase SDK (только клиент)
    push-notifications.client.ts # Обработка пуш-событий
  server/
    api/auth/google.post.ts # Верификация Firebase ID token + выдача JWT
    api/auth/validate.get.ts # Проверка JWT
    api/canvas/[id].get.ts # Мок .canvas JSON
    api/nodes/[id].put.ts # Обновление статуса ноды + автовыдача ачивок
    api/nodes/index.get.ts # Список нод с RBAC (фильтр по assigned_to)
    api/achievements/index.get.ts # Список ачивок пользователя
    api/push/subscribe.post.ts # Сохранение подписки
    api/push/send.post.ts # Отправка пуша (admin only)
    utils/auth.ts      # Генерация/верификация JWT (jose)
    utils/db.ts        # In-memory store (users, nodes, achievements, pushSubs)
public/
  favicon.svg
  pwa-*.svg            # Иконки PWA (SVG заглушки)

Ключевые бизнес-правила

1. Авторизация: Только Firebase Google Sign-In. Email/password удален. Cookie xflow_token.
2. RBAC: role: 'admin' дает доступ к /admin. Обычные пользователи видят только ноды с assigned_to == свой email.
3. Canvas ноды: Double-click переключает статус pending -> in_progress -> completed. При completed сервер автоматически выдает ачивку.
4. Frontmatter: Ноды могут содержать YAML frontmatter с полями alarm, script_id, assigned_to.
5. Push: Админ отправляет пуши через /api/push/send. Клиентский плагин слушает PUSH_RECEIVED и вибрирует.
6. Gamification: Ачивки выдаются автоматически при завершении нод. Отображаются через AchievementOverlay.

Конфигурация (.env)

Обязательные переменные для Firebase:

NUXT_PUBLIC_FIREBASE_API_KEY=
NUXT_PUBLIC_FIREBASE_AUTH_DOMAIN=
NUXT_PUBLIC_FIREBASE_PROJECT_ID=
NUXT_PUBLIC_FIREBASE_APP_ID=
NUXT_PUBLIC_FIREBASE_MESSAGING_SENDER_ID=
NUXT_FIREBASE_API_KEY=      # Серверная верификация (тот же ключ)
NUXT_JWT_SECRET=            # Секрет для подписи JWT

Критически важное правило: документация в .md

При ЛЮБЫХ изменениях архитектуры, API, бизнес-логики или структуры данных — обновляй соответствующие .md файлы.

Структура документации в проекте

• docs/architecture/ — архитектурные решения, ADR
• docs/api/ — контракты API, форматы данных
• docs/features/ — описание функционала
• README.md — общее описание, setup, структура

Правила обновления .md

1. Если добавляешь новый composable/component/API route — создай или обнови .md:

   • Назначение
   • Зависимости
   • Публичный API (методы, параметры, типы)
   • Пример использования

2. Если меняешь формат данных (.canvas JSON, frontmatter схема):

   • Обнови документацию формата
   • Укажи версию схемы
   • Опиши миграцию если нужна

3. Если добавляешь фичу:

   • Создай docs/features/feature-name.md
   • Опиши user flow, edge cases

Инструкция для сессии

1. Перед изменениями — прочитай соответствующий .md файл и код
2. После изменений — обнови .md или создай новый
3. Не ломай существующие форматы данных без явного запроса
4. При добавлении зависимостей — проверяй совместимость с Nuxt 3 / Vue 3 / TypeScript
5. Все Dart/Flutter файлы удалены — не возвращай их
6. Cookie называется xflow_token
7. Проект называется XFlow