Посібник користувача Cat-Scan¶

Проблема в одному зображенні¶

Воронка QPS

Google надсилає вашому біддеру потік запитів на ставки. Щосекунди десятки тисяч запитів надходять з біржі Authorized Buyers на ваш ендпоінт. Ваш біддер оцінює кожен із них, вирішує, чи робити ставку, і відповідає — усе за кілька мілісекунд.

Ось що більшість людей не помічає: переважна більшість цього сигналу — шум. Типовий сіт, який отримує 50 000 QPS, може виявити, що 30 000 із цих запитів стосуються інвентарю, який медіабаєр ніколи б не купив: неправильні географії, нерелевантні домени паблішерів, розміри оголошень без відповідних креативів. Ваш біддер все одно повинен отримати, розібрати та відхилити кожен із них. Це коштує пропускної здатності, обчислювальних ресурсів і грошей.

Діаграма вище показує це як дощ. QPS від Google — це форсунка зверху; краплі розлітаються по широкій площі. Ваш біддер — маленьке відро знизу. Усе, що не потрапляє у відро (краплі, що падають ліворуч і праворуч) — це втрати. Ви за це заплатили. Ви нічого не отримали натомість.

Cat-Scan існує, щоб зробити відро ширшим, а дощ — вужчим.

Він робить це, надаючи вам видимість того, де виникають втрати (які географії, які паблішери, які розміри оголошень, які креативи), і інструменти для їх усунення на джерелі, використовуючи конфігурації претаргетингу, які надає Google.

Чому це складніше, ніж здається¶

Google Authorized Buyers надає лише 10 конфігурацій претаргетингу на сіт, а також грубі географічні групи (Східні США, Західні США, Європа, Азія). Reporting API не існує. Усі дані про ефективність надходять із CSV-експортів, які приходять електронною поштою. Сам інтерфейс претаргетингу AB є функціональним, але ускладнює перегляд повної картини між конфігураціями або скасування зміни, яка пішла не так.

Cat-Scan усуває ці прогалини:

Він відновлює звітність із CSV-експортів (ручне завантаження або автоматичне отримання через Gmail), дедуплікуючи при імпорті, щоб повторна обробка ніколи не подвоювала дані.
Він показує повну воронку RTB — від сирого QPS через ставки, виграші, покази, кліки та витрати — з розбивкою за будь-яким виміром: географія, паблішер, розмір оголошення, креатив, конфігурація.
Він забезпечує безпечне управління претаргетингом з історією, поетапними змінами, попереднім переглядом у режимі dry-run та відкатом в один клік.
Він запускає оптимізатор, який оцінює сегменти та пропонує зміни конфігурацій з робочими запобіжниками (безпечний / збалансований / агресивний), щоб жодна зміна не набирала чинності без перевірки.

Для кого цей посібник¶

Цей посібник має два напрямки, оскільки Cat-Scan обслуговує дві дуже різні ролі:

Медіабаєри та менеджери кампаній використовують Cat-Scan для розуміння того, куди йде їхній бюджет, пошуку втрат, управління креативами, налаштування претаргетингу та затвердження пропозицій оптимізації. Вони мислять категоріями CPM, win rate та ROAS. Їхні розділи зосереджені на тому, що показує інтерфейс, що означають числа та які дії слід вжити.

DevOps-інженери та інженери платформи використовують Cat-Scan для розгортання, моніторингу та усунення несправностей системи. Вони мислять категоріями контейнерів, ендпоінтів перевірки стану та планів запитів. Їхні розділи зосереджені на архітектурі, конвеєрах розгортання, операціях з базою даних та інструкціях з реагування на інциденти.

Обидва напрямки мають спільну основу (початок роботи, глосарій), і розділи містять перехресні посилання там, де робочі процеси перетинаються. Медіабаєр, який повідомляє «свіжість даних не працює», та DevOps-інженер, який налагоджує запит за цим, повинні мати змогу вказати на один і той самий запис у глосарії та зрозуміти одне одного.

Як читати цей посібник¶

Частина 0 — для всіх. Починайте тут.
Частина I — напрямок для медіабаєрів. Якщо ви працюєте з кампаніями, оптимізацією або закупками — це ваш шлях.
Частина II — напрямок для DevOps. Якщо ви розгортаєте, моніторите або адмініструєте Cat-Scan — це ваш шлях.
Частина III — спільний довідник: глосарій, FAQ та довідник API.

Вам не потрібно читати лінійно. Кожен розділ є самодостатнім. Переходьте за посиланнями, що відповідають вашій ролі.

Зміст¶

