Операционная конфигурация¶

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

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

Параметры¶

Параметр (ключ)	Назначение	Значение по умолчанию
Счёт-источник начислений (`accrual.source-account`)	Системный счёт, с которого фондируются начисления (кредитовая сторона проводки начисления).	`MRK` (`LOYALTY_ACCRUAL_SOURCE_ACCOUNT`)
Счёт-приёмник списаний (`redemption.sink-account`)	Системный счёт, на который выводятся списанные (погашенные) баллы.	`RDM` (`LOYALTY_REDEMPTION_SINK_ACCOUNT`)
Счёт сгорания баллов (`expiry.breakage-account`)	Системный счёт, на который списываются сгоревшие (просроченные) баллы при закрытии лотов.	`BRK` (`LOYALTY_EXPIRY_BREAKAGE_ACCOUNT`)
Счёт корректировок (`correction.sink-account`)	Контрсчёт проводки «Корректировка» ручной операции — отдельный от счетов списания и сгорания.	`CORR` (`LOYALTY_CORRECTION_SINK_ACCOUNT`)
Валюта баллов (`points.currency`)	Код валюты баллов программы — единый источник истины для начисления, списания и витрины баланса. В неё начисляет программа: конфигурация программы валюту не выбирает.	`PTS`
Порядок списания лотов (`redemption.consume-order`)	Стратегия выбора лота при списании: `FIFO`, `LIFO` или `FEFO`.	`FEFO`
Срок жизни резерва баллов (`redemption.hold-ttl`)	Срок действия резерва (холда), если вызывающий не задал свой, в формате ISO-8601 (например, `PT30M`).	`PT30M`
Часовой пояс программы (`program.timezone`)	Единый часовой пояс контура (идентификатор IANA): в нём интерфейс вводит и показывает даты, а сервер считает календарные границы и трактует расписания — см. ниже.	`Europe/Moscow` (`LOYALTY_PROGRAM_TIMEZONE`)

Двойная бухгалтерия

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

Системные счета (MRK, RDM, BRK, CORR и др.) определяются в плане счетов модуля, валюта баллов (PTS) и прочие валюты — в справочнике валют. Параметры операционной конфигурации ссылаются на эти сущности по их кодам; счета и валюты должны существовать заранее.

Три системных счёта — по умолчанию разные

Источник начислений, счёт списаний и счёт сгорания по умолчанию — разные счета (MRK, RDM, BRK): по номеру счёта-получателя отчёты делят ушедшие с клиентских счетов баллы на «списано» и «сгорело». Счета RDM и BRK заводятся миграцией на базовом субсчёте валюты баллов, если их ещё нет; заданные на контуре переопределения параметров не меняются.

Изменение параметров¶

Список параметров с действующими значениями и собственными переопределениями отдаёт GET /v1/admin/system-config; задать или снять переопределение — PUT /v1/admin/system-config/{key}, без перезапуска модуля. Отдельной карточки для правки операционной конфигурации в интерфейсе нет: интерфейс только читает параметры — например, валюту баллов программы для конфигурации программы и для подсказки о сроке жизни баллов в форме акции.

Действующее значение определяется так: если для параметра задано собственное переопределение в базе — используется оно; иначе берётся значение из конфигурации среды (переменная окружения / свойство приложения), заданное при развёртывании. Так поведение по умолчанию совпадает с прежним, а правка через API переопределяет его без обновления конфигурации среды и без перезапуска экземпляра.

Согласованность с леджером

Изменение системного счёта или валюты баллов на «горячем» инстансе с уже накопленными остатками — операция повышенного риска: ранее проведённые операции остаются привязаны к прежним счетам. Такие изменения выполняются согласованно с планом счетов и, как правило, только на этапе ввода в эксплуатацию.

Срок жизни резерва: неразбираемое значение не ломает списание

Если переопределение поля «Срок жизни резерва баллов» не удаётся разобрать как срок ISO-8601 (например, из-за опечатки), модуль откатывается к значению из конфигурации среды — списание не остаётся без срока резерва.

Часовой пояс программы¶

program.timezone — единый пояс контура, и его применяет не только интерфейс, но и сервер:

