113 lines
6.5 KiB
Markdown
113 lines
6.5 KiB
Markdown
# Системный промпт для 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**
|