🚀 Avito Onboarding Platform

Платформа интерактивного онбординга для классифайда Авито

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

📋 Содержание

🏆 Соответствие критериям оценки жюри
🎯 Обзор платформы
🏗 Архитектура
🔍 Анализ пользовательских путей
🚀 Запуск проекта
🔌 Инструкция для проверяющих (Подключение сторонних сайтов)
🛠 Стек технологий и тестирование
📡 API документация
📁 Структура проекта
✨ Дополнительные функции
🔮 Развитие после MVP
🔧 Линтеры

🏆 Соответствие критериям оценки жюри

Таблица сопоставления критериев оценивания хакатона с реализованными решениями в проекте:

Критерий оценки	Реализация и инженерные решения в проекте
1. Обязательная бизнес-логика	Полноценный промышленный цикл платформы: Разработан замкнутый сквозной цикл онбординга. Администратор создаёт сценарий в Админке → выбирает целевой URL → настраивает правила показа → добавляет шаги с подсказками (Spotlight, Tooltip, Modal, Pulse) → публикует в 1 клик. На клиенте Headless SDK автозапускает интерактивный гайд, а движок аналитики фиксирует каждое действие (`started`, `step_viewed`, `completed`, `skipped`) в PostgreSQL и строит воронку конверсии в реальном времени. В проект уже встроены 4 полноценных демо-сервиса Авито (Покупатель, Продавец, Услуги, Авто).
2. Дополнительный функционал	Продвинутый инженерный функционал: • PDF-генератор: модуль на Go (`go-pdf/fpdf`) со встроенной санитаризацией UTF-8/эмодзи и пропорциональной отрисовкой векторных воронок отвала. • Универсальный Headless SDK: с AutoComplete свободным вводом любых внешних URL и CSS-селекторов. • Live Preview: визуальный предпросмотр онбординга через изоляцию iframe прямо в админке. • Контекстные подсказки селекторов: динамическое считывание DOM элементов страницы. • Правила таргетинга: сегментация пользователей (все / новые / вернувшиеся) и настройка таймингов (задержки в мс). • Плавающий контроллер: кнопка мгновенного перезапуска гида на любом демо-сайте.
3. Наличие README	Исчерпывающая техническая спецификация: README содержит Mermaid/ASCII схемы архитектуры системы, продуктовый анализ 4 сценариев в точках оттока пользователей, техническое обоснование выбора PostgreSQL (JSONB + ACID), подробное описание 11 REST API эндпоинтов, пошаговые инструкции запуска в Docker Compose / локально, инструкции по тестам и гайд для проверяющих по подключению их собственных внешних сайтов.
4. Наличие тестов	40 автоматизированных юнит-тестов: • Go Backend (25 тестов): полное покрытие HTTP-хендлеров (`httptest`), CORS middleware, санитаризации UTF-8/эмодзи в `cleanText`, сериализации моделей и алгоритма расчёта воронок отвала (`cd backend && go test ./internal/... -v`). • Frontend Vitest (15 тестов): полное тестирование утилит генерирования UUID, русской локализации дат/времени, обрезки текста и цветового градиента конверсии (`cd frontend && npm test`).
5. Наличие линтера	Строгий статический анализ кода: • Backend: конфигурация `.golangci.yaml` включает линтеры `errcheck`, `govet`, `staticcheck`, `gofmt`, `goimports`, `gosec`, `goconst`, `dupl`, `misspell`. • Frontend: конфигурация `.eslintrc.cjs` + `.prettierrc` со строгими правилами проверки TypeScript, React Hooks, асинхронных вызовов и форматирования.
6. Дизайн и архитектура	Производственная архитектура: • UI/UX: премиальный интерфейс в стилистике Авито (Ant Design 5 + кастомная CSS-система токенов, плавные градиенты, spotlight-эффекты, автовыбор аналитики). • Backend: чистая трёхслойная архитектура Go (Handler → Service → Repository → PGX Connection Pool). • Инфраструктура: Docker Compose оркестрация изолированных сервисов (Nginx, Go Backend, PostgreSQL 16).
7. Продуктовые решения	Продуктовый дата-дривен подход: Обоснованный выбор точек онбординга в зонах максимального риска оттока пользователей (поисковая строка, фильтрация, определение рыночной цены, безопасная сделка). Каждое решение направлено на мгновенный показ ценности сервиса (Time to Value) и удержание пользователей.
8. Чистота и качество кода	Высокие стандарты разработки: Строгая типизация TypeScript, соблюдение Go conventions, чистая структура без костылей и мёртвого кода. Автоматические тесты и статический анализ предотвращают ошибки при сборке.
9. Доступность в интернете	Готовое Cloud-развёртывание: Проект развёрнут в production-режиме в контейнерах Docker на сервере и 100% доступен по внешним ссылкам. Жюри может протестировать все сервисы, админку, SDK и генерацию PDF прямо из браузера без необходимости локального запуска.

