# ADR-0021. Кабинет покупателя

- Статус: принято; реализуется на этапе 7 — 7e-1 (адрес кабинета, вход по коду, сеансы), 7e-2 (вступление в
  программу, «Выйти везде», мерчант завершает сеансы), 7e-3a (согласия, имя и день рождения на плоскости участника),
  7e-3b (e-mail с подтверждением письмом), 7e-4 (ссылка «Отписаться» и реклама письмами), 7f-1 (приложение кабинета:
  вход, карта с кодом для кассы, история, главный экран телефона), 7f-2 (вступление в приложении, возраст), 7f-3
  (профиль и подписки), 7f-4 (цвет карты)
- Дата: 2026-10-24

## Контекст

Покупатель должен видеть свои баллы, историю, уровень и код для кассы без сайта мерчанта и без приложения из магазина
приложений (п. 7.1 roadmap), отзывать согласие на рекламу (38-ФЗ требует способа отказаться) и подтверждать свой e-mail
(письма участникам уходят на неподтверждённые адреса, ADR-0020). Плоскость участника (ADR-0018) уже отдаёт его данные
странице, но её сеанс открывает только сервер мерчанта или партнёра, и живёт он не больше часа. Кабинету покупателя
нужен свой вход: по коду на номер телефона, без кассира и без сайта мерчанта, — а это открытая страница, с которой
можно отправлять платные SMS.

Решения владельца продукта (2026-10-24): адрес — на хосте платформы с коротким именем программы
(`club.<платформа>/p/<имя>`, свой домен мерчанта позже); перед кодом — Yandex SmartCaptcha; покупатель сам меняет
согласия, e-mail (с подтверждением письмом) и имя, день рождения — только пока он не указан, телефон — через
мерчанта; вход держится до выхода, но не дольше года (рекомендация была 30 дней без визитов и 90 дней всего: потерянный
телефон с открытым кабинетом показывает баллы и код для кассы; защита — «Выйти везде», мерчант завершает сеансы,
блокировка участника).

## Решение

### Адрес кабинета

- Кабинет программы открывает мерчант («Программа» → «Кабинет покупателя», право `programs.manage`), выбирая короткое
  имя: 3–30 знаков, латинские буквы, цифры и дефисы (заглавные становятся строчными), первая — буква, без дефиса в конце
  и двух подряд, не из списка зарезервированных. Имя публично (это адрес), поэтому оно уникально на всей платформе:
  таблица `program_portals` (модуль `portal`, RLS) держит его первичным ключом — проверка уникальности открывает только
  то, что и так видно по адресу (обычный уникальный индекс тенанта начинается с `tenant_id`, ADR-0002; исключение
  названо в тесте схемы). Имя можно сменить — старые ссылки перестают работать, а браузеры входят заново (cookie привязан
  к адресу). Закрытие кабинета завершает все его сеансы; закрывает его и приостановленный мерчант — это только защищает
  (отдельное право `portal.close`: коды за его счёт прекращаются). Кабинет архивной программы не работает: в кабинете
  мерчанта его можно только закрыть. Имя закрытого мерчанта остаётся занятым.
- Хост — `PORTAL_DOMAIN`; кабинет программы — `https://<хост>/p/<имя>/`. Вне `local` и `testing` без своего хоста
  кабинет не отвечает нигде (как веб-касса без своего, ADR-0016): у кабинета покупателей и кабинетов сотрудников не
  должно быть общих cookie и общего источника страницы. Локально без него кабинет отвечает на любом хосте.
- Адрес находят до тенанта узкой функцией SECURITY DEFINER `portal_address` (ADR-0002): точное имя, тенант, программа,
  статус мерчанта и программы. Кабинет работает у открытого мерчанта с активной программой: приостановленный мерчант
  (ADR-0015) кабинет не теряет — как кассы и виджеты, — закрытый мерчант и архивная программа отвечают «не найдено».

### Вход по коду

- Страница кабинета и его собственные запросы — группа `web` на хосте кабинета: запросы, которые что-то меняют,
  проходят защиту от подделки запросов фреймворка (`Sec-Fetch-Site: same-origin` или токен XSRF), как у кассы.
  Ответы — problem+json; коды отказов этих запросов не входят в спецификации API (как у оболочки кассы).
- `POST /p/<имя>/codes` — номер и токен капчи. Сначала капча, потом участник по номеру в программе: есть (активный,
  замороженный или заблокированный) — код входа (`member_login`, привязан к программе); нет — код регистрации там, где
  в кабинете можно вступить в программу (7e-2, ниже), с тем же ответом, а где нельзя — 404, и SMS незнакомому номеру не
  уходит. Код идёт через каналы мерчанта и считается в его лимитах дня и месяца.
- **Публичные коды** (`verification_requests.public`): чтобы посторонний не тратил коды касс, у кодов кабинета свои
  лимиты — на номер (3 в час, 5 в сутки; коды касс считаются отдельно), не больше половины лимита мерчанта на день и
  месяц, и своя остановка: если из кодов кабинета за последний час подтверждают меньше пятой части, коды кабинета
  ждут; остановка сама кончается с уходом часа, и мерчанта о ней не извещают. Остановка мерчанта (ADR-0020) считает
  только коды касс. Коды кассы при этом уходят.
