Практическое руководство для технического аналитика и агента разработки
Посетитель → обращение → лид → сделка → оплата. Поведение на сайте, записи сессий, звонки и рекламные расходы дополняют эту цепочку, а агент отвечает на вопросы по проверяемым данным.
Для кого: вы знаете SQL, понимаете HTTP API и можете с агентом развернуть приложение на сервере.
Результат: собственная система сбора, сверки и анализа данных — от события браузера до подтверждённой оплаты.
Формат: архитектура, учебные контракты, восемь заданий на разработку и проверяемая приёмка. Готового приложения в этом комплекте нет.
Читать руководство на GitHub Pages
Презентация выступления — PDF, 22 слайда
| Глава | Что вы в ней найдёте |
|---|---|
| Эта страница | Состав системы, принципы и порядок работ. |
| Данные и интерфейсы | Ключи, сущности, HTTP, файлы записей, деньги и ответы инструментов. |
| Сборка и эксплуатация | Подготовку, восемь заданий агенту, первый запуск и обслуживание. |
| Приёмка | Контрольный набор, SQL-проверки, тесты отказов и критерии готовности. |
Сначала прочитайте обзор и контракты. Затем передавайте агенту по одному этапу из главы о сборке и принимайте его по контрольным примерам. Передавайте весь комплект: отдельная страница не заменяет остальные главы.
Все имена, адреса, идентификаторы и суммы в примерах вымышлены. Названия технологий обозначают предлагаемый стек; они не описывают инфраструктуру или текущее состояние какого-либо частного проекта.
Система должна отвечать на пять практических вопросов:
- Что посетитель сделал до обращения и сохранилась ли запись сессии?
- Принял ли сайт форму и появился ли соответствующий лид в 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 агент проверяет по официальной документации при реализации и фиксирует в зависимостях. Таблица не задаёт готовый совместимый набор версий.
| Принцип | Следствие для собственной реализации |
|---|---|
| Сначала разрешённое сырьё, затем преобразования | Сохраняйте принятый очищенный конверт и ссылку на него из сущности. Чувствительные значения удаляйте до передачи. |
| Повторная доставка безопасна | ID создаётся один раз; уникальные ключи и транзакции предотвращают дубли. |
| Три точки обращения | Копия браузера, итог сайта и объект CRM сверяются независимо. |
| Любая связь объяснима | Хранятся основание, уверенность, версия правила и ссылки на источники. |
| Пробелы видимы | Отсутствующий источник, устаревший опрос, неоднозначная связь и нулевой результат различаются. |
| Деньги сверяются до атрибуции | Общая сумма платежей не меняется из-за присоединения расходов, звонков или обращений. |
| Производные данные пересобираются | События записи, текст, отношения, витрины и граф имеют версию и перечень входов. |
| Агент получает ограниченное чтение | Права задаются в хранилище; инструмент сообщает свежесть, покрытие и усечение. |
Точные правила поиска совпадений, сроки ожидания и параметры нагрузочных лимитов выбирает владелец собственной системы. Они должны быть записаны в конфигурации и проверены на своих данных. В пилоте опирайтесь на явные ID; спорные совпадения оставляйте кандидатами.
Подготовка предшествует всем этапам. Базу, роли, миграции и постоянные тома поднимите до первого события. Этап 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. Затем заменяйте их реальными адаптерами по одному и повторяйте приёмку. Если источник недоступен, показывайте «не подключён»; нулевые расходы или оплаты из этого не следуют.
Скопируйте задание вместе с тремя главами:
Собери собственную систему по этому комплекту документации. Сначала подготовь спецификацию пилота и карту доступных источников. Зафиксируй свои решения о версиях, полях, нагрузке и сроках хранения. Реализуй этапы последовательно, сначала на синтетических данных. После каждого этапа покажи миграции, контракты, команду проверки и её фактический результат. Не считай имитацию API проверенной интеграцией. Не заменяй отсутствующие данные нулём и не придумывай связи. Не переноси реальные контакты, секреты и инфраструктурные реквизиты в документацию, фикстуры или журналы. Запись в CRM не входит в задачу.
Названия файлов, таблиц и маршрутов далее — согласованный учебный контракт для создаваемой реализации. Их можно изменить совместно, обновив все зависимые части и проверки.
Далее: Данные и интерфейсы →