📑 Что должно быть в документации по интеграциям?

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

Что такое интеграция между системами? Это "диалог" между системами. И работа аналитика сводится к созданию сценария взаимодействия для такого "диалога".
Сам сценарий мы рассмотрим внимательно в следующий раз. Но чтобы документация была полноценной, нужно указать дополнительные атрибуты.

🎾 Протоколы обмена информацией
В моей практике в одной интеграции встретились сразу 3 протокола обмена. И не стоит забывать указывать это в документации.

🎾 Sequence diagrams
Бывает, что потребители документации не хотят знать подробностей о работе систем. Для верхнеуровневого обзора последовательности шагов взаимодействия подойдет sequence диаграмма.

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

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

🎾 Модель физических данных, если она предусмотрена проектом.
или ERD. Редкая интеграция обходится без участия базы, поэтому не забывайте прописывать ее.

Именно такую схему я использую при создании документации для интеграций.

Ловите рецепт на предпраздничный день

Табличек много не бывает

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

Обычно аналитикам нужно сделать универсальную документацию, понятную и бизнесу, и разработчику. Как это сделать при документировании интеграций?

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

✴️ Краткое описание шага. Этот столбец предназначен для бизнес-заказчиков, которым важно получить общее представление о логике функционирования системы или конкретной функции/метода.

✴️ Направление. Такой столбец полезен в многоуровневых интеграциях, где можно запутаться между системами. Обычно его тоже смотрит бизнес.

✴️ Описание. Здесь содержится подробная информация для разработчиков: технические детали реализации, имена используемых методов, ключи для поиска в кешах и прочие важные аспекты.

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

· Такой подход помогает не только упростить восприятие информации, но и сделать процесс разработки более структурированным и организованным.
Как считаете, такой формат был бы вам удобен?
Какие шаблоны у вас выработались? Расскажите в комментариях

Diagramm-as-code – удобно?

Раз уж начали говорить про документацию, давайте обсудим самое насущное. Что чаще всего делает аналитик? Правильно, рисует диаграммы. Но это полбеды. Диаграммы нужно править. И не один раз. Обычные рисовалки как draw.io требуют много времени на правки, и я полюбила подход, когда нужно писать код для создания диаграмм.

Что рисуем
flowcharts, sequence diagrams, class diagrams, entity relationship diagrams

Какие плюсы я увидела
➕ Простота внесения изменений
➕ Возможность совместной работы

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


Какие инструменты рекомендую

🟤 Mermaid
простой и легкий инструмент, основанный на Markdown-подобном синтаксисе для создания различных типов диаграмм.

🔹 Поддерживает множество форматов вывода, таких как SVG, PNG и PDF.
🔹 Простота использования благодаря легкому синтаксису.
🔹 Может использоваться в паре с платформами вроде GitHub Pages, ReadTheDocs и MkDocs для автоматического отображения диаграмм.

Для visual studio Code требует отдельного плагина.

🟤 PlantUML
Мощный генератор UML-диаграмм, использующий собственный текстовый язык для построения классов, последовательности действий, компонентов и другой сложной архитектуры программного обеспечения.

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

PlantUML я использовала онлайн. Редакторов много, вот один из них https://editor.plantuml.com/


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

Нашла на просторах интернетов. Не смогла пройти мимо.
Жиза, коллеги?))

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

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

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

Типы БД

Для начала разберемся, какие бывают базы и почему они разные, для каких задач подойдут.

🔘 Реляционные

Этот тип основан на концепции отношений (таблиц), где информация представлена в виде строк и столбцов. Данные организованы в четкую структуру, которая обеспечивается системой ограничений и ключей.

Примеры

▪️MySQL: Бесплатная открытая СУБД, активно используется в веб-приложениях и малых/средних предприятиях.
▪️PostgreSQL: Открытая СУБД с мощным функционалом, популярной в финансовых и научных расчетах.
▪️Microsoft SQL Server: Коммерческий продукт от Microsoft, популярный в крупных компаниях и организациях.
▪️Oracle Database: Ведущая коммерческая СУБД, известная своей мощностью и возможностями. По известным причинам почти не используется у нас.

