02. Actors And Access Model

Статус: черновик для обсуждения

1. Назначение документа

Этот документ описывает пользователей системы, их типы, роли, permissions и правила доступа.

Цель документа - зафиксировать:

• какие типы пользователей существуют;
• какие product actors участвуют в MVP;
• как создаются пользователи;
• как создаются роли;
• как permissions связываются с ролями;
• как пользователь получает доступ к merchant или merchant group;
• как работает merchant user invitation;
• как работает provider access;
• как работает session management;
• какие действия должны попадать в audit log.

Важно: этот документ не описывает финальный UI. Он описывает продуктовые правила access model, на основе которых команда сможет проектировать Back Office, Merchant Portal, API и database model.

2. Основной принцип access model

В системе должны быть разделены:

• тип пользователя;
• роль;
• permission;
• контекст доступа.

Тип пользователя отвечает на вопрос: к какому классу относится пользователь?

Роль отвечает на вопрос: какой набор permissions у пользователя?

Permission отвечает на вопрос: какое конкретное действие разрешено?

Контекст доступа отвечает на вопрос: где именно эта роль применяется?

Пример:

User: john@example.com
User type: merchant user
Access context: Merchant A
Role in this context: Merchant Admin
Permissions from role:
  - view transactions
  - create API keys
  - invite merchant users

Один и тот же user может иметь разные роли в разных contexts.

Важно: user type является строгим разделением. Один user не может одновременно быть platform user и merchant user.

Это значит:

• platform user может иметь только platform-level role в global/platform context;
• merchant user может иметь merchant roles only in merchant context;
• merchant user может иметь merchant group access as access scope;
• platform user не получает merchant role в merchant context;
• platform user имеет доступ ко всем мерчантам системы;
• merchant user не получает platform role;

3. User Types

В MVP есть два основных типа пользователей:

• platform user;
• merchant user.

Тип пользователя выбирается при создании пользователя platform user'ом с соответствующей permission.

При создании user platform user обязан выбрать один из типов:

• platform user;
• merchant user.

Тип user определяет, какие роли и contexts могут быть назначены этому user.

В MVP user type после создания не меняется.

Минимальные поля user-а:

• email;
• first name;
• last name;
• status;
• user type.

Email должен быть уникальным в системе. Повторно использовать email нельзя, даже если предыдущий user был soft-deleted.

Platform User

Platform user - это пользователь платежной платформы / агрегатора.

Он может работать с platform-level функционалом:

• merchants;
• merchant groups;
• merchant brands;
• platform users;
• merchant users;
• roles;
• permissions;
• MASTER MID;
• SUB MID;
• SUB MID GROUP;
• SUB MID AGGREGATOR;
• routing;
• provider access;
• transactions;
• audit logs;
• migration;
• operational actions.

Точный доступ зависит от roles и permissions.

Platform user не должен назначаться в merchant context как merchant user. Если platform user работает с merchant data, он делает это через platform permissions и доступный platform scope, а не через merchant role. Platform user имеет доступ ко всем мерчанам.

Merchant User

Merchant user - это пользователь merchant-side части системы.

Он может работать только с теми merchants или merchant groups, к которым ему выдан доступ.

Он может видеть и делать только то, что разрешено его merchant role в конкретном merchant context.

Merchant user не должен автоматически получать доступ ко всем данным merchant. Доступ всегда должен быть основан на context + role + permissions.

Merchant user не может иметь platform role и не может получать platform-level permissions напрямую.

Merchant user может существовать без доступа к merchant или merchant group. В таком случае после login он не должен видеть merchant-scoped data, пока ему не выдадут access context.

Если user залогинился без access context, он должен видеть пустой Back Office.

4. Product Actors

Product actor - это участник системы с точки зрения бизнес-сценариев. Actor не всегда равен роли в системе.

Platform Admin

Platform Admin управляет platform-level настройками.

Возможные действия:

• создавать users;
• создавать roles;
• назначать permissions;
• создавать merchants;
• создавать merchant groups;
• создавать merchant brands;
• настраивать MASTER MID;
• настраивать SUB MID / SUB MID AGGREGATOR;
• управлять provider access;
• смотреть transactions;
• выполнять transaction correction;
• выполнять webhook resend;
• запускать migration;
• смотреть audit logs.

Доступ зависит от permissions. Название Platform Admin не должно быть hardcoded как единственный вариант роли.

Platform Support

Platform Support расследует transactions и операционные проблемы.

Возможные действия:

• смотреть transaction list;
• смотреть transaction details;
• смотреть transaction timeline;
• смотреть provider callback logs;
• смотреть merchant webhook logs;
• делать webhook resend, если есть permission;
• делать transaction correction, если есть permission;
• смотреть audit logs, если есть permission.

Merchant Admin

Merchant Admin работает в merchant context.

Возможные действия:

• смотреть transactions своего merchant;
• смотреть payment methods;
• смотреть доступный routing-level;
• создавать API keys;
• приглашать merchant users, если есть permission;
• выдавать роли users в доступном context;
• делать webhook resend, если есть permission;
• смотреть audit logs по доступным сущностям, если есть permission.

Merchant User

Merchant User - обычный пользователь merchant-side части.

Он может видеть только те разделы и действия, которые разрешены его ролью в конкретном context.

Merchant API Client

Merchant API Client - это не UI user, а API-интеграция merchant.

Использует API key для:

• создания deposit;
• получения transaction status/details;
• работы с webhook flow.

API key создается на уровне merchant, не brand.

Customer

Customer открывает hosted payment form и завершает payment flow.

Customer не является Back Office user.

Provider

Provider обрабатывает payment и отправляет callback.

Provider не является Back Office user.

5. Roles

Role - это настраиваемый набор permissions.

Роли создаются только platform users с соответствующей permission.

Роли должны поддерживать разные назначения:

• platform role;
• merchant role.

Роль не должна быть просто строкой в коде. Роль должна быть управляемой сущностью.

Default Bootstrap Role

При первом деплое Back Office должен быть bootstrap flow.

Если в системе нет ни одного пользователя:

1. Можно создать первого platform user.
2. Система автоматически создает role Admin.
3. Role Admin получает все permissions системы.
4. Первый platform user получает role Admin.

Обязательная смена пароля после bootstrap не требуется.

Default Merchant Admin Role

Default merchant admin role должна создаваться автоматически.

Эта role является merchant role и может быть назначена merchant user-у в context конкретного merchant.

Platform admin может изменить permissions этой role, если имеет permission управлять roles.

Merchant admin может назначать только merchant roles, которые platform пометила как assignable by merchant admin.

6. Permissions

Permission - это конкретное право на действие или просмотр данных.

Примеры categories permissions:

• user management;
• role management;
• merchant management;
• merchant group management;
• merchant brand management;
• payment method management;
• MASTER MID management;
• SUB MID management;
• SUB MID AGGREGATOR management;
• routing management;
• provider access management;
• transaction view;
• transaction correction;
• webhook view;
• webhook resend;
• API key management;
• audit log view;
• migration management;
• export.

Весь функционал Back Office и Merchant Portal должен быть permission-based.

Если действие влияет на данные, безопасность, деньги, routing или интеграции, оно должно иметь permission.

7. Access Contexts

Пользователь может получить роль в конкретном context.

В MVP есть два основных access contexts:

• merchant;
• merchant group.

Merchant Context

Если user получает доступ к merchant, нужно указать role этого user в контексте данного merchant.

Пример:

User: anna@example.com
User type: merchant user
Context: Merchant A
Role: Merchant Admin

Этот user получает permissions из роли только внутри Merchant A.

Merchant Group Context

Если user получает доступ к merchant group, это дает access scope к merchants внутри group.

Permissions для actions должны рассчитываться на основе merchant-specific roles и exact access model.

Пример:

User: support@example.com
User type: merchant user
Context: Merchant Group X
Role: Merchant Admin

Этот user получает access scope к merchants внутри Merchant Group X.

8. Merchant User Invitation

Merchant user может приглашать других users, если:

