В середине-конце нулевых работал в районной кадастровой палате. Мы одними из первых в РФ сделали электронную кадастровую карту, на базе ГИС (геоинформационная система) MapInfo. Файл-серверное решение: карта — это набор файлов-слоёв, лежащих на диске сервера в расшаренной папке.

Однажды кто-то нечайно испортил слой земельных участков. Результат был похож на последовательность:
• ctrl+A
• ctrl+C
• ctrl+V ×2
Заметили это только через 2 дня, когда наткнулись в ходе расследования начавшихся сбоев интегрированного с этой картой специализированного программного комплекса.
За эти же 2 дня, по «счастливому» стечению обстоятельств, было проделано много неповторимой работы, поэтому восстанавливать карту из бэкапа было нельзя.

Решили чистить вручную. Чуть более 35 тысяч земельных участков должны были вновь стать уникальными — соответственно примерно 70 тысяч дублей надо было удалить. Так как эта работа требовала крайней внимательности (нельзя удалить не тот экземпляр участка), хорошего понимания механик этой ГИС и особенностей интеграции со служебной системой, поручили сисадмину-технологу — то есть мне.

За первые два дня, работая по 16 часов, смог вычистить только около 20 тысяч дублей.
Следующие два дня по 17 часов были потрачены на изучение базовой теории реляционных БД, SQL (поддерживаемого этой ГИС) и немного MapBasic (язык программирования, на котором пишут плагины для этой ГИС).
А на пятый день за 3 часа остаток работы по очистке от дублей был закончен.

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

В качестве отправной точки для ответа на вопрос о том, с какими артефактами доводилось работать или в каком виде передавали задание на разработку, предлагаю рассмотреть следующее рассуждение:

Инфосистема — это совокупность (1) взаимодействующих (2) компонентов, которая что-то делает (3) с какими-то данными (4) при срабатывании каких-то триггеров (5) для достижения каких-то целей (6).

(1) Совокупность (компонентная архитектура) описывается:
• UML component dia
• C4

(1) Эти компоненты крутятся на железе (архитектура исполнения), что можно описать:
• UML deployment dia
• C4

(2) Взаимодействие компонентов:
• UML component dia
• C4
• UML sequence dia

(3) Работа (логика) компонента:
• UML activity dia
• блок-схема

(4) Данные, с которыми работает система:
• UML ERD
• class dia

(5) Триггеры возникают как в самой системе (расписание, отложенные обработчики), так и в контексте системы (люди, внешние системы):
• UML use case dia
• BPMN
• CJM
• C4

(5) Триггеры бывают обращениями извне (REST/SOAP/etc. API и брокер) или предопределёнными расписанием (шедулеры, кроны, демоны, etc.):
• проект API, описания отдельных методов
• проект очередей/топиков брокера, описания отдельных топиков
• проект событий по расписанию, описания отдельных событий/тасок

(5) Чтобы триггер мог быть вызван человеком, система должна обладать HMI:
• макеты UI
• описание экранных форм
• карта экранных форм

(5) С этим HMI надо как-то работать:
• use case
• CJM

(6) Зачем-то эта работа нужна:
• user story
• use case

#инструмент #собеседование

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

Вот вопросы. Тут всё сразу. Они относятся к разным этапам продвижения по воронке найма, поэтому не ожидаю все ответы сразу. Порядок не значит приоритетность. И это вопросы как запрос информации, а не как требования.

• Обратная связь по итогам встреч: сильные и слабые стороны, рекомендации по поднятию уровня
• Формат работы: офис, гибрид, удалёнка
• Возможность работать какое-то время из-за границы
• Служебное жильё или иное содействие при переезде
• Команда: ролевой и численный составы, смежники
• Стадия проекта/продукта
• Инструментальный стек: в чём и с чем придётся работать
• Задачи: виды и масштаб
• Флоу задачи
• Онбординг: продолжительность, помощь
• Знакомство и тимбилдинг: частота и формат
• Бронь (от мобилизации) и ИТ-аккредитация
• ДМС: наличие, условия, объём
• Карьера: трек, перспективы
• Зарплата: вся в окладе или с учётом премии
• Пересмотр ЗП: частота, условия
• Командировки: частота и обязательность
• Релокация: возможность для меня, желательность для работодателя, готовность содействовать

#собеседование

