Finalish на Agnostic: как устроен сервис ревью сайтов

Представьте, что вы отправили заказчику сайт на проверку. Через некоторое время он присылает скриншот формы и пишет: «Вот здесь что-то не работает». На снимке видна кнопка, но не видно адреса страницы и того, что происходило до нажатия. Вы открываете форму у себя, заполняете поля, отправляете, и всё получается. Приходится возвращаться в переписку и выяснять подробности.

Заказчик при этом вполне может считать своё сообщение понятным. Он только что держал телефон в руках, видел всю страницу и помнит, что нажимал. У разработчика этих сведений нет. Пока они восстанавливают последовательность действий, в чат приходят правки текста, новый логотип и вопрос о сроках запуска. Через день найти первоначальное замечание и понять, исправлено ли оно, уже сложнее, чем хотелось бы.

В Finalish обсуждение можно вести рядом с самой страницей. Человек выбирает элемент на сайте, оставляет замечание, а остальные участники видят его вместе с ответами и статусом. Это помогает сохранить место, к которому относится разговор. Дальше всё равно потребуется объяснить проблему и проверить исправление, поэтому давайте пройдём процесс целиком на примере формы записи в мастерскую.

01 / Страницы проектаОткрыть снимок

Допустим, посетитель открыл форму на телефоне, выбрал диагностику и нажал «Отправить», оставив телефон пустым. Проверка сработала, но сообщение об ошибке появилось выше видимой области. Страница осталась на месте, и человеку кажется, что кнопка не работает. Разработчик же может заполнить все поля и не встретить эту ситуацию вообще. Чтобы он повторил ошибку, стоит описать, что вы делали до её появления.

На странице записи, на мобильной ширине 390 px, выбираю «Диагностика», оставляю телефон пустым и нажимаю «Отправить». Ничего заметного не происходит. Хотелось бы увидеть подсказку возле телефона и перейти к этому полю, чтобы было понятно, что заполнить.

По такому сообщению уже можно открыть нужную страницу, повторить действия и проверить предположение. В нём есть и объяснение затруднения посетителя: он не понимает, почему отправка остановилась. Это помогает обсуждать решение. Возможно, достаточно прокрутить страницу к полю и перевести на него фокус; возможно, нужно ещё изменить расположение ошибки. У команды есть конкретный случай, на котором можно сравнить варианты.

Объём подробностей зависит от самой правки. Для лишней буквы достаточно выделить слово и написать правильный вариант. Если сломалась отправка, пригодятся шаги и сообщение об ошибке. Если разъехалась вёрстка, укажите устройство или размер окна. Человеку, который проверяет сайт, не нужно каждый раз составлять большой технический отчёт, но должно хватать сведений, чтобы другой участник увидел ту же проблему.

А вот несколько разных проблем лучше разделить. Если в одном замечании попросить исправить отправку, перекрасить кнопку и заменить заголовок, разработчик может выполнить два пункта и закрыть всё обсуждение. Когда у каждой правки есть своя ветка, видно, какая из них закончена, а по какой ещё нужен ответ. Это удобно и заказчику: он может согласиться с исправлением формы, не теряя вопрос о заголовке.

В рабочей области Finalish основную часть экрана занимает проверяемая страница, а рядом находятся замечания и ответы. Сначала можно пользоваться сайтом в режиме просмотра: открыть форму, выбрать услугу, добраться до нужного состояния. Затем перейти к комментированию и указать элемент. Так нажатие на кнопку при выборе места замечания не смешивается с обычной попыткой отправить форму.

02 / Контекст замечанияОткрыть снимок

Когда вы выбираете элемент, браузерный SDK собирает сведения о нём и размере окна. Эти данные помогают привязать отметку к странице, а текст объясняет, что случилось. В случае с телефоном стоит написать о пустом поле и невидимой ошибке. Сам маркер на кнопке не расскажет, какие значения были введены и какого поведения вы ждали.

