outlier-saver-extension/docs/superpowers/specs/2026-10-25-outlier-saver-design.md

Outlier Saver — дизайн расширения

Дата: 2026-10-25

Цель

Расширение для Chrome (Manifest V3), которое работает, пока пользователь просто смотрит YouTube: само находит видео с аномально высокими просмотрами относительно размера канала («outliers») и сохраняет их локально. Позже данные выгружаются в JSON или CSV.

Принятые решения

Вопрос	Решение
Источник outlier score	Гибрид: свой расчёт + значок VidIQ, если он есть на карточке
Хранение	IndexedDB в браузере, экспорт в JSON и CSV из popup (SQLite не используем)
Формула	score = просмотры ÷ подписчики
Страницы	Главная (лента), страница просмотра, поиск, страница канала
Источник цифр	YouTube Data API v3 (нужен ключ пользователя)
Сборка	Нет. Чистый JS, ES-модули, загрузка как «распакованное расширение»

Архитектура

Часть	Файл	Ответственность
Content script	src/content.js	Следит за DOM на youtube.com, достаёт ID видео из ссылок, читает значок VidIQ, шлёт пачки в background
Service worker	src/background.js	Очередь ID, цикл сброса пачками, статус и бейдж на иконке, реакция на смену ключа
Обработка пачки	src/lib/process.js	processBatch: проверка seen, запросы к API, расчёт score, решение «сохранять или нет», запись в БД. Зависимости (БД и API) передаются параметрами, поэтому логика покрыта тестами
Настройки и статус	src/lib/storage.js	Значения по умолчанию, normalizeSettings, чтение и запись настроек и статуса в chrome.storage.local
Формула и решение	src/lib/score.js	Чистые функции: computeScore, shouldSave
Разбор ссылок	src/lib/video-id.js	Извлечение ID из /watch?v=, /shorts/, отсев мусора, определение типа страницы по пути
Значок VidIQ	src/lib/vidiq.js	Селектор значка (одна константа) и parseVidiqScore(text)
API	src/lib/api.js	videos.list, channels.list, разбиение на пачки по 50, разбор ошибок
База	src/lib/db.js	Обёртка над IndexedDB
Экспорт	src/lib/export.js	Сериализация в JSON и CSV
Popup	src/popup/	Счётчик, список последних находок, кнопки экспорта, статус сбора
Options	src/options/	API-ключ, порог score, минимум просмотров

Ключ API хранится в chrome.storage.local и читается только в background и на странице настроек. Content script его не использует. Запросы к API идут из background, а не со страницы, поэтому CORS не мешает.

Поток данных

1. Content script на youtube.com реагирует на событие yt-navigate-finish (YouTube — SPA, страницы не перезагружаются) и на MutationObserver по документу. Сканирование запускается не чаще раза в 500 мс (троттлинг, а не дебаунс: пока играет видео, DOM меняется постоянно, и дебаунс не сработал бы). После навигации список уже отправленных ID сбрасывается.
2. Из ссылок a[href*="/watch?v="] и a[href*="/shorts/"] через video-id.js берутся ID. Для каждой карточки пробуется прочитать значок VidIQ. Уже отправленные с этой страницы ID запоминаются в Set, чтобы не спамить сообщениями.
3. Content script шлёт background сообщение {videoId, vidiqScore | null, viaShortsUrl, page}, где page — home | watch | search | channel.
4. Background копит ID и сбрасывает очередь раз в секунду либо при накоплении 50 штук. ID, проверенные менее 24 часов назад (seen.checkedAt), пропускаются, кроме ID со значком VidIQ: значок может отрисоваться позже первого сканирования, поэтому content script отправляет ID повторно, когда у него появился score, а проверка seen для таких ID не применяется.
5. videos.list (part=snippet,statistics,contentDetails) возвращает название, превью, просмотры, дату публикации, длительность и channelId.
6. Для каналов, которых нет в кэше channels или чья запись старше 24 часов, вызывается channels.list (part=statistics,snippet).
7. score = views / max(subscribers, 1). Если подписчики скрыты, score = null.
8. Решение о сохранении (shouldSave): видео сохраняется, если views ≥ minViews и score ≥ threshold, или если vidiqScore не null. Условие по VidIQ действует независимо от своего порога и от minViews. Уже сохранённое видео обновляется при каждой проверке, даже если его score опустился ниже порога.
9. Результат пишется upsert-ом в outliers, ID с временем проверки — в seen (в том числе несохранённые, чтобы не запрашивать их повторно).