🔘 Документоориентированные (NoSQL)

Эти системы хранят данные в виде "документов", представленных в форматах JSON, XML или YAML. Каждый документ самодостаточен и может содержать вложенные поля, что удобно для нерегламентированной структуры данных.

Примеры

▪️MongoDB: Одна из самых известных документоориентированных СУБД, популярна в веб-приложениях и стартапах.
▪️Couchbase: Используется для мобильных и web-приложений, где требуются высокие темпы обработки данных.
▪️ArangoDB: Гибридная СУБД, поддерживающая различные модели данных (документы, графы).

🔘Key-value

Эти СУБД хранят пары "ключ-значение", где ключ однозначно идентифицирует соответствующее значение. Часто применяются для временного хранения и кэширования данных.

Примеры

▪️Redis: Очень быстрая in-memory база данных, популярная для кэша, очередей сообщений и сессий.
▪️Memcached: Еще одно простое и быстрое решение для кэширования данных.
▪️RocksDB: Внутренняя база данных Facebook, используемая для высокоэффективных приложений.

🔘 Колоночные

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

Примеры

▪️ClickHouse: Российская СУБД, популярная в аналитике и обработке больших объемов данных.
▪️Vertica: Система от Micro Focus, нацеленная на аналитические задачи.
▪️Apache Kudu: Проект Cloudera для обработки больших данных.

🔘 Графовые

Эти СУБД специализируются на представлении данных в виде графов (вершин и ребер), показывая взаимоотношения между сущностями. Хорошо подходят для социальной аналитики, обнаружения мошенничества и картографии путей.

Примеры

▪️Neo4j: Известная графовая СУБД, используемая крупными компаниями.
▪️JanusGraph: Масштабируемая графовая база данных с поддержкой больших объемов данных.
▪️AllegroGraph: СУБД от Franz Inc., популярная в областях семантического анализа.

🔘 Time-series

Эти СУБД предназначены специально для хранения временных рядов, таких как показания датчиков, рыночные котировки акций и статистики производительности.

Примеры

▪️InfluxDB: Самая популярная time-series СУБД, ориентирована на IoT и DevOps.
Prometheus: Система сбора метрик и мониторинга.
▪️OpenTSDB: Open-source решение для больших временных серий.

Реляционные или нет?

В начале пути создания системы встает вопрос, какой тип БД выбрать? Обычно выбор стоит между реляционной и NoSQL базой. Оба типа обладают своими сильными сторонами и предназначены для различных случаев использования. Разберем, как выбрать между ними.

🟠 Реляционные

🔸Особенности

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

🔸 Преимущества

Строгая структура данных гарантирует ясность и предсказуемость.
Высокий уровень безопасности и устойчивости данных.

🔸Недостатки

Трудности с масштабированием для больших объемов данных.
Могут быть неэффективны для постоянно меняющейся структуры данных.
Сложность адаптации к изменениям структуры данных (необходимость миграции данных).

🔸Примеры ситуаций, когда предпочтительна реляционная база данных

Банковские системы: необходимость высокого уровня безопасности и согласованности данных.
Финансовая отчётность: требование точного соблюдения стандартов отчетности и соответствия стандартам регулирования.
CRM-системы: точные данные о клиентах и история взаимодействии необходимы для анализа и маркетинга.

🟠 NoSQL базы данных

🔸Особенности

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

🔸Преимущества

Гарантированная масштабируемость для больших объемов данных.
Легко адаптируются к изменению структуры данных.
Повышенная производительность для операций чтения и записи.
Лучшее соответствие современным задачам обработки больших данных и распределённых систем.

🔸Недостатки

