LightLeads

Платформа сквозной аналитики рекламы и продаж: показывает, какая кампания, группа, объявление и креатив в Meta и TikTok Ads приносят продажи и прибыль, а не только клики и лиды.

Полное ТЗ и план по фазам — в PROMPT.md.

Состояние: Фазы 4 и 5 — лиды из Meta и продажи

Готовы дизайн-система и все экраны (Фаза 0), вход, рабочие пространства и база данных с RLS (Фаза 1), подключение рекламных кабинетов Meta (Фаза 2) и TikTok Ads (Фаза 3), приём лидов с сайта и ручные лиды (Фаза 4), продажи в базе: ручной ввод, импорт CSV и Excel, товары с себестоимостью, привязка продажи к объявлению по телефону (Фаза 5). TikTok включится, когда в секретах сервера появятся ключи приложения TikTok: до этого кнопка подключения показана как «Скоро».

Лид-формы Meta и WhatsApp (Cloud API) написаны и выложены, но на настоящих страницах и номерах ещё не проверены: для этого владелец платформы добавляет права и вебхук в приложении Meta (раздел «Лиды из Meta» ниже). Из Фазы 4 не сделаны Instagram Direct и лид-формы TikTok. Лиды из Google-таблицы приходят скриптом таблицы, новые заявки бот присылает в Telegram (разделы «Лиды из Google-таблицы» и «Заявки в Telegram» ниже). Продажи из Google Sheets, amoCRM и Bitrix24 не сделаны: в интерфейсе они помечены «Скоро». Сейчас в работе только Meta: TikTok и CRM отложены по решению владельца.

• Регистрации нет. Аккаунт создаёт владелец платформы в разделе /admin («Аккаунты и проекты») или владелец проекта в «Настройки → Команда». Логин и пароль показываются один раз, их передают человеку вручную.
• Проект (в коде — workspace) — один клиент или бизнес. Любой вошедший человек создаёт себе проекты сам (переключатель слева вверху → «Новый проект») и становится их владельцем: таргетолог заводит проект под каждого клиента и подключает к нему свои кабинеты. Владелец платформы может создать проект и для другого человека, а также аккаунт без проекта.
• Раздел /admin показывает владельцу платформы всех людей и все проекты: кто в каком проекте, через чей аккаунт Facebook подключена реклама, какие кабинеты выбраны, страницы и номера WhatsApp, лиды и продажи за 30 дней. Данные берутся действием overview функции team. Открыть дашборд чужого проекта нельзя: для этого владелец платформы добавляет себя в проект.
• Несколько проектов. У проекта свои рекламные кабинеты, страницы, номера WhatsApp, лиды, продажи и участники. Один аккаунт Facebook можно подключить к нескольким проектам и выбрать в каждом свои кабинеты. При удалении проекта аккаунты людей остаются.
• Гость без аккаунта видит приложение в демо-режиме: данные генерируются в браузере.
• Workspace без рекламы показывает те же демо-данные (флаг demo_data), пока владелец не подключит Meta или TikTok в «Настройки → Подключения».
• После подключения кабинета кампании, группы, объявления, креативы и статистика по дням читаются из Supabase. Пока в workspace нет ни одной продажи, выручка и ROMI считаются без продаж, а советы «отключить объявление» не показываются.
• Продажи и товары workspace с настоящими данными лежат в Supabase. В workspace с демо-данными они, как и всё остальное, живут только в браузере.
• Лиды приходят с сайта клиента (скрипт или вебхук) и добавляются вручную. Первый настоящий лид, как и первый подключённый кабинет, выключает демо-данные workspace.

Экран	Адрес
Лендинг	/
Вход	/login
Аккаунты и проекты (владелец платформы)	/admin
Онбординг-мастер	/onboarding
Дашборд	/dashboard
Кампании (дерево)	/campaigns
Креативы, страница креатива	/creatives, /creatives/[id]
Лиды	/leads
Продажи, импорт CSV и Excel	/sales
AI-советы и чат	/ai
Настройки	/settings
Политика конфиденциальности, удаление данных	/privacy, /data-deletion