Модель данных

Хранилище outliers (ключ — videoId)

Поле	Описание
videoId	ID видео
title	Название
url	https://www.youtube.com/watch?v=<videoId> для всех видео, включая Shorts
thumbnailUrl	Лучшее доступное превью в порядке maxres → standard → high → medium → default
channelId, channelTitle, channelUrl	Канал
subscribers	Число подписчиков или null, если скрыто. API округляет до трёх значащих цифр
views	Просмотры на момент последней проверки
publishedAt	ISO-дата публикации
durationSec	Длительность
isShort	true, если хотя бы раз видео встретилось по ссылке /shorts/
score	Свой score, округлённый до двух знаков, или null
vidiqScore	Число со значка VidIQ или null
foundOn	Страница первой находки
firstSeenAt, updatedAt	Временные метки (ISO). firstSeenAt не меняется при upsert

Хранилище channels (ключ — channelId)

channelId, title, subscribers (число или null), fetchedAt.

Хранилище seen (ключ — videoId)

videoId, checkedAt, status (ok или unavailable). После 24 часов запись считается устаревшей и видео запрашивается заново. Это нужно, чтобы видео, которое стало outlier позже, не потерялось, а просмотры у сохранённых обновлялись.

Настройки (chrome.storage.local)

Ключ	По умолчанию
apiKey	пусто
threshold	5
minViews	10 000

Ошибки и граничные случаи

Ситуация	Поведение
Ключ API не задан	Сбор приостановлен, на иконке бейдж «!», popup ведёт в настройки. В seen ничего не пишется, после ввода ключа видео подхватятся
Квота исчерпана (403 quotaExceeded)	Пауза до сброса квоты (полночь по Тихоокеанскому времени), popup показывает причину. Необработанные ID в seen не попадают
Невалидный ключ (400 или 403 keyInvalid)	Как при отсутствии ключа, с сообщением об ошибке ключа
Сеть или 5xx	Три повтора с нарастающей задержкой, затем ID пропускается без записи в seen
Скрытые подписчики	score = null, видео сохраняется только при наличии vidiqScore
Очень мало подписчиков	Делитель max(subs, 1), мусор отсекается через minViews
Приватное или удалённое видео	API его не возвращает; в seen пишется status: unavailable, повторная проверка после TTL
Service worker выгрузили	Очередь живёт в памяти и может потеряться. seen пишется только после результата, а content script присылает ID снова после следующей навигации по YouTube или перезагрузки страницы
Повторная встреча видео	Upsert: обновляются views, subscribers, score, vidiqScore (если он есть сейчас), updatedAt; isShort может только стать true

Расход квоты

videos.list и channels.list стоят по 1 единице за запрос на 50 ID при лимите 10 000 единиц в сутки. Квота не должна быть проблемой при обычном просмотре.

Значок VidIQ: известное ограничение

Точная разметка значка VidIQ на карточке неизвестна, а доступа к живой странице с установленным VidIQ у разработки нет. Поэтому:

• селектор и разбор текста изолированы в src/lib/vidiq.js;
• пока селектор не заполнен, vidiqScore всегда null, остальная логика работает без изменений;
• последним шагом реализации пользователь показывает DOM карточки со значком VidIQ (правый клик → «Просмотреть код»), после чего селектор и parseVidiqScore заполняются и покрываются тестом на реальном образце текста.

Тестирование

• Автотесты на встроенном node:test, без зависимостей: score.js (формула, shouldSave на границах порогов и со скрытыми подписчиками), video-id.js (watch, shorts, мусорные ссылки), api.js (разбиение на пачки по 50, разбор ответов и ошибок на подставных данных), export.js (экранирование запятых, кавычек и переносов строк в названиях).
• Ручной чек-лист на живом YouTube: подгрузка карточек при скролле на главной; переход между страницами без перезагрузки; работа на /results и /@channel/videos; запись появляется в popup; скачивание JSON и CSV; поведение без ключа и с неверным ключом.

Вне объёма (YAGNI)

• SQLite и запись на диск через native messaging (можно добавить отдельным этапом, если экспорта станет мало)
• Формула «просмотры ÷ медиана канала»
• Синхронизация между устройствами
• Публикация в Chrome Web Store