• у него есть доступ к merchant;
• в этом context у него есть role;
• role содержит permission на управление users / invites;
• он пытается выдать роль только в том context, где сам имеет право управлять users.

Merchant user может приглашать users только в merchant context.

Доступ user-а к merchant group может выдавать только platform user с соответствующей permission.

Merchant user не может:

• добавлять users в merchant group;
• выдавать role в merchant group context;
• менять merchant group access.

Invitation должен работать через email link.

Если invite или user с таким email уже существует, повторная попытка invite должна вернуть ошибку.

Если invite expired, actor с permission может выполнить resend invite action.

Если активному user-у добавляют доступ к новому merchant или merchant group, email notification в MVP не отправляется.

Если user удаляется из merchant context, active sessions завершать не нужно. Достаточно сразу пересчитать permissions/access.

Если role или permissions role изменились, изменения должны примениться сразу, включая active sessions.

Если merchant добавили в merchant group или убрали из merchant group, users с group access должны сразу получить или потерять доступ к этому merchant.

Если role переводится в INACTIVE или DELETED, эта role должна быть удалена у users, которым она была назначена.

Invite link:

• действует 72 часа;
• время жизни invite link настраивается через environment variables;
• обязательная смена пароля после invite не требуется.

9. Authentication

В MVP нужна полноценная auth-система.

Обязательные возможности:

• login;
• logout;
• 2FA / OTP;
• forgot password;
• password reset через email code;
• active sessions management;
• bootstrap первого platform admin.

Password Reset

Password reset должен работать через email message с кодом.

Требования:

• reset code действует 30 минут;
• время жизни reset code настраивается через environment variables;
• максимальное количество attempts по умолчанию: 3;
• количество attempts настраивается через environment variables.

10. Session Management

Пользователь может иметь несколько активных sessions.

В профиле пользователь должен видеть свои active sessions.

В профиле пользователь должен видеть history завершенных sessions / login sessions.

В профиле пользователь должен видеть security events:

• login failed;
• password reset;
• 2FA reset;
• new device/IP login notification.

В MVP пользователь должен иметь возможность завершить / удалить одну выбранную session.

Session management actions должны попадать в audit log, если это значимое security action.

User может редактировать свои first name / last name.

Admin с permission может редактировать first name / last name user-а.

User в status DISABLED можно вернуть в ACTIVE.

User в status DELETED нельзя восстановить.

11. API Keys

API keys создаются на уровне merchant.

API keys не создаются на уровне brand.

Merchant user может создать API key самостоятельно, если у него есть permission в соответствующем merchant context.

API Key Rotation

При создании нового API key merchant может выбрать grace period, в течение которого старый key продолжает работать.

Варианты grace period для MVP:

• 1 час;
• 3 часа;
• 12 часов;
• 24 часа.

Это нужно, чтобы merchant мог безопасно переключить интеграцию на новый key.

Secret value должен быть безопасно обработан:

• secret нельзя раскрывать пользователям;
• key/secret data должны скрываться в merchant-facing audit logs;

12. Provider Access

Provider / SUB MID information должна быть скрыта от merchant users по умолчанию.

Provider access выдается на уровне merchant.

Provider access не выдается:

• на уровне brand;
• на уровне merchant group;
• на уровне конкретного user;
• на уровне provider method.

Merchant может видеть provider / SUB MID information только если:

• SUB MID создан под этого merchant;
• SUB MID создан merchant-user;
• merchant получил доступ видеть provider;
• конкретный user имеет permission видеть provider / SUB MID information.
• Если SUB MID создан platform-user, то если в конфигурации помечено available for merchant user, тогда эта конфигурация доступна merchant user.

Provider access выдает пользователь, у которого есть permission управлять provider access.

Provider access выдается к конкретному provider.

Если merchant получил access к provider, merchant users с нужными permissions могут видеть все provider methods этого provider при создании SUB MID.

Provider access можно revoke.

После revoke:

• уже созданные SUB MID остаются active;
• merchant users больше не видят provider details по этим SUB MID;
• merchant users больше не могут создать новый SUB MID этого provider;