Второй workspace в переключателе (Bilim Academy) пустой — на нём видны пустые состояния.

Запуск

Скопируйте .env.example в .env.local и впишите адрес проекта Supabase и публичный ключ (Supabase → Project Settings → API Keys). Без них приложение работает только в демо-режиме.

npm install
npm run dev        # http://localhost:3000

Чтобы открыть с телефона в той же сети Wi-Fi, возьмите адрес из строки Network в выводе npm run dev, например http://192.168.1.106:3000.

npm run lint       # ESLint
npx tsc --noEmit   # проверка типов
npm run build      # сборка для Vercel

Деплой

Сайт: https://lightleads-indol.vercel.app (Vercel, проект lightleads).

Сборка по push из GitHub отключена в vercel.json (git.deploymentEnabled: false): в октябре 2026 она падала с ошибкой git_info_fail — GitHub отвечал Vercel отказом 403 «secondary rate limit», и переподключение репозитория не помогло. Поэтому после git push сайт выкладывается напрямую:

npx vercel deploy --prod

Чтобы вернуть автоматическую сборку, удалите блок git из vercel.json.

База данных

Supabase, проект lightleads. Схема лежит в supabase/migrations:

• 0001_tenancy.sql — profiles, workspaces, workspace_members, функции проверки доступа и RLS;
• 0003_meta_sync.sql — поля и расписание для синхронизации Meta, бакет превью;
• 0004_tiktok_sync.sql — расписание синхронизации TikTok и поле «конверсии» из отчёта кабинета;
• 0005_leads.sql, 0006_leads_end_demo.sql — ключ приёма лидов, исходные данные заявки, проверка формата телефона, выключение демо-данных первым лидом;
• 0007_large_accounts.sql — место остановки обхода большого кабинета и очередь превью;
• 0008_sales.sql — права на запись продаж и товаров, проверка формата телефона продажи;
• 0009_meta_lead_channels.sql — страницы Facebook и номера WhatsApp, подключённые к workspace, ID объявления у лида и ежечасная проверка лид-форм;
• 0010_telegram_sheets.sql — источник лидов sheet, чаты Telegram проекта, одноразовые коды подключения, очередь заявок для отправки и ежеминутная отправка;
• 0011_whatsapp_telegram_chat.sql — связь сообщений бота с клиентами WhatsApp для ответов, защита от повторных уведомлений Meta, заявки WhatsApp вне общей очереди Telegram;
• 0012_lead_card.sql — комментарий менеджера к лиду (участник меняет только его) и мгновенная привязка лида к объявлению, которое загрузилось из кабинета позже заявки;
• 0013_telegram_sales.sql — продажи из Telegram: способ ввода telegram, имя продавца (seller_name) и вопросы бота о сумме (telegram_sale_prompts, только для сервера);
• 0002_data_model.sql — таблицы рекламы, лидов, продаж и интеграций. У каждой есть workspace_id, участник читает только свой workspace. Права записи добавляются в фазах, где появляются экраны.

Токены рекламных кабинетов и CRM хранятся в отдельных таблицах *_secrets без политик: их читает только сервер.

Аккаунты создаёт Edge Function supabase/functions/team: сервисный ключ есть только у неё, в приложение и в браузер он не попадает. Новый пароль участнику выдаёт только владелец платформы.

Первого владельца платформы назначают вручную: profiles.is_platform_admin = true.

Рекламные платформы

У каждой платформы своя Edge Function: meta-oauth и tiktok-oauth. Порядок работы у них общий и лежит в supabase/functions/_shared: вход на платформе, выбор кабинетов, шаги синхронизации, плановое обновление, шифрование токена. В папке платформы — только то, чем она отличается: адреса API, поля и разбор ответов. LightLeads только читает рекламу.

