ADR. Платёжные выписки
⚠️ Рекомендация по ADR
При формировании ADR следуйте принципам минимальной архитектуры: принимайте только те решения, которые закрывают актуальные риски или потребности текущей итерации разработки.
В ADR допускается описывать несколько последовательных раундов, если они логически связаны и решение в последующем раунде органично вытекает из предыдущего. Однако по возможности стремитесь к атомарности ADR, выделяя отдельные проблемы или проектные задачи в самостоятельные записи. Это существенно упрощает ревью, отслеживание решений и управление архитектурными рисками.
Глоссарий
- OPS - Система внутренних переводов
- PG - Платежный шлюз
- Online - Карточный процессинг
- Prime - Платежный процессинг
- XXI - ABC
- Notification Center - Система позволяющая отправить уведомления пользователю одним из каналов: email, смс, push
- SSO - Система аутентификации
- RoleApp - Система хранения конфигов авторизации. За авторизацию отвечает сама система. RoleApp лишь хранит пользовательские настройки.
Контекст
Формулировка проблемы
Необходимо спроектировать продукт "Выписки".
Проектирование выписок усложняется большим числом интеграций с "внешними" системами.
Информация о операциях хранится в разных системах банка:
- OPS - внутренние переводы
- PG - исходящие внешние переводы
- Online - карточные авторизации
- Prime - процессинговый центр
- XXI - ABC
Окружение проблемы
В данном сценарии рассматривается банк с активной пользовательской базой в 500к пользователей, с перспективами роста до 1кк. Банк давно на рынке с устаявщейся культурой и процессами разработки. В банке постоянно запускаются новые продукты. Большое разнообразие PaaS. Имеются принципы и стандарты разработки. Разработка ведется предпочтительно в крос-функциональных, продуктовых командах использую гибкие методологии Agile.
Надёжность
Наше окружение бесплатно предоставляет нам высокую дотступность наших решений:
- Высоко-доступные БД
- Все наши приложения деплоятся в Высоко-доступное окружение
- Все приложения разворачиваются с высокой избыточностью
- Ошибки на приложениях определяются и проблемные экземпляры выводятся из эксплуатации
Наша задача минимизировать проблемы связанные с отказами внешних (для проектируемой системы) компонет.
Безопастность
Наша инфраструктура бесплатно даёт нам системы:
- пользовательской аутентификации и авторизации
- межсервисной аутентификации и авторизации
- защиту от DDoS атак
Проблемы безопастности не будет затрагиваться на этом этапе проектирования.
Цель
Разработать инициализирующий дизайн для системы генерации платежных выписок.
Требования, ограничения и сценарии атрибутов качества
Функциональные требования (ФТ)
ID | Описание требования | Заказчик | Приоритет (H/M/L) |
|---|---|---|---|
| FR-001 | Пользователь личного кабинета хочет запрашивать выписку за указанный интервал времени, чтобы анализировать данные за нужный мне период. | Технолог. Вася Пупкин | H |
| FR-002 | Пользователь личного кабинета хочет запрашивать выписку с фильтром по счету, чтобы получать данные только по выбранному мной счету. | Технолог. Вася Пупкин | H |
| FR-003 | Пользователь личного кабинета хочет запрашивать выписку с фильтрацией по категории, чтобы быстро найти операции нужного типа. | Технолог. Вася Пупкин | M |
| FR-004 | Пользователь личного кабинета хочет запрашивать выписку с фильтрацией по бренду, чтобы отслеживать операции, связанные с конкретным брендом. | Технолог. Вася Пупкин | M |
| FR-005 | Пользователь личного кабинета хочет запрашивать выписку с фильтрацией по контрагенту, чтобы проверять операции с конкретными контрагентами. | Технолог. Вася Пупкин | M |
| FR-006 | Пользователь личного кабинета хочет запрашивать выписку по произвольной строке поиска, чтобы быстро находить нужную информацию по ключевым словам. | Технолог. Вася Пупкин | L |
| FR-007 | Пользователь личного кабинета хочет скачивать сгенерированную выписку, чтобы использовать её вне личного кабинета. | Технолог. Вася Пупкин | H |
| FR-008 | Пользователь личного кабинета хочет задавать правила генерации регулярных выписок (устанавливать фильтр и задавать расписание в формате CRON), чтобы регулярно получать нужную информацию без дополнительных ручных действий. | Технолог. Вася Пупкин | H |
| FR-009 | Пользователь личного кабинета хочет получать уведомления на почту по завершении генерации выписки, чтобы своевременно узнать, когда данные готовы. | Технолог. Вася Пупкин | H |
| FR-010 | Пользователь личного кабинета хочет, чтобы система автоматически запускала генерацию выписки по заданному мной расписанию, чтобы регулярно получать актуальную информацию без участия пользователя. | Технолог. Вася Пупкин | H |
Нефункциональные требования (НФТ)
ID | Связанные сценарии | Описание требования | Заказчик | Приоритет (H/M/L) | Влияние на архитектуру (H/M/L) |
|---|---|---|---|---|---|
| Security | |||||
| NFR-001 | Все | Система должна обеспечивать разграничение доступа к данным по компании: пользователь может получить доступ только к данным той компании, в которой он является сотрудником. Попытки доступа к чужим данным должны блокироваться и логироваться. | ИБ. Саша Пуговкин | H | L |
| NFR-002 | Все | Сотрудник службы поддержки должен иметь возможность получать доступ к данным любой компании, при наличии соответствующих прав доступа. | ИБ. Саша Пуговкин | H | L |
| NFR-003 | Все | Внутренние системы должны использовать механизмы аутентификации и авторизации для доступа к системе | ИБ. Саша Пуговкин | M | L |
Reliability | |||||
| NFR-004 | Все | Система должна продолжать работать в 99.8 % времени даже при выходе из строя любого из компонент системы | SRE. Петя Яковлев | H | H |
| NFR-005 | Все | При недоступности источника операций система должна обеспечивать доступность не менее 80% пользовательского функционала, критичного для основного сценария использования | SRE. Петя Яковлев | H | H |
| Scalability/Performance | |||||
| NFR-006 | Все | Система должна выдерживать нагрузку 20к DAU | Технолог. Вася Пупкин | H | L |
| NFR-007 | Все | К 2026 г. DAU должно увеличиться до 100к. Система должна предсказуемо масштабироваться. | Технолог. Вася Пупкин | H | M |
| NFR-008 | FR-001, FR-002 | Система должна хранить данные за весь период (предположительный объем данных на 2026 г будет 6 тб. прирост данных каждый год 1 тб) | Технолог. Вася Пупкин | H | H |
| NFR-009 | FR-001, FR-002 | Для 20к DAU выписка за пол года формируется за 1 минуту | Технолог. Вася Пупкин | H | L |
| NFR-010 | FR-007 | Система должна хранить сгенерированные выписки в течении 1 года. Дальше выписки удаляются (предполагаемый объем хранимых данных 1 тб). | Технолог. Вася Пупкин | M | L |
| Resource Utilization | |||||
| NFR-011 | FR-010 | Формирование регулярных выписок нагружает систему не больше 30% от номинального | DP | H | L |
| Agility | |||||
| NFR-012 | Все | Система должны быть лёгкой в расширении и сопровождении | Технолог. Вася Пупкин | M | H |
Ограничения
ID | Описание требования | Заказчик | Влияние на архитектуру (H/M/L) |
|---|---|---|---|
| CON-001 | Корпоративные стандарты (IT как Lego)
| IT как LEGO | H |
| CON-002 | Стек разработки .Net. Команда формируется вокруг этого стека т.к. вектор бизнес линии идёт в сторону диверсификации рисков связанных с наймом scala | Технолог. Вася Пупкин | L |
| CON-003 | Срок разработки конец 2023 года | Технолог. Вася Пупкин | M |
Выделение архитектурно значимых требований
ID | Описание требования | Причина ASR |
|---|---|---|
NFR-004 | Система должна продолжать работать в 99.8 % времени даже при выходе из строя любого из компонент системы | Влияние на надежность |
| NFR-005 | При недоступности источника операций система должна обеспечивать доступность не менее 80% пользовательского функционала, критичного для основного сценария использования. | Влияние на надежность |
| NFR-007 | К 2026 г. DAU должно увеличиться до 100к. Система должна предсказуемо масштабироваться. | Влияние на масштабируемость |
| NFR-008 | Система должна хранить данные за весь период (предположительный объем данных на 2026 г будет 6 тб. прирост данных каждый год 1 тб) | Влияние на масштабируемость |
| NFR-012 | Система должны быть лёгкой в расширении и сопровождении | Влияние на гибкость |
| CON-001 | Корпоративные стандарты (IT как Lego)
| Ограничивает возможный дизайн |
| CON-003 | Срок разработки конец 2023 года | Влияние на сроки |
Решение
Раунд 1. Функциональная декомпозиция
Цель раунда
Поскольку система разрабатывается с нуля, основной целью текущего раунда является первичная функциональная декомпозиция.
Объём имеющихся функциональных требований невелик и может быть реализован одной командой разработки, что делает монолитную архитектуру разумным стартовым выбором. В рамках дальнейшего анализа мы будем опираться именно на этот архитектурный подход.
Драйверы: Все ключевые функциональности. NFR-012
Элемент для проработки
Вся система
Выявление альтернатив и анализ компромиссов (trade-off)
Качество (utility tree) | ID | Архитектурный драйвер | Декомпозиция по слоям (layered) | Декомпозиция по бизнес функциям (Vertical Slice) | Декомпозиция по бизнес возможностям (Modular Monolith) |
|---|---|---|---|---|---|
| Functional Suitability | Все | Все ключевые функциональности | 🟢 | 🟢 | 🟢 |
Security | 🟢 | 🟢 | 🟢 | ||
| Reliability | 🔴 Любая ошибка в низком слое (например, базе или логике) может повлиять на все приложение. Высок риск каскадных сбоев. | 🟢 Ошибка в одном срезе редко затрагивает другие, т.к. связи между срезами минимальны. | 🟢 Ошибки внутри домена локализованы. Риск каскадных сбоев ниже, чем в монолите. | ||
Scalability | 🔴 Монолитное приложение сложно масштабировать, так как отдельные слои требуют разных подходов к масштабированию. | 🟢 Можно независимо оптимизировать и масштабировать отдельные функции, минимизируя лишнюю нагрузку. | 🟢 Масштабируется по доменам, позволяя гибко управлять ресурсами в зависимости от нагрузки. | ||
Agility | NFR-012 | Система должны быть лёгкой в расширении и сопровождении | 🔴 Изменения часто касаются нескольких слоев, что увеличивает время разработки и риски регрессий. | 🟢 Легко вносить изменения, так как код отдельной функции изолирован и изменения не касаются всей системы. | 🟠 Внутри домена изменения вносятся легко, но междоменные изменения требуют дополнительной координации. |
| Complexity | 🟢 Низкая (простая, понятная структура, минимум дополнительной сложности). | 🟢 Низкая (простая, понятная структура, минимум дополнительной сложности). | 🟠 Средняя (нужна архитектурная дисциплина и управление границами доменов, но проще масштабировать по отдельности). | ||
| Resource Utilization | 🟠 Возможны сложности с оптимальным использованием ресурсов, так как все слои делят общие ресурсы монолита. | 🟠 Возможны сложности с оптимальным использованием ресурсов, так как все слои делят общие ресурсы монолита. | 🟢 Позволяет эффективно использовать ресурсы, настроенные отдельно под каждый домен, но может возникнуть некоторое дублирование ресурсов между доменами. | ||
| Constrains | 🟢 | 🟢 | 🟢 |
Принятое решение
Вариант 1 исключаем, так как он имеет ограничения по общей надежности, не позволяет независимо масштабировать отдельные функции и плохо поддерживает эволюционное развитие системы.
Выбираем второй вариант.
Выбор между вторым и третьим вариантом определяется в первую очередь опытом и зрелостью команды в работе с выбранным подходом.
Раунд 2. Проработка сценариев надежности
Цель раунда
Большая надежда в этом решении закладывается на надёжность. Эта уже не первая версия выписок, старая страдала от проблем с доступностью.
Драйверы: Целью этой итерации будет проработка NFR-004, NFR-005.
Элемент для проработки
Вся система
Выявление альтернатив и анализ компромиссов (trade-off)
Качество (utility tree) | ID | Архитектурный драйвер | Асинхронно отливать данные из источников в БД Выписок используя очередь сообщений | Синхронно ходить в источники и забирать операции. |
| Functional Suitability | 🟢 | 🟢 | ||
|---|---|---|---|---|
Security | 🟠 Легче обеспечить контроль доступа и аудит, т.к. данные хранятся локально, но требуется защита реплик и управление доступом. | 🟢 Меньше рисков компрометации, так как данные не хранятся локально; контроль доступа делегируется внешним системам. | ||
| Reliability | NFR-004 | Система должна продолжать работать в 99.8 % времени даже при выходе из строя любого из компонент системы | 🟢 Высокая надёжность, поскольку доступность данных не зависит от текущего состояния внешних источников. | 🔴 Низкая надёжность, так как отказ внешней системы немедленно влияет на работу всей функциональности, зависящей от неё. |
| NFR-005 | При недоступности источника операций система должна обеспечивать доступность не менее 80% пользовательского функционала, критичного для основного сценария использования. | 🟢 Недоступность внешних сервисов ни как не влияет на надежность решения. | 🔴 Для некоторых источников возможно реализовать частичную деградацию, но не для ключевых. | |
Scalability | 🟢 Легко масштабируется, так как чтение происходит локально, и не ограничивается производительностью внешних систем. | 🔴 Сложно масштабировать, т.к. производительность зависит напрямую от пропускной способности и задержек внешних систем. | ||
Agility | 🟢 Использование собственного представления данных существенно повышает гибкость и скорость реализации новых требований, минимизируя зависимость от ограничений и скорости развития внешних систем. Однако, изменения на стороне дальних систем могут стать тяжелым бременем для нас. | 🟢 Высокая гибкость при наличии стабильного API внешних систем. Тем не менее, частые изменения API требуют немедленных изменений интеграции. | ||
| Complexity | 🟠 Средняя сложность: требуется реализация механизма отливки, хранения и актуализации данных, однако сложность централизована и управляемая. | 🟢 Низкая сложность: прямая реализация вызовов API, простота начальной интеграции, но сложность обработки ошибок и ретраев может возрастать. | ||
| Resource Utilization | 🟠 Средние затраты: необходимы ресурсы на хранение и периодическую актуализацию данных, но экономия ресурсов на сетевых вызовах в реальном времени. | 🟠 Может быть высокая нагрузка на ресурсы из-за ожидания сетевых вызовов, обработки ошибок и ретраев. | ||
| Constrains | 🟢 | 🟢 |
Принятое решение
Первое решение кажется самым надежным и перспертивным с точки зрения развития продукта.
Первое решение приносит нам и риски которые мы должны обработать:
- При найме нужно учесть опыт команды в событийном дизайне.
- При асинхронном обмене сообщений нужно продумать:
- гарантии доставки
- обнаружение потерь сообщений
- план доката в случае потери
Уточнение принятого решения
На этом шаге выделим брокер событий, возможно его конфигурацию, компоненты системы отвечающие за обработку входных данных.
| Дизайнерские решение и расположение | Обоснование |
|---|---|
Источник первый сгенерировавший событие обязан сгенерировать уникальный идентификатор операции. Любой из участников проведения платежа: OPS, PG, Online, Prime, XXI | Нам нужен согласованный идентификатор платежа на всех системах. Если хотя бы кто-то не получит этот идентификатор мы не получаем часть операции. |
Все источники обязаны присылать сквозной идентификатор операции. Все источники: OPS, PG, Online, Prime, XXI | Нам нужен согласованный идентификатор платежа на всех системах. Если хотя бы кто-то не получит этот идентификатор мы не получаем часть операции. |
В качестве брокера событий будем использовать Kafka как стандарт в компании
Все источники: OPS, PG, Online, Prime, XXI | Такая конфигурация гарантирует нам попадание и хранения события на стороне брокера |
Использовать шаблон outbox для гарантий отправки сообщения от источника в Kafka Все источники: OPS, PG, Online, Prime, XXI | Шаблон outbox гарантирует нам отправку сообщения в очередь. В противном случае мы рискуем получить несогласованность. |
При отправке сообщения в очередь используется парамерт acks=all. Это и min.insync.replicas 2 гарантируют нам долговечную запись на брокере Все источники: OPS, PG, Online, Prime, XXI | Такая конфигурация гарантирует фиксацию события минимум на двух репликах брокера. |
На стороне выписок НЕ используем авто. подтверждение обработки сообщений. Вручную фиксируем сообщение после гарантированной записи в БД Выписки | Так мы закрываем риск отсутствия записи в локальное хранилище. |
Раунд 3. Проработать сценарий обнаружения потери сообщения и проработать план доката
Цель раунда
На этой итерации закроем риски выявленные с предидущей итерации:
- обнаружение потерь сообщений
- план доката в случае потери
Элемент для проработки
Вся система
Выявление альтернатив и анализ компромиссов (trade-off)
Качество (utility tree) | ID | Архитектурный драйвер | Периодическая полная сверка данных (Full Reconciliation) Периодически (например, раз в сутки или час) синхронизировать все данные из внешних источников, выявляя и устраняя пропуски. | Использование событийного журнала (Event Log) Получение от внешних систем последовательности событий с номерами, позволяющими обнаруживать пропущенные события. | Мониторинг и запрос дельты (Delta polling) Регулярные запросы во внешние системы для получения обновлений (дельты данных за последний период). Сравнение текущего состояния с последним полученным позволяет выявить пропуски. |
|---|---|---|---|---|---|
| Functional Suitability | 🟢 | 🟢 | 🟢 | ||
Security | 🟠 Средняя (нужно периодически запрашивать большие объёмы данных) | 🟢 Высокая (запрашиваются минимальные наборы данных) | 🟠 Средняя (умеренные объёмы данных) | ||
| Reliability | обнаружение потерь сообщений | 🟢 Очень высокая (полностью гарантирует восстановление данных) | 🟢 Высокая (при надёжной реализации журнала событий) | 🟠 Средняя (зависит от реализации механизма дельт) | |
Scalability | 🔴 Низкая (большие объёмы данных, сложность при росте источников) | 🟢 Высокая (легко масштабировать по количеству событий) | 🟠 Средняя (зависит от объёма и частоты изменений) | ||
Agility | 🟠 Средняя (проста в реализации, но большие затраты на изменения) | 🟢 Высокая (легко адаптировать под новые сценарии) | 🟠 Средняя (необходима поддержка API внешних систем) | ||
| Complexity | 🟠 Средняя (простая логика, но ресурсоёмкий и требующий эффективной обработки данных) | 🟠 Средняя (требуется поддержка со стороны внешних систем) | 🟢 Низкая (простота реализации, вся нужная логика уже реализована на стороне XXI) | ||
| Resource Utilization | 🔴 Высокая (ресурсы на обработку и передачу больших объёмов данных) | 🟢 Низкая (минимальные расходы ресурсов на обработку событий) | 🟠 Средняя (зависит от частоты запросов) | ||
| Constrains | 🟢 | 🟢 | 🟢 |
Принятое решение
Подход с Event Log выглядит наилучшим решением. Проблема в том, что мы не можем модифицировать мастер систему и добавить в неё монотонно увеличивающийся идентификатор события.
Выбираем решение 3. Самое лучшее решение из оставшихся.
На первый взгляд автоматизировать докаты мы не можем. Слишком много нюансов в том, почему сообщение не попало в очередь и каждый сценарий нужно разбирать отдельно и исправлять его. Кажется, что если своевременно фиксить проблемы, то таких случаев после отладки быть не должно.
Уточнение принятого решения
| Дизайнерские решение и расположение | Обоснование |
|---|---|
Со стороны XXI нужна синхронная ручка получения балансов на указанный день. Пусть это будет внутренняя rest ручка принимающая на вход дату и счёт | Кроме как на стороне XXI брать гарантированно согласованные балансы нам негде. |
Раунд 4. Выбор БД
Цель раунда
Выбрать персистентное хранилище для сырах операций и сгенерированной выписки.
Драйверы: NFR-007, NFR-008, CON-001
Элемент для проработки
База данных.
Выявление альтернатив и анализ компромиссов (trade-off)
Качество (utility tree) | ID | Архитектурный драйвер | PostgreSQL (без шардинга) | PostgreSQL (шардированный) | Cassandra |
| Functional Suitability | 🟢 | 🟢 | 🟢 | ||
|---|---|---|---|---|---|
Security | 🟢 | 🟢 | 🟢 | ||
| Reliability | 🟠 Средняя, требуются HA и реплики, но при 6 ТБ это выполнимо | 🟢 Высокая, сбой одного шарда не затрагивает всю систему | 🟢 Высокая, встроенная отказоустойчивость | ||
Scalability | NFR-007 | К 2026 г. DAU должно увеличиться до 100к. Система должна предсказуемо масштабироваться. | 🟠 Средняя, под наши цели ограниченно масштабируется | 🟢 Высокая, масштабируемость горизонтальная, но управляемая вручную | 🟢 Высокая, автоматическое горизонтальное масштабирование |
| NFR-008 | Система должна хранить данные за весь период (предположительный объем данных на 2026 г будет 6 тб. прирост данных каждый год 1 тб) | 🟠 Средняя, 6 ТБ ещё можно поддерживать на мощном сервере | 🟢 Высокая, масштабируемость горизонтальная, но управляемая вручную | 🟢 Высокая, автоматическое горизонтальное масштабирование | |
Agility | 🟢 Хорошая гибкость. Запросы, схемы и индексы можно гибко менять, миграции умеренно простые. | 🔴 Низкая гибкость при изменении схемы запросов. Любое изменение может привести к созданию новых таблиц и затратным миграциям. | 🔴 Низкая гибкость при изменении схемы запросов. Любое изменение может привести к созданию новых таблиц и затратным миграциям. | ||
| Complexity | 🟢 Низкая, простота настройки и эксплуатации единого сервера | 🔴 Высокая, сложность шардинга, управления и балансировки данных | 🟠 Средняя, требует начальной экспертизы в NoSQL и понимания моделей данных | ||
| Resource Utilization | 🟠 Средняя, один дорогой сервер, но объём ещё управляемый | 🟠 Средняя, умеренная нагрузка на железо, но больше инфраструктурных затрат на управление шардами | 🟢 Высокая эффективность при использовании стандартного оборудования | ||
| Constrains | CON-001 | Корпоративные стандарты (IT как Lego)
| 🟢 | 🟢 | 🟢 |
Принятое решение
Вариант 1 выглядит наиболее удачным. Даёт максимум функциональности и минимум дополнительных затрат.
Уточнение принятого решения
| Дизайнерские решение и расположение | Обоснование |
|---|---|
Кластер PostgreSQL мы закажем в DBaaS. | Все конфигурации развертывания HA кластера берут на себя ребята из платформы. Предполагаемый объем данных на 2026 г = 5тб. Это вполне приемлемая цифра для PostgreSQL. Для партиционирования используем декларативное секционирование. Такой вид партиционирования наиболее удобен для обслуживания и разработки. |