интерфейс вводит и показывает все даты в этом поясе, а не в поясе браузера; под полями с временем — подсказка «Часовой пояс: UTC+3» со смещением на выбранный момент. Пояс открыт любому пользователю интерфейса — GET /v1/program/timezone → {zone};
сервер режет в нём календарные сутки, недели и месяцы (календарный лимит участий в акции за день, неделю или месяц, итоги субсчёта за даты, дневные разрезы отчётов и мониторинга), подписывает даты в текстах клиенту и в именах файлов выгрузок;
если операционный день не открыт, учётная дата проводки — календарная дата в этом поясе (с учётом переопределения);
расписания фоновых заданий (сгорание баллов, предупреждения о сгорании, выгрузки во внешние системы) трактуются в этом поясе.

Значение — только идентификатор IANA (например, Europe/Moscow): Moscow или UTC+3 отклоняются 422 program_timezone_invalid, а непригодный LOYALTY_PROGRAM_TIMEZONE не даёт модулю стартовать. Смена пояса действует без перезапуска (другие экземпляры модуля видят её в пределах срока кэша справочников LOYALTY_REFERENCE_CACHE_TTL, по умолчанию 30 секунд), но расписания сгорания баллов и предупреждений о сгорании перечитывают пояс только при старте модуля. Прошлое не пересчитывается: проставленные учётные даты и сроки лотов остаются как есть.

Прочие настройки программы¶

Раздел меню «Настройка ПЛ» (экран «Настройка программы лояльности») содержит карточки:

Карточка	Назначение	Роли
Ограничения на списание баллов	Общая политика списания: тип («Фикс (₽)» / «Процент (%)») и значение минимального и максимального списания за транзакцию, переключатель в заголовке карточки. Действует, пока у активной конфигурации программы нет своих правил списания.	чтение/запись `LOYALTY_DICTIONARY_READ` / `WRITE`
Лимиты по разрезам	Лимиты списания для конкретного уровня, сегмента или валюты баллов (`TIER` / `SEGMENT` / `CURRENCY`), флажок «Лимит активен». Частное бьёт общее: уровень → сегмент → валюта → правила активной конфигурации → общая политика. Лимит уровня задаётся кодом уровня и действует на этот код в любой конфигурации. Из нескольких сегментов клиента действует самое строгое ограничение.	`LOYALTY_DICTIONARY_READ` / `WRITE`
Глобальная механика	Базовое начисление (кешбэк в процентах от суммы покупки), применяемое ко всем покупкам вне акций: переключатель в заголовке карточки, «Процент начисления», «Описание».	`LOYALTY_DICTIONARY_READ` / `WRITE`

Управляющие флаги этих настроек (enabled политики списания, лимита и глобальной механики) обязательны в контракте: сохранение полной формы без этих полей отклоняется с указанием отсутствующего поля, а не общей ошибкой разбора тела.

Блок «Валюты и баллы» убран

Прежний блок управления балльными валютами в разделе «Настройка ПЛ» удалён из интерфейса. Балльные валюты заводятся и настраиваются в разделе «Администрирование» → «Валюты» — см. справочник валют программы. API /v1/admin/point-currencies сохранён для совместимости и работает поверх того же справочника.

Перенос настроек между контурами¶

Операционная конфигурация как таковая (переопределения system-config) между контурами не переносится — она возвращается к значениям из конфигурации среды целевого контура. Переносятся смежные объекты, от которых зависит работа акций:

flowchart LR
    A[Акции] --> B[Механики]
    B --> C[Справочники]

Что переносится	Правила	Подробнее
Механики (диаграммы RT Flow) с определениями параметров	Опознание по коду, отсутствующее создаётся, существующее пропускается, ошибка одной механики не отменяет перенос остальных. Механика едет вместе с определениями своих параметров одной транзакцией. Механика проверяется так же, как при заведении в админке (код, название, тип, диаграмма RT Flow), параметры — ключ и название обязательны, ключ не повторяется, тип из списка; набор без списка параметров переносит механику без параметров. Перенесённая механика попадает в журнал справочника механик.	`GET/POST /v1/admin/mechanics/export`, `/import`
Справочники (НСИ)	Те же правила, статус записи переносится как есть.	Справочники — перенос между контурами
Акции	Опознание по коду; приезжают выключенными (сбрасываются в черновик). Условие «Уровень клиента» ссылается на конфигурацию программы целевого контура: пара с конфигурацией или уровнем, которых там нет, отклоняется (`422 promotion_level_unknown`).	см. руководство по акциям

