# ADR-0019. Объединение дублей участников

- Статус: принято; реализовано на этапе 6 — ✅ 6k (перенос участника в леджере), ✅ 6l: 6l-1 (объединение
  участников в модулях), 6l-2 (API после объединения), 6l-3 (страница в кабинете мерчанта)
- Дата: 2026-10-14

## Контекст

Один человек оказывается в программе дважды: зарегистрировался на кассе по старому телефону и на сайте по новому,
получил карту и потерял её (п. 4.11 и 6.6 roadmap). Баллы, уровень и история такого участника разбросаны по двум
записям. Поддержка мерчанта должна объединить дубль с основной записью: баллы переходят к ней с теми же сроками,
возвраты прошлых покупок дубля списывают баллы там, где они теперь лежат, а дубль больше ничего не получает. Переводов
баллов между участниками в остальном нет (п. 4.7 roadmap): это не перевод, а исправление учёта одного человека.

## Решение

### Перенос в леджере (6k)

- `Ledger::transferMember(TransferMember{programId, fromMemberId, toMemberId, idempotencyKey, effectiveAt, actor})`
  переносит всё, что есть у дубля, к «выжившему» (основной записи) — во всех типах баллов программы и в любом другом,
  где у одного из них есть счёт. Одна транзакция БД; вызывающий (объединение 6l) может обернуть её своей. Сначала у
  обоих активируются и сгорают партии, чей срок наступил, а просроченные резервы дубля снимаются — как это сделали бы
  плановые команды.
- **Партии меняют владельца и сохраняют условия.** Каждая партия дубля (активная, ожидающая, сгоревшая, исчерпанная)
  получает `member_id` выжившего: срок активации, срок сгорания, скользящий срок, остаток и журнал движений не
  меняются. Поэтому порядок списания (ближайшее сгорание первым) общий для партий обоих, а возврат покупки дубля
  возвращает баллы в те же партии.
- **Балансы идут через клиринговый счёт** `transfer` (системный, без материализованного баланса; появляется вместе с
  остальными системными счетами типа баллов при первой операции в нём): транзакция `transfer` у дубля выводит доступное
  и ожидающее в клиринг, у выжившего — вводит. Пара ссылается на запись объединения (`reference_type =
  member_transfer`), и по каждому объединению и типу баллов клиринг сходится в ноль (это проверяет сверка). Резерва у
  дубля быть не может: при активном резерве перенос отклоняется (`member_has_active_holds`, 409) — сначала покупка
  завершается или резерв снимается.
- **Долг переходит тоже.** Отрицательный доступный баланс дубля приходит к выжившему: то, что покрывают его доступные
  партии, списывается с них (движение партий `transfer`), остаток остаётся долгом. Тип баллов такой долг допускает: он
  был у дубля в том же типе, а настройку «минус на балансе» у типа баллов изменить нельзя. Баллы, пришедшие к выжившему
  с долгом, сначала гасят долг, как любое поступление; ожидающие — когда станут доступны.
- **Кто в кого объединён** — `ledger_member_successors` (RLS, только добавление): участник объединяется один раз,
  никогда в самого себя и никогда в уже объединённого (`member_merged`, 409, с `survivor_id`); то, что было у
  участника, держит конец его цепочки (A в B, затем B в C — C), не длиннее 8 объединений.
- **Блокировки.** Перенос берёт advisory-блокировки обоих участников в порядке их id, затем счета обоих во всех типах
  баллов в порядке (участник, тип баллов): встречные переносы двух участников ждут друг друга, а не взаимно
  блокируются. Первые счета участника в типе баллов создаются под той же блокировкой участника с проверкой, не
  объединён ли он. Счета участника ищутся через типы баллов: индекс счетов начинается с типа баллов.