• Токен хранится в ad_connection_secrets зашифрованным (AES-256-GCM). Ключ выводится из секрета TOKEN_ENCRYPTION_KEY, а если он не задан — из сервисного ключа проекта: смена этого ключа потребует переподключить кабинеты.
• Первая загрузка — 90 дней, шагами с прогрессом. Дальше pg_cron каждые 2 часа перечитывает последние 3 дня: Meta на 7-й минуте часа, TikTok на 37-й. Курс НБРК на нужные даты загружается тут же.
• Большие кабинеты (сотни кампаний, тысячи объявлений) читаются страницами: шаг работает около 25 секунд и возвращает место остановки. Структура продолжается с ad_accounts.sync_cursor. Первая загрузка идёт до конца; обновление и pg_cron продвигают обход на одну порцию за запуск, статистика при этом обновляется каждый раз.
• Превью креативов копируются в публичный бакет Storage creatives: ссылки платформ живут недолго. Скачиваются только превью работающих объявлений и объявлений со статистикой.
• На экраны попадают работающие кампании, группы и объявления и те, по которым за 90 дней есть статистика или лиды. Остальное хранится в базе, но не показывается.
• Догрузить историю одного кабинета с сервера: действие cron с параметрами account, days, skip.
• Кабинеты в валютах кроме USD и KZT пока не подключаются.
• Функции выкладываются вместе с папкой _shared: пути файлов считаются от supabase/functions, точка входа — meta-oauth/index.ts или tiktok-oauth/index.ts.

Meta

• Секреты Edge Functions: META_APP_ID, META_APP_SECRET. Необязательные: META_LOGIN_CONFIG_ID (конфигурация Facebook Login for Business), META_GRAPH_VERSION.
• В приложении Meta должен быть разрешён адрес возврата https://<project>.supabase.co/functions/v1/meta-oauth. Право — ads_read.
• Пока приложение Meta в режиме разработки, подключаются только кабинеты людей с ролью в приложении. Для чужих кабинетов нужны Business Verification и App Review (Advanced Access для ads_read). Для ревью готовы страница политики конфиденциальности /privacy и страница /data-deletion. Data Deletion Callback принимает функция meta-leads (POST с полем signed_request, подпись секретом приложения): удаляет ключ доступа, имя и ID профиля Facebook и отвечает ссылкой на /data-deletion?code=…. Название оператора и почта для политики задаются в LEGAL (src/lib/config.ts); пока они пустые, на проверку Meta не подавать.

TikTok

• Приложение создаётся в TikTok API for Business и проходит проверку TikTok. До одобрения подключить настоящие кабинеты нельзя.
• Секреты Edge Functions: TIKTOK_APP_ID, TIKTOK_APP_SECRET.
• Адрес возврата в приложении (Advertiser redirect URL): https://<project>.supabase.co/functions/v1/tiktok-oauth.
• Нужны права на чтение: кабинеты (Ad Account Management), кампании и объявления (Ads Management), отчёты (Reporting), видео и картинки (Creative Management).
• Marketing API v1.3: структура из /campaign/get/, /adgroup/get/, /ad/get/, статистика из /report/integrated/get/ (AUCTION_AD, по дням, с удалёнными объявлениями), обложки видео из /file/video/ad/info/. Отдельной сущности «креатив» у TikTok нет: креативом считается видео или картинка объявления.
• Порог удержания видео у TikTok — 2 и 6 секунд (у Meta 3 секунды и ThruPlay), поэтому hook rate и hold rate двух платформ сравнимы только приблизительно.
• Вход и обмен кода на токен с настоящим приложением TikTok ещё не проверены: нет ключей приложения. Поля и запросы сверены с ответами настоящего кабинета.

Лиды

Edge Function supabase/functions/leads принимает заявки с сайтов и выполняет действия менеджера (ручной лид, удаление лида).