Дальше разработчик воспроизводит ситуацию и предлагает исправление в той же ветке. Например, после отправки формы фокус будет переходить к незаполненному телефону, а рядом появится объяснение. Если заказчик представлял себе другое поведение, это удобно уточнить здесь же, пока решение ещё обсуждается. К разговору позже сможет подключиться коллега и прочитать исходное замечание вместе с договорённостью.

После изменения нужно ещё раз пройти первоначальные шаги. Оставьте телефон пустым и посмотрите, заметна ли подсказка. Затем заполните поле и убедитесь, что заявка отправляется: исправляя обработку ошибок, можно случайно затронуть успешный сценарий. Участник с правом изменения статуса сможет закрыть замечание, а если проблема осталась, открыть его снова. В ответе полезно написать, что именно проверили, и приложить ссылку на версию сайта, на которой это делали.

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

В SDK Finalish для этого есть несколько ориентиров: устойчивый идентификатор элемента, CSS-селектор, текст и XPath, то есть путь к узлу в структуре страницы. Сохраняются также координаты и размер окна. При выборе SDK старается захватить кнопку или ссылку целиком, даже если человек нажал на маленькую иконку внутри неё. Пользователь обычно хочет обсудить действие кнопки, поэтому такая привязка понятнее, чем отметка на её декоративной части.

Несколько способов поиска помогают пережить изменения, но после полного редизайна кнопки может уже не быть. Когда SDK не находит подходящий видимый элемент, он не рисует отметку поверх страницы. В таком случае откройте текст замечания и разберитесь, осталось ли оно актуальным. Возможно, форму перенесли в другое место, и контекст нужно уточнить; возможно, проблемный элемент удалили. Закрывать замечание только потому, что маркер исчез, было бы преждевременно.

Есть ещё особенность адресов. Finalish определяет страницу по домену и пути, отбрасывая параметры запроса и часть после #. Для обычного сайта это удобно: одна и та же страница с разными рекламными метками не превращается в несколько обсуждений. В приложении параметры иногда меняют весь экран. Если история заявок открывается через ?tab=history или маршрут выглядит как #/orders, явно опишите нужное состояние в сообщении и заранее проверьте, подходит ли вашему сайту такой способ разделения страниц.

Чтобы выбор элементов работал, на проверяемом сайте должен быть подключён браузерный SDK Finalish. Встраивание сайта в окно ревью также зависит от его настроек. Когда страницу нельзя показать внутри сервиса, в реализации предусмотрена работа на самом сайте в отдельной вкладке. Подключение SDK при этом всё равно нужно проверить, особенно если вы передаёте ссылку человеку, который откроет её впервые.

В одном ревью могут участвовать заказчик, дизайнер, разработчик и руководитель проекта. Им нужно видеть общий разговор о результате, но у команды бывают и внутренние вопросы: кто возьмёт правку, почему возникла ошибка, как лучше изменить код. В Finalish для таких ответов предусмотрены внутренние комментарии. Заказчика можно пригласить гостевой ссылкой с ограниченным доступом, сроком действия и возможностью отзыва.

Гость получает свою сессию в пределах этой ссылки. Он не становится участником всей команды или пользователем платформы Agnostic. Владелец или администратор может заранее определить, какие страницы отдать на проверку и когда доступ закончится. Это удобно, например, если человек проверяет только страницу услуг и ему не нужны обсуждения остальных разделов сайта.

У участников команды тоже разные роли. Владелец и администратор управляют доступом и принимают решения по согласованию страницы. Участник может создавать замечания, отвечать и менять их статус в доступном проекте. Наблюдателю доступен просмотр. Благодаря такому разделению коллега может помочь с проверкой формы, а окончательное согласование останется у того, кто отвечает за результат.

Внутренние комментарии исключаются из гостевой выдачи на сервере с помощью условия is_internal: false. Это можно представить так: сервер сначала определяет, что разрешено гостю, и только потом отправляет подходящие записи. Если передать браузеру всю переписку и лишь скрыть часть строк на экране, содержимое останется в сетевом ответе и его можно будет прочитать. Поэтому правила видимости должны действовать до отправки данных.

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

