О модуле¶
CM Ocean Loyalty — модуль управления программой лояльности платформы CM Ocean
(вендор Data Sapience). В основе модуля — балльный леджер loyalty-billing,
построенный на принципах двойной бухгалтерии: каждая операция с баллами
проводится как пара взаимосвязанных проводок, что обеспечивает аудируемость,
обратимость и точную сверку балансов.
Модуль предназначен для суверенного (on-premise) развёртывания под каждого заказчика и ориентирован на enterprise-сегмент, требования к импортозамещению и 152-ФЗ.
Назначение¶
Модуль решает задачи учёта и начисления клиентской ценности в баллах:
- ведёт счета и балансы клиентов с разделением на
balance/held/available; - выполняет начисления (пополнение), двухфазное списание (hold → commit/cancel), переводы и обмен валют баллов;
- управляет лотами баллов, сроком их жизни и сгоранием;
- ведёт конфигурации программы лояльности: уровни, акции программы и уровней, правила списания;
- конфигурирует маркетинговые акции на базе каталога механик и применяет их к покупкам клиентов;
- показывает сводные отчёты за период и мониторинг операций;
- предоставляет операторский интерфейс и инструменты администрирования справочников, условий акций, карточки клиента и операционной конфигурации.
Денежная модель
Все суммы баллов хранятся и передаются в минорных единицах.
Денежные операции идемпотентны: повтор запроса с тем же
Idempotency-Key возвращает сохранённый результат, а операция выполняется
ровно один раз.
Ключевые возможности¶
| Область | Что реализовано |
|---|---|
| Леджер баллов | Счета (у клиента — во всех включённых валютах), субсчета с базовым субсчётом и областью списания, лоты, валюты (справочник валют программы — деньги и баллы одной записью, пары обмена), проводки; начисление, двухфазное списание (hold/commit/cancel) с сроком резерва по умолчанию, перевод, обмен, срок жизни баллов по цепочке, плановое и ручное сгорание лотов с предупреждениями клиенту, кеш баланса |
| Акции | Каталог механик (CASHBACK, MULTIPLIER, GIFT, REFERRAL, UNIT_BONUS, BUNDLE_1PLUS1) с параметрами из справочника, CRUD акций, тип события и настройки начисляемых баллов, метки акций, условия из реестра условий («Настройка акции»: товары, место покупки, мерчант, канал, сегменты, сумма чека, клиент, теги, участие в акциях, дополнительные условия), ограничения и лимиты (бюджет в деньгах, лимит участий с настраиваемым окном), согласование запуска, автоведение по периоду (статус «Запланирована»), арбитраж, версионирование, статистика, цикл «покупка → акция → начисление» |
| Конфигурации программы | Несколько конфигураций, одна активная: уровни, акции программы и уровней, правила списания, механика перехода и режим пересчёта уровня, активация с историей |
| Клиенты | Каталог клиентов (поиск, фильтры, массовые операции, импорт из CSV), карточка клиента по версионируемой настройке (атрибуты, таблицы данных), теги клиента (справочник + присвоение), сегменты из системы кампаний, мягкое удаление, обезличивание |
| Ручные операции | Начисление, корректировка, перевод уровня, добавление и снятие тегов — одиночно и пакетом (список/файл) с причиной из справочника и асинхронным выполнением |
| Уровни (тиры) | Уровень клиента по журналу покупок (сумма и/или количество покупок): повышение при покупке, пересмотр в личную дату клиента, ручное назначение уровня, история переходов |
| Вовлечённость | Реферальная программа, достижения и бейджи, карта участника в мобильном кошельке (Apple Wallet / Google Кошелёк) |
| Личный кабинет (B2C) | Карта, баланс, уровень, история операций, доступные акции и партнёрские предложения, бейджи |
| Партнёрские предложения | Реестр партнёров и справочник мерчантов, офферы по осям доставки/акцепта/аудитории/финансирования, card-linked начисление, взаиморасчёты |
| Бизнес-день | Открытие и закрытие операционного дня, дневной отчёт |
| Отчёты | Раздел «Отчёты»: обзор, баллы, уровни, акции (с выгрузкой таблицы в CSV) и рефералы за выбранную глубину |
| Мониторинг и аудит | Сводки и аномалии операций за произвольный период, журнал аудита (изменения, доменные события и обращения к персональным данным, защита от подделки, выгрузка), очередь приёма застрявших асинхронных команд |
| Справочники (НСИ) | Локальные справочники с ЖЦ DRAFT / ACTIVE / ARCHIVED и аудитом, собственные справочники (теги, метки, сегменты, города, торговые точки, мерчанты, каталог товаров), реестр условий акции, настройка карточки клиента, единицы измерения, операционная конфигурация, перенос справочников между контурами |
| Интеграции | POS-адаптер (приём чеков и возвратов, резолюция карты), приём начислений от модуля Promo и от RT Flow, проверка условий для RT Flow, приём сегментов из системы кампаний, исходящие события (смена уровня, уведомления клиентам), проекция клиента для Check Scan, профиль клиента через MDM, обмен данными (ленты изменений, выгрузка витрин) |
Натуральные единицы
Механика UNIT_BONUS начисляет баллы за натуральную единицу покупки —
например, за литр топлива или за штуку товара, — а не только за сумму чека.
Технологический фундамент¶
- Бэкенд: Spring Boot, Java, Spring Data JDBC (явный SQL), PostgreSQL, миграции схемы — Liquibase (применяются приложением на старте).
- API: REST под префиксом
/v1, ответы в формате DTO; коллекции возвращаются в конверте{ items, page, size, total }. Ошибки — RFC-7807 (application/problem+json) со стабильнымcodeиtraceId. - Безопасность: OAuth2 resource server на Keycloak (JWT), роли
LOYALTY_*,@PreAuthorize, принцип deny-by-default. - Наблюдаемость: JSON-логи с
traceId, метрики Prometheus, health-пробы для Kubernetes. - Контракт API: OpenAPI генерируется из кода (code-first); расхождение кода и опубликованной спецификации блокируется автоматической проверкой (diff-gate).
- Фронтенд:
loyalty-ui— микрофронтенд (MF-remote) под единым хост-окном Core UI на React и Ant Design.
Положение в контуре CM Ocean¶
CM Ocean Loyalty работает не изолированно, а как один из модулей платформы. Соседние модули — самостоятельные продукты, с которыми Loyalty интегрируется.
flowchart LR
POS[POS / касса / чеки] -->|события покупки| LOY
PROMO[Promo<br/>кампании, коммуникации] -->|начисления| LOY
LOY[CM Ocean Loyalty<br/>балльный леджер + акции] -->|профиль клиента| MDM[MDM<br/>мастер-данные]
LOY --> COREUI[Core UI<br/>единое окно-хост]
RTF[RT-Flow / SDE<br/>Apache Flink] -.-> LOY
LOY -.-> DWH[DWH<br/>аналитические витрины]| Модуль контура | Роль | Связь с Loyalty |
|---|---|---|
| Core UI | Единое окно-хост платформы | Loyalty-UI встраивается как микрофронтенд |
| Promo | Кампании и коммуникации | Передаёт в Loyalty события начисления |
| MDM | Мастер-данные клиента (golden record) | Loyalty читает идентичность клиента и публикует лоялти-атрибуты |
| RT-Flow / SDE | Потоковый decisioning на Apache Flink | Исполняет механики и обращается к доменному API Loyalty |
| DWH | Аналитические витрины | Потребляет данные для отчётности и BI |
Внешние модули — отдельные продукты
Core UI, Promo, MDM, RT-Flow/SDE и DWH не входят в поставку модуля Loyalty. Настоящая документация описывает только модуль Loyalty и его контракты интеграции с ними.
В дорожной карте¶
Перечисленные ниже возможности ещё не реализованы и находятся в планах развития модуля.
Запланированные возможности
- Трансляция изменений справочников во внешние потребители в реальном времени (outbox → Kafka → SDE); кеширование справочников в памяти реплик уже реализовано.
- Механики как параметры — конфигурирование логики акций без выпуска кода.
- Сертификаты — выпуск и погашение.
- Мастер импорта клиентов в интерфейсе — пока доходит до шага «Проверка»; сама загрузка файла доступна через API.
Обзор разделов документации¶
Документация портала организована по ролям читателя и сценариям эксплуатации:
- Руководство пользователя — назначение модуля, бизнес-сценарии работы с акциями, балансами клиентов, конфигурациями программы и уровнями, отчётами и операционным днём; работа в интерфейсе Loyalty-UI.
- Администрирование — справочники (НСИ), настройка акции, настройка карточки клиента, валюты, единицы измерения, операционная конфигурация, управление ролями доступа.
- API — справочник REST-эндпоинтов
/v1, форматы DTO, конверт коллекций, модель ошибок RFC-7807, идемпотентность. - Интеграции — приём чеков и возвратов от POS, приём начислений от Promo, приём сегментов, исходящие события, связка с MDM.
- Эксплуатация — развёртывание, конфигурация окружения, наблюдаемость (логи, метрики, health-пробы), безопасность.
Принцип документации
Портал описывает только реально доступную функциональность модуля. Запланированные, но ещё не реализованные возможности явно помечаются как относящиеся к дорожной карте.