• Адрес приёма: POST /api/ingest/lead на домене приложения (переадресация в next.config.ts на функцию leads). Ключ workspace передаётся заголовком x-workspace-key, параметром ?key= или полем key. Ключ лежит в таблице ingest_keys, участники видят его в «Настройки → Источники лидов». По ключу можно только добавить лид.
• Формат: JSON или поля формы, в том числе вложенные (вебхуки квизов). Телефон ищется в полях phone, tel, телефон и похожих, метки — в utm_*, fbclid, ttclid или в объекте utm. Проверочный запрос Tilda (test=test) получает ответ 200. Если в Tilda включено «Передавать Cookies», метки берутся из cookie TILDAUTM, когда их нет в полях формы.
• Телефон приводится к E.164 (страна по умолчанию — из workspace, KZ). Невалидный номер — ответ 422.
• Привязка к объявлению: utm_content — ID объявления, utm_term — ID группы, utm_campaign — ID кампании на платформе. Берётся самый точный из найденных в подключённых кабинетах.
• Дубли: та же заявка (номер заявки сайта или тот же телефон в течение 10 минут) — один лид. Больше 60 заявок в минуту с одного ключа отклоняются.
• Скрипт для сайта public/ll.js: одна строка <script src="…/ll.js" data-key="…">. Хранит метки в cookie 30 дней, подставляет их в скрытые поля форм и при отправке формы с телефоном передаёт лид. data-send="off" отключает отправку, если лиды уже шлёт вебхук сайта.
• Разбор заявок покрыт тестами: deno test supabase/functions/leads/extract_test.ts.
• Лид запоминает ID объявления на платформе (leads.external_ad_id). Если объявление ещё не загрузилось из кабинета, лид привяжется к нему при ближайшей ежечасной проверке (relink_leads).

Лиды из Meta

Edge Function supabase/functions/meta-leads принимает лиды из лид-форм страниц Facebook и из WhatsApp (Cloud API). Подключённые страницы и номера лежат в lead_channels; страница или номер принадлежит одному workspace.

• Права Facebook запрашиваются отдельно от чтения рекламы, кнопкой «Разрешить доступ» в «Настройки → Источники лидов». Лид-формы: pages_show_list, pages_read_engagement, pages_manage_metadata, pages_manage_ads, leads_retrieval. WhatsApp: business_management, whatsapp_business_management, whatsapp_business_messaging. Вход завершает meta-oauth (её адрес возврата уже разрешён в приложении), новый токен заменяет прежний.
• Что нужно сделать в приложении Meta: добавить эти права в сценарии использования, добавить продукт WhatsApp, а в разделе Webhooks указать Callback URL и Verify token из /admin («Вебхук приложения Meta») для объекта Page (поле leadgen) и объекта WhatsApp Business Account (поле messages). Verify token выводится из секрета приложения и нигде не хранится.
• Уведомления проверяются по подписи X-Hub-Signature-256 (секрет приложения). Запрос без верной подписи отклоняется.
• Лид-форма: по уведомлению заявка дочитывается токеном страницы; ID объявления берётся из уведомления. Заявка без телефона не сохраняется, на канале остаётся пояснение.
• WhatsApp: лидом становится сообщение с объектом referral типа ad (переход с рекламы, лид привязан к объявлению) и первое сообщение клиента, который не был лидом проекта последние 30 дней. Сохраняются номер, имя профиля, объявление и текст первого сообщения (raw_payload.message, до 500 знаков). Все сообщения клиентов пересылаются в Telegram проекта (раздел «Заявки в Telegram»); сама переписка в базе не хранится, только ID обработанных сообщений (whatsapp_seen, от повторов Meta).
• Ежечасная проверка (pg_cron, 22-я минута): дочитывает заявки форм, которые не пришли уведомлением (при подключении страницы — за 30 дней), и привязывает лиды к новым объявлениям.
• Пока приложение Meta в режиме разработки, всё это работает только для людей с ролью в приложении. Для чужих страниц и номеров нужны Business Verification и App Review по каждому праву.
• Разбор уведомлений и проверка подписи покрыты тестами: deno test supabase/functions/meta-leads/webhook_test.ts.
• Функция выкладывается с файлами _shared/core.ts, leads/extract.ts, meta-oauth/lib.ts, точка входа — meta-leads/index.ts.