Хоть я и с 2007 года айтишник, в ИТ-отрасли работать начал лишь с первой половины 2021. С тех пор по сегодняшний день мной:
• пройдено более 100 собеседований — нюанс ныне покинутого мной аутсорса, плюс для тонуса хожу;
• проведено 145 собеседований и техсрезов (которые провожу в формате собеседования) — столько в моей Notion-базе протоколов;
• просмотрено более 50 собеседований, проведённых коллегами: вживую или на записи.

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

До трёх четвертей проведённых на моих глазах собеседований — плохие. А именно, процессу проверки присущи 1..N методологических просчётов:
• несоответствие портрета кандидата потребности заказчика найма;
• не релевантные предстоящим задачам вопросы;
• непрофильный интервьюер;
• преобладание теоретических вопросов;
• практические задачи — на основе экзотических «однажды у соседа»-ситуаций;
• формулировка практических задач — «из головы»;
• отсутствие наблюдаемой структуры или замысла в последовательности вопросов;
• формулировка вопросов таким образом, что ответ на них будет говорить скорее о знакомстве с терминами, а не о понимании их смысла и существа вопросов;
• избыточное число участников интервью;
• избыточное количество этапов проверки.

«Критикуя, предлагай»? Мне пришлось однажды сформулировать свой подход к процессу проверки, чтобы внедрить его в процедуру найма и подготовки. А развёрнутое описание вышеперечисленных просчётов — вряд ли здесь имеет смысл быть. По крайней мере, в этот раз.

#инструмент #собеседование

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

Примеры последствий такого упущения у всех на виду. Можно найти много информации про городские кварталы, дороги к которым наотказ забиты пробками в часы пик, в школы которых не записаться, в которых нет медпунктов и регулярно сбоит коммунальное обеспечение. Поэтому, готовясь в начале десятых годов стать начальником сектора ИСОГД при районной архитектуре, я думал в качестве тестового задания просить прислать сохранение из Cities: Skylines, в котором город развит до населения в полмиллиона, чтобы оценить "красноту дорожного трафика". 🙂

Хорошо, что в крупных городах стали всё чаще понимать, что девелопер — это от слова development (развитие территории), а не construction (освоение пятна застройки).

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

PS: Начальником сектора не стал, кстати. Подготовил положение, оргштатную структуру, должностные инструкции, проект постановления об учреждении и всё необходимое для мун.закупки ИСОГД. А на позицию взяли красивую девушку. И через полгода-год упразднили сектор.

#проектирование

Классификация инфопотоков на уровне контекста
Назначение интеграции (как проекта) — обеспечить движение потоков данных (для каких-то целей).

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

Общие критерии (безотносительно бизнес-домена):
• По частоте
→ реального времени — поток идёт непрекращающимися порциями (напр. АСУТП)
→ оперативный — поток создаётся ежедневными многократными событиями (обычно триггер — работа юзеров)
→ периодический — по известному расписанию
→ эпизодический — может возникнуть в любой момент, но случается редко
• По срочности/синхронности
→ синхронный — нужен получателю здесь и сейчас (напр., нужно получить опции для dropdown в UI или прямо сейчас узнать ID создаваемой сущности)
→ асинхронный — м.б. предоставлен с задержкой (напр., результат клиринга операции оплаты)
• По инициативе
→ активный — мы сами обращаемся вовне, чтобы отдать или забрать данные
→ пассивный — к нам обращаются извне с данными или запросом их
• По направлению потока
→ входящий — мы получаем данные
→ исходящий — мы отдаем данные
• По подготовленности
→ трансформированный — данные представлены моделью, с которой получатель умеет работать
→ сырой — данные д.б. трансформированы в модель, с которой получатель умеет работать: отправителем, получателем или «по пути»
• По формату
→ данные — поток в виде собственно данных (запись БД, текст в Kafka-сообщении или теле запроса/ответа)
→ файл — данные передаются в виде файла (*.csv, *.xml, *.xls и т.п.)
• По объёму
→ большой — предпочтительно обработать в порядке очереди (асинхронно)
→ малый — допустимо обработать синхронно
• По автоматичности
→ автоматический — возможен программный обмен без участия человека
→ автоматизированный — возможен программный обмен с участием человека
→ ручной — возможен только ручной ввод/вывод пользователем через UI
• По публичности данных
→ закрытый
→ открытый