Сложность выполнения сложных запросов и соединений.
Потенциальные риски нарушения целостности данных.

🔸Примеры ситуаций, когда предпочтительны NoSQL базы данных

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

❓Рассмотрим кейсы, в которых нужно выбрать тип бд.

🅰️ Онлайн-магазин книг

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

🅱️ Социальная сеть

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

Итог

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

Понедельник - день тяжелый. Хотите интересную задачку, чтобы размять мозг в начале недели?

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

- Собирать подробную историю болезни пациента, включающую разнообразные медицинские данные: анализы крови, рентгеновские снимки, УЗИ, МРТ, ЭКГ и многие другие.
- Предоставлять врачам быстрый доступ ко всей истории болезней пациента
- Проводить регулярный анализ данных пациентов для выявления закономерностей заболеваний и рисков осложнений.
- Вести учёт лечения и назначаемых препаратов пациентам.
- Планировать профилактические мероприятия и диспансеризацию.

❓Какой тип базы данных вы бы выбрали для этого проекта: реляционный или NoSQL? расскажите в комментариях, почему?

📝Ответ расскажу вечером

Неловко получилось...
🤣

Идеальным вариантом будет комбинация двух типов баз данных:

🏥 Реляционная база данных
используется для хранения точной и последовательной информации о пациенте, врачах, лечении, лекарствах, результатах обследований и истории болезней. Сюда относятся стандартные диагностические данные, такие как имя пациента, фамилия врача, назначения лекарств и регулярные проверки.

🏥 NoSQL база данных
используется для хранения разнородных данных — изображений (рентгеновских снимков, МРТ, КТ), биоэлектрических сигналов (ЭКГ), лабораторных данных и нестандартных показателей. Эта база будет отвечать за расширение набора данных и экспериментальные нововведения.

Такой подход позволяет сочетать преимущества обеих технологий и обеспечить оптимальное функционирование системы медицинского учёта.

Кто едет на ЛАФ? признавайтесь)))

Кажется, мне пора открывать свое hr-агентство... а пока попробуем здесь :)

📣 ищу аналитика уровня middle и выше на интересный банковский проект . нужен хороший технический бекграунд (sql, очереди и всякое такое)
есть желающие?

Выбор СУБД

Разобрались с типом БД. Но в каждом типе представлено много разных моделей СУБД. Как понять, какую выбрать? Правда ли, что каждая СУБД хороша для своих задач?
Рассмотрим особенности каждой из популярных СУБД и рекомендации по выбору.
📌 Сохраняйте себе, чтобы быстро найти эту памятку, когда будете выбирать СУБД для проекта.

🕹 MySQL

Особенности
- Открытый исходный код, распространенная среди разработчиков.
- Поддерживает реляционную структуру данных (таблицы, строки).
- Подходит для простых запросов и относительно небольших объемов данных.
- Хорошо интегрируется с PHP и JavaScript фреймворками.

Рекомендуемые задачи
- Веб-приложения с небольшими нагрузками (например, блоги, небольшие корпоративные порталы).
- Простые системы учета товаров/заказов/сотрудников.
- Хранение структурированных данных, требующих строгих отношений между таблицами.


🕹 PostgreSQL
Особенности
- Более мощная альтернатива MySQL с поддержкой сложных SQL-запросов и расширенных функций.
- Гибкая поддержка транзакций ACID, оптимизированная работа с большими объемами данных.
- Возможность создавать расширения, хранимые процедуры и триггеры.

Рекомендуемые задачи
- Средние и крупные проекты с большим объемом данных и сложными структурами.
- Приложения, которым важна высокая производительность и надежность.
- Географические приложения благодаря встроенной поддержке пространственных данных (расширение PostGIS).


🕹 MongoDB
Особенности
- NoSQL база данных с документоориентированной моделью хранения данных.
- Высокая гибкость схемы базы данных — возможность хранить разнородные данные без жесткой структуры.
- Отличается высокой производительностью при работе с большими массивами документов.

