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

Описание соответствует версии схемы БД 00088 (ProBonus 1.2.86.411). Номер версии схемы конкретной базы хранится в таблице db_information, поле version_num.

Важно! Структуру БД создаёт и обновляет сервер ProBonus при подключении к базе и при обновлении версии. Не изменяйте структуру и данные таблиц вручную — все операции со счетами, балансами и акциями выполняйте через веб-интерфейс или ProBonus API. Прямые SQL-запросы к базе допустимы только на чтение (например, для отчётов).

• СУБД: Microsoft SQL Server 2017 и выше (подходит редакция Express). Подробнее о создании и подключении базы: БД. Создание, Подключение, Заполнение.
• Схема: все объекты находятся в схеме dbo.
• Состав: 64 таблицы, 78 внешних ключей, 7 уникальных ограничений, 1 CHECK-ограничение, 1 последовательность (transaction_balance_tag).
• Программная логика: хранимых процедур, функций, представлений и триггеров ProBonus в базе нет — вся бизнес-логика выполняется сервером ProBonus. (Процедуры sp_*diagram* и функция fn_diagramobjects — стандартные объекты SQL Server Management Studio для диаграмм.)

• Имена таблиц и полей — строчные, слова разделены подчёркиванием (account_group, date_start).
• Первичный ключ большинства таблиц — поле id типа int с автоинкрементом (IDENTITY). Таблицы-связки (например, segment_account) имеют составной первичный ключ из полей связи.
• Мягкое удаление. Записи справочников и счетов не удаляются физически: при удалении в веб-интерфейсе поле is_deleted принимает значение 1. В отчётах такие записи нужно исключать условием is_deleted = 0.
• Суммы (балансы, бонусы, суммы чеков и скидок) хранятся в целых копейках в полях типа bigint. Например, 10000 = 100,00 руб.
• Дата и время хранятся в типе datetime в локальном времени сервера ProBonus. Значение 1753-01-01 (минимальная дата SQL Server) означает «без ограничения начала», 9999-12-31 — «бессрочно».
• Коды r_keeper. Поля rk_code, discount_code, dish_code, rest_code содержат коды объектов справочников r_keeper (скидок, типов бонусов, блюд, ресторанов).
• Перечисления (поля type, status, kind и т. п.) хранятся целыми числами; их значения определяются сервером ProBonus. Известные значения приведены в разделе Коды и перечисления.
• Параметры акций, сегментов и настроек хранятся в формате JSON в полях nvarchar(max) (parameters, settings_json и др.).

Основные связи, сгруппированные вокруг ключевых таблиц. Запись A ──► B означает, что таблица A содержит внешний ключ на таблицу B. Полный перечень ключей приведён в описании каждой таблицы.

account (гость)
 ├──► account_group ──► account_template ──► discount ◄── discount_level
 ├──► discount                      (индивидуальная составная скидка)
 │
 │  Ссылаются на account:
 ├◄── phone, email, additional_contact
 ├◄── identifier ──► identifier_type
 ├◄── accounts_tags ──► tag ──► tag_group
 ├◄── discount_temporary, account_coupon_dish ──► coupon_dish
 ├◄── account_event ◄── account_event_handling
 ├◄── anti_fraud_events, segment_account ──► segment
 ├◄── account_referral (пригласивший и приглашённый)
 ├◄── transaction_balance, mailing_message, review, promotion_actuation_log
 └◄── transaction

transaction (операция по счёту)
 ├──► check ◄── check_cache ──► dishes_cache_by_check
 ├──► identifier, restaurant
 ├──► transaction_manual ──► user
 ├◄── transaction_balance
 ├◄── transaction_promo_stamp ──► promo_stamp
 └◄── account_coupon_dish, anti_fraud_events

promo_stamp (акция «Штампики»)
 ├◄── promo_stamp_dish_code
 ├◄── promo_stamp_account_group ──► account_group
 └◄── promo_stamp_restaurant ──► restaurant

promotion (сегментная акция) ──► segment
 └◄── promotion_action ──► segment
       ├◄── promotion_actuation ◄── promotion_actuation_log
       ├◄── mailing ◄── mailing_message ──► message_content ◄── message_content_media ──► media
       └◄── promocode_activation, accounts_tags

promotion_trigger
 ├◄── promotion_trigger_promo_stamp_settings ◄── promotion_trigger_promo_stamp_settings_stamp ──► promo_stamp
 └◄── promotion_actuation_log