Специфичные:
Помимо общих критериев, бывают ещё домен-специфичные, проект-специфичные и прочие, например: получатель/отправитель, назначение, критичность, принадлежность к БП, приоритетность реализации и т.п.

Фильтрация в запросах к списковым GET-эндпоинтам (via POST)

1. По модели
Для каждого вида данных предусматривается свой "фильтрующий объект", в котором есть атрибуты, специфические для модели вида данных. Например:

{
  "filter":
  {
    "loc": "Москва",
    "dateFrom": "2024-01-01",
    "dateTo": "2024-03-31",
    "items": [1, 3, 6]
  }
}

– Для этого подхода надо сразу знать модель данных.
– Изменение модели влечёт к переделке реализации фильтра.
+ Этот "фильтрующий объект" применим ко в т.ч. иерархической модели (имеющей вложенности).
+ Этот "фильтрующий объект" легко читаем и используем.

2. По контексту
"Фильтрующий объект" также предопределён, но содержит не поля модели данных, а свойства абстрактного контекста, который уже в сервисе интерпретируется, маппясь на поля модели. Например:

{
  "filter":
  {
    "loc": "Москва",
    "quarter": "2024.1",
    "overallStatus": "READY_TO_BE_SHIPPED"
  }
}

+ Для этого подхода не надо знать модель данных — лишь бизнес-требования к фильтрации.
+ Изменение модели редко влечёт к переделке реализации фильтра.
+ Этот "фильтрующий объект" применим ко в т.ч. иерархической модели (имеющей вложенности).
+ Этот "фильтрующий объект" легко читаем и используем.
– (Не увидел сходу)

3. SQL-like
Есть стандартный "фильтрующий объект", могущий быть применённым к любой модели. Например:

{
  "filter":
  {
    "type": "GROUP",
    "operation": "AND",
    "filters": [
      {
        "type": "FILTER",
        "operation": "EQUALS",
        "field": "loc",
        "values": ["Москва"]  //для EQUALS — только первый элемент
      },
      {
        "type": "FILTER",
        "operation": "BETWEEN",
        "field": "date",
        "values": ["2024-01-01", "2024-03-31"] //для BETWEEN — только первые 2 элемента
      },
      {
        "type": "FILTER",
        "operation": "IN",
        "field": "item",
        "values": [1, 3, 6]
      }
    ]
  }
}

• Имена полей, подставляемые в "фильтрующий объект", м.б. получены из отдельного эндпоинта — ответ от него будет типа "вот какой набор столбцов бывает в ответе GET /entities/list".
+ Для реализации этого подхода модель вида данных безразлична. Т.е. делаем один раз для всех видов данных.
+ Этот фильтр безразличен к изменениям модели в процессе эксплуатации.
+ Предельно гибкий фильтр.
– Наивысший (из предложенных) порог вхождения для пользователя (программиста, аналитика, консультанта).
– Модель данных д.б. "плоской" (без вложенностей). Хотя тут ещё можно подумать.

#api

Вариант реализации асинхронного логирования пользовательских действий, изменяющих данные.
+ Логи пишутся отдельно от логируемых действий — снижение нагрузки на СУБД, засчёт чего...
+ Повышается пропускная способность СУБД для пиковых нагрузок.
+ Имеем отдельную БД с логами для тяжеловесного анализа их (сложные запросы или манипуляция с большими объёмами данных) — меньше нагрузка на рабочую СУБД.
+ Пиковые скачки нагрузки при логировании сглаживаются, размазываясь во времени.
– Ловятся только изменения в отдельных таблицах. Не залогать комплексное изменение во многих таблицах. Хотя тут не копал глубоко — допускаю, что можно вытянуть всю транзакцию, а не только data-change'и записей по-таблично.
– Нет контекстных данных об изменении: при какой операции изменились данные, кем изменены, как долго выполнялось изменение и т.п.
– Необходимо обслуживать как минимум ещё один контейнер или сервер.

#архитектура #логи #async

БТ (бизнес-требования) — ради чего бизнес затеял делать что-то. Цели. Увеличить конверсию, уменьшить издержки, снизить загруженность, увеличить привлечение, снизить отток, увеличить лояльность... Такие словосочетания ожидаются в БТ. Желательно с «засчёт...», «путём...» и т.п.

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

