Перейти до вмісту
SmartFeed Studio Docs

� Огляд Сторінок та Функціоналу Десктопного Клієнта

🗺 Карта Маршрутів Десктопного Додатку

graph TD
    Login["/auth/login\n(Вхід до системи)"] -->|Успіх| Home["/\n(Дашборд)"]
    Register["/auth/register\n(Реєстрація)"] -->|Успіх| Home
    Forgot["/auth/forgot-password\n(Запит скидання)"] --> Reset["/auth/reset-password\n(Новий пароль)"] --> Login


    subgraph Private["🛡 Захищені Маршрути (DashboardLayout)"]
        Home --> Catalogs["/catalogs\n(Каталоги товарів)"]
        Home --> AI["/ai-enrichment\n(AI Асистент)"]
        Home --> Cloud["/cloud-sync\n(Хмарний бекап)"]
        Home --> Plans["/plans\n(Тарифні плани)"]
        Home --> Team["/team\n(Команда та Компанія)"]
        Home --> Settings["/settings\n(Профіль і мова)"]
    end

📄 Детальний Огляд Екранів

1. Дашборд (/)

  • Привітання авторизованого користувача з відображенням ролі та активного тарифу.
  • Віджети швидкої статистики: підключені каталоги, статус останньої синхронізації, залишок AI-кредитів.
  • Кнопка швидкого переходу до тарифів.

2. Каталоги Товарів (/catalogs)

  • Перегляд списку завантажених фідів (Rozetka XML, Prom.ua YML, Google Merchant Center CSV).
  • Фільтрація за форматом (XML / CSV / YML) та швидкий пошук товарів.
  • Політика доступу: якщо термін тарифу завершився, сторінка замінюється компонентом <ExpiredPlanBlocker />, що запобігає маніпуляціям з товарами.

3. AI Асистент (/ai-enrichment)

  • Лічильник доступних AI-кредитів (aiCredits).
  • Інструменти автоматичної генерації SEO-описів, структурованих характеристик та перекладів карток товарів.
  • Політика доступу: блокується при isExpired === true.

4. Хмарна Синхронізація (/cloud-sync)

  • Моніторинг локальних та хмарних знімків у MinIO / S3.
  • Створення моментального знімку бази (Create Snapshot Now) за допомогою прямого завантаження через Presigned URL.
  • Політика доступу: блокується при isExpired === true.

5. Тарифні Плани та Порівняльна Матриця (/plans)

  • Сегментований перемикач режимів (Segmented View Switcher):
    • 🗂️ Картки тарифів (LayoutGrid): 4-колонковий адаптивний перегляд тарифів (STARTER, GROWTH, PRO, ENTERPRISE), 4 квоти (Товари, Постачальники, Канали, AI), чітке розділення на доступні можливості (✅) та недоступні в поточному тарифі (❌ сірі закреслені), ціни в грн та знижка -20% за рік.
    • 📊 Порівняльна матриця (TableProperties): інтерактивна таблиця 1-в-1 з адмінкою за 4 категоріями:
      1. 📥 Вхідні ліміти (Input Quotas) (ArrowDownToLine)
      2. 📤 Вихідні канали експорту (Output Channels) (Share2)
      3. ⚙️ Ресурси та автоматизація (Resources & Automation) (Cpu)
      4. 🛡️ B2B & Розширений функціонал (Enterprise & Advanced) (ShieldCheck)
  • Інтерактивні дії клієнта та Оформлення підписки (PaymentCheckoutModal):
    • Бейдж та disabled статус «Ваш поточний тариф» для активного плану.
    • Для безкоштовного STARTER: миттєвий перехід без виклику платіжного шлюзу.
    • Для платних тарифів (GROWTH, PRO, ENTERPRISE): відкриття модального вікна PaymentCheckoutModal:
      • Review: підсумок замовлення, період (щомісяця або щорічно зі знижкою 20%), сума у грн, ліміти SKU/AI/каналів, 256-bit SSL захист WayForPay.
      • Оплата: перехід до платіжної сторінки WayForPay (POST /api/payments/checkout).
      • Sandbox термінал: швидкі кнопки тестування для симуляції Approved (успіх) та Declined (відхилення банком).
      • Розблокування доступу (Approved): миттєве подовження ліцензії (30 або 365 днів), оновлення LicenseContext та NavigationContext, повне зняття блокувальника ExpiredPlanBlocker та доступ до Каталогів, AI та Хмари.
      • Захист блокування (Declined): сповіщення про причину відхилення банком, доступ до каталогів залишається заблокованим до успішної оплати.
  • Динамічна синхронізація з адмінкою: миттєве відображення оновлених цін, квот та списку переваг з бекенду (GET /api/plans) без дублювання запитів (Zero-Duplicate Requests).
  • Завжди залишається доступною для користувача навіть у заблокованому стані!

6. Команда та Компанія (/team)

  • Дані компанії: назва організації, власник, бейдж тарифного плану та лічильник днів до завершення дії.
  • Редагування назви: власник може оновити назву організації через модальне вікно EditCompanyNameDialog.
  • Командні місця (maxTeamSeats):
    • STARTER / GROWTH: 1/1 місць (Solo-режим) з інформаційним блоком про переваги командної роботи.
    • PRO: до 3 місць (Власник + 2 колеги) з візуальним прогрес-баром використання.
    • ENTERPRISE: безліміт місць (used / ∞).
  • Інтелектуальна кнопка «Запросити колегу» (Always Clickable):
    • При наявності вільних місць: відкриває форму інвайту InviteMemberDialog (вибір ролі: MEMBER або ADMIN).
    • При вичерпаному ліміті або соло-тарифі: відкриває модальне вікно пропозиції апгрейду UpgradeTeamSeatsDialog з прямим переходом до /plans.
  • Список учасників: картки співробітників, ролі, дата входу та кнопка вилучення (RemoveMemberDialog), що вивільняє місце в тарифі.