Рекомендуемые задачи
- Масштабируемые веб-сервисы и мобильные приложения с частым изменением структуры данных.
- Работа с полуструктурированными или слабо формализованными данными (логирование действий пользователей, социальные сети).
- Анализ больших объемов неструктурированных данных (Big Data).


🕹 ClickHouse
Особенности
- Колоночная СУБД, разработанная специально для аналитики и обработки огромных объемов данных в режиме реального времени.
- Обладает уникальной скоростью обработки аналитических запросов (OLAP), отлично масштабируется горизонтально.
- Идеальна для сбора и анализа метрик, логирования событий и построения дашбордов.

Рекомендуемые задачи
- Аналитика поведения пользователей, обработка журналов событий.
- Реалтайм-аналитические запросы и построение отчетов по данным большого объема.
- Логирование активности приложений и серверов (системы мониторинга, BI-платформы).

У кого совпало? 😆

Теперь, когда мы выбрали СУБД, можно приступать к модели данных. Эта часть является одним из моих любимых процессов при проектировании системы. Но очень редко я следую правилам. Сначала я думала, что я нетерпелива, чтобы проходить последовательно по всем процессам. А потом я поняла, что эти знания вложены в меня настолько глубоко, что я «из коробки» проектирую модель нормализованной и со всеми ключами.
Но давайте разложим по полочкам весь процесс. Будет долго, но эффективно. Такой очевидный этап как сбор требований мы пропустим и перейдем сразу к данным.

🏮Сбор и классификация сущностей
Определяется перечень объектов предметной области (сущностей), которые должны быть представлены в модели данных. Эти сущности классифицируются по типу (например, клиенты, товары, заказы)


🏮 Определение отношений между сущностями
Далее устанавливаются связи между выявленными сущностями. Например, один клиент может иметь много заказов, а один заказ может содержать несколько товаров. Связи бывают трёх типов:
- Один-к-одному (1:1)
- Один-ко-многим (1:N)
- Многие-ко-многим (N:M)

🏮 Создание концептуальной модели данных
Концептуальная модель отражает высокоуровневую структуру данных без привязки к конкретной СУБД. Обычно используется нотация ERD (Entity Relationship Diagram). Здесь отражаются сущности, их атрибуты и взаимосвязи.

🏮 Нормализация данных
Нормализация является важным этапом, целью которого является устранение избыточности данных и повышение целостности базы данных. Она заключается в последовательном приведении схемы базы данных к определённым формальным нормам (нормальные формы):

- Первая нормальная форма (1NF): Уничтожение повторяющихся групп.
- Вторая нормальная форма (2NF): Устранение частичной зависимости атрибутов от первичного ключа.
- Третья нормальная форма (3NF): Исключение транзитивной зависимости атрибутов.
- Четвёртая нормальная форма (4NF): Разделение многозначных зависимостей.
- Пятая нормальная форма (5NF): Минимизация аномалий обновления путём разбиения сложных зависимостей.

Этот процесс позволяет минимизировать дублирование данных и повысить производительность запросов.


🏮 Физическое проектирование
На данном этапе разрабатывается физическая структура базы данных, учитывающая особенности выбранной СУБД. Определяются типы полей, индексы, ограничения целостности, триггеры и другие элементы физической структуры.

Примеры решений физического уровня:
- Выбор оптимального типа поля (INT, VARCHAR, DATE и др.)
- Создание уникальных ключей и индексов для ускорения выборок.


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

Сбор сущностей

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

📒 Особенности и условия:
1. За просрочку возврата полагается штраф
2. Книгу можно взять домой или в читальный зал библиотеки. Статусы книги должны различаться.
3. Система предназначена не только для просмотра статуса книги, но и места ее хранения на полке

Как говорили ранее, начинаем со сбора сущностей. Напишите в комментариях, какие сущности вы бы предложили. Вечером покажу свой вариант :)