БП (бизнес-правила) — нормативные или устоявшиеся в бизнес-среде ограничения и предписания для бизнес-процессов. Например, минимальная сумма заказа (один имбирь не повезём), его максимальная масса (чтобы курьер не сломался) и, следовательно, обязательность учёта массы упаковки при подсчёте массы заказа.

#проектирование

Бизнес-возможности
На верхнем уровне архитектуры «сидят» бизнес-возможности (business capabilities, BC). Это та ценность, которую в целевую среду несёт бизнес, «выпятив» в эту среду своё решение. Их обычно мало. Например:
• ТВ-платформа предоставляет линейный и хранимый контент, инструменты оплаты доступа к нему и рекламные слоты.
• Складская система нужна для учёта имущества, его движения и инвентаризации.
• Мессенджер позволяет мгновенно обмениваться текстовыми сообщениями, аудио- и видео-записями и файлами.

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

Из BC далее можно вывести бизнес-процессы высшего для системы уровня. А из них начнут вырисовываться и роли, и ключевые сущности (entities), и события (events) для EDA, и бизнес-процессы следующих уровней детализации, из которых в свою очередь станут понятны варианты использования (use cases). Но это уже совсем другая история.

#проектирование

Синхронные интеграции
REST API, SOAP, gRPC, GraphQL, etc. — среди синхронных «способов интеграции» есть много вариантов.

Это не все. И у них разные возможности и области применимости. Но есть у них и общая принципиальная часть, которую интегратору полезно понимать, чтобы а) начать осваивать конкретный «способ» и б) спроектировать взаимодействие конкретным «способом». На эту общую часть можно посмотреть с 3-ёх перспектив (точек зрения):

Поведенческая
• Они все — клиент-серверные, т.е. взаимодействующих компонентов два, и один из них — компонент-заказчик взаимодействия (клиент; например, фронтенд), а второй — компонент-исполнитель (сервер; бэкенд-приложение).
• Акт взаимодействия состоит из запроса и ответа (на sequence dia это 2 стрелки: сплошная «туда» и пунктирная «обратно»).
• Клиент, отправив серверу запрос, ждёт от него ответ; это не мешает клиенту параллельно выполнять другие процессы, просто один из процессов ждёт ответ на запрос.
• Сервер, получив запрос, запускает исполнение конкретной функции (логики, обработки запроса), в алгоритме которой одним из шагов является отправка ответа клиенту.

Структурная
Запрос→обработка→ответ — получающаяся структура синхронного взаимодействия.
Запросом клиент просит сервер совершить конкретную работу. Запрос — это как постановка задачи.
Обработкой сервер совершает эту работу. Обработка — это как исполнение задачи.
Ответом сервер отчитывается о выполнении работы, сообщая результат. Ответ — это как отчёт о выполнении задачи.
Чтобы поставить задачу — что нужно указать и чем обеспечить?
Чтобы исполнить задачу — что нужно знать?
Чтобы отчитаться о выполнении — что нужно сообщить?

Описательная
Описание «API-ручки», исходя из поведения и структуры, сводится к таким типовым разделам:
• Запрос:
→ функция (тип запроса + path-часть эндпоинта в REST API) — это заголовок задачи
→ назначение функции (напр.: создать юзера, обновить заказ, постричь лоха) — это цель задачи
→ адрес (host-часть эндпоинта в REST API) — это исполнитель
→ параметры вызова (query-параметры в REST API) — это уточнения и дополнения
→ полезная нагрузка (тело запроса в REST API) — это вводные и приложения
• Обработка:
→ что и как делает сервер, получив запрос: что предварительно проверяет, что и откуда собирает, что из этого (и полученного из запроса) делает, куда и как раскладывает.
• Ответ (позитивный):
→ код ответа, можно вкратце: ок/не ок.
→ полезная нагрузка (тело ответа в REST API)
• Ошибки (негативные ответы):
→ по каким причинам могут возникать
→ кто виноват в возникновении
→ что вернуть в случае каждой из причин
... — это часто довольно большой раздел, т.к. не выполнить задачу можно всегда гораздо большим количеством способов, чем выполнить.

Т.е. для любых синхронных API можно применить один шаблон и по нему описывать и REST API, и gRPC, и GraphQL, и SAP-овский RFC, и чёрта лысого.

P.S.: асинхронная интеграция отличается поведенчески только отсутствием ожидания ответа, а структурно — самого ответа. Со всеми вытекающими из этого последствиями проектирования.

#sync #api #проектирование