- `POST /p/<имя>/session` — номер, код и его идентификатор. Код проверяется отдельно (неверная попытка остаётся
  посчитанной), затем в одной транзакции кабинет удерживается открытым, ищется участник, и код расходуется прежде, чем
  об участнике что-то сказано — по коду другого номера ничего не узнать; любой отказ возвращает код. Верный код
  активного или замороженного участника открывает сеанс кабинета; заблокированному — 409 `member_blocked` (о блокировке
  узнаёт только тот, кто получил код). Подтверждённый код регистрации этого самого номера и кабинета, у которого нет
  участника, отвечает 409 `portal_registration_required` и остаётся целым для вступления (а если вступление тем
  временем выключили — 409 `portal_joining_closed`).
- Лимиты запросов кабинета — по адресу (IPv6 по /64), щедрые: за Wi-Fi магазина или мобильным оператором много
  покупателей на одном адресе. Коды берегут капча и лимиты публичных кодов.

### Вступление в программу (7e-2)

- Вступать в программу в кабинете можно, если мерчант разрешил (`program_portals.joining`, по умолчанию да: переключатель
  при открытии кабинета и «Разрешить / Запретить вступление» в «Кабинете покупателя», журнал `portals.joining`) и
  программа опубликовала правила и согласие на обработку персональных данных. Иначе незнакомый номер получает 404, а
  кабинет мерчанта показывает, чего не хватает. Разрешить — `programs.manage`; запретить только защищает (коды
  регистрации за счёт мерчанта прекращаются), как закрытие, — `portal.close`, и у приостановленного мерчанта.
- Незнакомый номер получает код регистрации (`registration`, публичный, привязан к программе) с тем же ответом, что и код
  входа: по ответу не узнать, участник ли номер. Оба запроса к базе делаются для любого номера, и время ответа этого
  тоже не выдаёт; пауза перед повторным кодом и «повторный — по SMS» у публичных кодов считаются по всем публичным кодам
  номера, какой бы ни была цель, — иначе два кабинета одного мерчанта выдали бы это разницей пауз. Публичный код берёт
  только тот, кто называет его контекст целиком: код регистрации кабинета не годится для регистрации на кассе.
  Подтверждённый код говорит `POST session`, что сначала вступление.
- `GET /p/<имя>/documents` — действующие версии документов вступления с текстами: обязательные (правила программы,
  согласие на обработку персональных данных) и по желанию (реклама по SMS и письмами); `GET /p/<имя>/program` отвечает,
  можно ли вступить (`joining`).
- `POST /p/<имя>/members` — номер, идентификатор подтверждённого кода регистрации, согласия — вид и версия документа,
  которую показала страница (оба обязательных, других видов кабинет не берёт), имя и фамилия (хотя бы одна буква, без
  управляющих, невидимых, разделяющих строки и «пустых» знаков), день рождения и код пригласившего — по желанию. В одной
  транзакции кабинет удерживается открытым, проверяется, что вступление разрешено, затем — что код регистрации этого
  номера и кабинета подтверждён (до всего остального: код пригласившего не проверить тому, у кого нет кода), что
  версии документов всё ещё действующие (вышла новая — 409 `consent_document_outdated`: человек соглашается с тем
  текстом, который видел), и участник вступает через канал `portal` (согласия — с каналом `portal`, адресом и кабинетом
  в доказательствах, код регистрации расходуется с привязкой к программе), получает сеанс кабинета и cookie, как при
  входе. Номер, вступивший тем временем на кассе, — 409 `member_already_exists`, код возвращается.

### Проверка «я не робот»

- Перед каждым кодом кабинет проверяет токен Yandex SmartCaptcha на сервере (`validate` с ключом сервера и адресом
  покупателя). Невалидный токен — 422 `human_check_failed`. Если сервис проверки не ответил или ответил ошибкой,
  покупатель проходит (так советует Яндекс: сбой сервиса не должен закрывать вход), остальные лимиты остаются.
- Ключи — `PORTAL_CAPTCHA_CLIENT_KEY` и `PORTAL_CAPTCHA_SERVER_KEY` (аккаунт Yandex Cloud владельца). Без них в рабочем
  окружении кабинет кодов не отправляет: 409 `human_check_unavailable`, а «Состояние системы» предупреждает
  (`portal.human_check`), если при этом открыт хоть один кабинет. Локально, в тестах и в песочнице без ключей проверка
  проходит всегда.

### Сеанс кабинета

- Сеанс `lps_<префикс>.<секрет>` (`portal_sessions`, модуль `access`, RLS) — один участник одной программы; хранится
  только SHA-256 секрета с маркером окружения, как у ключей и сеансов участника. Живёт год с входа (решение владельца) и
  не продлевается; `last_used_at` пишется не чаще раза в пять минут.