Лиды из Google-таблицы

В «Настройки → Источники лидов» лежит готовый скрипт Google Apps Script с ключом проекта (src/lib/snippets.ts, sheetsScript). Его вставляют в таблицу («Расширения → Apps Script») и запускают функцию start.

• Скрипт раз в минуту отправляет до 40 новых строк на адрес приёма с заголовком x-lead-source: sheet и отмечает результат в колонке «LightLeads». Строки, которые были в таблице до запуска, помечаются «было до подключения»; функция sendOldRows отправляет и их.
• Заголовки первой строки становятся названиями полей: телефон, имя, ad_id и дата заявки («Дата», created_time, «Отметка времени») распознаются в leads/extract.ts. Дата без часового пояса считается временем Казахстана. Дату не старше года принимает только источник sheet; у сайта время заявки — время приёма.
• Для таблицы свой лимит — 120 строк в минуту.

Заявки в Telegram

Edge Function supabase/functions/telegram — бот, который присылает новые заявки проекта в Telegram: имя, телефон, источник, объявление, кампанию, первое сообщение WhatsApp и кнопку «Написать в WhatsApp» (ссылка wa.me).

• Настройка (один раз, владелец платформы): создать бота у @BotFather и задать токен в секрете Edge Functions TELEGRAM_BOT_TOKEN. Адрес вебхука бот ставит себе сам при первом подключении чата; строка проверки вебхука выводится из токена и нигде не хранится. Состояние бота видно в /admin.
• Подключение чата: любой участник проекта в «Настройки → Telegram» получает ссылку на бота с одноразовым кодом (30 минут) — в личный чат (?start=) или в группу (?startgroup=). Бот принимает «/start КОД», записывает чат в telegram_chats и отвечает «Готово». До 10 чатов на проект.
• Отправка: триггер на leads ставит в telegram_queue новые заявки проекта с активным чатом, кроме ручных и заявок старше суток (подгруженная история). pg_cron раз в минуту вызывает функцию, только если очередь не пуста. Больше 5 заявок проекта сразу — одно сообщение со списком. Временная ошибка Telegram оставляет заявки в очереди (не дольше суток); удалённый из чата или заблокированный бот помечает чат ошибкой.
• Ответы клиентам WhatsApp. Сообщения клиентов с номера WhatsApp Cloud API присылает в чаты функция meta-leads сразу (заявки WhatsApp в общую очередь не попадают). Для каждого такого сообщения бота в telegram_threads записано, какой это клиент и с какого номера компании ему отвечать. Ответ менеджера на это сообщение (reply) бот отправляет клиенту через Cloud API (POST /{phone_number_id}/messages, токен подключения Meta проекта, право whatsapp_business_messaging) и ставит реакцию 👍; при ошибке отвечает понятной причиной (telegram/whatsapp.ts), например «прошло больше 24 часов». Файлы ходят в обе стороны. Фото, видео, голосовое или документ клиента meta-leads скачивает у Meta (GET /{media_id}, до 20 МБ) и присылает в чат самим файлом. Для нескольких чатов файл загружается один раз, дальше отправляется по file_id. Если Telegram не принял файл как фото или голосовое, он уходит документом. Геопозиция приходит ссылкой на карту, контакт — именем и номером. Ответ менеджера файлом бот скачивает из Telegram (getFile, до 20 МБ), загружает в WhatsApp (POST /{phone_number_id}/media) и отправляет с подписью. Тип сообщения WhatsApp выбирается по формату и размеру: фото до 5 МБ, видео и аудио до 16 МБ, остальное уходит документом. Стикеры не отправляются.
• Продажи из чата. Под заявкой (и под следующими сообщениями клиента WhatsApp) есть кнопка «✅ Продажа». Бот задаёт вопрос «какая сумма» (force reply) и запоминает его в ; ответ вида , , или () записывается в с , телефоном и именем лида, датой «сегодня» в поясе проекта и именем менеджера в . Товар подбирается по названию из справочника (себестоимость из товара), иначе — средняя маржа проекта. Под подтверждением — «Отменить» (в течение суток). Записывать и отменять можно только из чата, подключённого к проекту этого лида. Вебхук бота должен получать : он перерегистрируется при подключении чата или открытии .

