# Что нового?

В 2024 году вышла в релиз новая версия Offline Trade-In, которая сильно превосходит легаси, которое работало на стеке 2017 года.
Это было раньше:
- SSR на стороне Django (Python v3.6)
- jQuery / JS Vanilla / Web API
Краткая история: В 2020 году код фронта (при моем первом знакомстве с ним) представлял собой спагетти-легаси и содержал в себе императивную логику преобразования DOM в зависимости от различных событий (понятие Бизнес Логика в приложении отсутствовало в декларативном виде).
Таким образом с 2017 по 2024 велась доработка фич (+ максимально возможный рефакторинг в пользу DX), но все это время требовался новый продукт с более удачным подходом в плане поддержки кода и управлению Бизнес Логикой на уровне менеджмента - именно это и будет составлять основную ценность в будущем. И в 2024, наконец, пришло время переписать старое легаси на современные рельсы **(ссылка на демо будет в конце)**. Чтоб эта информация не потерялась, решил задокументировать текущие подходы и достижения в области решения проблем отладки в числе прочего (это был основной момент, требующий решения, т.к. устранив это, мы стали работать намного эффективнее).

<CollapsibleBox
header="Сводка о проектах"
text="Всего было 4-5 проектов, каждый из которых является частью экосистемы и имеет свой стек технологий:
1️⃣ Сайт для сбыта б/у устройств;
2️⃣ Админская панель;
3️⃣ Сайт для сдачи устройств в Trade-In для физ. лиц (2020);
4️⃣ Сайт для сдачи устройств в Trade-In для юр. лиц (2017) 👉 поддержка + рефакторинг + развитие Легаси с 2020 до 2023;
5️⃣ Сайт для сдачи устройств в Trade-In для юр. лиц (2024) 👉 На новом стеке технологий"
/>

# Решённые задачи

## 1. 🏗️ Монорепа разделена на фронтенд и бэкенд

Сборка партнерской версии клиентского приложения вынесена в отдельный проект с настраиваемыми Environments variables для вариативности инстансов (разработка, стейджинг, продакшен) - теперь исходный код узнает для какого инстанса он собирается, только получив envs при сборке (это было важным для нас в рамках спец. операции под кодовым названием **"Соскочить с легаси"**).

<Alert
type="success"
text="Теперь деплой фронта не требует сборки бэкенда, а сборка фронта на всех инстансах работает одинаково"
/>

## 2. 💼 Управление Бизнес Логикой стало прозрачным

Главная особенность текущего проекта (точнее, одного из тех что в работе) заключается в требовании гибкой настройки ветвлений пользовательских сценариев, периодически требующее добавления шагов (в дальнейшем - **дискретных состояний Стейт-Машины**). Новая реализация позволяет донастраивать различные сценарии поведения веб-приложения и дебажить эти сценарии на разных уровнях (внутренняя бизнес-логика, данные по API, вычисляемые значения на основе вводимых пользователем данных - одним словом, все параметры, влияющие на успешный User Flow). Чего удалось достичь:
- Настраиваемая последовательность шагов на уровне конфига Стейт Менеджера XState. Это важно, т.к. в прошлых версиях проекта, с ростом вариантов ветвлений сценариев, настраивать их было весьма затруднительно (императивный подход к мутации DOM требовал анализа всего кода без возможности декомпозировать его на отдельные подзадачи)
- Появилась гибкая валидация ответов API на уровне СТМ (сценарий не пойдет дальше, если ответ не соответствует валидации, все подобные ошибки теперь можно транслировать в UI с соответствующей формулировкой)
- На всем промежутке времени моей деятельности в компании не было представителя бизнеса, который полностью владел логикой приложения (даже Продукт менеджер - но это не его вина, просто проект очень стар). На мои попытки явным образом получить описание бизнес-логики в виде вопросов "Как оно должно здесь работать?", я получал что-то вроде "Оно же как-то работает, а сейчас требуется внести небольшое изменение" (опять же, ничего страшного, просто наша команда попала в ловушку легаси без доки). Итак, **Документация - теперь она есть в виде конфига XState + интерактивной схемы!** Теперь любой разработчик будет знать, *как оно работает*.

