VavaStone - учёт, продажи и доставка для индустрии натурального камня

Задача

VavaStone - международная платформа для учёта, продажи и доставки натурального камня, то есть предметная область со сложной логистикой: складские остатки по нескольким складам, доставка с расчётом по весу, ценообразование в нескольких валютах и мультинациональные пользовательские сценарии. Инженерная команда была распределена по нескольким странам. К моменту, когда я присоединился, микросервисная архитектура на Go + React работала, но накопила трение: границы сервисов были неявными, локальная разработка требовала серьёзной настройки, а онбординг новых инженеров занимал слишком много времени.

Найм занял один день: созвонились в WhatsApp, поговорили, и тем же вечером подписали контракт и начали работать.

В рабочем Slack меня назвали абстрактным DEV, но по факту я был fullstack-разработчиком и занимался и фронтендом, и бэкендом на Go.

Исследование

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

Рассмотренные варианты

1. Внедрить service mesh и автогенерируемые клиенты - слишком тяжело для размера команды; миграция существующих сервисов заняла бы месяцы.
2. Добавить OpenAPI-спецификации и генерировать типизированные клиенты для каждого сервиса - выбрано как прагматичная золотая середина. Явные контракты, генерируемые типы, без новой инфраструктуры.
3. Перейти на монорепозиторий с общими пакетами типов - отложено; жизнеспособно в долгосрочной перспективе, но слишком болезненно в краткосрочной.

Решение

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

Реализация

Добавил OpenAPI-описания к сервисам, с которыми работал, и сгенерировал типы TypeScript-клиента, используемые React-фронтендом. Это ловило класс багов на этапе компиляции, которые раньше всплывали только на стейджинге. Отрефакторил локальную настройку Kubernetes в задокументированный workflow на основе Makefile - `make dev-up` вместо шести ручных команд. Новые инженеры могли запустить весь стек локально в первый же день.

На продуктовой стороне реализовал улучшения модуля управления складом и заказами: отображение остатков по складам, отслеживание статусов заказов и сценарии расчёта стоимости доставки. Активно участвовал в найме: писал описания вакансий, проводил технические собеседования и провёл первый структурированный онбординг для двух новых инженеров.

Результат

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

Демо

Укрепление типов между бэкендом и фронтендом свелось к одному рабочему варианту: генерировать аннотацию под каждый api-вызов. Руками по всей поверхности это долго, поэтому я протестировал доступный на тот момент ИИ - ещё сырой - и выбрал его, чтобы ускорить эту работу. Здесь запись R&D по этому подходу.

Вторая часть той же истории: утилита OpenAPI читает эти аннотации вызовов и генерирует по ним типы для фронтенда. Дальше несоответствие типов само всплывает ошибкой компиляции, а это снимает целую категорию runtime-багов интеграции.

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

Ранняя альфа прототипа системы отчётности - аналитика заказов и складских остатков, построенная поверх типобезопасного слоя данных.

Показ заказчику одного из реализованных экранов на видеозвонке, вместе с кодом за ним: генерация отчёта запущена под отладчиком в VS Code и остановлена на точке останова в шаге, который загружает выбранные сущности из базы. Камера заказчика размыта.

Отзыв заказчика о готовом модуле в канале отчётности. Договорились сначала показывать отчёт на сайте, а экспорт в XLS или PDF вынести в кнопку, и в ответ пришло «Good progress!!». Фото заказчика и личная реплика скрыты.