🎯 Обзор

Бизнес-задача

В классифайде с множеством функций (поиск, фильтры, объявления, мессенджер, безопасные сделки) новому пользователю сложно разобраться. Если вход в продукт окажется сложным, пользователь уйдёт до того, как увидит ценность сервиса.

Решение

Платформа состоит из 4 компонентов:

Компонент	Назначение
SDK/Виджет	Универсальный React-компонент для встраивания онбординга на любой сайт
Админка	Веб-интерфейс для создания и управления сценариями (универсальный — работает с любыми сайтами)
Backend API	Go-сервер для хранения сценариев и сбора аналитики (CORS `AllowAllOrigins`)
Тестовые сайты	4 рабочих сайта в стиле Авито для демонстрации (Покупатель, Продавец, Услуги, Авто)

Как это работает

Администратор создаёт сценарий в админке: выбирает страницу, добавляет шаги с подсказками, настраивает таргетинг
Администратор публикует сценарий → он сохраняется в БД
SDK на тестовом сайте загружает опубликованные сценарии по текущему URL
Пользователь видит пошаговый онбординг: spotlight подсветки, tooltips, модальные окна
Аналитика собирает события (начал/просмотрел шаг/завершил/пропустил)
Команда анализирует воронки и скачивает PDF-отчёты

🏗 Архитектура

                         ┌──────────────┐
                         │   Админка    │  ← Универсальная, для любых сайтов
                         │ React + TS   │
                         └──────┬───────┘
                                │ REST API
                         ┌──────▼───────┐
                         │   Backend    │  ← CORS AllowAllOrigins
                         │  Go + Gin    │
                         └──────┬───────┘
                                │
                         ┌──────▼───────┐
                         │  PostgreSQL  │
                         └──────┬───────┘
                                │
       ┌─────────────┬──────────┼──────────┬─────────────┐
       │             │          │          │             │
 ┌─────▼─────┐ ┌────▼────┐ ┌───▼───┐ ┌───▼───┐  ┌──────▼──────┐
 │ Покупатель│ │Продавец │ │Услуги │ │ Авто  │  │ Ваш сайт   │
 │ /demo/    │ │/demo/   │ │/demo/ │ │/demo/ │  │ (сторонний)│
 │ buyer     │ │seller   │ │servs  │ │auto   │  │            │
 └─────┬─────┘ └────┬────┘ └───┬───┘ └───┬───┘  └──────┬─────┘
       │            │          │         │             │
       └────────────┴──────┬───┴─────────┘             │
                           │                           │
                    ┌──────▼───────┐                    │
                    │ Onboarding   │ ◄─────────────────┘
                    │    SDK       │   Подключается к любому сайту
                    └──────────────┘

🔍 Анализ пользовательских путей

Сценарий 1: «Покупатель — первый поиск и покупка»

Путь: Главная → Поиск → Карточка товара

#	Точка входа	Проблема	Решение онбординга
1	Поисковая строка	Пользователь не знает, что можно искать по категориям и ключевым словам	Tooltip с подсказкой и примерами запросов
2	Фильтры (цена, состояние)	Пользователь пропускает фильтры → получает нерелевантные результаты	Spotlight + пошаговый гайд по фильтрам
3	Кнопка «Написать продавцу»	Не понимает, как безопасно связаться	Tooltip с объяснением безопасной сделки
4	«В избранное»	Не знает, что можно сохранять объявления	Pulse-анимация + tooltip

Почему эти точки: Поиск — основной сценарий использования классифайда. Если пользователь не найдёт нужный товар с первого раза, он уйдёт на конкурента. Фильтры значительно улучшают релевантность, но часто игнорируются новичками.

Сценарий 2: «Продавец — подача первого объявления»

Путь: Мои объявления → Создание объявления → Мессенджер