<ImagesGalleryBox2 itemsJson='[
  {
    "src": "https://pravosleva.pro/express-helper/chat/storage/uploads/sp.pravosleva/1734127033086.png",
    "original": "https://pravosleva.pro/express-helper/chat/storage/uploads/sp.pravosleva/1734127033086.png",
    "title": "Фрагмент схемы",
    "caption": " Внимание, прототип! Все персонажи и события вымышлены исключительно для визуального представления о разработке в духе Enterprise каким его видела наша команда =)"
  },
{
    "src": "https://pravosleva.pro/express-helper/chat/storage/uploads/sp.pravosleva/1733993517636.png",
    "original": "https://pravosleva.pro/express-helper/chat/storage/uploads/sp.pravosleva/1733993517636.png",
    "title": "Фрагмент схемы",
    "caption": " Внимание, прототип! Все персонажи и события вымышлены исключительно для визуального представления о разработке в духе Enterprise каким его видела наша команда =)"
  }
]' />

<Alert
type="success"
text="Теперь основная часть бизнес-логики (понятная и очевидная схема пользовательских сценариев) может быть быстро настроена на уровне конфига и наглядно продемонстрирована в виде блок-схемы. Взаимодействие с менеджером Продукта стало эффективнее. DX стал более совершенным и декларативным"
/>

## 3. 📈 Повысилась эффективность отдела IT

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

- **BFF сервисы (немного фулл-стека):** Появилась возможность добавить автоматизированные оповещения об ошибках по socket.io (далее некоторые из них улетают в Google Sheets, Telegram и т.д.) **по Socket соединению в отдельном потоке Web Worker**. Анализ логов теперь также может быть автоматизирован для ретрансляции в чаты в виде задач (возможно даже с указанием исполнителя).
- Добавлена функция "Сообщить об ошибке", позволяющая отправить сообщение от Пользователя и историю его взаимодействия с приложением для анализа Разработчиком

<CollapsibleBox
header="Отправка лога и обратная связь от сервера"
text="➡️ Event from App to Worker
➡️ Socket event to your Service
⬅️ Incoming socket event to Worker
⬅️ Event from Worker to App 🏁"
/>

<Alert
type="success"
text="**Теперь информация по каждому прецеденту прилетает в Telegram группу!** Ранее были проблемы скорости реагирования на ошибки в продакшене - их диагностика занимала много времени. Теперь анализ логов взаимодействия пользователя с интерфейсом (и не только) в рамках сессии занимает минуты"
/>

## 4. 🤝 Кастомизация UI для каждого из партнёров стала гибче

Решены проблемы вариативности дизайна, связанные с тем, что кодовая база собираемого приложения ранее НЕ была разделена на подпроекты - изменения интерфейса (как и бизнес-логики) затрагивали всех пользователей. Не было unit & e2e тестов.

<Alert
type="success"
text="Ранее были проблемы реализации специфичного дизайна в зависимости от роли/типа пользователя. Теперь каждый из партнёров будет перенаправлен на конкретное SPA в соответствии с внешним роутом NGINX"
/>

# Стек технологий

- **Vite** / **React** / **Typescript** (принято в стек как современный стандарт, когда SSR не требуется)
- **XState v4.x** (отлично вписался под свои задачи, связанные с ветвлением пользовательских сценариев, 5-я версия на тот момент ещё была не готова к релизам в прод)
- **Valtio** (минималистичный и гибкий подход к управлению состоянием на базе нативных JS механизмов объекта Proxy)
- **Tailwind CSS** / **Headless UI** (ориентированная на утилиты CSS-инфраструктура для быстрого создания современных веб-сайтов, которая позволяет удобно и быстро создавать кастомные компоненты с заданными стандартными параметрами - настройки стилей типовых элеметнов и т.д.)
- **CSS modules** / SCSS (для компонентов с нестандартной версткой)
- Необычное решение: **Web Socket connection** in **Web Worker** (для отправки логов в отдельном потоке, не нагружая основной поток)

<ControlsBox
  controlsJson='[
    {
      "title": "PREV",
      "label": "Наши стандарты DX (подробнейший разбор)",
      "type": "link",
      "link": "/blog/article/good-dx-exp-2024"
    },
    {
      "title": "START_NEW_TAB",
      "label": "XState interactive scheme",
      "type": "link",
      "link": "https://stately.ai/registry/editor/embed/4c16acf2-6d92-4602-849d-99e1b06f2f39?mode=Design&machineId=f4ab287d-d1a6-4a2f-b0b5-25f6a0d3f4af"
    },
    {
      "title": "NEXT",
      "label": "Life Demo",
      "type": "link",
      "link": "https://pravosleva.pro/subprojects/sp/tradein"
    }
  ]'
/>

💳 Offline Trade-In (Level Up) #smartpriceRINGEO #рабочие_моменты 2024.8 [3/3]