Конфигурации программы с их уровнями между контурами не переносятся — их заводят в целевом контуре.

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

Предпросмотр импорта. Загрузка бандла механик или справочников с параметром dryRun=true ничего не записывает, но считает итог по тем же правилам, что и настоящая загрузка: что будет создано, что пропущено как уже существующее, что не пройдёт (включая полную проверку создания — период, лимиты, параметры — для акций). Отдельной ручки предпросмотра нет: предпросмотр и применение обязаны отвечать одинаково, иначе предпросмотр показывал бы «всё хорошо» там, где настоящая загрузка отказывает. Права на предпросмотр — те же, что на запись.

# Экспорт механик (все или по кодам)
GET /v1/admin/mechanics/export?codes=cashback_v1,cashback_v2

# Предпросмотр импорта — ничего не пишет
POST /v1/admin/mechanics/import?dryRun=true

# Применение
POST /v1/admin/mechanics/import

Просмотр через раздел «Справочники»¶

Эффективные системные счета, валюты и единицы измерения доступны для просмотра в разделе «Справочники» как справочники только для чтения — модуль отображает их актуальные значения из соответствующих системных таблиц.

Справочник	Что показывает
Системные счета	Список счетов плана счетов: код, наименование, балансовая природа, тип погашения.
Валюты	Список валют: код, наименование, символ, точность (знаков после запятой).
Единицы измерения	Единицы для начисления по объёму, массе, штукам: код, символ, размерность, точность.

# Просмотр системных счетов (read-only)
GET /v1/admin/dictionaries/system-account/entries

# Просмотр валют (read-only)
GET /v1/admin/dictionaries/currency/entries

Управление доступом¶

Роль	Возможности
`LOYALTY_DICTIONARY_READ`	Просмотр операционной конфигурации и её эффективных значений.
`LOYALTY_DICTIONARY_WRITE`	Изменение параметров операционной конфигурации, политики списания, лимитов по разрезам и глобальной механики.
`LOYALTY_PROMOTION_READ` / `WRITE`	Экспорт / импорт механик между контурами.

Программный интерфейс¶

Метод и путь	Назначение	Роль
`GET /v1/admin/system-config`	Список параметров операционной конфигурации с эффективными значениями.	`LOYALTY_DICTIONARY_READ`
`PUT /v1/admin/system-config/{key}`	Задать (или снять — пустым значением) переопределение параметра; неизвестный ключ — `404 system_config_not_found`, пояс не IANA — `422 program_timezone_invalid`.	`LOYALTY_DICTIONARY_WRITE`
`GET /v1/program/timezone`	Часовой пояс программы `{zone}`.	любой аутентифицированный пользователь
`GET /v1/admin/redemption-policy`	Глобальная политика списания.	`LOYALTY_DICTIONARY_READ`
`PUT /v1/admin/redemption-policy`	Изменить глобальную политику списания.	`LOYALTY_DICTIONARY_WRITE`
`GET /v1/admin/redemption-limits`	Лимиты списания по разрезам.	`LOYALTY_DICTIONARY_READ`
`PUT /v1/admin/redemption-limits/{scopeType}/{scopeKey}`	Изменить (или создать) лимит по разрезу; `DELETE` на том же пути снимает его.	`LOYALTY_DICTIONARY_WRITE`
`GET /v1/admin/global-mechanic`	Базовое начисление (глобальная механика).	`LOYALTY_DICTIONARY_READ`
`PUT /v1/admin/global-mechanic`	Изменить базовое начисление.	`LOYALTY_DICTIONARY_WRITE`
`GET/POST /v1/admin/mechanics/export`, `/import`	Перенос механик между контурами (`dryRun` — предпросмотр).	`LOYALTY_PROMOTION_READ` / `WRITE`

Пример ответа GET /v1/admin/system-config:

[
  {
    "key": "points.currency",
    "title": "Валюта баллов",
    "overrideValue": null,
    "effectiveValue": "PTS"
  },
  {
    "key": "program.timezone",
    "title": "Часовой пояс программы",
    "overrideValue": "Asia/Yekaterinburg",
    "effectiveValue": "Asia/Yekaterinburg"
  }
]