review ──► account, additional_contact, restaurant
 └◄── review_message ──► media

• Гость — это запись account. Все данные гостя (телефоны, идентификаторы, транзакции, купоны, теги, сообщения, отзывы) ссылаются на account.id.
• Условия лояльности гостя определяются цепочкой account → account_group → account_template → discount → discount_level. Значения, заданные непосредственно в account, имеют приоритет над шаблоном группы. Временные скидки гостя хранятся в discount_temporary.
• Применение карты на кассе создаёт запись transaction, ссылающуюся на check (данные чека r_keeper). Изменения баланса записываются в transaction_balance; покупки по акции «Штампики» — в transaction_promo_stamp.
• Ручное пополнение/изъятие создаёт transaction со ссылкой на transaction_manual (без чека).
• Сегментная акция: promotion (расписание, сегмент) → promotion_action (действия) → promotion_actuation (запуски) → promotion_actuation_log (результат по каждому гостю). Рассылки акции — mailing → mailing_message.

Обозначения в колонке «Ключ»: PK — первичный ключ, ID — автоинкремент (IDENTITY), FK — внешний ключ (в скобках — правило удаления, если оно отличается от NO ACTION), DF — значение по умолчанию.

Счёт гостя — центральная таблица системы. Хранит анкету гостя, его группу, индивидуальные настройки скидки/бонуса, лимиты и признаки блокировки. Настройки, заданные в счёте, переопределяют настройки шаблона группы. См. Счета.

Индексы:

• ixaccountis_deletedaccount_group_idid — (is_deleted, account_group_id, id)
• IX_account_group_id — (account_group_id)

На таблицу ссылаются: account_coupon_dish.account_id, account_event.account_id, account_referral.invited_account_id, account_referral.inviting_account_id, accounts_tags.account_id, additional_contact.account_id (CASCADE), anti_fraud_events.account_id, discount_temporary.account_id, email.account_id, identifier.account_id, mailing_message.account_id, phone.account_id, promocode_activation.account_id, promotion_actuation_log.account_id (CASCADE), review.account_id, segment_account.account_id (CASCADE), transaction.account_id, transaction_balance.account_id

Группа счетов. Объединяет гостей с одинаковыми условиями лояльности; условия задаются через шаблон. См. Группы счетов.

На таблицу ссылаются: account.account_group_id, promo_stamp_account_group.account_group_id, referral_program.invited_account_group_id

Шаблон группы счетов — набор настроек, которые получает счёт группы: скидка/бонус, лимиты, стартовый баланс, сроки жизни бонусов. Поля аналогичны одноимённым полям account.

На таблицу ссылаются: account_group.account_template_id

Телефоны гостя. У счёта может быть несколько номеров, один из них — основной.

Индексы:

• ixphoneaccount_id — (account_id)
• ixphoneaccount_idis_deleted — (account_id), включённые поля: number, фильтр: ([is_deleted]=(0))
* ixphoneis_deleted — (is_deleted)

==== email ====
Адреса электронной почты гостя.

^ Поле ^ Тип ^ NULL ^ Ключ ^ Описание ^
| id | int | | PK, ID | Идентификатор записи |
| address | nvarchar(320) | | | Адрес e-mail |
| is_primary | bit | | | Основной адрес |
| account_id | int | | FK → account.id | Счёт гостя |

Индексы:
* ixemailaccount_id — (account_id), включённые поля: address

==== additional_contact ====
Дополнительные контакты гостя в мессенджерах (Telegram, MAX) — используются ботами и рассылками.

^ Поле ^ Тип ^ NULL ^ Ключ ^ Описание ^
| id | int | | PK, ID | Идентификатор контакта |
| is_deleted | bit | | | Признак удаления |
| type | int | | | Тип контакта (канал мессенджера) |
| value | nvarchar(256) | | | Значение (идентификатор чата/пользователя в мессенджере) |
| account_id | int | | FK → account.id (CASCADE) | Счёт гостя |
| telegram_fail_count | int | | DF 0 | Счётчик неудачных отправок в Telegram |
| max_fail_count | int | | DF 0 | Счётчик неудачных отправок в MAX |

Индексы:
* ix_additional_contact_type_value — (type, value)

На таблицу ссылаются: review.additional_contact_id

==== identifier ====
Идентификаторы гостя — всё, по чему гостя можно найти на кассе: телефон, пластиковая карта, Wallet, системный и временный (QR) коды бота. См. Типы идентификаторов.

