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

Задача

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

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

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

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

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

Решение

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

Реализация

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

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

Результат

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

Демо

Видео ниже демонстрирует результат обеспечения строгого соответствия типов при вызовах API — несоответствия типов автоматически всплывают как ошибки компиляции, устраняя целую категорию runtime-багов интеграции.

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

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