- Браузер держит его в cookie своего кабинета — `__Host-loyal_portal-<имя>` (локально по http — `loyal_portal-<имя>`):
  HttpOnly, SameSite=Strict, только для хоста кабинета, путь `/`; покупатель двух программ остаётся в обеих. Скрипт
  страницы её не видит. Приставка `__Host-` (7f-1) значит, что браузер принимает такую cookie только от самого хоста
  кабинета: другой хост того же домена — сайт мерчанта, хост коробки «Я не робот» — не подложит свою и не войдёт за
  покупателя в чужую запись. Поэтому кабинет — в её имени, а не в пути (`__Host-` требует путь `/`).
- Участник проверяется на каждом запросе сеанса: заблокированный, обезличенный, объединённый или участник другой
  программы — сеанс завершается, и cookie стирается. Блокировка, смена телефона, обезличивание и объединение завершают
  сеансы кабинета сразу, в своей транзакции (события модуля участников): разблокировка их не возвращает.
- Истёкшие и завершённые сеансы удаляет `member-sessions:prune` через сутки.
- `DELETE /p/<имя>/session` — выход: сеанс завершён, cookie стёрт (и без действующего сеанса — тоже 204).
- `DELETE /p/<имя>/sessions` — «Выйти везде» (7e-2): все сеансы участника и выданные ими сеансы плоскости участника
  завершаются, cookie стёрт; без действующего сеанса — 401 `portal_session_required`.
- Мерчант завершает сеансы участника из его карточки («Выйти из кабинета покупателя везде», 7e-2): карточка показывает,
  на скольких устройствах открыт кабинет. Это только защищает, как блокировка потерянной карты, поэтому право то же —
  `members.block_cards` (есть и у приостановленного мерчанта); журнал `members.end-portal-sessions`.

### Данные покупателя — через плоскость участника

- Кабинет — сайт, у которого бэкенд — сама платформа: `POST /p/<имя>/session/tokens` по cookie выдаёт сеанс плоскости
  участника `lms_…` (ADR-0018) для сайта кабинета на 15 минут со скоупами `profile`, `history`, `presentation_code`,
  `consents` и `details` (покупатель подтвердил номер кодом — это сильнее, чем слово сервера мерчанта). Приложение
  кабинета (7f) читает баланс, историю и код для кассы и меняет данные покупателя обычным клиентом участника SDK — тем же
  API, что виджеты.
- Сеанс участника называет того, кто его открыл: ключ мерчанта, клиент партнёра или — теперь — сеанс кабинета
  (`member_sessions.issued_by_portal_session_id`, ровно один из трёх). Он работает, пока работает открывший: выход из
  кабинета сразу закрывает и выданные им сеансы участника.
- Сайт сеанса — источник страницы кабинета. Плоскость участника принимает запрос страницы того же хоста, что и API:
  без `Origin` (браузер не шлёт его в запросах GET своего же хоста), но с `Sec-Fetch-Site: same-origin` от хоста,
  равного сайту сеанса. Этот заголовок ставит сам браузер, и страница чужого сайта его не подделает. Так приложение
  кабинета обращается к API на своём хосте.

### Изменения покупателя (7e-3a)

- На плоскости участника (ADR-0018, поправка 7e-3): имя и фамилия, день рождения, пока он не известен (скоуп
  `details`), и согласия (скоуп `consents`): дать согласие на рекламу к версии документа, которую покупатель видел
  (вышла новая — 409 `consent_document_outdated`), или отозвать его; правила программы и обработку персональных данных
  здесь не отозвать — без них участия нет, это решает мерчант. Повтор ничего не записывает. Согласие записывается с
  каналом `portal`, если сеанс открыл кабинет, и `website`, если сайт мерчанта или партнёра; в доказательствах — сеанс,
  открывший его и id его учётных данных, сайт и адрес. Модуль участников меняет данные, держа строку участника
  (`for no key update`: два изменения ждут друг друга, обезличивание и объединение — тоже, кассы — нет;
  `Members::changeDetails`, `changeConsent`). Изменений участника — 30 в час.
- День рождения, указанный позже регистрации, известен с этого момента (`members.birth_date_known_at`; пусто — известен
  с регистрации): бонус на день рождения он приносит, только когда известен столько, сколько программа требует
  участия, а в акциях дня рождения на кассе учитывается через 30 дней (`CheckoutService::OWN_BIRTHDAY_DAYS`) — как и
  день рождения, указанный при вступлении в кабинете: без кассира никто его не видел, а день рождения «на сегодня»
  приносил бы скидку сразу. Известный день рождения исправляет сотрудник мерчанта в карточке участника («Исправить день
  рождения», право `members.manage`, причина в журнале `members.birth-date`): мерчант за него ручается, и он считается
  известным с регистрации.

### E-mail покупателя (7e-3b)

- На плоскости участника (скоуп `details`): `POST me/email` с адресом — письмо с кодом из 6 цифр уходит на адрес через
  почту мерчанта (ADR-0020), пока покупатель ждёт (запрос — не дольше 8 секунд до ответа сервера: SDK ждёт ответа 10);
  `POST me/email:confirm` с кодом — адрес становится подтверждённым адресом участника (`members.email_confirmed_at`);
  `DELETE me/email` — адреса больше нет. Код, а не ссылка: ссылку в письме открывают почтовые сканеры, и адрес
  подтвердился бы без человека. Код действует 15 минут, на него 5 попыток (неверная засчитывается и при отказе),
  подтверждает только код последнего письма участника; тот же код повторно после подтверждения (ответ потерялся)
  отвечает как сейчас. Адрес хранится зашифрованным, пока код может его подтвердить, и не дольше часа после
  (`messages:prune` ежечасно). В песочнице — только тестовые адреса и код `000000`, письмо «уходит» через почту
  мерчанта, подключённую с любыми данными.