^ Поле ^ Тип ^ NULL ^ Ключ ^ Описание ^
| id | int | | PK, ID | Идентификатор записи |
| is_deleted | bit | | | Признак удаления |
| code | nvarchar(50) | да | | Код идентификатора (номер карты, телефон, код QR) |
| account_id | int | да | FK → account.id | Счёт гостя |
| identifier_type_id | int | да | FK → identifier_type.id | Тип идентификатора |
| is_using_with_manager_card | bit | | | Применяется вместе с картой менеджера |
| is_blocked | bit | | | Идентификатор заблокирован |
| delete_reason | nvarchar(100) | да | | Причина удаления |
| block_reason | nvarchar(100) | да | | Причина блокировки |
| expired | datetime | да | | Срок действия (для временных кодов) |
| is_sys_code | bit | да | | Системный код |
| code_upper | nvarchar(50) | да | | Код в верхнем регистре — для регистронезависимого поиска |

Индексы:
* ixidentifieraccount_id — (account_id)
* ixidentifieraccount_idlist — (account_id), включённые поля: code, identifier_type_id, is_blocked, is_sys_code, фильтр: ([is_deleted]=(0))
• ixidentifieridentifier_type_id — (identifier_type_id)
• ixidentifieris_deleted — (is_deleted)
• ixidentifieris_sys_code — (is_sys_code)
• IX_identifier_code — (code)
• IX_identifier_code_upper — (code_upper), включённые поля: id, account_id, is_deleted, is_blocked, expired

На таблицу ссылаются: transaction.identifier_id, wallet_device_cards.identifier_id

Справочник типов идентификаторов. Системные типы создаются автоматически: phone, card, wallet, wallet_dynamic, system, temporary, system_tg, temporary_tg, system_max, temporary_max.

На таблицу ссылаются: identifier.identifier_type_id

Группы тегов счетов. См. Теги счетов.

На таблицу ссылаются: tag.group_id

Теги счетов — метки для классификации гостей.

На таблицу ссылаются: accounts_tags.tag_id

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

Индексы:

• ixaccounts_tagsaccount_iddate_end — (account_id, date_end), включённые поля: tag_id
* ix_accounts_tags_account_tag — (account_id, tag_id)

==== account_event ====
События по счёту (регистрация, транзакция, движение по штампикам и т. п.) — источник для триггерных акций и уведомлений.

^ Поле ^ Тип ^ NULL ^ Ключ ^ Описание ^
| id | int | | PK, ID | Идентификатор события |
| type | int | да | | Тип события |
| parameters | nvarchar(max) | да | | Параметры события (JSON) |
| datetime | datetime | да | | Дата и время события |
| account_id | int | | FK → account.id | Счёт гостя |

На таблицу ссылаются: account_event_handling.account_event_id (CASCADE)

==== account_event_handling ====
Обработка событий — отметки о том, какой обработчик (триггер) и когда обработал событие.

^ Поле ^ Тип ^ NULL ^ Ключ ^ Описание ^
| id | int | | PK, ID | Идентификатор записи |
| handling_datetime | datetime | да | | Дата и время обработки |
| handler_type | int | да | | Тип обработчика |
| handler_id | int | да | | Идентификатор обработчика (например, триггера) |
| account_event_id | int | | FK → account_event.id (CASCADE) | Обработанное событие |

==== anti_fraud_events ====
События антифрода — предупреждения и блокировки при превышении лимитов применений. См. Антифрод.

^ Поле ^ Тип ^ NULL ^ Ключ ^ Описание ^
| id | int | | PK, ID | Идентификатор события |
| account_id | int | | FK → account.id | Счёт гостя |
| transaction_id | int | да | FK → transaction.id | Транзакция, вызвавшая событие |
| datetime | datetime | да | | Дата и время |
| event | int | да | | Тип события (предупреждение / блокировка) |
| text | varchar(max) | да | | Текст события |

===== Скидки =====

==== discount ====
Составные скидки/бонусы (лестницы скидок): уровень гостя зависит от суммы его потрат. См. Составные скидки/бонусы.

^ Поле ^ Тип ^ NULL ^ Ключ ^ Описание ^
| id | int | | PK, ID | Идентификатор составной скидки |
| is_deleted | bit | | | Признак удаления |
| name | nvarchar(50) | | | Наименование |
| limit_period_in_days | int | да | | Период накопления суммы потрат, дней (NULL — за всё время) |

