fb-spend-automation MVP

Input: google doc

goal:

Автоматизировать учет затрат в рекламных кабинетах Facebook. Так же реализовать отчетность по затратам в разрезе медиабаеров.

Glossary

• facebook агентство (Агенство): это компания холдер которая предоставляет нам бизнес аккаунты. Для нас это точка входа в Facebook, через них мы пополняем балансы, выводим балансы, перемещаем балансы между аккаунтами
• facebook бизнес менеджер (БМ): это, собственно говоря, пользователь кабинета БМ внутри Facebook. Каждый агентский аккаунт имеет свой баланс, свои рекламные ассеты и настройки. Внутри него мы запускаем рекламные компании
• баер: пользователь БМ. Мы выдаем БМ конкретным баерам для настройки и запуска рекламы.
• facebook api: в данном документе мы подразумеваем Facebook Marketing API, и доступ к нему через GraphQL ключ.

Userstories

фин отдел

я как финансист хочу понимать:

• сколько у меня есть фейсбук кабинетов, какой у меня остаток баланса на каждом кабинете
• какие заблокированные или не активные кабинеты имеют на данный момент остаток (который нужно забрать)
• какие активные кабинеты имеют маленький остаток баланса (их нужно пополнить)
• хочу иметь возможность руками внести фактический остаток на кабинете (корректировка)

admin

я как администратор системы:

• добавляю в систему новые агентские аккаунты FB
• добавляю в систему новые бизнес аккаунты FB (токен аккаунта, прокси, название и принадлежность)
• проверяю что доступ к аккаунтам сохраняется
• обновляют токены доступов к аккаунтам, в случае если они перестают работать
• редактировать метаинформацию агенств и баеров (контакты и т.п.)

баер

я как баер:

• хочу видеть отчеты по затратам своих кабинетов
• хочу получать уведомления о блокировке моих кабинетов

Entities

Список сущностей в системе:

Agency

Агентство:

• created_at: дата создания (в utc-0)
• updated_at: время редактирования
• contact_email: текстовое поле с е-мейлом
• contact_tg: текстовое поле с tg nickname
• notes: текстовое поле
• status: текущий статус агентства выставляемый в ручную (тест, активно, архив)

bm_account

БМ аккаунт:

• created_at: дата создания (в utc-0)
• updated_at: время редактирования
• agency: какому агентству принадлежит аккаунт
• bmID: ид БМ внутри facebook
• accessToken: токен для запросов к апи фейсбук
• proxy: proxy con string, для подключения к апи
• notes: заметки к аккаунту

Вычисляемые свойства:

• last_sync_at: дата последней актуализации данных
• status: текущий статус кабинета
• buyer: связанный с аккаунтом баер на данный момент

spend

спенды зарегистрированные в системе

• created_at: дата создания записи
• date: дата за которую выгружается спенд (может не совпадать с датой создания для ручных корректировок)
• ba: с каким бизнес аккаунтом связан спенд
• type: тип спенда (initial - начальный, manual - руками, api - полученный через api)
• user: кто выполнил действие, если оно ручное или initial
• amount: сумма спенда
• currency: валюта в которой учитывается спенд

balances

балансы зарегистрированные в системе

• created_at: дата создания записи
• date: дата за которую получен баланс
• ba: с каким бизнес аккаунтом связанна синхронизация баланса
• type: тип баланса (initial - начальный, manual - руками, api - полученный через api)
• user: кто выполнил действие, если оно ручное или initial
• amount: сумма
• currency: валюта баланса

inquires

действия связанные с аккаунтами

• created_at: дата создания записи
• date: дата за которую произошло событие
• type: api, manual
• action: какое событие произошло (block, withdrawal_requested, withdrawal_completed)
• value: сумма заблокированная, сумма запроса на вывод, сумма вывода — зависит от контекста
• user: кто выполнил действие, если оно ручное

currencies

• name: имя валюты
• denomination: фейсбук стремится отдавать валюту во float, что не ок, поэтому мы лучше заведем справочник деноминаций и будем хранить int.

users

• name: имя пользователя
• email: емейл пользователя
• created_at: дата регистрации
• updated_at: дата обновления данных
• role: роль, bayer, admin, fin

bm_users

• created_at: дата привязки
• bm: какой бизнес кабинет
• buyer: к какому баеру привязан
• user: кто выполнит привязку

sync requests

лог всех запросов к апи facebook

• created_at: когда
• bm: какой БМ
• apiKey: какой был использован апи ключ
• proxy: параметры прокси
• url: куда стучались
• payload: что отправляли
• responceStatus: статус код ответа
• responceBody: сам ответ
• errorDescription: описание ошибки, если она была

Важно:

• в процессе использования БМ можем измениться привязанный к нему баер. После смены баера затраты аккаунта старые должны остаться в отчете старого баера, а новые затраты должны попасть в затраты нового баера.
• не понятно как должна вести себя ручная корректировка. Если фин пользователь создал корректировку, а после нее произошла выгрузка из апи - что произойдет.
• не понятно как учитывать пополнения баланса, т.к. при пополнении баланса он может быть потрачен до синхронизации
• как будет производится управление пользователями? Откуда получать список баеров? Как назначать баеру пароль для авторизации в кабинете?

Отчеты

какие отчеты в системе хотелось бы иметь:

bm statuses

spend (с фильтром за период - last 7 days)

inquires status

sync log

todo: дописать примеры отчетов которые еще нужны

Technical decisions

поскольку апи fb может лежать, аккаунтов может быть много и т.п. - реализацию сбора данных предлагается реализовать в виде workflows на temporal

Результат работы workflows мы можем складывать в BQ или PG. Так же в нем удобно реализовать отправку отчетов или алертов (на этапе mvp это out of scope).

Для построения отчетов можем использовать MetaBase.

Все данные внутри таблиц иммутабельные — то есть данные только append only.

Для построения веб интерфейса мы возьмем sveltekit + betterauth для реализации авторизации.

mocks

Рисовать моки тут

Экраны

• авторизация
• сброс пароля
• введение нового пароля
• управление агентствамии
  • список агенств
  • редактирование агентства
  • добавление агентства
• управление БМ
  • список БМ
  • добавление БМ
  • редактирование БМ
• управление пользователями (админ)
  • список пользователей
  • заблокировать пользователя
  • добавить пользователя
    • форма добавления пользователя
• раздел отчеты
  • bm statuses (все пользователи, фильтр по себе для баеров)
  • spend (все пользователи, фильтр по себе для баеров)
  • inquires status (админы, финансисты)
  • sync log (админы)
• управление БМ (админы)
  • список бм с указанием текущего баера
  • форма назначения баера