- Тот же адрес, запрошенный снова в течение минуты, — то же письмо (200, `resend_after`): SDK сам повторяет отказ 429
  с короткой паузой, и второе письмо отменило бы код, который покупатель уже вводит. Пока уходит другое письмо
  участника или на тот же ящик, запрос сразу получает 429 на несколько секунд (никто не ждёт дольше, чем SDK).
- Почта мерчанта как способ завалить чужой ящик письмами закрыта лимитами: 3 в час и 10 в сутки на участника, 3 в сутки
  от участника на один ящик (один участник не выберет чужой ящик целиком), 5 в сутки на ящик от всех участников
  мерчанта и 3000 в сутки у мерчанта; письмо, которое сервер не принял, считается тоже. Ящик, а не адрес: варианты
  одного ящика (`+метка`, точки в Gmail, домены и точки-дефисы Яндекса) считаются вместе. Ожидание из-за писем других
  участников называется с точностью до часа: когда шли их письма, спрашивающему знать не нужно. Без почты мерчанта —
  409 `code_delivery_unavailable` (локально и в тестах письмо пишется в журнал приложения), сервер не принял — 409
  `code_delivery_failed`.
- Занят ли адрес другим участником программы (адрес — одного участника в программе), узнаёт только тот, кто ввёл код
  письма (409 `email_taken`): по одному адресу нельзя выяснить, состоит ли его владелец в программе.
- Адрес, который указал сотрудник при регистрации, не подтверждён; карточка участника в кабинете и Management API
  (`email_confirmed`) показывают, подтвердил ли адрес сам покупатель. Коды писем исчезают при обезличивании и
  объединении участника и через сутки после письма (`messages:prune`).
- Отложено: покупатель меняет или убирает подтверждённый адрес без письма на прежний (сеанс короткий и привязан к
  сайту); письмо на прежний адрес — с сообщениями безопасности (7g).

### Отписка от рекламных писем (7e-4)

- Рекламное письмо уходит только на адрес, который покупатель подтвердил сам, с его согласия на рекламу письмами и со
  ссылкой «Отписаться» (ADR-0020, «Реклама письмами»). Ссылка ведёт на страницу хоста кабинета `/u/<токен>` — вне
  кабинета программы: рекламу письмами шлёт и мерчант, не открывший кабинет. Без хоста кабинета рекламных писем нет.
- **Открыть ссылку — только спросить:** почтовые сервисы и их сканеры открывают ссылки писем, и ссылка, которая
  отписывала бы при открытии, отписывала бы людей, которые этого не просили. Страница называет программу и спрашивает
  «Отписаться от рекламных писем?» с одной кнопкой; кнопка отзывает согласие на рекламу письмами — в один шаг, без входа
  и кода. Согласие на рекламу по SMS и служебные письма остаются; страница так и говорит. Если покупатель уже отписан,
  страница говорит «Вы уже отписались». Там, где кабинет программы работает, страница ведёт в его профиль (7f-3), где
  подписку можно вернуть или выбрать другие.
- **Работает везде, где отписка защищает:** у заблокированного участника, архивной программы и закрытого мерчанта
  ссылка тоже отзывает согласие — отзыв только защищает человека (закрытый мерчант всё равно ничего не отправляет).
- **Кнопка почтового сервиса** (RFC 8058) — `POST` на тот же адрес с `List-Unsubscribe=One-Click`; ответ тот же. Поэтому
  страница вне группы `web`: без сеанса, cookie и токена от подделки запросов — сервис их не пришлёт, а всё, что нужно, —
  подписанный токен в адресе (подделанный запрос другого сайта отписал бы только того, чья ссылка уже есть у
  подделывающего). Повтор ничего не записывает.
- **Что записывается:** отзыв согласия `marketing_email` через `Members::changeConsent` (строка участника удерживается,
  как при изменениях в кабинете) с каналом `email` («ссылка «Отписаться» в письме» в карточке участника) и
  доказательствами: сообщение очереди, способ (`page` — кнопка страницы, `one_click` — кнопка почтового сервиса) и адрес
  запроса (способ — только из тела запроса). Ссылка участника, объединённого с другим (ADR-0019), отзывает согласие
  основной записи: это тот же человек, и реклама приходила бы ему от её имени. Обезличенного участника ссылка не трогает —
  его согласия ушли вместе с данными.
- **Ссылка ничего не находит** (подпись не сходится, сообщение не рекламное или уже удалено — через 13 месяцев) — 404 и
  страница «Ссылка не найдена» без подробностей. Политика страницы: ничего не загружает, форма только на свой хост,
  без реферера (адрес — сам токен), без кэша.
- **Лимит запросов — у каждой ссылки свой** (30 в минуту, `portal.unsubscribe_per_minute`; ключ — хеш токена, не сам
  токен): кнопку почтового сервиса нажимают с тех же адресов, с которых его сканеры открывают ссылки всех писем, и общий
  лимит адреса отказал бы ей. Ссылка, которая ничего не находит, считается по адресу, как запросы кабинета.