Provider access grant/revoke должен попадать в audit log.

Provider access управляется на странице merchant details.

В Merchant section отдельная страница Provider Access не нужна. При создании SUB MID merchant user видит в provider selector только providers, к которым merchant имеет access.

Если используется SUB MID AGGREGATOR, merchant не должен видеть его внутренние настройки. SUB MID AGGREGATOR - platform-level reusable configuration.

13. Audit Logs Visibility

Audit log должен создаваться на любые изменения сущностей в системе.

Для каждой важной сущности в Back Office должна быть вкладка или раздел Audit logs.

Audit log visibility зависит от:

• user type;
• context access;
• role;
• permissions;
• visibility rules сущности.

Merchant users могут видеть audit logs по доступным им сущностям, если у них есть permission.

Audit logs не должны хранить key/secret values.

Merchant-facing audit logs должны скрывать platform-hidden provider/internal details.

Другие provider-sensitive поля дополнительно скрывать не нужно, если у пользователя есть право видеть соответствующую сущность.

14. Access Rules Summary

Основные правила:

1. User имеет тип: platform user или merchant user.
2. User не может одновременно быть platform user и merchant user.
3. Role создается только platform users с нужной permission.
4. Role состоит из permissions.
5. Role назначается user в конкретном context, допустимом для его user type.
6. Merchant context access требует merchant role в этом merchant context.
7. Merchant group access является access scope и требует роль из merchant roles.
8. Merchant group access может выдавать только platform user с соответствующей permission.
9. Merchant user может приглашать users только в merchant context, где у него есть permission.
10. Provider information скрыта от merchant по умолчанию.
11. Provider access выдается merchant-у к конкретному provider.
12. API keys создаются на уровне merchant.
13. Audit logs создаются на любые изменения сущностей.
14. Изменения user access должны попадать в audit log.

15. MVP Acceptance Criteria

Access model считается достаточной для MVP, если:

• Можно создать первого platform user через bootstrap flow.
• Первому platform user автоматически выдается role Admin со всеми permissions.
• Platform user с permission может создать platform user.
• Platform user с permission может создать merchant user.
• При создании user platform user выбирает user type.
• Merchant user может существовать без merchant / merchant group access.
• User без access context видит пустой Back Office.
• User email уникален и не переиспользуется после soft-delete.
• User не может одновременно иметь platform role и merchant access.
• Platform user с permission может создать role.
• Platform user с permission может назначать permissions role.
• Merchant user может получить role в merchant context.
• Merchant user может получить role в merchant group context.
• Merchant user может получить merchant group access as access scope.
• Merchant user с permission может пригласить user через email link только в merchant context.
• Merchant group access может назначать только platform user с permission.
• Повторный invite на email существующего user-а или pending invite возвращает ошибку.
• Expired invite можно отправить повторно через resend invite action.
• Отдельный invite status CANCELED в MVP не нужен.
• Добавление нового merchant / merchant group access не отправляет email notification.
• Удаление user-а из merchant context не завершает active sessions, а сразу пересчитывает permissions.
• Изменения role/permissions применяются сразу.
• Изменение состава merchant group сразу влияет на доступ users с group access.
• INACTIVE/DELETED role удаляется у users, которым она была назначена.
• Invite link действует 72 часа и настраивается через environment variables.
• Password reset работает через email code.
• Password reset code действует 30 минут и настраивается через environment variables.
• Password reset attempts по умолчанию ограничены 3 и настраиваются через environment variables.
• User может видеть свои active sessions.
• User может видеть history завершенных sessions / login sessions.
• User может видеть security events в profile.
• User может удалить одну выбранную session.
• Если user получает status DISABLED или DELETED, все его active sessions завершаются автоматически.
• DISABLED user можно вернуть в ACTIVE.
• DELETED user нельзя восстановить.
• Merchant user с permission может создать API key.
• API key rotation grace period поддерживает 1 час, 3 часа, 12 часов, 24 часа.
• Provider access работает через permission-based управление.
• Merchant user без provider access не видит provider / SUB MID details.
• Merchant-facing audit logs скрывают key/secret data.