На таблицу ссылаются: account.discount_id, account_template.discount_id, discount_level.discount_id

==== discount_level ====
Уровни составной скидки.

^ Поле ^ Тип ^ NULL ^ Ключ ^ Описание ^
| id | int | | PK, ID | Идентификатор уровня |
| rk_code | int | | | Код скидки (бонуса) r_keeper для уровня |
| rk_bonus_type_code | int | да | | Код типа бонуса r_keeper |
| level_amount | bigint | | | Порог суммы потрат для перехода на уровень |
| discount_id | int | | FK → discount.id | Составная скидка |
| level_name | varchar(max) | | DF Название уровня | Название уровня |

==== discount_temporary ====
Временные скидки — назначенные гостю на срок (например, сегментной акцией «Назначение временной скидки/бонуса»).

^ Поле ^ Тип ^ NULL ^ Ключ ^ Описание ^
| id | int | | PK, ID | Идентификатор записи |
| rk_code | int | да | | Код скидки (бонуса) r_keeper |
| rk_bonus_type_code | int | да | | Код типа бонуса r_keeper |
| valid_until | date | да | | Действует до (включительно) |
| reason | nvarchar(256) | да | | Причина назначения |
| account_id | int | | FK → account.id | Счёт гостя |

===== Транзакции и чеки =====

==== transaction ====
Транзакции — каждая операция по счёту: применение карты в чеке (продажа или возврат) либо ручная операция. Все суммы в копейках.

^ Поле ^ Тип ^ NULL ^ Ключ ^ Описание ^
| id | int | | PK, ID | Идентификатор транзакции |
| check_id | int | да | FK → check.id | Чек r_keeper (для кассовых операций) |
| account_id | int | | FK → account.id | Счёт гостя |
| identifier_id | int | да | FK → identifier.id | Идентификатор, по которому применили карту |
| transaction_manual_id | int | да | FK → transaction_manual.id | Ручная операция (для пополнений/изъятий) |
| date | datetime | | | Дата и время транзакции |
| restaurant | int | да | | Код ресторана (устаревшее поле, см. restaurant_id) |
| rk_date | int | да | | Реквизиты чека r_keeper: дата |
| rk_unit | int | да | | Реквизиты чека r_keeper: станция (касса) |
| rk_check | int | да | | Реквизиты чека r_keeper: номер чека |
| sum_0 | bigint | да | | Сумма оплаты бонусами (по данным r_keeper; при продаже — отрицательное значение) |
| sum_1 | bigint | да | | Скидка (по данным r_keeper; при продаже — отрицательное значение) |
| sum_2 | bigint | да | | Начисление бонусов (по данным r_keeper) |
| sum_3 | bigint | да | | Сумма к оплате (по данным r_keeper, с учётом скидки) |
| sum_4 | bigint | да | | Сумма ручной операции (пополнение или изъятие) |
| check_guid | uniqueidentifier | да | | GUID чека r_keeper |
| chmode | int | да | | Режим чека r_keeper: 1 — оплата, 3 — возврат (суммы с обратным знаком); NULL — ручная операция. См. Режимы чека |
| rest_code | nvarchar(9) | да | | Код ресторана r_keeper |
| restaurant_id | int | да | FK → restaurant.id | Ресторан |
| system_identifier_type | int | да | | Тип системного идентификатора, по которому применили карту |
| is_return | bit | да | | Служебный признак; для определения возврата чека используйте chmode = 3 |
| cash_server_name | nvarchar(255) | да | | Имя кассового сервера (MID) |

Индексы:
* ixtransactioncheck_id_account — (check_id), включённые поля: account_id, date, is_return, chmode, фильтр: ([check_id] IS NOT NULL)
* IX_transaction_check_guid_chmode — (check_guid, chmode)
* IX_transaction_check_id — (check_id), включённые поля: sum_3
* IX_transactions — (date, account_id, check_guid)

На таблицу ссылаются: account_coupon_dish.transaction_id, anti_fraud_events.transaction_id, transaction_balance.transaction_id, transaction_promo_stamp.transaction_id

==== transaction_balance ====
Движение баланса счёта — «порции» бонусов/денег с периодом действия. Начисление создаёт порцию с положительной суммой, списание — записи с отрицательной суммой по той же порции (тот же tag и период). Сгорание отдельной записью не фиксируется: порция просто перестаёт учитываться после date_stop. Баланс счёта = сумма sum по записям, действующим на текущий момент.