# В сухом остатке

Осматривая продуктовый труп как результат не самых удачных маркетинговых ходов и уловок (в числе прочего), я хочу обратить пристальное внимание на пару важных моментов, которые следует рассмотреть, как типичные ошибки проектирования UX. В этой статье речь пойдет не про качество кода, а только про удобство пользователя (точнее, о причинах его отсутствия).

![fuckup](https://pravosleva.pro/express-helper/chat/storage/uploads/sp.pravosleva/1723371813428.jpg)

<Alert type="warning" header="Disclaimer" text="Все персонажи и события вымышлены (или нет?)" />

# 🚧 1. Не предлагайте то, чего у Вас нет

> От посетителя магазина, выбравшего товар, следует ожидать, что он захочет купить именно этот товар.

## Проблема
В нашем случае предлагается ассортимент без учёта нулевого количества на складе. Настройка "В наличии" в данном случае не играет роли и является лишней нагрузкой на интерфейс - посетитель воспринимает все предложенное, как доступное для выбора (внезапно, да?). Справедливо предположить, что если в процессе покупки выбранного товара выясняется, что его нет и **вместо выбранного товара клиенту будет предложено найти что-то другое** - это определенно будет раздражать клиента.

![wtf](https://pravosleva.pro/express-helper/chat/storage/uploads/funny-day/1724610381074.jpg)

## ✅ Решение
Не запутывайте клиента, просто не показывайте товар с нулевым количеством на складе.

# 🚧 2. Не уводите клиента от его цели

> От посетителя магазина, ищущего товар, следует ожидать, что он захочет найти именно этот товар.

В нашем случае основную часть видимой области загруженной страницы занимает баннер с информацией **которой клиент не интересовался**. Модель попадания клиента на страницу с кнопкой "Положить в корзину" соответствует следующим вариантам маршрута:

- Главная с поиском -> Каталог с поиском -> Страница продукта с настройками
- Главная с поиском -> Страница продукта с настройками

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

Можно утверждать, что клик по баннеру скорее всего будет случайным. Объясню, почему: На самом баннере нет кнопки, описывающей действие по клику, поэтому пользователь не ожидает никаких действий при клике на баннер.

## Конкретные кейсы
### Пример 1 🤌
1. Я пришел на сайт;
2. Ищу в поиске продукцию Apple;
3. **Попадаю в каталог с сортировкой по бренду** (казалось бы, я почти нашел то что мне надо);
4. 🚫 По клику на баннер оказываюсь в том же каталоге с сортировкой которая мне не нужна;

![wtf](https://pravosleva.pro/express-helper/chat/storage/uploads/sp.pravosleva/1723368242870.jpg)

### Пример 2 🤌🤌
1. Я пришел на сайт;
2. Ищу в поиске модель Apple iPhone X;
3. Попадаю в каталог с сортировкой по бренду;
4. **Захожу на страницу интересующего меня продукта** (казалось бы, я уже нахожусь на странице с целевой кнопкой "Заказать продукт");
5. 🚫 По клику на баннер оказываюсь в каталоге с сортировкой которая мне не нужна;

![wtf](https://pravosleva.pro/express-helper/chat/storage/uploads/sp.pravosleva/1723367860723.jpg)

## ✅ Решение
Ликвидировать баннеры на сайте, как лишний мусор.
Не уводите клиента с его маршрута.
Если есть конкретные предложения для клиента, сделайте это явным образом: Если хотите предложить выборку товаров - сделайте отдельный информационный блок с кнопкой "Перейти".

# 🏒 3. Проектируйте минимум кликов до достижения цели

> От посетителя магазина, ищущего товар, следует ожидать, что он захочет купить этот товар быстро.

Своего рода "воронка" выглядит следующим образом: Пользователь должен дойти до кнопки "Добавить в корзину" (которая находится только на странице продукта) исключительно по выстроенному для этого маршруту (см. пункт 2).

## Проблема
Клиент не может заказать продукт из любой точки сайта - вместо этого, мы заставляем его делать дополнительные клики по страницам. Таким образом, в данной реализации, путь до продукта слишком затруднителен. Почему так произошло, понятно - API предполагает, что попадать в корзину должен уже сконфигурированный товар. Надеюсь, урок для всех нас не прошел мимо.

## ✅ Решение
Переделать корзину: Дать возможность добавить в нее продукт **из любого места сайта**, для возможной конфигурации в самой корзине. А также, ликвидировать баннеры со всех страниц кроме главной по очевидным причинам (см. пункт 2).

<ControlsBox
  controlsJson='[
    {
      "title": "PREV",
      "label": "Наши стандарты DX",
      "type": "link",
      "link": "/blog/article/good-dx-exp-2024"
    },
    {
      "title": "smartprice.ru",
      "label": "Check it out",
      "type": "link",
      "link": "https://smartprice.ru"
    }
  ]'
/>

Как не сломать UX на стадии проектирования #ретроспектива #маркетинг #рабочие_моменты 2024.8 [2/3]

Наши стандарты DX #рабочие_моменты 2024.8 [1/3]

Ссылка на оригинал статьи с объяснением принципа Доказательного Планирования (в оригинале Evidence Based Scheduling - далее будет фигурировать как EBS)
- Joel Spolsky [Evidence Based Scheduling](https://www.joelonsoftware.com/2007/10/26/evidence-based-scheduling/)
- [Перевод на русский](https://habr.com/ru/articles/186410/)

## Суть проблемы планирования

Из опыта работы в "Кровавом Enterprise" плечом к плечу с Менеджером Продукта, перед поступлением очередной задачи в работу, у меня интересовались, сколько на нее уйдет времени (внезапно). Такая оценка должна затрагивать все возможные факторы "торможения", к примеру:
- Неоднократное выяснение деталей до того момента, как задача станет "прозрачной"
- Перерывы в работе по разным причинам
- Фактор непредсказуемости изменений ТЗ (добавление требований в процессе разработки фичи)

Да, слишком абстрактно, и эти пункты можно детализировать на много факторов, но сама проблема свелась к учету их всех неявным образом. Условно, будем считать, что проблема локализована (Вы удивитесь, но детали, действительно не так важны).

## Каким я вижу решение
Чтобы получить прогноз для конкретной задачи по срокам, достаточно иметь статистику по аналогичным задачам, каждая из которых должна иметь четыре параметра:
1. Дату старта исполнителем;
2. Дату прогноза от исполнителя;
3. Дату фактического ее завершения (которую потом ~~можно~~ **нужно** двигать по мере доработки задачи);
4. Грейд задачи (сложность фичи по мнению исполнителя) - также может повышаться по мере разработки. Есть категория задач, в процессе реализации которых происходит рост сложности в связи с добавлением требований со стороны бизнеса. Таким образом, любая задача может перейти в категорию более сложных и ее прогноз при этом будет скорректирован.

### Шаг 1: Два вопроса при постановке
- Какова сложность фичи по шкале от 1 до 5?
- Сколько времени тебе нужно на ее выполнение?

### Шаг 2: Контроль дат
Далее следует вопрос самоконтроля эффективного менеджера - зафиксировать даты старта и фактического завершения этой задачи (это важно!). С момента завершения первой задачи, можно предсказывать будущее, с учетом ошибок разработчика, основываясь на предыдущем опыте работы с ним: Чем больше задач набирается в опыт, тем точнее прогноз.

<Alert
type='warning'
header='Да, кстати, важный момент!'
text='Прогноз исполнителя НЕ должен основываться на аналитически расчитаных значениях. Оценить должен именно исполнитель - именно его прогнозы имеют ценность для анализа.'
/>

### Шаг 3: Результат анализа
> Следствие - всегда результат принятых решений (из фильма "Разрабы")
А теперь посмотрим, что мы имеем:
- Предполагаемая дата лучшего сценария (обычно, мало кого интересует)
- Предполагаемая дата "среднего по больнице" сценария (наиболее бесполезный, кмк - см. спойлер ниже)
- ⚡ **Предполагаемая дата худшего сценария** - самая ценная информация при стратегическом планировании сроков фичи (*)

**(*) Поправка в 2024: периодически возвращаясь к интересной задаче, пришел к выводу, что это не совсем верный подход (см. спойлер ниже)**

<CollapsibleBox
header="Спойлер: Обновления 2024"
text="В версии 2024 появится новая характеристика - **Наиболее вероятный сценарий** - разработан расчет более точного прогноза: Значение ожидаемой даты рассчитывается как среднее между аналогичными случаями, но только теми, **значения разниц скоростей которых минимальны**: Отсортируйте скорости выполнения задач аналогичной сложности и оставьте только те, где дельта отклонения друг от друга равна (либо чуть больше) минимальному из них"
/>

## Инструкция и [Демо](https://pravosleva.pro/team-scoring/legacy)

Хотел бы собрать обратную связь насчет работы демо версии - мнение можно оставить [здесь](https://t.me/bash_exp_ru/415).

Пару слов о том, как я использую этот инструмент в своей работе:

1. **Создаю новую таску, назначенную на исполнителя, который оценивает ее навскидку**:
- а) субъективная оценка сложности от 1 до 5 - возможно, эту оценку можно скорректировать по факту выполнения задачи (думаю, по итогам ретроспективы в момент завершения таски - самое время);
- б) субъективный срок выполнения;
- в) фиксирую дату старта выполнения - она должна соответствовать факту старта;

2. **⚡ Если *такая* задача не первая! Получаю прогноз по методике EBS на самый худший вариант развития** - ~~это тот самый срок, который следует озвучить Продукт Менеджеру~~ (в обновленной версии все иначе, см. обновления в конце);

3. **Фиксирую фактическую дату завершения задачи** - это именно тот параметр, который следует скорректировать в случае, если задача потребовала доработки для более точной статистики и, как следствие, более точной оценки последующих задач.

*При наличии статистики, перед постановкой задачи можно прикинуть, насколько "обманет" испытуемый исполнитель:*

![img](https://pravosleva.pro/express-helper/chat/storage/uploads/team-scoring-2019/1698044852385.png)

В процессе работы каждый исполнитель обрастает собственным уникальным грейдом (можно сказать, коэффициент качества планирования):
- Меньше единицы - сотрудник ответственный либо перестраховывается;
- Больше единицы - сотрудник черезчур самоуверенный;

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

*Продолжение следует...*

<ControlsBox
  controlsJson='[
    {
      "title": "PREV",
      "label": "Joel Spolsky // Evidence Based Scheduling (2007)",
      "type": "link",
      "link": "https://www.joelonsoftware.com/2007/10/26/evidence-based-scheduling/"
    },
    {
      "title": "END_DEMO",
      "label": "Живой пример (русскоязычная версия 2019)",
      "type": "link",
      "link": "/team-scoring/legacy"
    }
  ]'
/>

## 🚀 Обновления 2024

### Более удачный UX
- **Estimated** (заявленный сценарий) - прогрессбар доходит до 100%, дата заявлена исполнителем (никакой магии);
- **The Worst** (худший сценарий) - значение ожидаемой даты основано на той задаче, которая была завершена исполнителем с минимальной скоростью;
- 💥 **Sensed** ("ощущаемый") - это новый прогрессбар, значение даты, соответствующей 100% рассчитано как среднее между теми сценариями, скорости выполнения которых отличаются не слишком сильно (в него НЕ входят те задачи, которые завершены исполнителем аномально быстро или аномально медленно). Логика простая: Человек работает, как правило, [плюс-минус] с одной ***комфортной*** скоростью - алгоритм должен ее "ощутить". Как именно: если среди возможных вариантов скоростей его работы встречаются два с минимальным отклонением - это повод искать ещё варианты с примерно таким же отклонением. В итоге, найденные варианты образуют "скопления", среднее значение которых можно учитывать как наиболее вероятное.

Здесь же надо заметить, у каждого человека комфортная скорость может разниться в зависимости от сложности задачи - простые планировать легко, средние чуть сложнее и т.д. - именно по этой причине нужно не забывать уточнять грейд задачи на старте и на финише (в процессе возможна переоценка с соответствующим пересчетом вероятностей).

### Более удачный DX
- "Чем проще, тем лучше" - чисто клиентский билд для раздачи NGINX-ом. Как показала практика, простые проекты живут дольше, деплой проще и быстрее, инфраструктура без особых затрат
- Более современный стек технологий (за 5 лет кое-что изменилось)

### Более удачный UI
- За основу взят MUI v6.x

<ControlsBox
  controlsJson='[
    {
      "title": "END_DEMO",
      "label": "Estimate Corrector (English version 2024)",
      "type": "link",
      "link": "/p/estimate-corrector-2024"
    },
    {
      "title": "NEXT",
      "label": "Продолжение на Хабре (2024)",
      "type": "link",
      "link": "https://habr.com/ru/articles/874226/"
    }
  ]'
/>

рабочие_моменты

💳 Offline Trade-In (Level Up) #smartpriceRINGEO #рабочие_моменты 2024.8 [3/3]

Как не сломать UX на стадии проектирования #ретроспектива #маркетинг #рабочие_моменты 2024.8 [2/3]

Наши стандарты DX #рабочие_моменты 2024.8 [1/3]

Теория Вероятностей в действии (2019) // Методика #EBS #рабочие_моменты