Своя система аналитики
Практическое руководство для технического аналитика и агента разработки
Посетитель → обращение → лид → сделка → оплата. Поведение на сайте, записи сессий, звонки и рекламные расходы дополняют эту цепочку, а агент отвечает на вопросы по проверяемым данным.
Для кого: вы знаете SQL, понимаете HTTP API и можете с агентом развернуть приложение на сервере.
Результат: собственная система сбора, сверки и анализа данных — от события браузера до подтверждённой оплаты.
Формат: архитектура, учебные контракты, восемь заданий на разработку и проверяемая приёмка. Готового приложения в этом комплекте нет.
Презентация выступления — PDF, 22 слайда
Как читать руководство
| Глава | Что вы в ней найдёте |
|---|---|
| Эта страница | Состав системы, принципы и порядок работ. |
| Данные и интерфейсы | Ключи, сущности, HTTP, файлы записей, деньги и ответы инструментов. |
| Сборка и эксплуатация | Подготовку, восемь заданий агенту, первый запуск и обслуживание. |
| Приёмка | Контрольный набор, SQL-проверки, тесты отказов и критерии готовности. |
Сначала прочитайте обзор и контракты. Затем передавайте агенту по одному этапу из главы о сборке и принимайте его по контрольным примерам. Передавайте весь комплект: отдельная страница не заменяет остальные главы.
Все имена, адреса, идентификаторы и суммы в примерах вымышлены. Названия технологий обозначают предлагаемый стек; они не описывают инфраструктуру или текущее состояние какого-либо частного проекта.
1. Что строим
Система должна отвечать на пять практических вопросов:
- Что посетитель сделал до обращения и сохранилась ли запись сессии?
- Принял ли сайт форму и появился ли соответствующий лид в CRM?
- С каким обращением или посетителем связан звонок и на каком основании?
- Какие сделки и оплаты найдены, какие суммы остались без связи?
- Насколько свежи и полны данные, на которых основан ответ агента?
«Лид создан», «сделка успешна» и «деньги получены» — разные факты. Отдельно определите выручку: это бизнес-показатель, который нельзя автоматически приравнивать к сумме сделок или оплат.
Общая схема
Browser ---- events / form copy ----> Receiver ----> PostgreSQL: raw
Site server ---- form result ------> Receiver ----------^
External APIs ---> Connectors --------------------------^
Browser ---- rrweb batches --------> Durable buffer ---> S3 + catalog
|
raw + files ---> Parse / Fold
|
Entities + Relations
| |
SQL views Neo4j
+-------+-------+
|
Read tools ---> Agent
Site server ---- normal delivery --------------------> CRM
(independent of analytics)
Аналитика получает копии и результаты. Штатная форма и доставка в CRM продолжают работать при недоступности аналитики. Приёмник сохраняет данные быстро; сетевые загрузки, разбор DOM и отчёты выполняются отдельно.
Базовый стек
| Компонент | Предлагаемый инструмент | Назначение |
|---|---|---|
| HTTP-приёмник | Python, FastAPI, psycopg | Проверка доступа, сохранение конвертов и подтверждение приёма. |
| Основное хранилище | PostgreSQL, JSONB | Сырьё, типизированные сущности, отношения, курсоры и SQL-витрины. |
| Загрузчики и фоновые задачи | Python | Опрос API, разбор, сверка, пересчёт и история запусков. |
| Запись поведения | rrweb | Снимки DOM и изменения для воспроизведения сессии. |
| Файлы записей | NDJSON, zstd, закрытый S3 | Потоковый архив; в PostgreSQL остаётся каталог файлов. |
| Плеер | Совместимый rrweb-player | Просмотр записей через защищённый интерфейс. |
| Граф | Neo4j | Поиск и объяснение путей между подготовленными сущностями. |
| Инструменты агента | Ограниченные SQL/граф-инструменты, например MCP | Чтение данных с лимитами, происхождением и признаками неполноты. |
| Развёртывание | Docker Compose, Caddy, планировщик | Повторяемый запуск, HTTPS, фоновые задания и наблюдение. |
Стек можно заменить, сохранив контракты. Для пилота достаточно одного приложения с отдельными командами и ролями; отдельный сервис на каждую операцию не нужен. PostgreSQL остаётся источником подготовленных данных, граф — восстанавливаемой проекцией. Начните без отдельного брокера: очередью событий может служить таблица сырья.
Версии библиотек, образы и методы API агент проверяет по официальной документации при реализации и фиксирует в зависимостях. Таблица не задаёт готовый совместимый набор версий.
2. Принципы, от которых зависит результат
| Принцип | Следствие для собственной реализации |
|---|---|
| Сначала разрешённое сырьё, затем преобразования | Сохраняйте принятый очищенный конверт и ссылку на него из сущности. Чувствительные значения удаляйте до передачи. |
| Повторная доставка безопасна | ID создаётся один раз; уникальные ключи и транзакции предотвращают дубли. |
| Три точки обращения | Копия браузера, итог сайта и объект CRM сверяются независимо. |
| Любая связь объяснима | Хранятся основание, уверенность, версия правила и ссылки на источники. |
| Пробелы видимы | Отсутствующий источник, устаревший опрос, неоднозначная связь и нулевой результат различаются. |
| Деньги сверяются до атрибуции | Общая сумма платежей не меняется из-за присоединения расходов, звонков или обращений. |
| Производные данные пересобираются | События записи, текст, отношения, витрины и граф имеют версию и перечень входов. |
| Агент получает ограниченное чтение | Права задаются в хранилище; инструмент сообщает свежесть, покрытие и усечение. |
Точные правила поиска совпадений, сроки ожидания и параметры нагрузочных лимитов выбирает владелец собственной системы. Они должны быть записаны в конфигурации и проверены на своих данных. В пилоте опирайтесь на явные ID; спорные совпадения оставляйте кандидатами.
3. Маршрут сборки
Подготовка предшествует всем этапам. Базу, роли, миграции и постоянные тома поднимите до первого события. Этап 8 завершает эксплуатационную готовность, а не откладывает инфраструктуру на конец.
Preparation -> 1. Events -> 2. Recordings -> 3. Forms + CRM
|
4. Calls -> 5. Money -> 6. Graph
|
7. Agent
|
8. Operations
|
End-to-end check
| Этап | Контрольный результат |
|---|---|
| Подготовка | Спецификация пилота, имитации источников, окружение и миграции. |
| 1. События | Одно событие проходит от браузера до SQL; повтор не удваивает его. |
| 2. Записи | Сессия воспроизводится; действия и текст связаны с файлами. |
| 3. Формы и CRM | Одно обращение прослеживается по трём точкам. |
| 4. Звонки | Звонок загружен; связь с посетителем подтверждена либо отсутствует явно. |
| 5. Деньги | Оплаты и расходы сходятся с источниками; несвязанные суммы видны. |
| 6. Граф | Путь до оплаты объясним и совпадает с контрольным SQL. |
| 7. Агент | Ответ подтверждён данными и сообщает ограничения. |
| 8. Эксплуатация | Запуск, наблюдение, резервирование и восстановление проверены. |
Сначала пройдите маршрут с имитациями API. Затем заменяйте их реальными адаптерами по одному и повторяйте приёмку. Если источник недоступен, показывайте «не подключён»; нулевые расходы или оплаты из этого не следуют.
4. Что передать агенту перед началом
Скопируйте задание вместе с тремя главами:
Собери собственную систему по этому комплекту документации. Сначала подготовь спецификацию пилота и карту доступных источников. Зафиксируй свои решения о версиях, полях, нагрузке и сроках хранения. Реализуй этапы последовательно, сначала на синтетических данных. После каждого этапа покажи миграции, контракты, команду проверки и её фактический результат. Не считай имитацию API проверенной интеграцией. Не заменяй отсутствующие данные нулём и не придумывай связи. Не переноси реальные контакты, секреты и инфраструктурные реквизиты в документацию, фикстуры или журналы. Запись в CRM не входит в задачу.
Названия файлов, таблиц и маршрутов далее — согласованный учебный контракт для создаваемой реализации. Их можно изменить совместно, обновив все зависимые части и проверки.
Далее: Данные и интерфейсы →
Данные и интерфейсы
Назначение главы: определить, что передают друг другу компоненты. Это учебный контракт собственной реализации, а не копия схемы частного проекта.
В этой главе: ключи · хранилище · HTTP · записи · источники · деньги · инструменты
1. Идентификаторы и время
| Идентификатор | Область уникальности и смысл |
|---|---|
site | Сайт в своей системе. Приёмник определяет его по ключу доступа. |
source | Система и аккаунт источника: например, crm_demo или finance_demo. |
visitor_id | Браузер в области cookie. Это не подтверждённый человек и не сквозной ID всех устройств. |
session_id | Сессия внутри сайта; объединяет события, формы и записи. |
stream_id | Отдельный поток страницы или вкладки внутри сессии; устраняет коллизии локальной нумерации. |
request_id | Одно обращение. Передаётся в форме, серверном результате и отдельном поле CRM. |
msg_id | Одно сообщение. Создаётся до отправки и сохраняется при повторах. |
batch_id | Одна неизменяемая пачка записи; сохраняется при повторной доставке. |
| Внешний ID | ID объекта вместе с source; одинаковые номера разных аккаунтов не склеиваются. |
Внутренние ID создавайте устойчивым генератором, например UUID.
request_id не равен msg_id: одно обращение порождает несколько сообщений.
Новое самостоятельное обращение получает новый request_id; повтор доставки
прежней попытки сохраняет старый. Сервер валидирует ID и при необходимости
выдаёт его сам, возвращая фактическое значение в ответе формы.
Для собственной реализации зафиксируйте правила начала/окончания сессии,
совместного использования ID вкладками и работы без хранилища браузера.
При отказе cookie допускается visitor_id = NULL, при невозможности
сохранить сессию — новая локальная сессия с признаком ограниченного покрытия.
Пустой ID можно дополнить; два разных непустых ID нельзя молча заменить
один другим. Независимые домены не получают общую cookie автоматически.
Время: client_ts — действие в браузере, sent_at — первая отправка,
received_at — приём сервером, modified_at — изменение внешнего объекта.
Храните их раздельно как время с часовым поясом; для обмена используйте UTC.
В отчётах задавайте часовой пояс и полуоткрытый интервал [from, to).
Порядок внутри потока уточняет seq; несколько вкладок не образуют
идеально упорядоченную единую шкалу. Сроки серверной доставки нельзя
измерять только по часам браузера.
2. Слои и сущности
Три слоя хранения
| Слой | Содержимое | Обязательная трассировка |
|---|---|---|
| Сырьё | Разрешённый очищенный JSON, метаданные приёма, версии внешних объектов. | Источник, ключ сообщения/объекта, время, версия формата и состояние разбора. |
| Сущности | Типизированные события, обращения, лиды, звонки, сделки, оплаты и расходы. | Ссылка на сырьё и версия преобразования. |
| Производные данные | Свёртка записи, текст, отношения, граф и витрины. | Версия построения, входные объекты/файлы и отметка актуальности. |
Сырьё означает «то, что разрешено принять», а не полную копию всех полей. До передачи удаляйте секреты, значения ввода и лишние контакты; применяйте списки разрешённых параметров URL, свойств событий и полей форм. Загрузчики очищают ответы внешних API до сохранения в сырьё. Сохраняйте исходный очищенный URL рядом с нормализованным. Fragment, query, заголовки, текст DOM и сообщения ошибок тоже могут содержать данные.
Минимальная логическая модель
? обозначает необязательное поле. Стрелки и ключи связи не обещают 1:1.
| Сущность | Ключ | Поля и назначение |
|---|---|---|
session | (site, session_id) | visitor_id?, начало/последнее действие, очищенный входной URL и метки источника. |
event | (site, event_id) | session_id, stream_id, seq, name, client_ts, raw_id. |
request | (site, request_id) | session_id?, form_id, ссылки на копию и серверные результаты. |
crm_lead | (source, lead_id) | site?, request_id?, modified_at, raw_id. |
call | (source, call_id) | Время, результат, мосты посетителя/CRM при наличии, raw_id. |
deal | (source, deal_id) | Стадия, сумма, валюта, время изменения, ссылка на сырьё. |
payment | (source, payment_id) | deal_source?, deal_id?, paid_at, amount, currency, status. |
cost | (source, report_key, day, channel_key, currency) | Сумма выбранного отчёта; report_key фиксирует фильтры, измерения и часовой пояс. |
relation | Устойчивый ключ типа и обоих концов | Ключи сущностей с их областями, основание, уверенность и версия правила. |
Лиды и сделки могут относиться к разным обращениям; храните такие переходы
в relation, а не одним полем, которое теряет остальные связи.
У оплаты из учётной системы source может отличаться от CRM: для связи
со сделкой нужны оба поля deal_source и deal_id либо отдельное
объяснимое отношение. Одного номера сделки недостаточно.
(site, visitor_id) -> (site, session_id) -> (site, request_id)
| |
events + files (source, lead_id)
| |
(source, call_id) (source, deal_id)
|
(source, payment_id)
У сущностей есть собственные строки даже без найденного соседа. Не теряйте
непривязанные оплаты и звонки из-за INNER JOIN. При допустимой задержке
загрузки сохраняйте внешний ключ источника как факт и проверяйте отсутствие
соседа отдельным аудитом; подтверждённое отношение строится после появления
обоих концов.
Служебные данные
| Реестр | Минимально необходимые сведения |
|---|---|
| Сайты и ключи | Сайт, разрешённые Origin/виды сообщений, статус ключа; серверные секреты отдельно. |
| Входящие сообщения | Уникальность (site, kind, msg_id), очищенное тело, new/ok/failed, версия/ошибка разбора. |
| Внешние версии | Источник, вид объекта, внешний ID, версия/хеш содержимого, время приёма. |
| Файлы записей | Сайт, сессия, ключ S3, размер, SHA-256, диапазоны потоков, полнота и срок хранения. |
| Запуски и курсоры | Источник/задача, область окна, начало/конец, статус, счётчики, последний полный курсор. |
| Производные результаты | Версия, перечень входов, время построения, признаки устаревания и неполноты. |
Неизвестная версия формата остаётся в сырье со статусом ошибки разбора; синтаксически неверный JSON не считается принятым и отражается в отказе.
3. Приём событий и форм
Маршруты и доступ
| Маршрут | Вход / выход | Граница доступа |
|---|---|---|
POST /v1/inbox | Массив сообщений event, form_copy, form_result; результат по каждому элементу. | Браузерный ключ: первые два вида; серверный секрет: form_result. |
POST /v1/rec | Одна пачка записи; accepted или duplicate. | Ключ сайта, допустимый Origin и включённый флаг записи. |
GET /v1/flags | Разрешение записи и версия публичной конфигурации. | Ключ сайта и Origin; без секретов и внутренних правил. |
GET /health | Доступность приёмника. | Без клиентских данных; подробная свежесть задач доступна служебной роли. |
POST /v1/call-hook | Уведомление телефонии. | Отдельная проверка подлинности по контракту поставщика. |
Для учебной реализации используйте Authorization: Bearer <ключ>.
Ключ выбирает site; поле сайта в теле не позволяет изменить эту область.
Поддержите браузерный OPTIONS, точный список Origin и нужных заголовков.
Серверный запрос проверяется отдельным секретом и не требует Origin.
Браузерный ключ публичен. CORS и Origin не доказывают подлинность посетителя вне браузера. Нужны ограничения частоты, объёма, распаковки и наблюдение за мусорным трафиком. Браузерные сообщения сами по себе не подтверждают принятие формы или платёж.
Тело запроса с одним событием
[
{
"v": 1,
"kind": "event",
"msg_id": "ev_demo_01",
"session_id": "s1",
"visitor_id": "v1",
"stream_id": "tab1_page1",
"seq": 1,
"name": "page_view",
"url": "https://www.example.com/prices",
"ts": "2026-11-16T10:00:00Z",
"sent_at": "2026-11-16T10:00:01Z"
}
]
В этой модели msg_id события становится event_id, ts — client_ts.
received_at и site добавляет сервер. Версия и kind выбирают разбор.
Конверт после первой отправки неизменяем; повтор с тем же ключом и другим
содержимым — конфликт, а не обновление старого действия.
Для всех видов нужны v, kind, msg_id, ts, sent_at.
Дополнительные поля:
| Вид | Обязательные поля | Необязательные сведения |
|---|---|---|
event | session_id, stream_id, seq, name, url. | visitor_id, разрешённые свойства. |
form_copy | request_id, form_id, url. | session_id, visitor_id, разрешённые поля без контактов в учебном варианте. |
form_result | request_id, form_id, result: accepted или rejected. | Машинная причина отказа без значений полей. |
Каждая копия и каждый серверный результат имеют собственный msg_id.
История этих фактов сохраняется; сводная строка request не заменяет её.
accepted означает решение обработчика сайта, а не создание лида CRM.
Подтверждение и повтор
Пример ответа на пачку из трёх элементов: новый, повторный и неверный. Индексы начинаются с нуля.
{
"accepted": [0],
"duplicate": [1],
"rejected": [{"i": 2, "error": "bad_envelope"}]
}
Каждый входной индекс появляется ровно в одном списке. Подтверждение
accepted выдаётся только после надёжного сохранения сырья.
При разборе сущность и статус ok меняются одной транзакцией.
receive -> validate -> commit raw(new) -> acknowledge
|
parse -> commit entities + raw(ok)
|
+----> raw(failed, reason)
| Ответ | Действие отправителя |
|---|---|
200 | Прочитать поэлементный результат. Удалить из outbox только принятые и повторы; постоянные отказы отделить. |
400/401/403/415 | Исправить данные, доступ или формат; не повторять бесконечно. |
413 | Уменьшить пачку, сохранив ID элементов. Слишком большой одиночный элемент пометить отказом. |
429/503, обрыв сети или потеря ответа | Повторить неподтверждённые сообщения с прежними ID, паузой и ограниченным возрастом очереди. |
Если все элементы отклонены, верните 400 с тем же форматом ошибок.
На повтор с изменённым телом верните поэлементный id_conflict;
для отдельной пачки записи — 409. Ограничения очереди и число
отброшенных сообщений видимы в диагностике. Наличие ID сессии в
localStorage не заменяет outbox сообщений.
4. Контракт записи поведения
Пачка содержит v, session_id, stream_id, batch_id, диапазон
seq_from/seq_to, события rrweb и признаки усечения. Порядок и дедупликация
внутри потока опираются на (stream_id, seq), не на порядок HTTP-запросов.
Приёмник проверяет совпадение диапазона с содержимым. Ключ повтора пачки —
(site, session_id, batch_id), ключ события записи —
(site, session_id, stream_id, seq). Трекер и рекордер ведут отдельные
последовательности: их номера не смешиваются между типами данных.
Для каждого потока нужны начальный полный снимок DOM и последующие изменения. Дублирующие записи одинакового ключа должны совпадать; конфликт отмечается, а не выбирается произвольно.
batch -> durable local buffer -> immutable compressed file -> S3
| |
+---- register <----+
|
verify -> remove local copy
catalog + main + late files -> player / fold -> events + text
| Артефакт | Контракт готовности |
|---|---|
| Буфер | Подтверждённые пачки переживают перезапуск процесса и контейнера; повтор безопасен. |
| Архив | Версия формата, ID сессии/потоков, события, диапазоны, пропуски и контрольная сумма. |
| Каталог | Файл зарегистрирован после проверки загрузки; ключ и SHA-256 позволяют безопасно повторить шаг. |
| Плеер | Проверяет доступ, размер и распаковку; показывает пропуски, отсутствие снимка и усечение. |
| Свёртка | Время, поток, вид действия, очищенный URL и разрешённое имя элемента; ссылка на файл/позицию. |
| Текст сессии | Объяснимая последовательность производных событий, версия и перечень входных файлов. |
Файл и БД не образуют общую транзакцию. Проверьте сбой между записью буфера и отметкой приёма, а также между S3 и регистрацией каталога. Повтор должен завершить операцию без потери единственной копии. Поздние данные создают отдельный неизменяемый файл и помечают прежнюю свёртку устаревшей. События и текст нового поколения публикуются согласованно.
Маскируйте чувствительные узлы, атрибуты и ввод до записи. Свёртка не восстанавливает введённые значения. Тип и длину ввода сохраняйте, только если выбранный безопасный формат позволяет их получить. Ошибки JavaScript требуют отдельного обработчика и очистки; сам факт подключения rrweb не гарантирует их сбор.
Запись DOM — не видео. Ресурсы страницы могут измениться; для длительного хранения нужно разрешённое архивирование ресурсов или явно ограниченная гарантия воспроизведения. Плеер изолируйте от основного приложения: скрипты записи и внешние ресурсы не должны получать его привилегии.
5. Внешние источники и связи
Для каждого адаптера создайте карту полей: внешний путь → учебное поле, тип, необязательность и преобразование. Начальная загрузка охватывает явный исторический период; последующие — изменения с пагинацией. Если API не даёт надёжной метки изменения, адаптер использует повторные окна/сверочные снимки и объявляет ограничение покрытия.
last cursor -> bounded window -> all pages -> raw versions -> entities
|
commit cursor
failure before completion -> retain old complete cursor -> repeat
Курсор продвигается только за полностью сохранённое и обработанное окно. Повтор окна не создаёт неизменённых версий. Нужны повторная загрузка изменяемой истории и политика удалений: частичная выборка или отказ в правах не доказывают, что все отсутствующие объекты удалены.
Метаданные отношения
| Поле | Смысл |
|---|---|
type, from, to | Тип связи и полные ключи обоих концов с сайтом/источником. |
basis | Объяснение: явный request_id, внешний CRM-переход, мост поставщика или кандидатное совпадение. |
confidence | confirmed, candidate или ambiguous; это категории, не вычисленная вероятность. |
rule_version | Версия правила своей реализации. |
built_at, provenance | Время и ссылки на исходные строки/версии. |
Несколько подходящих соседей не превращаются автоматически в один подтверждённый. Телефон или близкое время сами по себе не гарантируют идентичность посетителя. Подтверждённые пути и кандидатные гипотезы разделяйте в витринах и ответах агента.
6. Денежные витрины
| Набор | Одна строка означает | Контроль |
|---|---|---|
| Сделки | Актуальное состояние одной сделки в одном источнике. | Сумма и стадия не подменяют оплату. |
| Платежи | Одно денежное движение с устойчивым ID и статусом. | Связь с CRM не меняет общую сумму; неизвестная сделка допустима. |
| Расходы | Одну строку выбранного отчёта за день, канал и валюту. | Не суммировать пересекающиеся отчёты по каналам и кампаниям. |
| Атрибуция | Распределение выбранной метрики по каналам. | Сумма распределённых и нераспределённых денег равна контрольному итогу. |
Для учебного набора amount — decimal, валюта обязательна;
в JSON суммы передаются строками. Учитываются только движения settled.
Оплата положительна, возврат — отдельное отрицательное движение;
отменённое движение не входит в итог. Реальные статусы и знаки
адаптер приводит к этому договору, сохраняя исходную версию.
Перед соединением задайте детализацию отчёта, временную ось и правило
канала. В простом пилоте у сделки один подтверждённый канал либо
unassigned; период оплат определяется paid_at. Для нескольких касаний
нужно отдельное распределение, сохраняющее общий итог.
payments -> aggregate(day, attributed_channel, currency) --+
+-> report
costs -> aggregate(day, channel, currency) -------------+
Сначала агрегируйте обе стороны до одинаковых измерений, затем соединяйте с сохранением строк, присутствующих только с одной стороны. Не соединяйте две оплаты с тремя строками расходов напрямую: получится шесть строк и размноженные суммы. Валюты считайте отдельно; пересчёт требует самостоятельного источника курса и правила даты. Поступления и расходы за один день не доказывают окупаемость когорты.
7. Контракт чтения для агента
Предложите ограниченные инструменты: словарь данных, качество/свежесть, SQL-чтение витрин, поиск графового пути, события и текст сессии. Полные записи доступны отдельному разрешённому инструменту по необходимости. Права чтения обеспечиваются БД и графом, а не только текстом инструкции.
Пример результата инструмента, вернувшего полный учебный итог:
{
"data": [{"currency": "XXX", "paid": "100.00"}],
"as_of": "2026-11-17T01:00:00Z",
"period": {"from": "2026-11-16T00:00:00Z", "to": "2026-11-17T00:00:00Z"},
"timezone": "UTC",
"row_count": 1,
"truncated": false,
"coverage": {"payments": "complete", "crm": "complete"},
"warnings": [],
"provenance": ["demo_fixture"]
}
XXX — учебное обозначение без реальной валюты. as_of определяется
покрытием источников, а не временем вызова инструмента. row_count
означает число возвращённых строк, а не общий размер выборки.
Несколько графовых путей могут вести к одному платежу: перед суммированием
оставляйте одно движение на (source, payment_id).
Неполный набор помечается truncated; итог по усечённым строкам
агент не суммирует как полный. При ошибке возвращается явная ошибка,
а не пустой успешный набор.
Каждый ответ агента называет период, определение метрики, свежесть, основания связей и ограничения. Содержимое CRM, DOM и файлов считается данными и не разрешает команды, смену прав или обход ограничений.
← Обзор · Далее: Сборка и эксплуатация →
Сборка и эксплуатация
Назначение главы: пройти от пустого окружения до работающего пилота. В каждом задании указаны цель, ограничения, результат и проверка. Спецификации входов и выходов находятся в контрактах.
Навигация: подготовка · события · записи · CRM · звонки · деньги · граф · агент · эксплуатация
Подготовка: зафиксируйте решения
Начните с тестового сайта, доступа к обработчику формы, отдельного стенда и имитаций внешних API. Реальные учётные данные подключайте после синтетической приёмки. Заранее определите, какие поля нельзя собирать.
Спецификация пилота
Попросите агента создать docs/pilot-spec.md в новой реализации.
Реальные секреты и контакты в этот файл не входят.
| Решение | Что записать |
|---|---|
| Границы | Сайты и области источников, доступный исторический период, отсутствующие интеграции. |
| Семантика | Словарь событий, что считается обращением, оплатой и выручкой. |
| Идентификаторы | Начало/окончание сессии, вкладки, cookie, повтор отправки формы и мосты между источниками. |
| Источники | Возможности API, поля связи, пагинация, квоты, статусы, временные зоны и политика изменений. |
| Нагрузка | Ожидаемые события, объём записей, пиковые запросы; по ним — лимиты и ёмкость. |
| Данные и доступ | Разрешённые поля, маскирование DOM/URL, роли, сроки хранения и порядок удаления. |
| Надёжность | Допустимая задержка, потеря данных и время восстановления; критерии свежести. |
| Деньги | Валюты, знаки возвратов, период отчёта, детализация расходов и пилотная атрибуция. |
Если владелец ещё не выбрал бизнес-правило, агент выделяет его как открытое решение. Пилот может работать с документированным учебным вариантом; реальный отчёт не должен молча наследовать этот вариант.
Структура создаваемого проекта
analytics/
+-- browser/ # tracker, outbox, recorder
+-- app/
| +-- receiver/ # HTTP, access, validation
| +-- parsers/ # raw -> entities
| +-- connectors/ # source adapters + cursors
| +-- recordings/ # close, fold, player
| +-- relations/ # evidence + graph projection
| `-- tools/ # restricted reads for agent
+-- sql/
| +-- migrations/
| `-- views/
+-- tests/
| +-- fixtures/
| +-- integration/
| `-- acceptance/
+-- deploy/ # compose.yml, .env.example, proxy
`-- docs/ # pilot-spec, contracts, runbook
До этапа 1 создайте PostgreSQL, роли, миграции, тома БД/буфера и базовый Compose. Служебный запуск миграций отделите от приложения. Это минимальная инфраструктура для всего дальнейшего маршрута.
Этап 1. Браузер, приёмник и разбор
Вход: спецификация пилота и конверты из главы о контрактах.
Выход для следующих этапов: raw, session, event, доставка и диагностика.
Начните с page_view и явного события формы. Для каждого имени задайте
конкретный триггер: попытка отправки не становится автоматически успехом.
Скрипт должен запускаться один раз; переход внутри SPA учитывается
отдельно от первой загрузки страницы.
Событие сначала попадает в ограниченный outbox, затем отправляется. Клиент читает ответ по каждому элементу. Уход со страницы — лишь попытка дослать хвост, а не гарантия доставки. Сбой аналитики не блокирует сайт. При отсутствии разрешения на сбор скрипт не создаёт очередь скрытно.
action -> stable ID -> outbox -> send -> response per item
^ |
+---- retry -------+
remove only acknowledged items
Разборщик выбирает необработанные строки с блокировкой, превращает их в сущности и фиксирует результат транзакцией. Ошибка одной строки не останавливает весь поток. Переразбор имеет версию и не размножает события.
| Задание агенту | Требование |
|---|---|
| Цель | Реализуй миграции, скрипт, outbox, приёмник и разбор page_view и события формы. |
| Ограничения | Разные права приёма/разбора; лимиты тела и распаковки; неизменяемые ID; без ожидания аналитики в форме. |
| Результат | OpenAPI/JSON-схемы, примеры запросов/ответов, связанные строки сырья и сущностей, счётчики отказов/очереди. |
| Проверка | Повтор, потерянный ответ, смешанная пачка, конфликт ID, две вкладки, запрет хранения и остановка разборщика. Число действий не растёт от повторов. |
Этап 2. Записи, плеер и свёртка
Зависит от: сессий, доступа и устойчивой доставки этапа 1. Выход: файлы, каталог, воспроизведение, события и текст сессии.
Запускайте рекордер по флагам сайта и правилам разрешённого сбора.
Сначала проверьте маскирование на тестовых секретах в DOM, атрибутах,
URL и вводе. Не ограничивайтесь полями с типом password.
Пачки и локальный буфер имеют ограничения размера/возраста. Задача закрытия создаёт неизменяемые файлы, проверяет S3 и регистрирует каталог. До этого единственная локальная копия не удаляется. Исчерпание диска даёт видимую ошибку и неполноту, а не успешное подтверждение потери.
Плеер объединяет основной и поздние файлы по контракту потоков. Свёртка строит клики, прокрутку и разрешённые имена элементов; неизвестный элемент остаётся неизвестным. События и текст связываются с файлами. Поздняя пачка требует нового поколения свёртки.
| Задание агенту | Требование |
|---|---|
| Цель | Собери рекордер, файловый поток, защищённый плеер и детерминированную свёртку. |
| Ограничения | Маскирование до отправки; закрытый бакет; лимиты памяти/распаковки; без исполнения кода записанной страницы с правами плеера. |
| Результат | Запись контрольной сессии, каталог, события и текст с версиями и признаками полноты; документированный формат архива. |
| Проверка | Две страницы и вкладки, пропуск, поздняя пачка, отсутствие снимка, отказ S3 и падение между файлом и БД. Тестовые секреты отсутствуют во всех артефактах. |
Этап 3. Формы и CRM
Зависит от: этапа 1. Запись поведения дополняет сверку, но не является обязательным доказательством доставки формы.
Browser ---- request_id=r1 ----> Site server ----> CRM
| | |
+-- form_copy | |
form_result <---+ |
CRM poll <-------+
Analytics: (site, request_id) -> copy + result + lead + evidence
Встройте request_id в штатную отправку, проверьте сервером и передайте
в отдельное поле CRM. Для нескольких сайтов CRM также должна различать
сайт или иметь однозначную карту источника; одного клиентского ID мало.
Серверный результат отправляется независимо с сохранением неподтверждённых
сообщений. Отказ аналитики не отменяет успешное действие сайта.
Загрузчик сохраняет версии лидов, затем строит нормализованные строки. Для каждой карты полей документируйте типы и отсутствие значений. Проверьте создание пользовательских полей и их перенос при конвертации лида в сделку на выбранной CRM; это не универсальное поведение API.
Карточка обращения показывает факты и качество наблюдения раздельно:
| Что видно | Корректная интерпретация |
|---|---|
Итог сайта accepted, лид найден по явному ключу | Доставка подтверждена в рамках этого основания. |
Итог rejected, лида нет | Отказ обработчика формы, а не потеря принятого обращения. |
| Лид пока не найден | До проверки покрытия и выбранного срока ожидания вывод откладывается. |
| Опрос CRM просрочен или окно не покрыто | Данных для вывода недостаточно, независимо от времени ожидания. |
| Найдено несколько кандидатов или факты противоречат друг другу | Нужна диагностика; подтверждённая связь не назначается произвольно. |
Это смысл состояний, а не подробный алгоритм сопоставления. Точные условия и сроки выбираются в собственной реализации.
| Задание агенту | Требование |
|---|---|
| Цель | Реализуй две точки формы, карту CRM, загрузчик с курсором и карточку трёх точек. |
| Ограничения | Серверный секрет только на сервере; аналитическое чтение CRM отделено от штатной записи; сверка не создаёт лиды автоматически. |
| Результат | По request_id видны копия, решение сайта, лид, основания связей и покрытие опроса. |
| Проверка | Принятие/отказ формы, потеря копии, задержка CRM, сбой страницы API, два сайта, изменение лида и повтор окна. |
Этап 4. Звонки
Вход: вебхук и/или API телефонии, карта аккаунтов и объектов сайта. Выход: история звонков, контроль покрытия и объяснимые отношения.
Вебхук даёт оперативное уведомление, API — историю и контроль пропусков, если эти возможности доступны у поставщика. Заранее проверьте тариф, доступный период истории, типы ID и возможность передать свой параметр. Уведомление и строка истории одного звонка не должны стать двумя звонками.
Если виджет поддерживает visitor_id, передайте его до звонка и
проверьте возврат в API. Учитывайте сайт, источник и контекст времени.
Общий телефон даёт кандидатов; без надёжного моста связь может остаться
неподтверждённой. Если сервис предоставляет только один канал получения,
объявите это ограничением покрытия.
| Задание агенту | Требование |
|---|---|
| Цель | Подключи доступные каналы, нормализуй звонки и подготовь контроль покрытия. |
| Ограничения | Проверка подлинности вебхука; повторы безопасны; контакты и секреты исключены из журналов; аудио требует отдельного решения. |
| Результат | Звонки с исходными версиями, карта мостов и явные подтверждённые/кандидатные связи. |
| Проверка | Контрольный звонок, повтор, пропущенный вебхук, несовпадающие типы ID и звонок без моста к посетителю. |
Этап 5. Сделки, оплаты и расходы
Зависит от: модели источников, CRM и словаря денежных показателей. Выход: денежные сущности, витрины и сверка до/после атрибуции.
Получите сделки и явные переходы из лидов, движения платежей и выбранный отчёт расходов. Если оплаты приходят из другой системы, создайте карту её ключей к CRM. Не восстанавливайте платёж из стадии сделки.
История может измениться задним числом: загрузчики должны уметь повторить заданный период и отличить исправление версии от нового движения. Выберите один непересекающийся отчёт расходов для итогов; детализации по кампаниям не добавляются к уже включённому итогу канала.
Сначала сверяйте суммы с каждым источником по одинаковым фильтрам,
валютам и временному поясу. Затем применяйте атрибуцию из спецификации.
Включайте unassigned и оплату без найденной сделки в контрольные суммы.
| Задание агенту | Требование |
|---|---|
| Цель | Подготовь сделки, платежи, расходы и витрины с явной детализацией и словарём показателей. |
| Ограничения | Decimal; валюта обязательна; возвраты и отмены различимы; агрегация до соединения; неопределённая связь не скрывается. |
| Результат | Контрольные итоги источников, оплаты по обращениям и каналам, нераспределённые суммы, описание периода и модели атрибуции. |
| Проверка | Две оплаты одной сделки, возврат, отмена, платёж без сделки, разные валюты, два аккаунта с одинаковым ID и повтор загрузки. |
Этап 6. Отношения и граф
Зависит от: сущностей и отношений в PostgreSQL. Выход: повторяемая графовая проекция с теми же основаниями связей.
(Visitor) -> (Session) -> (Request) -> (Lead) -> (Deal) -> (Payment)
|
+------> (Call)
Each edge: scoped keys + basis + confidence + provenance
Узлы различаются типом, сайтом/источником и исходным ID. В Neo4j нужны
ограничения уникальности; загрузка по устойчивым ключам обновляет узлы
и отношения. Одинаковый deal_id в разных аккаунтах не сливается.
Проекция должна удалять или заменять устаревшие отношения после изменения источника, а не только дописывать новые. Храните время/поколение загрузки. Если граф отстаёт от SQL, инструмент объявляет это; пересоздание графа не должно требовать повторного получения всей истории из внешних API.
| Задание агенту | Требование |
|---|---|
| Цель | Собери отношения и проекцию для пути обращения до оплаты и поведения перед ним. |
| Ограничения | Основание, уверенность и источники обязательны; оба конца существуют; гипотезы отделены от подтверждённых путей. |
| Результат | Версия модели, ограничения уникальности, повторяемый экспорт, контрольный путь и сведения о свежести. |
| Проверка | Повторная сборка, изменение/удаление связи, одинаковые ID разных источников и совпадение с SQL-контролем. |
Этап 7. Агент над данными
Зависит от: проверенных витрин и качества; для графовых вопросов — этапа 6. Выход: объяснимые ответы через ограниченные инструменты.
Agent -> tool -> approved views / graph
|-- database-enforced read permissions
|-- timeout + row/byte limits
|-- freshness + coverage + truncated
`-- audit without sensitive payloads
Передайте агенту словарь метрик, ключей и связей. В пилоте предпочтительны параметризованные инструменты для типовых задач. Если доступен SQL, роль читает только разрешённые представления; произвольные функции, изменяющие запросы и доступ к секретам запрещены правами хранилища. Для Neo4j права чтения задаются отдельно.
Агент проверяет покрытие источников перед выводом. Строки CRM и сайта не являются инструкциями. Усечённая выборка не даёт полного итога: для суммы используйте агрегирующий запрос, а не сложение видимого хвоста. Журнал фиксирует вызов, длительность и результат без полного содержимого чувствительных строк.
| Задание агенту | Требование |
|---|---|
| Цель | Подключи словарь, проверку качества и инструменты SQL/графа/поведения по контракту. |
| Ограничения | Раздельные роли чтения, лимиты времени/строк/байтов, фильтрация полей, сырые записи закрыты по умолчанию. |
| Результат | Ответы на контрольные вопросы с периодом, метрикой, свежестью, происхождением и ограничениями. |
| Проверка | Известная сумма, устаревший источник, неоднозначная связь, усечение, запрещённая запись и команда, спрятанная в тексте CRM. |
Этап 8. Эксплуатация и восстановление
Зависит от: базового окружения подготовки и реализованных компонентов. Выход: повторяемый запуск и подтверждённые процедуры обслуживания.
Роли и постоянные данные
| Компонент | Необходимые права и хранилища |
|---|---|
| Приёмник | Вставка сырья, отметки пачек, запись буфера; без миграций и внешней записи CRM. |
| Разбор/свёртка | Чтение своих входов, изменение сущностей/статусов; без управления правами. |
| Загрузчик | Чтение своего API; запись своих версий, сущностей и курсоров. |
| Экспорт графа | Чтение подготовленных сущностей/отношений, запись проекции. |
| Плеер | Разрешённые данные сессии и чтение закрытого S3; изолированное воспроизведение. |
| Инструменты агента | Чтение утверждённых витрин и графа; без изменения данных и схемы. |
| Миграции | Отдельная роль владельца и отдельный управляемый запуск. |
Постоянные тома нужны БД и буферу; данные графа могут восстанавливаться
из проекции. Снаружи открыты только необходимые HTTPS-маршруты.
Плеер, его API и выдача файлов защищены одинаково. Не публикуйте порты
БД и графа. В репозитории только .env.example с пустыми значениями;
реальная конфигурация хранится отдельно и не попадает в логи.
Первый запуск
Агент создаёт deploy/compose.yml и описывает точные команды своей
реализации в docs/runbook.md. Команды ниже — требуемый интерфейс
будущей сборки, а не уже существующие команды этого комплекта.
| Порядок | Действие | Признак готовности |
|---|---|---|
| 1 | Создать тестовую конфигурацию, тома, секреты и закрытый бакет. | Проверка конфигурации успешна; секреты не напечатаны. |
| 2 | Запустить postgres, дождаться готовности и выполнить migrate. | Миграции применены; роли проверены. |
| 3 | Зарегистрировать сайт demo, ключи и разрешённый Origin. | Браузерный ключ не принимает серверный результат. |
| 4 | Запустить receiver, worker, proxy; затем player, neo4j, tools по мере готовности. | Маршруты доступны; воркер обрабатывает очереди. |
| 5 | Выполнить seed-demo, затем test-acceptance. | Контрольный набор из главы приёмки даёт ожидаемые числа. |
| 6 | Подключать реальные источники по одному. | Карта полей и сверка каждого API подтверждены отдельным тестом. |
| 7 | Включить расписания, наблюдение и независимые копии. | Контрольный сбой обнаружен; восстановление проверено. |
Для готовой реализации служебные контейнеры должны поддерживать, например:
docker compose -f deploy/compose.yml --env-file deploy/.env run --rm migrate
docker compose -f deploy/compose.yml --env-file deploy/.env run --rm seed-demo
docker compose -f deploy/compose.yml --env-file deploy/.env run --rm test-acceptance
seed-demo работает только на явно обозначенном учебном стенде и
повторяемо загружает контрольный набор через соответствующие входы.
test-acceptance ждёт завершения обработки и заканчивается ненулевым
кодом при нарушении ожиданий. Он проверяет данные и доступы, а не только
то, что контейнеры запущены.
Фоновые задачи и наблюдение
timer -> acquire task lock -> run(running) -> bounded batches -> run(ok)
|
+----> run(failed, reason)
Таймер не заменяет блокировку. После падения повторяемые порции должны возобновиться без дублей. Отличайте отсутствие запуска, успех без новых строк и ошибку. Задачи разбора, закрытия/свёртки записей, загрузки API, перестроения отношений/графа, удаления и резервирования имеют отдельные статусы и наблюдаемые границы покрытия.
Наблюдайте возраст очередей, курсоров и копий, ошибки, диск, буфер, доступность S3, отставание графа и долю несвязанных объектов. Пороги берутся из спецификации и измеренной нагрузки. Независимая проверка должна обнаруживать остановку самого сервера аналитики.
Резервирование и удаление
Бэкап включает БД, файлы и необходимую конфигурацию; ключи восстановления хранятся отдельно. Копия не должна зависеть только от того же диска или единственной учётной записи. Зафиксируйте точку восстановления и перечень файлов: файлы, пришедшие после снимка БД, могут потребовать сверки каталога.
Восстановление проверяйте на другом стенде: применить конфигурацию, поднять БД, сверить файлы по каталогу, пересобрать производные данные, открыть запись, сравнить суммы и права. Успешная команда создания дампа сама по себе не доказывает восстанавливаемость.
Удаление по сроку охватывает сырьё, сущности, файлы, свёртки, граф и кэш инструментов. У копий своя политика истечения; восстановление старой копии не должно возвращать в рабочую систему уже удалённый набор. Проверьте это на учебных ID, не на реальных данных.
| Задание агенту | Требование |
|---|---|
| Цель | Заверши окружение, роли, миграции, расписания, наблюдение, копии и удаление по срокам. |
| Ограничения | Независимость копий; секреты вне репозитория; опасные проверки на отдельном стенде; явные границы потери/восстановления. |
| Результат | Runbook с точными командами, схема прав, история задач, протокол восстановления и удаления. |
| Проверка | Пересоздание контейнеров, обрыв задания, отказ API/S3, нехватка буфера, восстановление БД/файлов, повторное удаление и тест запрещённого доступа. |
← Данные и интерфейсы · Далее: Приёмка →
Приёмка системы
Назначение главы: проверить результат на наблюдаемых данных. Все сценарии выполняются на отдельном учебном стенде. Проверки реальных API проводят дополнительно после подключения каждого источника.
В этой главе: контрольный набор · порядок проверки · SQL · отказы · готовность
1. Контрольный набор
Используйте дату 2026-11-16, пояс UTC и учебную валюту XXX.
Период отчёта: [2026-11-16T00:00:00Z, 2026-11-17T00:00:00Z).
Все перечисленные платежи и расходы входят в этот период.
| Объект | Входные данные |
|---|---|
| Сайт и браузер | Сайт demo, URL https://www.example.com, посетитель v1, сессия s1. |
| Обычные события | Два page_view для / и /prices, одно form_submit; три разных msg_id. |
| Запись | Два потока страниц с начальными снимками, переход, клик и прокрутка; всё в s1. |
| Обращение | request_id=r1, копия формы и серверный accepted с разными msg_id. |
| CRM | Источник crm_demo, лид l1 с site=demo, request_id=r1; явный переход к сделке d1. |
| Атрибуция пилота | Сделка crm_demo/d1 имеет один подтверждённый канал demo_cpc. |
| Оплаты | Источник finance_demo, платежи p1=40.00, p2=60.00, оба settled, deal_source=crm_demo, deal_id=d1. |
| Звонки | Источник voice_demo: c1 с проверенным мостом к demo/v1, c2 без моста. |
| Расходы | Источник ads_demo, один отчёт daily_channels: каналы demo_cpc=2.00, demo_email=3.00, demo_other=5.00. |
Ожидания после полного разбора:
| Проверка | Ожидаемый результат |
|---|---|
| События и сессии | 3 события, 1 сессия; события разных потоков не конфликтуют. |
| Формы и CRM | 1 обращение, 1 лид, 1 сделка; путь r1 → l1 → d1 подтверждён. |
| Сырьё приёмника | 5 принятых сообщений: 3 события, 1 копия и 1 серверный итог; пачки rrweb учитываются отдельно. |
| Оплаты | 2 движения; общий итог 100.00 XXX, и столько же по crm_demo/d1. |
| Расходы | 3 строки выбранного отчёта, общий итог 10.00 XXX; у demo_cpc — 2.00 XXX. |
| Звонки | 2 звонка; c1 связан с посетителем, c2 сохранён без выдуманной связи. |
| Поведение | Запись доступна, два потока различимы, действия и текст прослеживаются до файлов. |
| Граф и агент | Подтверждённый путь до двух оплат; контрольный ответ даёт 100, а не сумму сделки. |
Число файлов зависит от выбранного закрытия и не является фиксированным ожиданием. Проверяются состав потоков, контрольные суммы, воспроизведение и полнота. Запись может быть неполной; агент должен объявить это.
Независимые расширения набора
Каждый сценарий ниже начинается с чистого базового набора, чтобы ожидания не зависели от порядка тестов.
| Дополнительный вход | Ожидание |
|---|---|
Возврат -20.00, статус settled | Чистые поступления 80.00 XXX; видны исходные оплаты и возврат. |
Отменённый платёж 20.00 | Контрольный итог остаётся 100.00 XXX. |
Платёж 30.00 без найденной сделки | Общий итог 130.00 XXX; 100.00 связаны, 30.00 относятся к unassigned. |
| Оплата в другой валюте | Отдельная строка итога; суммы разных валют не складываются. |
Второй CRM-аккаунт с deal_id=d1 | Две разные сделки; оплаты не переходят между ними по одному номеру. |
Обращение с серверным rejected | Отказ формы; лид не создаётся системой сверки. |
2. Сквозной прогон
- Поднимите пустой стенд и примените миграции. Проверьте роли, ключи и Origin.
- Пройдите контрольные страницы через настоящий браузерный скрипт. Проверьте сообщения, outbox и запись; одной вставки SQL для этой части мало.
- Отправьте форму через тестовый обработчик. В имитации CRM сначала
задержите лид, затем верните его с тем же
request_id. - Загрузите сделки, оплаты, звонки и расходы через адаптеры имитаций API. Дождитесь завершения окон и обработки сырья.
- Закройте запись, проверьте S3 и плеер, выполните свёртку и экспорт графа.
- Сравните числа из таблицы и SQL ниже с ответами инструментов агента.
- Повторите те же сообщения с прежними ID и окна API. События, денежные суммы и неизменённые версии не увеличиваются; записи запусков и попыток могут увеличиться.
- Выполните независимые расширения и матрицу отказов. Сохраните протокол: вход, воздействие, ожидаемый и фактический результат, команду и код завершения.
Воспроизводимую автоматическую приёмку агент оформляет в test-acceptance.
Браузерный smoke-тест и тестовые API входят в её описанный сценарий;
ручные шаги должны быть явно названы. Синтетический прогон подтверждает
свою реализацию, а не доступность методов и полей реального поставщика.
3. Контрольные SQL-запросы
Запросы используют учебные имена таблиц из контрактов. Выполняйте их после обработки очередей; до этого отсутствие сущности может быть задержкой.
События без сессии
SELECT e.site, e.session_id, COUNT(*) AS orphan_events
FROM event AS e
LEFT JOIN session AS s
ON s.site = e.site AND s.session_id = e.session_id
WHERE s.session_id IS NULL
GROUP BY e.site, e.session_id;
На базовом наборе результат пустой. В отдельном негативном тесте удалите или не создайте соответствующую сессию и убедитесь, что аудит её находит. Для реальных данных вывод требует диагностики, а не автоматического удаления.
Оплаты по сделке с учётом обоих источников
SELECT source, deal_source, deal_id, currency, SUM(amount) AS paid
FROM payment
WHERE status = 'settled'
GROUP BY source, deal_source, deal_id, currency;
Базовый результат: finance_demo / crm_demo / d1 / XXX / 100.00.
В расширении без сделки запрос также сохраняет группу с пустыми ключами
CRM; её нельзя терять на последующем соединении.
Для отчёта за период добавьте фильтр по paid_at с границами из начала главы.
Итог до присоединения графа и расходов
SELECT currency, SUM(amount) AS paid
FROM payment
WHERE status = 'settled'
AND paid_at >= '2026-11-16T00:00:00Z'
AND paid_at < '2026-11-17T00:00:00Z'
GROUP BY currency;
Сравните эти суммы с итогом витрины по всем каналам, включая unassigned.
Они должны совпасть. Отдельно сверяйте расходы с выбранным отчётом источника;
их присоединение не изменяет число платежей и сумму поступлений.
4. Матрица отказов
Для каждой строки проверяются и видимый статус, и фактическое состояние хранилища. Успешный HTTP-ответ сам по себе не является приёмкой.
| Воздействие | Что должно произойти |
|---|---|
| Потерян ответ после сохранения события | Повтор с тем же ID даёт duplicate; одно событие в сущностях. |
| Один ID с другим содержимым | Явный конфликт; прежний факт не перезаписан. |
| Смешанная пачка | У каждого индекса один исход; годные сохранены, постоянные отказы отделены. |
| Чужой Origin, отозванный ключ или серверный вид с браузерным ключом | Отказ; чужие данные не сохранены в нужной области. |
| Превышение тела, распаковки или частоты | Ограниченный отказ; приложение не расходует неограниченную память и не подтверждает несохранённое. |
| Недоступна аналитика при форме | Штатный обработчик и доставка CRM работают; очереди аналитики ограничены и наблюдаемы. |
| Обрыв разбора | Нет половины транзакции; повтор не создаёт дубликат сущности. |
| Сбой после записи буфера, до отметки БД | Повтор и закрытие не удваивают действия; единственная подтверждённая копия не теряется. |
| S3 не отвечает или регистрация каталога прервалась | Локальная копия остаётся; повтор завершает загрузку/регистрацию без молчаливой перезаписи конфликта. |
| Пропуск, поздняя пачка или нет полного снимка | Неполнота видима; поздние входы делают прежнюю свёртку устаревшей. |
| Сбой середины окна API | Последний полный курсор сохранён; повтор не теряет страницу и не создаёт новые неизменённые версии. |
| CRM устарела или после смены прав вернула пусто | Нет вывода о потере всех заявок или массовом удалении объектов. |
| Изменилась подтверждённая связь | Старое отношение перестало действовать в SQL и графе; поколения и свежесть видны. |
| Усечён ответ инструмента | truncated=true; агент не считает видимые строки полным итогом. |
| Команда спрятана в CRM/DOM или запрошена запись через read tool | Команда остаётся данными; хранилище запрещает изменение. |
| Секрет помещён в URL, DOM, атрибут и поле формы | Он отсутствует в переданном сырье, архивах, свёртках, тексте и журналах. |
| Потерян основной сервер | На другом стенде восстановлены БД и файлы; проверены запись, суммы и права. |
| Удалён тестовый набор по сроку | Он недоступен во всех рабочих слоях; после восстановления старой копии применяется политика повторного удаления. |
5. Когда принимать результат
Три уровня готовности
| Уровень | Что подтверждено |
|---|---|
| Учебная сборка | Контрольный сценарий и отказы пройдены на имитациях; команды запуска повторяемы. |
| Подключённый пилот | Для каждого реального источника проверены поля, права, покрытие истории, статусы и сверка контрольных сумм. |
| Эксплуатационная готовность | Нагрузка укладывается в выбранные пределы; наблюдение, доступ, удаление и восстановление проверены на стенде. |
Не заменяйте один уровень другим: наличие исходного кода не означает проверенную интеграцию, а работающий API не доказывает восстановление.
Комплект сдачи от агента
- Спецификация пилота и зафиксированные версии зависимостей.
- Миграции, роли, карта источников и формальные схемы сообщений.
- Конфигурация без секретов, точные команды запуска и
runbook. - Синтетические фикстуры и повторяемый сквозной тест с фактическими результатами.
- Словарь метрик, детализация витрин и сверка денег до/после атрибуции.
- Основания отношений, свежесть проекций и примеры ответов агента.
- Протокол проверки маскирования, прав, восстановления и удаления.
- Перечень неподключённых источников, ограничений и оставшихся решений.
Граница руководства: оно задаёт технический каркас и критерии сборки. Агенту предстоит написать приложение, миграции, адаптеры, инструменты и тесты. Поля и возможности конкретных API проверяются во время реализации; бизнес-определения и допустимые риски принимает владелец своей системы.