^ Поле ^ Тип ^ NULL ^ Ключ ^ Описание ^
| id | int | | PK, ID | Идентификатор записи |
| transaction_id | int | | FK → transaction.id | Транзакция |
| account_id | int | | FK → account.id | Счёт гостя |
| tag | int | | | Номер порции (из последовательности transaction_balance_tag); связывает начисление и его списания |
| date | datetime | | | Дата операции |
| date_start | datetime | | | Начало действия порции (1753-01-01 — без ограничения; позднее — отложенное начисление) |
| date_stop | datetime | | | Окончание действия — дата сгорания бонусов |
| sum | bigint | | | Сумма, копейки (+ начисление, − списание) |

Индексы:
* ixtransaction_balanceaccount_iddates — (account_id, date_start, date_stop), включённые поля: sum
• ix_transaction_balance_transaction_id — (transaction_id)

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

На таблицу ссылаются: transaction.transaction_manual_id

Чеки r_keeper — исходные данные чека, полученные с кассы через FarCards.

На таблицу ссылаются: check_cache.check_id, transaction.check_id

Справочник блюд из чеков — блюда, встречавшиеся в чеках, по ресторанам. Используется отчётами и выбором блюд в акциях.

Индексы:

• ixdishes_cache_by_checkname_rest_code — (name, rest_code)
• uqdishes_cache_by_checkcode_rest_code — уникальный, (code, rest_code)

На таблицу ссылаются: check_cache.dishes_cache_by_check_id

Состав чеков — блюда в каждом чеке с количеством (разобранный XML для быстрых отчётов).

Индексы:

• ixcheck_cachecheck_id — (check_id)
• ixcheck_cachedish_check_covering — (dishes_cache_by_check_id, check_id), включённые поля: count
• ixcheck_cachedishes_cache_by_check_id — (dishes_cache_by_check_id)
• uqcheck_cachecheck_id_dishes_cache_by_check_id — уникальный, (check_id, dishes_cache_by_check_id)

Рестораны, подключённые к ProBonus (с учётом лицензирования). См. Рестораны.

На таблицу ссылаются: promo_stamp_restaurant.restaurant_id, review.restaurant_id, transaction.restaurant_id

Акции «Штампики N+1». См. Штампики.

На таблицу ссылаются: promo_stamp_account_group.promo_stamp_id, promo_stamp_dish_code.promo_stamp_id, promo_stamp_restaurant.promo_stamp_id, promotion_trigger_promo_stamp_settings_stamp.promo_stamp_id (CASCADE), transaction_promo_stamp.promo_stamp_id

Блюда акции «Штампики» — акционные (покупаемые) и подарочные.

Группы счетов, участвующие в акции «Штампики». Нет записей — акция действует для всех групп.

Рестораны акции «Штампики». Нет записей — акция действует во всех ресторанах.

Движения по акции «Штампики» — каждая покупка акционного блюда и каждая выдача подарка в чеке. Отдельного счётчика нет: прогресс гостя вычисляется по этой таблице (см. раздел «Типовые запросы»).

Индексы:

• IX_tps_transaction_id — (transaction_id), включённые поля: check_dish_code, check_dish_qnt

Товарные купоны (справочник). См. Товарные купоны.

На таблицу ссылаются: account_coupon_dish.coupon_dish_id, referral_program.invited_reward_coupon_dish_id, referral_program.inviting_reward_coupon_dish_id

Товарные купоны, выданные гостям.

Сегменты гостей — правила отбора («Все гости», день рождения, составной, ручной по списку, сгорающие бонусы, RFM и др.). См. Сегменты.

На таблицу ссылаются: promotion.segment_id, promotion_action.segment_id, segment_account.segment_id (CASCADE)

Состав сегментов — счета, попавшие в сегмент при последнем пересчёте.

Сегментные акции — контейнер с расписанием и сегментом, объединяющий одно или несколько действий (с версии 1.2.82.395). См. Сегментные акции.

На таблицу ссылаются: promotion_action.promotion_id

Действия акций: назначение временной скидки/бонуса, начисление бонусов, рассылка, начисление товарного купона, промокод. Параметры действия хранятся в JSON.

Индексы:

• ixpromotion_actionpromotion_id — (promotion_id)

На таблицу ссылаются: accounts_tags.promotion_action_id, mailing.promotion_action_id, promocode_activation.promotion_action_id, promotion_actuation.promotion_action_id, promotion_actuation_log.promotion_action_id