- **На своём хосте кабинета ссылка всегда `https://`**: кнопка почтового сервиса принимает только такую (RFC 8058).
- На том же хосте и так же, вне кабинета программы и группы `web`, — страница ссылки «Не вы?» уведомлений о списании
  `/r/<токен>` (7g-2, ADR-0022): открыть — только спросить, кнопка замораживает карту; свой лимит у каждой ссылки
  (`portal.redemption_per_minute`) и та же политика страницы (`security.headers:redemption`).

### Приложение кабинета (7f-1)

- **Страница кабинета — приложение** (`frontend/portal`): TypeScript без зависимостей поверх клиента участника SDK и
  исходников виджетов (ADR-0018), собранный компилятором SDK, как приложение кассы (ADR-0016): `composer portal:build`
  кладёт сборку в `public/portal-app/<версия>` (не в git) рядом с `build.json` и service worker сборки. Страница
  `/p/<имя>` подставляет папку текущей сборки и не держит ничего встроенного: её политика не пускает встроенные
  скрипты и стили. Ответа на запрос к кабинету страница ждёт не дольше 20 с — самый долгий честный ответ, на запрос
  кода, занимает до 13 с (проверка «Я не робот» до 5 с и отправка кода до 8 с), — потом обрывает запрос и говорит «Нет
  соединения», как без сети, а не ждёт вечно.
- **Адрес кабинета — со слешем** (`/p/<имя>/`): приложение берёт путь страницы своей границей, а браузеры сравнивают
  её с адресами как начало строки — граница `/p/kofe` захватила бы `/p/kofe-house` другого мерчанта (установленная
  карта одной кофейни открывала бы чужой кабинет, а её service worker управлял бы им). Адрес без слеша ведёт на адрес
  со слешем (301, с параметрами), а правило `public/.htaccess` для Apache слеш кабинета не убирает. Ссылки и QR-коды
  кабинета мерчанта — со слешем.
- **Вход** — номер телефона, проверка «Я не робот» и код из сообщения (запросы кабинета выше). Проверка — коробка
  Yandex SmartCaptcha с ключом платформы. Её скрипт чужой, пишет стили прямо в страницу и грузит фреймы и скрипты с
  хостов Яндекса, поэтому коробка живёт в рамке своей страницы `/box` на **своём хосте**, `PORTAL_CAPTCHA_DOMAIN` —
  лучше на другом домене, не поддомене домена кабинета: на хосте кабинета скрипт коробки имел бы всю власть этого
  источника — запросил бы сеанс участника любого кабинета, где браузер вошёл, и подложил бы свои файлы в кэш service
  worker'а. На своём хосте он не видит ни cookie, ни хранилища, ни страниц кабинетов, а cookie кабинетов с приставкой
  `__Host-` не подложит и с соседнего хоста. Рамка не может увести страницу кабинета на другой адрес (`sandbox` без
  навигации верхнего окна). Страница рамки (вне группы `web`) — со своей политикой
  (`security.headers:portal-box`): хосты Яндекса — страница называет их в запросе, ядро берёт только простые
  `https://`-хосты и только в разрешённые директивы, — встроенные стили коробки, а рамку открывает только страница
  кабинетов (`frame-ancestors https://<хост кабинета>`; X-Frame-Options не умеет назвать другой сайт и не ставится). На
  своём хосте кабинет всегда по HTTPS — и его адрес в кабинете мерчанта, и источник, которому рамка сообщает токен.
  Рамка сообщает странице токен, свою высоту и задание проверки (тогда рамка закрывает экран) сообщениями, страница
  просит её сбросить коробку; обе стороны слушают только друг друга и только источник другой стороны. Страница
  кабинета сохраняет строгую политику и берёт хост коробки только для рамок. Хост коробки обязателен вместе с ключами
  вне разработки: без него кабинет не отправляет коды, а «Состояние системы» говорит почему; локально и в тестах
  коробка без своего хоста — на хосте кабинета. Коробка есть только на экране, который просит код, а вход и выход
  открывают страницу заново: в памяти страницы не остаётся ничего от прошлого входа. Токен проверки проходит один раз:
  после отказа, который дошёл до проверки, покупатель отмечает коробку снова.
- **Карта** — те же виджеты, что у сайтов мерчантов: сначала код для кассы (QR на две минуты по кнопке — у кассы он
  нужнее всего), потом баллы, уровень с прогрессом, штампы и код для друзей; история баллов — на своей вкладке
  (`#history`: кнопка телефона «Назад» возвращает к карте). Сеансы плоскости участника выдаёт сеанс кабинета
  (`POST session/tokens`), один на все виджеты страницы. Без связи карта говорит, что код для кассы не показать, и
  просит назвать кассиру номер телефона, а когда связь вернулась, показывает цифры заново; вернувшись на экран через
  минуту и позже — тоже, но без связи прежние цифры остаются на экране. Сеанс кончился («Выйти везде» на другом
  устройстве, мерчант завершил сеансы, блокировка) — страница просит войти снова; кабинет закрыли — говорит, что он
  закрыт.