- **Взаимные блокировки с операциями.** Операция, которая блокирует счета дубля или выжившего в другом порядке, может
  встретить перенос взаимной блокировкой: покупка или возврат в двух типах баллов (баллы, затем штампы), продление
  скользящего срока перед начислением бонуса, создание счетов во втором типе баллов. PostgreSQL прерывает одну из
  транзакций, и повторяется только прерванная: чек — протоколом кассы, объединение — своими попытками. Попытки
  Laravel повторяет только у внешней транзакции, поэтому объединение 6l — одна внешняя транзакция с попытками.
- **Повтор** той же пары возвращает записанный результат (`replayed`); тот же ключ для другой пары —
  `idempotency_key_reused`, в том числе когда его одновременно занял перенос других участников; повтор после
  объединения дубля с другим — `member_merged`. Ключ переноса хранится в записи объединения, отдельно от ключей
  операций.

### Объединённый участник в леджере

- Счета дубля отмечаются `merged_into_id` последними, при нулевых балансах. Новых баллов, резервов и корректировок у
  объединённого нет: блокировка счетов читает отметку из строк, которые блокирует, поэтому операция, дождавшаяся
  переноса, видит его, — и отвечает `member_merged` с `survivor_id`; в типе баллов, где у дубля нет счетов, их не
  создаёт проверка записи объединения. Повтор по ключу начисления, корректировки или резерва, сделанных до объединения,
  возвращает их результат; новые операции выжившего ключи дубля не наследуют.
- То, что было у дубля, следует за выжившим: отмена начисления, возврат оплаченного баллами и обслуживание партий
  (активация, сгорание) находят владельца через цепочку объединений — и находят снова, если, пока операция ждала
  блокировку, объединили и выжившего. Повтор такой операции по ключу узнаётся по её начислению или резерву, кто бы ни
  держал его тогда. Партии и резервы адресуются по id, поэтому возврат приходит в те же партии на тех же условиях;
  вернувшееся в сгоревшую партию сгорает, как всегда.
- **Гарантии базы.** Партия меняет владельца только на записанного преемника владельца, который сам не объединён;
  партию объединённому участнику не создать; отметку счёта ставят один раз — при нулевом балансе до и после изменения
  и только с записанным преемником, — и после неё счёт не меняется ни по балансу, ни по отметке.
- **Сверка** проверяет, что у объединённого нет партий и балансов, а все его счета отмечены преемником, и что клиринг
  каждого переноса сходится в ноль.

### Объединение участников (6l-1)

- **Одна точка входа** — `Modules\Support\Contracts\MemberMerges`: `preview` показывает, что объединение сделает и что
  ему мешает, `merge` объединяет. Объединение — отдельная внешняя транзакция с тремя попытками (Laravel повторяет
  только внешнюю). До неё просроченные резервы дубля отменяются, каждый своей транзакцией, как это сделала бы плановая
  команда. Порядок блокировок в ней: оба участника `for update` в порядке id (`Members::lockForMerge`) → бонусные
  награды участников (до баллов: покупка друга берёт награду, затем баллы, которые она даёт) → баллы
  (`Ledger::transferMember`) → данные модулей. Регистрация чека, его подтверждение, отмена, аннулирование и возврат
  берут участника раньше его баллов — поэтому ждут объединение, а не встречают его взаимной блокировкой; чек дубля,
  дождавшийся объединения, отклоняется (`member_merged`). Повтор того же объединения (любым ключом) возвращает его
  результат; ключ — до 194 символов (ключ переноса в леджере — он же с префиксом `merge:`).
- **Отказы** (`merge_refused` со списком причин): тот же участник, разные программы, один из них объединён, обезличен,
  заморожен или заблокирован (баллы замороженного не должны стать доступными у другого), у обоих есть внешний
  идентификатор (какой оставить — решает мерчант), у дубля есть незавершённые покупки (резервы чеков). Цепочку глубже
  8 объединений отклоняет леджер.