Запуски акций — каждое срабатывание действия по расписанию.

На таблицу ссылаются: promotion_actuation_log.promotion_actuation_id

Журнал применения акций к гостям — по строке на каждого гостя в каждом запуске или срабатывании триггера. См. Логи акций.

Индексы:

• ix_promotion_actuation_log_datetime — (datetime)
• ix_promotion_actuation_log_promotion_actuation_id — (promotion_actuation_id)

Активации промокодов гостями. Гость может активировать промокод один раз (уникальный индекс). См. Промокоды.

Индексы:

• uqpromocode_activationpromotion_id_account_id — уникальный, (promotion_action_id, account_id)
• uq_promocode_activation_promotion_action_account — уникальный, (promotion_action_id, account_id)

Триггеры — реакции на события по счёту. Системные триггеры: обновление баланса Wallet-карты, вознаграждение и оповещение по реферальной программе; пользовательский — «Транзакция в акции «Штампики»».

На таблицу ссылаются: promotion_actuation_log.promotion_trigger_id, promotion_trigger_promo_stamp_settings.promotion_trigger_id (CASCADE)

Настройки триггера по штампикам — шаблон сообщения гостю после покупки/получения подарка.

На таблицу ссылаются: promotion_trigger_promo_stamp_settings_stamp.promotion_trigger_id (CASCADE)

Акции «Штампики», по которым срабатывает триггер (при включённом фильтре).

Настройки реферальной программы (одна запись). Вознаграждение пригласившему (inviting_*) и приглашённому (invited_*): бонусы или товарный купон, условие получения и тексты сообщений для бота и Wallet. См. Реферальная программа.

Связи «пригласивший — приглашённый». Приглашённый может быть приглашён только один раз (уникальный индекс).

Индексы:

• uqaccount_referralinvited_account_id — уникальный, (invited_account_id)

Рассылки — пакет сообщений, созданный вручную или действием акции. См. Рассылки.

На таблицу ссылаются: mailing_message.mailing_id, promotion_actuation.mailing_id

Сообщения гостям — очередь и история отправки по каналам (Telegram, MAX, Wallet и др.), в том числе одиночные сообщения и запросы отзывов.

Индексы:

• IX_mailing_message_sending_status_channel_type — (sending_status, channel_type), включённые поля: id, sending_datetime, channel_destination, message_content_id, account_id

Содержимое сообщений — текст, тема и кнопка-ссылка.

На таблицу ссылаются: mailing_message.message_content_id, message_content_media.message_content_id (CASCADE)

Вложения сообщений (изображения) с порядком вывода.

Файлы (изображения рассылок, фото из отзывов), хранятся в БД.

На таблицу ссылаются: message_content_media.media_id, review_message.media_id

Отзывы гостей из бота. См. Отзывы.

На таблицу ссылаются: mailing_message.review_id, review_message.review_id

Сообщения в отзыве — текст и фото от гостя.

Версии текстов политик и соглашений, которые гость принимает в боте. Допустимые типы (CHECK): personal_policy, argeement, argeement_advertisement, loyalty_rules, age_confirmation. См. Образцы политик.

Индексы:

• uqpolicy_text_versiontext_typeversion — уникальный, (text_type, version)

===== Wallet =====

==== wallet_cards_template ====
Шаблон карты Apple/Google Wallet — изображения, цвета и тексты полей карты. См. Настройки Wallet.