- **Главный экран телефона** — это и есть веб-карта вместо Apple Wallet: у каждого кабинета свой манифест (название
  программы, кабинет — начало и граница приложения, значки) и свой service worker с границей `/p/<имя>/`. Браузер, который
  сам ставит страницы (Chromium), предлагает «Добавить» на карте; Safari на iPhone и iPad ставит страницу только через
  «Поделиться» — карта говорит, как. «Не сейчас» убирает подсказку на этом устройстве на месяц; в окне приложения
  подсказки нет.
- **Service worker** хранит файлы сборки, и каждый — только таким, каким его сделала сборка: она пишет в него
  отпечаток SHA-256 каждого файла, и копию с другим отпечатком (её мог положить в кэш браузера любой скрипт этого
  хоста) он не отдаёт никогда — берёт файл из сети. Страницу кабинета он берёт из сети, сколько бы она ни отвечала, а
  без сети или при ошибке сервера отдаёт страницу сборки «Нет соединения» (тоже по отпечатку); страниц кабинетов,
  манифеста, ответов API участника и запросов кабинета он не хранит — на устройстве не остаётся ничего о покупателе.
  Регистрируется он после того, как страница открылась: файлы сборки — много запросов, они не должны задерживать
  первые запросы покупателя.
- **Значки карты** — карта с полосой на цвете программы (сама карта белая на тёмном цвете, почти чёрная на светлом),
  PNG, нарисованный без графической библиотеки один раз на цвет (кэш приложения держит его текстом); адрес значка
  называет версию рисунка и цвет, и браузер хранит его навсегда. Свой цвет мерчант выбирает с 7f-4 (решение владельца
  продукта: цвет сейчас, логотип позже — для него нужно хранилище файлов).
- **Манифест, service worker, значки и рамка коробки** — вне группы `web`: браузер запрашивает их без cookie, и каждый
  запрос начинал бы сеанс. Закрытый кабинет не отдаёт ни их, ни страницу.
- Локально кабинет пробуют на мерчанте без каналов, у которого код кабинета пишется в журнал приложения:
  `php artisan db:seed --class=LocalPortalSeeder` (`/p/kofe-u-doma/`).

### Вступление в приложении (7f-2)

- **Номер, которого нет в программе**, после кода регистрации видит анкету вместо отказа: имя, фамилия, дата
  рождения, код друга (всё по желанию), документы — обязательные (правила программы, согласие на обработку
  персональных данных) и по желанию (реклама по SMS и письмами), у каждого флажок и текст, который можно прочитать
  тут же (тексты — узлами текста, как написал мерчант), — и строка «Мне есть N лет». Анкета приходит свежей
  (`GET program` и `GET documents` при каждом показе); вступление выключено тем временем — номер слышит, что вступить
  здесь нельзя. Кнопка «Вступить» шлёт `POST members` с версиями показанных документов; сеанс кабинета приходит в
  cookie, и страница открывается заново с картой, как после входа.
- **Возраст** — решение владельца продукта: в кабинете вступают с 14 лет, мерчант может поставить 18
  (`program_portals.min_age`, проверка в базе — только 14 и 18; выбор при открытии кабинета и «Возраст для вступления»
  в «Кабинете покупателя», `programs.manage`, журнал `portals.age`). Это правило только кабинета: на кассе человека
  видит кассир. Анкета просит подтвердить возраст строкой «Мне есть N лет» (`age_confirmed` — тот возраст, что она
  назвала, и он должен быть возрастом кабинета сейчас): возраст, изменённый мерчантом, пока анкета была открыта
  (поднятый или опущенный), — 409 `portal_age_outdated` с новым `min_age`, и строка называет его снова без отметки,
  так что в доказательствах всегда тот возраст, по которому проверялся день рождения; день рождения младше — 422
  `portal_age_not_reached`, и строка теряет отметку, поставленную рядом с ним. Возраст считается по дню часового пояса
  программы с самого дня рождения; родившийся 29 февраля в невисокосный год — с 1 марта. Обе проверки — после проверки
  кода, как всё, что говорит запрос, и код при отказе не расходуется. Подтверждённый возраст записывается в
  доказательства согласий вместе с адресом и кабинетом.
- **Возраст проверяется при вступлении.** День рождения, сказанный позже (профиль кабинета, сотрудник в карточке),
  сохраняется как сказан, даже младше возраста кабинета: отказ спрятал бы факт, а участника не исключил. Такого
  участника мерчант видит в карточке, а в доказательствах его согласий остаётся возраст, который он подтвердил.
- **Что анкета говорит**: какое поле не подошло (первое в её порядке: поле отмечено и получает фокус), что кода друга
  нет, что документы обновились (анкета показывается заново с новыми текстами, сообщение — над ней и с фокусом,
  введённое остаётся, флажки — нет), что номер уже вступил на кассе (войти по новому коду с тем же номером), что код
  больше не действует (получить новый с тем же номером), что нет связи (введённое остаётся). Введённое хранится только
  в памяти страницы — для своего номера, до перезагрузки — и переживает новый код; ответ, пришедший после того, как
  человек ушёл за новым кодом, его экран не меняет. Обязательные флажки браузер проверяет сам и показывает, какой не
  отмечен; сообщения страницы о них — там, где проверок браузера нет.