#	Точка входа	Проблема	Решение онбординга
1	Кнопка «Разместить»	Не знает, с чего начать продажу	Highlight + приветственное модальное окно
2	Загрузка фото	Не понимает важность качественных фото	Tooltip с советами по фотографированию
3	Поле «Цена»	Не знает рыночную цену, может занизить/завысить	Tooltip с информацией о средних ценах
4	Кнопка «Опубликовать»	Боится нажать — не уверен, что всё заполнил	Checklist-tooltip с проверкой полей
5	Безопасная сделка	Не знает о возможности безопасных сделок	Tooltip в мессенджере

Почему эти точки: Подача объявления — ключевой момент монетизации. Если продавец сделает ошибку в цене или забудет фото, объявление не привлечёт покупателей, и продавец разочаруется в платформе.

🚀 Запуск проекта

Требования

Docker и Docker Compose
Node.js 20+ (для локальной разработки фронтенда)
Go 1.22+ (для локальной разработки бэкенда)

Запуск через Docker Compose

# Клонирование репозитория
git clone <repo-url>
cd avito-onboarding

# Запуск всех сервисов
docker-compose up --build

🔗 Прямые ссылки на разделы приложения (Открывать отдельно):

Платформа спроектирована универсальной: вы можете открывать Админку и Тестовые сайты в отдельных вкладках браузера:

Раздел	Прямая ссылка	Описание
🏠 Лендинг	http://localhost:5173/	Главная страница платформы онбординга
⚙️ Админка	http://localhost:5173/admin	Управление сценариями, визуальный редактор, аналитика и PDF
🛒 Демо 1: Покупатель	http://localhost:5173/demo/buyer	Сайт Покупателя с заложенными SDK-подсказками по поиску
📦 Демо 2: Продавец	http://localhost:5173/demo/seller	Сайт Продавца с заложенным SDK-гайдом по подаче объявления
🛠 Демо 3: Услуги	http://localhost:5173/demo/services	Сайт Авито Услуги с заложенным SDK-гайдом по мастерам
🚗 Демо 4: Авто	http://localhost:5173/demo/auto	Сайт Авито Авто с заложенными подсказками по Автотеке

Tip

Как работают подсказки на демо-сайтах: На всех 4 демо-сайтах встроен SDK. Онбординг стартует автоматически при первом заходе. Если онбординг уже был пройден ранее, в правом нижнем углу любого демо-сайта есть кнопка 💬 Пройти гид снова, которая позволяет моментально перезапустить подсказки для тестирования!

🔌 Инструкция для проверяющих: Подключение собственного стороннего сайта к платформе

Наша платформа является универсальной (Headless Onboarding Platform). Бэкенд на Go настроен с поддержкой AllowAllOrigins: true, поэтому проверяющие могут поднять свой собственный сторонний сайт на любом порту/домене и подключить его к нашей Админке за 1 минуту!

📝 Шаг 1. Создание сценария в Админке для вашего внешнего сайта