^ Поле ^ Тип ^ NULL ^ Ключ ^ Описание ^
| id | int | | PK, ID | Идентификатор шаблона |
| name | varchar(max) | | | Наименование |
| icon_img | varchar(max) | | | Иконка (base64) |
| logo_img | varchar(max) | | | Логотип (base64) |
| strip_img | varchar(max) | | | Изображение-полоса (base64) |
| back_text | varchar(max) | | | Текст оборотной стороны |
| background_color | nvarchar(7) | | | Цвет фона (#RRGGBB) |
| label_color | nvarchar(7) | | | Цвет подписей |
| foreground_color | nvarchar(7) | | | Цвет текста |
| organization_name | varchar(max) | | | Название организации |
| description | varchar(max) | | | Описание карты |
| sharing_prohibited | bit | | | Запретить передачу карты |
| header_content | nvarchar(max) | | | Значение поля в заголовке |
| secondary_left_content | nvarchar(max) | | | Значение левого вторичного поля |
| secondary_right_content | nvarchar(max) | | | Значение правого вторичного поля |
| header_label | nvarchar(max) | | | Подпись поля в заголовке |
| secondary_left_label | nvarchar(max) | | | Подпись левого вторичного поля |
| secondary_right_label | nvarchar(max) | | | Подпись правого вторичного поля |

==== wallet_device_cards ====
Карты Wallet, установленные на устройствах — регистрации устройств для push-обновления карты.

^ Поле ^ Тип ^ NULL ^ Ключ ^ Описание ^
| device_id | varchar(256) | | PK | Идентификатор устройства |
| wallet_identifier_code | nvarchar(256) | | PK | Код карты Wallet |
| identifier_id | int | да | FK → identifier.id | Идентификатор гостя |
| client_ip | varchar(max) | да | | IP-адрес клиента |
| device_type | varchar(max) | | | Тип устройства / платформы |
| authentication_token | nvarchar(max) | да | | Токен аутентификации карты |
| user_agent | nvarchar(max) | да | | User-Agent устройства |
| push_token | nvarchar(max) | да | | Push-токен |
| headers | nvarchar(max) | да | | HTTP-заголовки регистрации |

===== Интеграция с r_keeper и кассами =====

==== rkeeper_bonus_types ====
Кэш справочника типов бонусов r_keeper (JSON), загружается при связи с r_keeper.

^ Поле ^ Тип ^ NULL ^ Ключ ^ Описание ^
| id | int | | PK, ID | Идентификатор |
| bonus_types | nvarchar(max) | да | | Справочник типов бонусов (JSON) |
| bonus_types_data_version | int | да | | Версия данных справочника r_keeper |
| updated_at | datetime | да | | Дата обновления |

==== rkeeper_discount_tree ====
Кэш дерева скидок r_keeper (JSON) — для выбора кодов скидок в веб-интерфейсе.

^ Поле ^ Тип ^ NULL ^ Ключ ^ Описание ^
| id | int | | PK, ID | Идентификатор |
| discount_tree | nvarchar(max) | да | | Дерево скидок (JSON) |
| discount_data_version | int | да | | Версия данных скидок |
| discount_types_data_version | int | да | | Версия данных типов скидок |
| updated_at | datetime | да | | Дата обновления |

==== cash_registration_settings ====
Настройки регистрации гостей с кассы — профили формы регистрации, доступ по токену. См. Настройка регистрации.

^ Поле ^ Тип ^ NULL ^ Ключ ^ Описание ^
| id | int | | PK, ID | Идентификатор |
| name | nvarchar(100) | | | Наименование профиля |
| token | uniqueidentifier | | | Токен доступа (уникальный) |
| settings_json | nvarchar(max) | | | Настройки формы (JSON) |

Индексы:
* uqcash_registration_settings__token — уникальный, (token)

Пользователи веб-интерфейса и API. См. Пользователи.

На таблицу ссылаются: accounts_tags.user_id, mailing_message.creator_user_id (CASCADE), transaction_manual.user_id, user_db_object_permission.user_ref, user_refresh_token.user_id

Роли. См. Роли.

На таблицу ссылаются: user_role_right.role_id

Права роли — разрешённые методы API (<метод>/<путь>, например get/api/v0/accounts/get).

Refresh-токены сессий веб-интерфейса — по одному на пару «пользователь — устройство (fingerprint)».

Индексы:

• IX_user_refresh_token — (user_id, fingerprint, refresh_token)
• UX_user_refresh_token_user_fp — уникальный, (user_id, fingerprint)

Доступ пользователей к объектам — например, к ресторанам (entity_type = restaurant).

Сведения о БД (одна запись): версия схемы, владелец лицензии, GUID базы.

Счётчики обращений к API по дням (ключ — метод и путь).

Стандартная таблица SQL Server Management Studio для хранения диаграмм БД. Системой ProBonus не используется.

Индексы:

• UK_principal_name — уникальный, (principal_id, name)

Для большинства внешних ключей действует правило NO ACTION: удалить запись, на которую есть ссылки, нельзя. Каскадное удаление (ON DELETE CASCADE) настроено для следующих связей:

Значения перечислений задаются сервером ProBonus. Ниже приведены значения, назначение которых однозначно определено.

Суммы в transaction (копейки). Поля sum_0–sum_3 заполняются по данным r_keeper при применении карты на кассе:

При возврате (chmode = 3) знаки сумм меняются на противоположные.

Поле chmode в таблицах transaction и check (а также атрибут chmode тега CHECK в XML чека) содержит режим чека r_keeper, переданный кассой через FarCards. Значения определены r_keeper — см. XML описание кассового документа для предоставления внешним системам.

В таблицах ProBonus на практике встречаются только значения 1 (оплата) и 3 (возврат) — транзакции по завершённым кассовым операциям. У ручных операций (без чека) transaction.chmode равно NULL.

Важно! Для определения возврата используйте chmode = 3. Поле transaction.is_return признаком возврата чека не является: у кассовых транзакций оно содержит 0 или NULL независимо от режима чека.

Примеры запросов для построения собственных отчётов. Запросы только читают данные.

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

SELECT b.account_id,
       SUM(b.sum) / 100.0 AS balance_rub
FROM transaction_balance b
WHERE b.account_id = @account_id
  AND b.date_start <= GETDATE()
  AND b.date_stop  >  GETDATE()
GROUP BY b.account_id;

SELECT a.id, a.last_name, a.first_name, a.middle_name, g.name AS account_group
FROM phone p
JOIN account a       ON a.id = p.account_id
JOIN account_group g ON g.id = a.account_group_id
WHERE p.number = '79991234567'
  AND p.is_deleted = 0
  AND a.is_deleted = 0;

Отдельного счётчика штампиков в БД нет: прогресс вычисляется по transaction_promo_stamp. Возвраты (отрицательное количество) вычитаются.

WITH s AS (
    SELECT t.account_id, ps.promo_stamp_id,
           SUM(CASE WHEN ps.kind = 0 THEN ps.check_dish_qnt ELSE 0 END) AS bought,
           SUM(CASE WHEN ps.kind = 1 THEN ps.check_dish_qnt ELSE 0 END) AS redeemed
    FROM transaction_promo_stamp ps
    JOIN [TRANSACTION] t ON t.id = ps.transaction_id
    GROUP BY t.account_id, ps.promo_stamp_id
)
SELECT s.account_id,
       p.name                                                      AS promo,
       s.bought                                                    AS dishes_bought,
       s.bought / p.promo_dish_count * p.gift_dish_count           AS gifts_accrued,
       s.redeemed                                                  AS gifts_redeemed,
       s.bought / p.promo_dish_count * p.gift_dish_count - s.redeemed AS gifts_left,
       s.bought % p.promo_dish_count                               AS in_current_cycle
FROM s
JOIN promo_stamp p ON p.id = s.promo_stamp_id
WHERE p.is_deleted = 0 AND s.bought > 0
ORDER BY s.bought DESC;

SELECT t.date,
       CASE t.chmode WHEN 1 THEN 'Продажа' WHEN 3 THEN 'Возврат' ELSE 'Ручная операция' END AS operation,
       r.name                 AS restaurant,
       t.sum_3 / 100.0        AS amount_due,
       t.sum_1 / 100.0        AS discount,
       t.sum_0 / 100.0        AS paid_with_bonuses,
       t.sum_2 / 100.0        AS bonus_accrued,
       t.sum_4 / 100.0        AS manual_sum,
       m.refill_reason
FROM [TRANSACTION] t
LEFT JOIN restaurant r         ON r.id = t.restaurant_id
LEFT JOIN transaction_manual m ON m.id = t.transaction_manual_id
WHERE t.account_id = @account_id
  AND t.date >= @date_from AND t.date < @date_to
ORDER BY t.date;

Важно! Имена таблиц transaction, check и user совпадают с зарезервированными словами SQL — в запросах их нужно заключать в квадратные скобки: [transaction], [check], [user].

• Размер. Самые объёмные таблицы — check (XML чеков), promotion_actuation_log, transaction, mailing_message и transaction_balance. При использовании MS SQL Express учитывайте ограничение 10 ГБ на размер базы; при приближении к нему потребуется переход на редакцию Standard.
• Резервное копирование. Настройте регулярное резервное копирование базы средствами SQL Server. Обязательно сделайте резервную копию перед обновлением ProBonus — при обновлении сервер может изменить структуру БД.
• Доступ для отчётов. Для внешних отчётов и BI-систем создайте отдельного пользователя SQL с правами только на чтение (роль db_datareader), не используйте учётную запись, под которой работает сервер ProBonus.
• Версия схемы. Номер версии в db_information.version_num позволяет определить, какой версии ProBonus соответствует база, например при переносе базы между серверами.