### Профиль (7f-3)

- **Вкладка «Профиль»** (`#profile`, рядом с картой и историей) — то, что покупатель меняет о себе сам (7e-3), обычным
  клиентом участника SDK с сеансом страницы (скоупы `details` и `consents`). Профиль спрашивает данные, когда его
  вкладку открыли впервые, — не раньше: карте у кассы они не нужны.
- **Имя и фамилия** уходят, только если покупатель изменил то, что показывает форма (пустое поле убирает их): правка
  магазина тем временем в другом из них остаётся. Новое имя карта сразу показывает в приветствии.
- **День рождения** — пока он не известен: поле даты и «Сохранить», и перед отправкой страница спрашивает «Сохранить
  день рождения — 15 марта 1990 г.? Исправить его потом сможет только магазин»: указать его можно один раз. Известный
  день рождения профиль только показывает. Указанный тем временем (магазином, на другом устройстве) — 409
  `birth_date_set`: профиль показывает его. Поле даты берёт день не позже вчерашнего (кабинет и плоскость участника
  принимают только прошедший день), а дату, которую браузер без поля даты не прочёл, страница не отправляет. Правило
  возраста кабинета — только при вступлении (7f-2).
- **E-mail**: адрес, подтверждён ли он (адрес, который указал магазин, — нет: его подтверждают письмом, рекламные
  письма приходят только на подтверждённый), «Изменить» (у неподтверждённого — «Подтвердить»: адрес вводят ещё раз,
  страница знает его только скрытым) и «Убрать» (с вопросом). Новый адрес — письмо с кодом, затем поле кода; прежний
  адрес остаётся адресом покупателя, пока новый не подтверждён. «Отправить письмо ещё раз» в минуту после письма
  (до `resend_after`, но не дольше минуты от ответа: часы телефона могут отставать) ничего не спрашивает, а говорит,
  когда можно; код уже не действует (410) — новое письмо уходит сразу. Тот же адрес раньше — то же письмо, и если
  сервер вернул его (часы телефона спешат), страница говорит, что письмо уже в пути, а не что ушло новое. «Другой
  адрес» возвращает введённый. Адрес у другого участника программы (409 `email_taken`) — форма адреса снова, с ним.
- **Подписки** — согласия на рекламу, которые программа публикует: флажок, документ и его текст тут же. Флажок даёт
  согласие к показанной версии документа или отзывает его сразу; вышла новая версия, пока профиль открыт (409
  `consent_document_outdated`), — подписки показываются заново, без отметки, а сообщение над ними называет документ.
  Согласие, данное к прежней редакции, отмечено с припиской об этом: чтобы согласиться с новой, флажок снимают и ставят
  снова. Под флажком рекламных писем, пока подтверждённого e-mail нет, — подсказка, что они приходят только на
  подтверждённый. Правила программы и согласие на обработку персональных данных — в «Документах программы»: их можно
  прочитать, но не отозвать здесь (без них участия нет).
- **Что профиль говорит**: отказ — в строке своего раздела (она всегда на странице, и программа чтения с экрана слышит,
  как она меняется), поле, которое не подошло, отмечено и получает фокус, введённое остаётся; неверный код — с
  оставшимися попытками, ожидание — сколько ждать (писем слишком много, слишком много запросов: изменений — не больше
  30 в час); сеанс кончился — вход заново, как у карты. Пока запрос раздела идёт, его кнопки ждут, а потом
  возвращают фокус, который отдали странице; ответ всегда приходит к тому шагу, который спросил, и переносит фокус,
  только если покупатель не ушёл в другое место страницы. Что покупатель набрал, пока имя сохранялось, остаётся.
- **Флажок подписки** во время запроса не выключается (иначе фокус клавиатуры ушёл бы с него), но другого изменения не
  берёт. Отказ или изменение, которое не ушло (связи не было до отправки, портал не продлил сеанс), — флажок
  возвращается. Нет ответа, сбой сервера или ответ, который не прочесть, — изменение могло пройти: профиль спрашивает
  подписки снова и показывает, какие они на самом деле; не удалось и это — флажок остаётся, как его отметил
  покупатель, с предупреждением проверить подписку чуть позже. Вернувшись на экран (через минуту и позже, как карта),
  профиль показывает подписки заново — их могла отозвать ссылка из письма. Подписки, прочитанные заново, меняют строки
  на месте (фокус остаётся), и не трогают строку, изменение которой идёт или началось после того, как их прочли.
- **Страница отписки** ведёт в профиль кабинета программы (`/p/<имя>/#profile`), если кабинет работает (и у
  приостановленного мерчанта) и покупатель участвует в программе (активен или заморожен: заблокированный и обезличенный
  войти не могут): «Вернуть подписку или настроить остальные можно в кабинете покупателя». Покупатель без входа
  сначала входит, и страница открывается на профиле. Ссылка — только добавка: если кабинет не прочитался, страница
  отвечает без неё, а отписка остаётся в силе.