7. Налаштування (/settings)

  • Зміна мови інтерфейсу (Українська / English).
  • Вибір колірної теми (Zinc, Slate, Stone, Bronze) та перемикач темного/світлого режиму.
  • Зміна паролю користувача.

8. Єдина Реактивна Система Синхронізації Лічильників (DataSync)

  • Централізована шина подій (@/lib/syncEvents.ts):
    • SyncDomain: 'all' | 'suppliers' | 'feeds' | 'products' | 'categories' | 'quotas' | 'licenses'.
    • Функції emitDataSync(domain, detail) та реактивний хук useDataSync(domains, callback).
  • Автоматична узгодженість лічильників:
    • При будь-якій мутації (видалення фіду, імпорт товарів, видалення категорій, оновлення постачальника, завершення черги BullMQ) всі залежні компоненти (квоти в шапці QuotaMetricCard, лічильники карток activeFeedsCount / productsCount, списки джерел) оновлюються миттєво та тихо в реальному часі без перезавантаження сторінки (0 ms desync).
  • Захист від дублювання запитів (Zero-Duplicate Requests):
    • Усі фонові оновлення захищено через isFetchingRef та lastFetchedTokenRef, що гарантує відсутність подвійних або каскадних запитів до API.

9. Розширений Майстер Імпорту Фідів та Проактивне Блокування Переліміту SKU

  • Просторий інтерфейс 95vw:
    • Діалогове вікно ImportFeedWizardDialog адаптовано під розмір w-[95vw] max-w-6xl h-[92vh] для зручного вибору сотень категорій та широкої таблиці попереднього перегляду товарів.
  • Проактивний контроль залишку квоти товарів:
    • У реальному часі підраховується сума SKU у вибраних категоріях (totalSelectedSkus).
    • Якщо totalSelectedSkus > remainingQuota:
      • Відображається контрастний банер з попередженням про перевищення ліміту та точним залишком SKU.
      • Кнопка «Розпочати імпорт» блокується (disabled={true}) з підказкою (title).
    • Користувач знімає галочки з зайвих категорій -> як тільки кількість стає <= remainingQuota, кнопка автоматично активується для безпечного запуску.

10. Локальна Зашифрована База Даних (SQLCipher), Онбординг та Управління Сховищем

  • Безпечне локальне зберігання каталогів (0 ms затримка, 100% приватність):
    • Усі товари, собівартість та націнки зберігаються безпосередньо на комп’ютері користувача у зашифрованій базі даних SQLite + SQLCipher AES-256 (database/catalog.db).
    • Ключ шифрування генерується локально та захищено зберігається в системному сховищі паролів OS Keychain (через Rust keyring).
  • Майстер вибору робочої папки (First-Run Workspace Setup / Onboarding):
    • Після реєстрації/першого входу з’являється повнорозмірне модальне вікно FirstRunWorkspaceSetupDialog (з порталом у document.body та м’яким затемненням bg-black/40 backdrop-blur-sm).
    • Пропонується системна рекомендована папка (~/Documents/SmartFeedStudioData) або можливість вказати власну папку на диску.
    • Автоматичне розгортання структури: database/, feeds/, exports/, backups/, logs/.
  • Вкладка «База даних та сховище» у Налаштуваннях (/settings):
    • Активна робоча область: поточний шлях, статус шифрування SQLCipher AES-256, кнопка «Відкрити в провіднику» та кнопка «Змінити папку» (MigrateWorkspaceDialog).
    • Використання дискового простору: картки загального об’єму, розміру БД, фідів, експортів та бекапів.
    • Локальні лічильники: кількість збережених товарів, постачальників та підключених фідів.
    • Операції: створення бекапу (create_local_backup), дефрагментація та оптимізація (run_database_maintenance / VACUUM), очищення тимчасового кешу фідів (clear_storage_cache).

11. Єдиний Принцип Побудови Сторінок та Інтерактивний AI-Асистент у Шапці

  • Компактні шапки без громіздких банерів: усі масивні статичні інформаційні банери (як у медіасховищі) вилучено для максимального вивільнення вертикального простору під робочі каталоги й таблиці.
  • Іконка розділу + заголовок + кнопка [i]: у хлібних крихтах шапки виводиться іконка маршруту (<Cloud />, <Layers />, <Truck /> тощо), назва сторінки та інтерактивна кнопка [i].
  • Контекстна модалка від 3D AI-асистента (PageHeaderGuide): при кліку відкривається діалогове вікно з 3D аватаром AI Copilot, роллю, описом розділу, чеклистом ключових можливостей та порадою від ШІ.
  • Єдине джерело істини для фото асистента (useAiAssistantProfile): аватар і метадані асистента централізовано контролюються бекендом (GET/PUT /api/page-guides/assistant/profile) та автоматично синхронізуються скрізь у додатку (у шапці, віджетах AiCopilotCard та гайдах) з надійним локальним офлайн-фолбеком.