# 1. Цель проекта
Создать автономное (без внешних источников, кроме API Wildberries, оплаты через ЮKassa и опциональной нейросети GigaChat) расширение для Chrome и Яндекс.Браузера, которое:
* собирает и визуализирует статистику по рекламным кампаниям WB;
* показывает выдачу (органическую и рекламную) по запросам/товарам;
* отображает ключевые метрики и заказы из «Джема» (если функция включена);
* работает поверх интерфейса кабинета WB в виде настраиваемого overlay;
* имеет модуль автоминусации и автобиддера (ручной и нейро-режим);
* поддерживает оплату подписки через ЮKassa;
* устанавливается и настраивается «под ключ».
# 2. Целевая среда и совместимость
* Chromium-based: Google Chrome (актуальная LTS-ветка), Яндекс.Браузер (актуальная версия).
* Manifest V3 обязательный.
* ОС: Windows 10+, macOS 12+, Linux (актуальные дистрибутивы).
* Разрешения расширения: activeTab, scripting, storage, alarms, tabs, notifications, offscreen, declarativeNetRequest (минимально необходимые), доступ к доменам WB кабинета и API WB (список доменов будет уточнён).
* Локализация: ru-RU (возможность добавить en).
# 3. Архитектура
## 3.1. Клиент расширения
* Background Service Worker (MV3): планировщик задач, веб-запросы к WB API/бэкенду (если требуется), биллинг-статусы, обновления.
* Content scripts: внедрение overlay и сбор данных из DOM на страницах кабинета.
* Options page (панель настроек) и Popup (быстрые действия).
* UI-стек: TypeScript + React (или Preact) + Vite, TailwindCSS. Графики: Recharts или Apache ECharts.
* Локальное хранилище: chrome.storage.local + IndexedDB (кэш метрик и снимков выдачи).
* Межкомпонентная связь: chrome.runtime messaging.
## 3.2. Бэкенд (минимальный, при необходимости)
* Назначение: биллинг-вебхуки ЮKassa, управление лицензиями/подписками, прокси к GigaChat (если нельзя вызывать напрямую из расширения), выпуск ключей/токенов.
* Технологии: Node.js (NestJS/Express), PostgreSQL, Redis (кэш), Docker.
* Безопасность: HTTPS, JWT для сессий устройств, rate limiting, CORS (на домены WB запрещено, кроме контент-скриптов).
* Возможный режим «без сервера»: если ЮKassa и GigaChat допускают прямую работу из клиента — всё равно нужен end-point для вебхуков оплаты.
# 4. Доступы и безопасность
* Ключи WB API вводит пользователь вручную в настройках. Хранение локально, зашифровано (WebCrypto AES-GCM, ключ derivation через PBKDF2 на основе локального PIN пользователя).
* Токены GigaChat (если требуются) — через бэкенд-прокси или локально с теми же принципами.
* Доступ к API WB — строго по документированным эндпоинтам и лимитам; экспоненциальный backoff и очереди запросов.
* Логи только анонимные и агрегированные (опционально выключаемые пользователем). Данные рекламных кампаний не отправлять на внешний сервер без явного согласия.
* Соответствие GDPR (особенно для EU пользователей): политика конфиденциальности, механизм удаления данных, экспорт.
# 5. Основные функции
## 5.1. Overlay-аналитика (основной UI)
* Отображение поверх страниц кабинета WB (инъекция overlay-контейнера).
* Перетаскиваемые / фиксируемые панели, кнопка «свернуть/развернуть», запоминание макета.
* Виджеты:
* Сводка аккаунта: расходы, показы, клики, CTR, CPC, CPA, CR, конверсии, ROAS/ROMI, выручка.
* Таблицы по кампаниям/группам/ключам: сортировка, фильтры, поиск, пагинация.
* Графики за период: расходы, показы, клики, заказы, выручка, ROAS.
* «Заказы из Джема»: число и список заказов, атрибуция к кампаниям/ключам (при включенной функции и наличии данных).
* Рекламные позиции и органика по запросам (см. 5.2).
* Экспорт: CSV/XLSX/PNG (скрин-графиков).
* Быстрые действия: «минус-слова», «повысить/понизить ставки», «пауза/возобновить кампанию».
## 5.2. Мониторинг выдачи (органика и реклама)
* По выбранным ключам/артикулам — получение текущих рекламных позиций и органических мест в выдаче.
* Снимок выдачи с метаданными: запрос, дата/время, позиция, тип (organic/ads), страница, видимость.
* История изменений позиции во времени (мини-спарклайн в таблице).
* Расписание автосборов (например, каждые N часов) с ограничением частоты, чтобы не нарушать правила WB.
## 5.3. Метрики и отчёты
* Дашборд по периодам: «Сегодня», «Вчера», «7 дней», «30 дней», «Произвольный».
* Разрезы: кампании → группы → ключевые фразы → места размещения (если применимо).
* Атрибуция: модель по умолчанию «последний клик» (настраиваемо, если данные позволяют).
* Преднастроенные отчёты: «Эффективность кампаний», «Срез по ключам», «Срез по поисковым запросам», «Нецелевые запросы», «Отчёт по Джему».
* Сохранённые отчёты и быстрые пресеты пользователя.
Полное описание ТЗ в файле прикрепленном к заданию |