- **Участник** (`members`): статус `merged`, основная запись (`merged_into_id`) и время (`merged_at`), навсегда — база
  отклоняет другой статус, другую основную запись и объединение в объединённого. Карты дубля (рабочие и
  заблокированные) и его внешний идентификатор (если у основной записи его нет) переходят; контакты и коды для кассы
  дубля удаляются, а согласия отзываются — у основной записи свои; из данных человека остаётся только имя, для истории
  (дата рождения, пол, атрибуты и реферальный код стираются). Объединённого не находят ни по телефону, ни по карте, ни
  по коду; что-либо сделать для него — `member_merged` с `survivor_id`; обезличивание основной записи стирает и имена её
  дублей.
- **Уровни**: покупки суммируются по дням; у основной записи остаётся высший из двух уровней — уровень дубля целиком, со
  сроком удержания и ручной фиксацией (с её причиной); суммарные покупки могут поднять ещё выше. Вебхук
  `member.tier_changed` называет это `upgrade`.
- **Акции и промокоды**: использования акций по периодам суммируются (сумма может превысить лимит — дальше акция для
  человека не применяется), использования промокодов засчитываются основной записи, персональные промокоды дубля
  отключаются.
- **Бонусы** — одна награда каждого вида на человека: ждущие покупки приветственная награда и награда друга дубля
  переходят к основной записи, если у неё нет своей такого вида, и гаснут иначе; награды дубля за приглашённых им друзей
  переходят; награда пригласившего дубля ждёт покупки основной записи, если её саму не пригласили; ждущие награды
  основной записи (и награда пригласившего её) гаснут, если дубль такую уже получил; приглашение человеком самого себя
  не награждается. Выданные награды остаются; месячный лимит наград пригласившего считает и награды его дублей.
- **Баллы за действия**: лимит участника на период считает и награды его дублей (`activity_rewards` неизменны).
- **Процессинг**: подтверждение, отмена, аннулирование и возврат чека дубля действуют на основную запись (уровни,
  лимиты акций, бонусы, баллы); чек из офлайн-пакета, названный дублем по id, — чек дубля (касса узнаёт его по тому
  участнику, которого назвала), начисляющий основной записи; по телефону дубль не найдётся — его телефон стёрт. Покупки
  дубля — покупки основной записи: в списке покупок (возврат на кассе находит их там; у таких чеков участник — дубль со
  статусом `merged`), в счётчике покупок для условий акций и в ограничении частоты списаний. В событиях `receipt.*`
  `member_id` — тот, кто купил. Статус `merged` есть в схемах участника Runtime и Management API, основная запись — в
  `merged_into_id` у Management API.
- **Вебхук** `member.merged`: дубль, основная запись, программа, время.

### API после объединения (6l-2)

- **Runtime API**: запросы с id дубля — поиск, баланс, история баллов, покупки, код для приложения, код для списания,
  баллы за действия, расчёт и проведение чека — получают 409 `member_merged` с `survivor_id` — записью, у которой
  теперь всё (концом цепочки объединений; `merged_into_id` — запись, с которой объединили): касса не продолжает с
  дублем. Веб-касса сама находит эту запись по id, показывает её вместо объединённой и просит повторить действие —
  кассир не ищет клиента по стёртому телефону и не заводит нового дубля. Офлайн-чек, названный дублем, принимается,
  как в 6l-1: касса не может назвать участника заново, когда чек уже продан; и когда объединение идёт в тот же момент,
  чек ждёт его и готовится заново, для основной записи. Объединённый участник другой программы для ключа — никто (404
  `member_not_found`): id основной записи не называется чужой программе.
- **API участника**: сеанс дубля не работает — 401 `unauthenticated` на всё, кроме закрытия сеанса, как у
  заблокированного и обезличенного; участник, заблокированный, обезличенный или объединённый во время выдачи кода, —
  тоже 401.