Частина 0: Початок роботи¶

Це читають усі.

Розділ 0: Що таке Cat-Scan? Що робить платформа, для кого вона призначена та основні концепції, які потрібно знати перш за все: сіти, QPS, претаргетинг, воронка RTB.
Розділ 1: Вхід у систему Методи автентифікації (Google OAuth, локальні облікові записи), сторінка входу, що робити, коли вхід не вдається, та як працює перемикач сітів.
Розділ 2: Навігація панеллю керування Бічна панель, перемикання сітів, вибір мови, контрольний список налаштування для нових облікових записів та організація сторінок.

Частина I: Напрямок для медіабаєрів¶

Для медіабаєрів, менеджерів кампаній та інженерів з оптимізації.

Розділ 3: Розуміння вашої воронки QPS Головна сторінка. Як читати розбивку воронки: покази, ставки, виграші, витрати, win rate, CTR, CPM. Що означає «втрати» в конкретних термінах. Картки конфігурацій та що контролюють їхні поля.
Розділ 4: Аналіз втрат за вимірами Три перегляди аналізу втрат та коли використовувати кожен:
Географічний (/qps/geo): які країни та міста споживають QPS без конверсій.
Паблішери (/qps/publisher): які домени та додатки показують низьку ефективність.
Розмір (/qps/size): які розміри оголошень отримують трафік, але не мають відповідних креативів. Google надсилає ~400 різних розмірів; більшість не стосуються фіксованих дисплейних оголошень.
Розділ 5: Управління креативами Галерея креативів (/creatives): перегляд за форматом, фільтрація за рівнем ефективності, пошук за ID. Мініатюри, значки форматів, діагностика призначення. Кластеризація кампаній (/campaigns): перетягування, автокластеризація за допомогою AI, пул непризначених.
Розділ 6: Конфігурація претаргетингу Що контролює конфігурація претаргетингу (географії, розміри, формати, платформи, максимальний QPS). Як читати картку конфігурації. Застосування змін із попереднім переглядом у режимі dry-run. Хронологія історії змін (/history). Відкат: як він працює, навіщо він існує та коли його використовувати.
Розділ 7: Оптимізатор (BYOM) Bring Your Own Model: реєстрація зовнішнього ендпоінта для скорингу, його перевірка, активація. Життєвий цикл: оцінка — пропозиція — затвердження — застосування. Пресети робочого процесу: безпечний, збалансований, агресивний. Економіка: ефективний CPM, базова вартість хостингу, зведення ефективності. Як виглядає пропозиція та як її оцінити.
Розділ 8: Конверсії та атрибуція Підключення джерела конверсій. Інтеграція піксельного відстеження. Налаштування вебхука: підписи HMAC, спільні секрети, обмеження частоти. Перевірки готовності. Статистика отримання даних. Що означає «здоров'я конверсій» та як читати сторінку статусу безпеки.
Розділ 9: Імпорт даних Як дані потрапляють у Cat-Scan і чому це важливо. Ручне завантаження CSV (/import): перетягування, зіставлення колонок, валідація, частинне завантаження для великих файлів. Автоімпорт із Gmail: як він працює, як перевірити статус, що відбувається при збої. Сітка свіжості даних: що означає «імпортовано» та «відсутнє» для кожної дати та типу звіту. Гарантії дедуплікації.
Розділ 10: Читання ваших звітів Статистика витрат, панелі ефективності конфігурацій, метрики ефективності ендпоінтів. Як інтерпретувати тренди. Що показує щоденна розбивка. Порівняння знімків: до і після зміни претаргетингу.

Частина II: Напрямок для DevOps¶

Для інженерів платформи, SRE та системних адміністраторів.