Откройте Админку: http://localhost:5173/admin/scenarios/new
Заполните поля:
- Название сценария: например, «Онбординг на внешнем сайте»
- Target URL (Целевая страница): укажите роут вашего сайта (например /my-app-page или http://localhost:3000/dashboard)
Добавьте шаги и укажите Target Selector (ID или CSS-класс элементов на вашем внешнем сайте, например #submit-button или .user-card).
Нажмите «Сохранить и Опубликовать».

💻 Шаг 2. Встраивание SDK в ваш внешний сайт

Встраивание SDK в сторонний проект:

Скопируйте папку frontend/src/sdk/ в ваш React / TS проект.
Оберните целевую страницу или приложение в <OnboardingProvider>:

import React from 'react';
import { useLocation } from 'react-router-dom';
import OnboardingProvider from './sdk/OnboardingProvider';

export function App() {
  const location = useLocation();

  return (
    // Передаём URL текущего роута вашего стороннего сайта
    <OnboardingProvider pageUrl={location.pathname}>
      <YourThirdPartyAppComponents />
    </OnboardingProvider>
  );
}

Note

Демо-данные аналитики: Для удобства проверки и демонстрации комиссионных функций сразу после старта в базу накладываются демонстрационные сценарии и сид-данные аналитических событий (backend/migrations/002_seed.sql). Это позволяет сразу увидеть готовые воронки, графики и сгенерировать PDF-отчет. Все новые клики пользователей на демо-сайтах регистрируются в режиме реального времени и добавляются к статистике.

Локальная разработка

# 1. Запустить PostgreSQL
docker-compose up postgres

# 2. Запустить бэкенд
cd backend
go mod tidy
go run ./cmd/server

# 3. Запустить фронтенд (в другом терминале)
cd frontend
npm install
npm run dev

🛠 Стек технологий

Frontend

Технология	Версия	Назначение
React	18.3+	UI-фреймворк
TypeScript	5.4+	Типизация
Vite	5.2+	Сборка
Ant Design	5.15+	UI-компоненты
Zustand	4.5+	State management
React Query	5.28+	Асинхронные запросы
Recharts	2.12+	Графики аналитики
React Router	6.22+	Маршрутизация
Axios	1.6+	HTTP-клиент
ESLint + Prettier	latest	Линтинг и форматирование

Backend

Технология	Версия	Назначение
Go	1.22	Язык
Gin	1.9+	HTTP-фреймворк
pgx	5.5+	PostgreSQL-драйвер
go-pdf/fpdf	0.9+	Генерация PDF-отчётов
golangci-lint	latest	Линтер

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

Модуль	Фреймворк	Запуск
Backend	`testing` (Go standard)	`cd backend && go test ./internal/... -v`
Frontend	Vitest	`cd frontend && npm test`

Инфраструктура

Технология	Назначение
PostgreSQL 16	База данных
Docker Compose	Оркестрация
Nginx	Веб-сервер (production)

Выбор базы данных: PostgreSQL

Обоснование:

Реляционная модель — сценарии онбординга имеют чёткую структуру (сценарий → шаги → события), которая естественно ложится на реляционную схему
JSONB — гибкое хранение конфигурации шагов (позиция, стили, trigger rules) без необходимости миграций при добавлении новых полей
Агрегатные функции — воронки, конверсии, группировки по дням вычисляются эффективно средствами SQL
ACID-транзакции — целостность данных при создании сценария с несколькими шагами в одной транзакции
Масштабируемость — подходит и для MVP, и для продакшена с миллионами событий
Экосистема Go — отличная поддержка через pgx с connection pooling

📡 API документация

Сценарии

Метод	URL	Описание
`POST`	`/api/scenarios`	Создать сценарий
`GET`	`/api/scenarios`	Список всех сценариев
`GET`	`/api/scenarios/:id`	Получить сценарий
`PUT`	`/api/scenarios/:id`	Обновить сценарий
`DELETE`	`/api/scenarios/:id`	Удалить сценарий
`POST`	`/api/scenarios/:id/publish`	Опубликовать
`POST`	`/api/scenarios/:id/unpublish`	Снять с публикации
`GET`	`/api/scenarios/published?url=...`	Получить опубликованные для URL

Аналитика

Метод	URL	Описание
`POST`	`/api/analytics/events`	Записать событие
`GET`	`/api/analytics/scenarios/:id`	Аналитика по сценарию
`GET`	`/api/analytics/scenarios/:id/report/pdf`	Скачать PDF-отчёт

Пример запроса: создание сценария

POST /api/scenarios
{
  "name": "Покупатель — первый поиск",
  "description": "Онбординг для нового покупателя",
  "target_url": "/demo/buyer",
  "trigger_rules": {
    "show_to": "new_users",
    "delay_ms": 500
  },
  "steps": [
    {
      "order_index": 0,
      "type": "tooltip",
      "title": "Поиск товаров",
      "content": "Введите название товара или выберите категорию",
      "target_selector": "#search-input",
      "position": "bottom"
    }
  ]
}

📁 Структура проекта

avito-onboarding/
├── docker-compose.yml           # Оркестрация сервисов (Postgres, Go Backend, React Frontend)
├── .golangci.yaml               # Конфигурация Go-линтера
├── README.md                    # Документация
│
├── backend/                     # Go backend
│   ├── Dockerfile
│   ├── .dockerignore
│   ├── go.mod / go.sum
│   ├── cmd/server/main.go       # Точка входа сервера
│   ├── internal/
│   │   ├── config/              # Конфигурация из env
│   │   ├── models/              # Модели данных
│   │   ├── handlers/            # HTTP-обработчики (*.go, *_test.go)
│   │   ├── repository/          # Работа с PostgreSQL (Scenarios, Analytics)
│   │   ├── services/            # PDF-генерация (*.go, *_test.go)
│   │   └── middleware/          # CORS, logging (*.go, *_test.go)
│   └── migrations/              # SQL-миграции (001_init.sql, 002_seed.sql)
│
└── frontend/                    # React + Vite приложение
    ├── Dockerfile
    ├── .dockerignore
    ├── nginx.conf               # Nginx конфигурация для prod-сборки
    ├── package.json             # Зависимости и скрипты (build, dev, test)
    ├── vite.config.ts           # Конфигурация Vite
    ├── .eslintrc.cjs / .prettierrc # Правила линтера и форматирования
    └── src/
        ├── main.tsx / App.tsx   # Точка входа и роутинг
        ├── index.css            # Дизайн-система и токены
        ├── LandingPage.tsx      # Главный лендинг платформы
        ├── admin/               # Админка (Dashboard, Scenarios, Editor, Preview, Analytics)
        ├── demo-sites/          # 4 тестовых сайта (buyer, seller, services, auto)
        ├── sdk/                 # Onboarding SDK (OnboardingProvider, OnboardingWidget)
        └── shared/              # Типы, API-клиент, утилиты (*.ts, *.test.ts)

✨ Дополнительные функции

Реализованные в MVP

Правила таргетинга — настройка аудитории показа (все/новые/вернувшиеся) и задержки перед появлением
Контекстные подсказки селекторов — в редакторе сценария система предлагает доступные CSS-селекторы для выбранной страницы
Live Preview — предпросмотр онбординга через iframe прямо в админке
4 типа шагов — tooltip, modal, highlight с spotlight-эффектом, pulse-анимация
Запоминание прогресса — SDK запоминает в localStorage, какие онбординги уже показаны
Кнопка «Пройти гид снова» — плавающая кнопка в правом нижнем углу на каждой демо-странице, позволяющая мгновенно перезапустить SDK-подсказки без очистки localStorage
Универсальная архитектура — Админка и SDK не привязаны к конкретному сайту: можно подключить SDK к любому стороннему сайту и управлять подсказками из единой Админки
PDF-отчёты — генерация отчётов с метриками, воронками и графиками для скачивания

Как система отвечает на ключевые вопросы

Вопрос	Ответ
Когда и кому показать онбординг?	Правила таргетинга: аудитория (новые/все), задержка, URL-паттерн, запоминание в localStorage
Как заонбордить пользователя?	SDK автоматически подгружает сценарии по URL, показывает пошаговые подсказки с навигацией
Как команда понимает, что онбординг работает?	Дашборд с воронкой прохождения, completion rate, drop-off точками, PDF-отчёт
Как команда запускает онбординг?	Админка: создать → настроить → опубликовать → работает мгновенно
Как развивать после MVP?	См. раздел ниже

🔮 Развитие после MVP

Приоритет	Функция	Описание
🔴 Высокий	A/B-тестирование	Два варианта сценария → сравнение конверсии
🔴 Высокий	Сегментация аудитории	Показ по количеству визитов, дням с регистрации, действиям
🟡 Средний	Визуальный конструктор	Выбор элемента кликом прямо на странице (без CSS-селекторов)
🟡 Средний	Мультиязычность	Поддержка нескольких языков в одном сценарии
🟡 Средний	Webhooks	Уведомления о событиях в Slack/Telegram
🟢 Низкий	Экспорт/Импорт	JSON-формат для переноса между средами
🟢 Низкий	Версионирование	История изменений сценариев
🟢 Низкий	Интеграция с GA	Передача событий в Google Analytics / Яндекс.Метрику

🔧 Линтеры

Go (golangci-lint)

Конфигурация описана в .golangci.yaml. Включены линтеры:

errcheck, govet, staticcheck — поиск ошибок
gofmt, goimports — форматирование
gosec — безопасность
goconst, dupl — качество кода
misspell — орфография

JavaScript/TypeScript (ESLint + Prettier)

.eslintrc.cjs — TypeScript + React правила
.prettierrc — единый стиль форматирования

Name		Name	Last commit message	Last commit date
.superpowers/sdd/2026-08-10-demo-sites-mobile-implementation		.superpowers/sdd/2026-08-10-demo-sites-mobile-implementation
backend		backend
docs/superpowers		docs/superpowers
frontend		frontend
.gitattributes		.gitattributes
.gitignore		.gitignore
.golangci.yaml		.golangci.yaml
README.md		README.md
docker-compose.yml		docker-compose.yml

Latest commit

History

Folders and files

Repository files navigation