Продажи

Продажи и товары приложение пишет прямо в таблицы sales и products (src/lib/sales-api.ts); права проверяет RLS.

• Кто что может: продажу вносит любой участник workspace, меняет в ней только источник, выбранный вручную; удаляет тот, кто внёс, или владелец. Товары добавляет и убирает владелец. Товар не удаляется, а уходит в архив: на него ссылаются продажи.
• Кто внёс продажу, записывает база (created_by), браузер это поле передать не может. Товар и объявление-источник должны быть из того же workspace.
• Источник продажи не хранится: приложение находит лид с тем же телефоном в окне атрибуции при показе (src/lib/attribution.ts). Модель и окно меняются в настройках без пересчёта базы. Таблица sale_attributions пока не используется.
• Импорт: CSV (разделитель определяется сам) и Excel .xlsx (первый лист). Мастер сопоставляет колонки, показывает строки с ошибками и возможные дубли (телефон + сумма + дата ±1 день).

Стек

Next.js 15 (App Router) · TypeScript strict · Tailwind CSS 4 · shadcn/ui · Framer Motion · Recharts · lucide-react · zod · date-fns · libphonenumber-js.

Структура

src/
  app/                    страницы (App Router)
    (app)/                кабинет: дашборд, кампании, креативы, лиды, продажи, AI, настройки
    (auth)/               вход
    onboarding/           мастер подключения
  components/
    kit/                  дизайн-система: кнопки, карточки, деньги в двух валютах, бейджи, анимации
    shell/                каркас: сайдбар, верхняя панель, нижняя навигация, выбор периода
    charts/               графики
    features/             крупные блоки: добавление продажи, импорт, KPI, воронка, советы
    ui/                   компоненты shadcn/ui
  i18n/ru.ts              все тексты интерфейса (для kk/en добавить словарь того же типа)
  lib/
    mock/seed.ts          детерминированный демо-сид
    store.tsx             состояние демо; в Фазе 1 заменяется чтением из Supabase
    metrics.ts            все производные метрики: прибыль, ROMI, ROAS, CPL, CAC, конверсия
    analytics.ts          сведение расхода, лидов и продаж за период
    attribution.ts        связка продажи с лидом по телефону, поиск дублей
    currency.ts           конвертация по курсу на дату операции
    score.ts              рейтинг креатива 0–100 со сглаживанием
    rules.ts              правила-сигналы для AI-советов
    phone.ts              нормализация телефона в E.164
    csv.ts                разбор и проверка CSV для импорта

Что в демо настоящее, а что имитация

Настоящая логика (перейдёт в следующие фазы без переписывания): нормализация телефона, атрибуция с выбором модели и окна, поиск дублей, двойная валюта с курсом на дату операции, расчёт метрик, рейтинг креативов, правила-сигналы, разбор CSV.

Имитация (в демо-режиме без аккаунта): подключение кабинетов, синхронизация, тексты AI-советов (шаблоны вместо Claude API), чат (ответы на вопросы-подсказки), превью креативов (сгенерированные обложки вместо файлов из Storage), курсы НБРК (сгенерированный ряд).