- **Management API**: дубль читается (участник со статусом `merged` и `merged_into_id`, история баллов, бонусы), а
  изменения — корректировка баллов, фиксация уровня, смена статуса, обезличивание, сеанс виджетов — получают 409
  `member_merged` с `survivor_id`. Внешний id мерчанта после объединения находит основную запись. Персональный промокод
  дублю не выдаётся с тем же ответом, что участнику другой программы (422 `invalid_promo_code`): операция под скоупом
  `programs` не называет id основной записи учётным данным без скоупа `members`.

### Кабинет мерчанта (6l-3)

- **«Объединить дубли»** (`Merchant\Pages\Members\MemberMerge`) открывается из «Действий» карточки участника —
  «Объединить с дублем»: участник карточки — основная запись. Дубль находят кнопкой «Найти дубль» по телефону, номеру
  карты или внешнему идентификатору целиком в программе основной записи, как «Найти участника» в списке (общий
  `MemberLookups`, тот же лимит промахов; журнал `members.lookup` получает найденного, а не введённое); найденный
  хранится в закреплённом свойстве страницы, которое меняют только поиск и «Поменять местами» — если страницу открыли
  из карточки дубля.
- Страница показывает обе записи (с контактами в маске, датой рождения и каналом вступления) и то, что сделает
  объединение (`MemberMerges::preview`): баллы и штампы обоих (баллы дубля переходят со своими сроками), карты дубля,
  уровни (у участника без своего уровня — стартовый, как в карточке; остаётся более высокий из двух), внешний
  идентификатор, персональные промокоды, которые перестанут работать, ожидающие покупки бонусы — дубля, основной
  записи и пригласивших их, — которые перейдут или погаснут, код для приглашения друзей, удаление контактов дубля; или
  почему объединить нельзя — по каждой причине своим текстом. Телефон, почта и дата рождения, которые есть только у
  дубля, удалятся: страница предупреждает об этом и советует поменять записи местами. Открыть её и объединить может
  только тот, кто видит участников и вправе их объединять, — владелец или администратор (`members.merge`): это
  чувствительное право — второй фактор, подтверждённый недавно, и никогда через доступ поддержки; приостановленный
  мерчант не объединяет.
- «Объединить» просит причину (она остаётся в журнале аудита) и слово «объединить», не больше 30 раз в час одному
  человеку; ключ идемпотентности создаётся при открытии формы. Журнал `members.merge` называет обе записи (`member` —
  основную, `duplicate` — дубль) и причину. Если объединение стало невозможным, пока форма была открыта (покупка
  началась, статус изменился), кнопка пропадает, форма закрывается, а причины показывает страница; отказ в момент самого
  объединения тоже закрывает форму и называет причины в уведомлении (слишком длинную цепочку объединений — тоже).
  После объединения кабинет открывает карточку основной записи; карточка дубля показывает статус «Объединён с основной
  записью» и ссылку на неё, а действий для него не предлагает.

## Последствия

- Объединение — одна внешняя транзакция: блокировка двух участников, проверки, перенос баллов и данных модулей;
  задачи по участникам (бонусы ко дню рождения) объединённых пропускают: такие задачи выбирают активных и замороженных.
- История дубля заканчивается переносом: его баланс уходит в ноль. В истории выжившего перенос приносит баланс дубля,
  долг — со знаком минус. Перенос, который не меняет общий баланс (долг, равный ожидающим баллам), не виден ни в одной
  истории, как и активация. Кабинет и виджеты называют операцию «Перенос баллов», основание — «Объединение
  участников».
- Записи объединений и отметки счетов неизменны: «разъединить» участников нельзя. Ошибочное объединение исправляют
  вручную — баллы снимают корректировкой у выжившего и начисляют новой записи участника, — поэтому объединение в 6l
  требует явного подтверждения.
- Цепочка объединений ограничена 8 звеньями: девятое объединение конца цепочки отклоняется; на практике объединения
  дубля дубля почти не бывает.