Вернёмся к форме записи. Подсказка теперь видна, фокус переходит к телефону, заполненная заявка отправляется, и замечание можно закрыть. Но рядом ещё обсуждают стоимость диагностики, а заказчик не смотрел страницу целиком после изменений. Статус одной правки здесь мало говорит о готовности всей страницы.

Поэтому в Finalish состояния разделены. Замечание бывает открытым или решённым. Страница может находиться в черновике, на согласовании, быть согласованной или возвращённой с запросом изменений. Решение о согласовании принимает владелец или администратор. Можно закрыть все известные замечания и отправить страницу на просмотр человеку, который проверит её целиком и даст окончательный ответ.

Решения по странице записываются в историю событий, из которой сервер получает её текущее состояние. В истории сохраняется последовательность действий: отправили на согласование, запросили изменения, доработали и отправили снова. Это помогает вернуться к разговору и выяснить, кто и когда принял решение. Ссылку или обозначение проверяемой версии стоит отдельно оставить в обсуждении, чтобы согласование относилось к понятному состоянию сайта.

До первого совместного ревью договоритесь, кто проверяет исправления и кто согласует страницу. Иногда разработчик отмечает задачу выполненной после изменения кода, а заказчик считает её законченной только после своего просмотра. Оба действуют логично, но без общей договорённости один и тот же статус будет означать для них разное. Для формы можно заранее определить: исправление закрываем после повторной отправки с пустым и заполненным телефоном, страницу согласуем после просмотра всех её разделов.

Теперь, когда весь путь замечания понятен, посмотрим, как он устроен внутри. У Finalish есть интерфейс на React и TypeScript, браузерный SDK для выбора элементов и сервер на NestJS. Сервер проверяет сессию и права пользователя, а затем сохраняет или читает данные. В этом ему помогают App Auth и Agnostic Runtime SDK. Роли команды, гостевые ссылки и правила согласования описаны в самом Finalish.

Например, сообщение «не вижу ошибку возле телефона» остаётся в записи замечания. Предложение разработчика и ответ заказчика добавляются как отдельные комментарии. Если бы каждый новый ответ заменял исходный текст, через несколько дней было бы трудно понять, с чего всё началось. Отдельные записи сохраняют разговор, а заодно позволяют ограничить видимость конкретного внутреннего ответа, сохранив доступ к остальной ветке.

Обращения к Agnostic Data проходят через сервер приложения с Runtime SDK. Служебный runtime-токен остаётся там же. Браузерному SDK Finalish, который выбирает кнопку на странице, этот токен не нужен: у него другая задача. Такое разделение позволяет серверу проверить права перед работой с данными и не передавать посетителю служебный доступ вместе с кодом сайта.

Если вы проектируете похожий сервис, начните с того же разговора между участниками. Кто оставляет замечание, кто может его видеть, куда попадают ответы и кто подтверждает результат? Из ответов получатся и необходимые данные, и правила доступа. Тогда агенту можно поручить определённое действие с понятным результатом, например сохранение ответа в доступном проекте, и проверить его на отдельных учётных записях.

Для начала возьмите одну страницу и пригласите коллегу на короткое ревью. Пусть он оставит замечание, а вы откроете его под своей учётной записью и попробуете воспроизвести проблему по написанному. Если пришлось уточнять исходные действия, дополните сообщение в той же ветке. Такой проход быстро показывает, каких сведений не хватает именно вашей команде.

После исправления попросите коллегу повторить проверку. Закройте замечание, обновите страницу и убедитесь, что ответ и статус сохранились. Если меняли вёрстку, посмотрите, куда указывают оставшиеся отметки. Затем отдельно пройдите согласование всей страницы. Так вы проверите и сохранение данных, и договорённость о том, в какой момент работу можно считать законченной.

Для гостевого доступа используйте отдельную сессию браузера: под учётной записью администратора ограничения гостя незаметны. Проверьте доступные страницы, отсутствие внутренних комментариев в ответе API и работу отзыва ссылки. На снимках в этой статье показаны демонстрационные данные, а в своём проекте для первого такого прохода тоже удобно оставить несколько тестовых замечаний, которые легко узнать и удалить после проверки.

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