Розділ 11: Огляд архітектури Топологія системи: бекенд на FastAPI, фронтенд на Next.js 14, Postgres (Cloud SQL), BigQuery. Чому існують обидві бази даних (вартість, затримка, попередня агрегація, управління з'єднаннями). Схема контейнерів: api, dashboard, oauth2-proxy, cloudsql-proxy, nginx. Ланцюг довіри автентифікації: OAuth2 Proxy встановлює X-Email, nginx передає його, API довіряє йому.
Розділ 12: Розгортання Конвеєр CI/CD: GitHub Actions build-and-push.yml збирає образи при пуші; deploy.yml запускається лише вручну (з підтвердженням DEPLOY). Теги образів Artifact Registry (sha-XXXXXXX). Послідовність розгортання: git pull на VM, docker compose pull, пересоздання, очищення. Перевірка після розгортання: перевірка стану, перевірка контрактів. Чому автоматичне розгортання вимкнене (інцидент січня 2026). Як перевірити розгортання: curl /api/health | jq .git_sha.
Розділ 13: Моніторинг стану та діагностика Ендпоінти стану: /api/health (перевірка живучості), /system/data-health (повнота даних). Сторінка статусу системи (/settings/system): Python, Node, FFmpeg, база даних, диск, мініатюри. Скрипти перевірки стану під час виконання: diagnose_v1_buyer_report_coverage.sh, run_v1_runtime_health_strict_dispatch.sh. Канаркова автентифікація: CATSCAN_CANARY_EMAIL, CATSCAN_BEARER_TOKEN. Робочі процеси CI: v1-runtime-health-strict.yml та що означають PASS/FAIL/BLOCKED.
Розділ 14: Операції з базою даних Лише Postgres у продакшені. Cloud SQL через проксі-контейнер. Ключові таблиці та їхній масштаб: rtb_daily (~84M рядків), rtb_bidstream (~21M рядків), rtb_quality, rtb_bid_filtering. Критичні індекси: (buyer_account_id, metric_date DESC). Модель з'єднання: per-request (без пулу), run_in_executor для асинхронності. Тайм-аути запитів (SET LOCAL statement_timeout). Налаштування збереження даних. Роль BigQuery: пакетне сховище сирих даних; Postgres надає попередньо агреговані дані додатку.
Розділ 15: Інструкція з усунення несправностей Відомі шаблони збоїв та способи їх вирішення:
Петля входу: Cloud SQL Proxy не працює, _get_or_create_oauth2_user мовчки дає збій, /auth/check повертає {authenticated:false}, фронтенд зациклюється на перенаправленнях. Триrівневе виправлення. Як виявити: лічильник перенаправлень у браузері, 503 від /auth/check.
Тайм-аут свіжості даних: Великі таблиці виконують послідовне сканування замість використання індексів. Симптоми: /uploads/data-freshness дає тайм-аут або повертає 500. Діагностика: pg_stat_activity, EXPLAIN ANALYZE. Шаблон виправлення: generate_series + EXISTS.
Збій імпорту Gmail: /gmail/status показує помилку. Перевірте контейнер Cloud SQL Proxy. Перевірте кількість непрочитаних.
Порядок перезапуску контейнерів: cloudsql-proxy повинен бути справним перед запуском api. Ознаки неправильного порядку: connection refused у логах API.
Розділ 16: Адміністрування користувачів і дозволів Панель адміністратора (/admin): створення користувачів (локальних та попередньо створених OAuth), управління ролями, дозволи для окремих сітів. Сервісні облікові записи: завантаження JSON облікових даних GCP, що це розблоковує (виявлення сітів, синхронізація претаргетингу). Обмежені користувачі: що вони бачать і що приховано. Журнал аудиту: які дії відстежуються, як фільтрувати, термін зберігання.
Розділ 17: Інтеграції Сервісні облікові записи GCP та підключення проєкту. Google Authorized Buyers API: виявлення сітів, синхронізація конфігурацій претаргетингу, синхронізація ендпоінтів RTB. Інтеграція Gmail: OAuth2 для автоматичного отримання звітів. Провайдери мовного AI: Gemini, Claude, Grok (для визначення мови креативів та сповіщень про невідповідності). Вебхуки конверсій: реєстрація ендпоінтів, перевірка HMAC, обмеження частоти, моніторинг свіжості.

Частина III: Довідник¶

Спільна для обох напрямків.

Глосарій Кожен термін двома мовами. Колонка медіабаєра: «претаргетинг» — це «правила, що контролюють, які запити на ставки досягають вашого біддера.» Колонка DevOps: «претаргетинг» — це «мутабельна сутність, синхронізована з AB API, що зберігається в pretargeting_configs, доступна через /settings/pretargeting.» Обидва потребують одного слова; жоден не використовує визначення іншого.
Часті запитання З тегами за аудиторією. Запитання медіабаєра («Чому моє покриття на рівні 74%?») поруч із запитаннями DevOps-інженера («Чому суворий тест стану під час виконання не пройшов?»). Відповіді містять перехресні посилання на відповідний розділ.
Короткий довідник API Усі 118+ ендпоінтів, згруповані за доменом: основні, сіти, креативи, кампанії, аналітика, налаштування, адміністрування, оптимізатор, конверсії, інтеграції, завантаження, знімки, автентифікація. Метод, шлях, ключові параметри та що повертає. Не замінює специфікацію OpenAPI на /api/docs, але є зручним навігаційним індексом.