- Виджета профиля для сайтов мерчантов нет: сайт делает свои формы над плоскостью участника (те же операции SDK);
  виджет — по запросу.

### Цвет карты (7f-4)

- **Цвет выбирает мерчант** в «Кабинете покупателя» → «Цвет карты» (`programs.manage`, журнал `portals.colour` с цветом;
  «Вернуть цвет платформы» пишет туда пустой): `#` и шесть шестнадцатеричных знаков, хранится строчными в
  `program_portals.colour` (проверка формата и в базе), пусто — цвет платформы `#0f766e`. Кабинет, перенесённый на другой
  адрес, цвет сохраняет; открытый заново — снова в цвете платформы. У приостановленного мерчанта цвет не меняется, как и
  всё, что не защищает.
- **Сам цвет** — там, где он стоит один: фон значка на главном экране телефона и строка браузера (`theme-color` страницы
  и манифеста). Карта на значке белая на тёмном цвете и почти чёрная на светлом — какая заметнее (на белом фоне белой
  карты не видно).
- **Кнопки, цифры и ссылки приложения** берут оттенок цвета, который читается: в светлой теме телефона — с контрастом не
  меньше 4,5 к странице, в тёмной — к карточкам (WCAG 2, уровень AA для текста), и на нём белый или почти чёрный текст,
  что читается лучше. Цвет, который читается и так, остаётся как есть (у тёмных цветов в светлой теме, у светлых — в
  тёмной); остальные сохраняют тон и количество цвета (бледный цвет остаётся приглушённым, яркий — ярким) и меняют только
  светлоту — ровно настолько, насколько нужно: светлый жёлтый в светлой теме становится тёмно-золотым, тёмно-синий в
  тёмной — светло-синим, бледно-розовый — приглушённым тёмно-розовым, а не красным. Как и у цвета платформы: в тёмной
  теме акцент светлее. Фон, к которому считается контраст, взят из стилей приложения (тест сверяет их).
- Оттенки приходят отдельной таблицей стилей `/p/<имя>/theme.css` (вне группы `web`, как манифест), которую страница
  подключает после стилей сборки: политика страницы по-прежнему не разрешает ничего встроенного. Адрес таблицы и
  значков называет цвет (и версию рисунка или оттенков), и браузер хранит их навсегда; адрес прежнего цвета получает
  нынешний и не хранится — иначе браузер показал бы чужой цвет, если мерчант вернётся к прежнему. Кабинет в цвете
  платформы таблицы не подключает: его оттенки — в стилях сборки; цвет платформы, выбранный вручную, — то же, что
  никакого (в базе пусто). Страница «Нет соединения» — в цвете платформы: её отдаёт service worker из файлов сборки.
- Значок, который покупатель уже добавил на экран телефона, может остаться прежним: iPhone его не обновляет, Android
  обновляет позже, когда перечитает манифест; форма цвета говорит об этом мерчанту. Значки рисуются один раз на цвет и
  держатся в кэше приложения 30 дней (большой рисуется около 0,2 с).
- Логотип на карте — позже: для него нужно хранилище файлов. Название на экране телефона короче названия программы — по
  запросу.

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

- Покупатель получает кабинет без сайта мерчанта — и карту на главном экране телефона с кодом для кассы; мерчант —
  ссылку и QR-код для чека и кассы.
- Каждый вход по коду стоит мерчанту SMS: капча, лимиты публичных кодов (номер, доля дня и месяца, своя остановка) и
  лимиты кодов мерчанта держат накрутку; коды касс от кабинета не страдают. Без ключей капчи в рабочем окружении
  кабинет не отправляет коды.
- Где вступление выключено, ответ на незнакомый номер (404) говорит, что номер не участник: SMS незнакомым номерам не
  уходят, а перебор номеров упирается в капчу и лимит по адресу. Где включено, каждый номер получает код — за счёт
  мерчанта, в лимитах публичных кодов, — а узнаёт, участник ли он, только тот, кто подтвердил код.
- Год входа — решение владельца: потерянный телефон долго остаётся в кабинете; закрывают его «Выйти везде», мерчант
  (завершение сеансов из карточки, блокировка участника) и закрытие кабинета.
- Рекламные письма уходят только на подтверждённые покупателем адреса и всегда со ссылкой «Отписаться», которая
  отзывает согласие одной кнопкой; без хоста кабинета платформа рекламных писем не отправляет.
- Кабинет и API могут жить на одном хосте: плоскость участника принимает запросы своего хоста по `Sec-Fetch-Site`.
  Браузеры без этого заголовка (выпущенные до 2023 года) получат отказ, когда приложение кабинета обратится к API
  на своём хосте; им же не хватит общих таблиц стилей виджетов, которые требует строгая политика страницы.
- Коробка «Я не робот» проверена в браузере с ненастоящим ключом в рамке на хосте кабинета (локально, в тестах и в
  песочнице без ключей её нет): её скрипт, фреймы и стили работают в рамке без нарушений политики, а сама коробка
  отвечает «неверный ключ». Рамку на своём хосте и задание проверки с настоящим ключом посмотрят на тестовом стенде.
- Развёртыванию кабинета нужны два хоста — кабинета и коробки «Я не робот» — и сборка его приложения.
