Архитектура WebExtension: Manifest V3 и несколько браузеров

ShopTools AI получает предложения для магазина и проверяет доступные промокоды на поддерживаемой странице корзины. Эти задачи требуют разных контекстов: сетевые данные, интерфейс расширения и DOM продавца не стоит объединять в один процесс.

Ниже приведена референсная архитектура на основе исходных разборов проекта. Это не описание всех модулей текущего релиза и не подтверждение совместимости одной сборки со всеми браузерами. Платформенные возможности проверяйте отдельно.

Разделите четыре ответственности

• Manifest задаёт права, точки входа и допустимые ресурсы. Описывайте доступ content script к страницам отдельно от разрешения обращаться к своему API.
• Фоновый слой получает каталог, координирует запросы и хранит настройки. Не переносите в него управление DOM магазина.
• Content script находит допустимые элементы, наблюдает сумму и выполняет команду пользователя. Ссылки на DOM-узлы остаются в контексте страницы.
• Popup выбирает магазин и отображает состояние. Закрытие окна не должно уничтожать единственную запись о незавершённой операции.

Состояние должно пережить остановку контекста

Для MV3 проектируйте фоновые обработчики так, чтобы они могли продолжить работу после остановки worker. Переменные процесса используйте как ускорение, а нужные после перезапуска данные сохраняйте с версией схемы и сроком актуальности.

У кэша разделите свежесть ответа и допустимость устаревшего резерва. Объединяйте одинаковые запросы через single flight. Быстрое чтение старой копии не делает истёкший купон актуальным: данные всё равно проходят предметные фильтры.

Сопоставляйте магазин по целевому домену, а не адресу трекера. Для сохранённых операций проверяйте контекст вкладки и магазина. При недостаточных данных завершайте запрос объяснимым отказом, а не оставляйте бесконечное ожидание.

Общее ядро не равно одному архиву

В общем ядре можно держать правила сопоставления, сравнение сумм и схему сообщений. Различия browser API изолируйте в тонких адаптерах. Обёртка должна завершать операцию один раз независимо от callback или Promise-интерфейса.

Проверяйте наличие возможности, а не только название браузера. Ошибку API не маскируйте пустым успешным ответом. Фоновый жизненный цикл, разрешения и упаковку нужно тестировать для каждой целевой платформы.

Для Safari отдельно учитывайте приложение-контейнер и расширение. Установка контейнера, включение расширения и доступ к сайту являются разными этапами. Это не подтверждение, что соответствующие пакеты уже опубликованы.

Собирайте проверяемую матрицу релиза

1. Зафиксируйте исходную ревизию, версию общего кода, платформенный manifest и идентификаторы. Для приложения отдельно учитывайте номер сборки.
2. Проверьте обновление с предыдущего пакета: настройки должны мигрировать по явному правилу, а неизвестный формат данных завершаться безопасно.
3. Для каждой платформы воспроизведите открытие popup, чтение магазина, сетевой отказ, восстановление после reload и отказ в доступе к странице.
4. Проверьте длинные локализованные подписи и сценарий без необязательной телеметрии. Результат теста одной платформы не переносите на другую.

Серверные данные не должны становиться кодом

В референсном проекте держите исполняемую логику внутри пакета. Удалённую конфигурацию ограничивайте проверяемыми данными с локальными пределами. Не исполняйте строки через eval и не загружайте скрипт ради исправления магазина.

Упакованный архив, успешный локальный тест и доступное пользователю обновление являются разными результатами. Перед выпуском отдельно сверяйте требования площадки, подпись и фактический статус публикации, не полагаясь на старые инструкции.