Перейти к содержанию

Роли и аккаунты

Кто пользуется OneWallet, какие типы аккаунтов бывают, что даёт каждый KYC-tier и как устроен жизненный цикл пользователя от регистрации до удаления.

На какие вопросы отвечает

  • Кто такие consumer, merchant, agent и operator/admin — чем отличаются?
  • Что такое KYC-tier (уровень верификации) и какие возможности он открывает?
  • Какие статусы бывают у пользователя и как он становится active?
  • Что происходит с брошенными регистрациями и удалёнными аккаунтами?
  • Какие фоновые задания (кроны) чистят и архивируют пользователей?

Роли (кто действует в системе)

Роль Где Что делает
consumer one_loop_app (Flutter) Конечный пользователь: пополнение, P2P, QR/NFC-оплата, мини-аппы
merchant one_merchant_app (Flutter) Приём оплаты: POS (NFC + QR-invoice), запрос расчёта (settlement)
agent one_merchant_app Разновидность merchant с расширенными операциями (топапы)
operator/admin admin-panel (SvelteKit) Сотрудники: KYC-ревью, лимиты, fee-rules, расшифровка PII, разбор интентов

Тип учётной записи хранится в users.accountType (значения: consumer | merchant | agent | wallet). Доступ к эндпоинтам ограничен на сервере: requireAccountType(session, [...]).

Роли операторов — отдельная таблица admin_roles: superadmin | operator | finance | support.

KYC-tiers (уровни верификации)

Уровень хранится в user_profile.accountTier и определяет лимиты и доступ к операциям. Числовой claim для JWT мини-аппов формируется в miniapp_endpoint.dart (0=BASIC … 3=VIP).

Tier claim Когда присваивается Что даёт
BASIC 0 При создании профиля (стартовый) Базовый кошелёк, минимальные лимиты
STANDARD 1 Автоматически после успешного KYC (если admin не задал tier вручную) Повышенные лимиты, полный набор операций
PREMIUM 2 Вручную оператором (admin-panel) Дополнительно расширенные лимиты
VIP 3 Вручную оператором Максимальные лимиты

Допустимые значения проверяются в admin_kyc_endpoint.dart (allowedTiers = ['BASIC','STANDARD','PREMIUM','VIP']). Ручная установка ставит флаг accountTierOverriddenByAdmin=true — автоповышение после KYC её больше не перезаписывает.

Конкретные суммы лимитов и комиссий — см. 05-limits-and-fees.md. Регуляторные требования к верификации — см. ../compliance/bot-qa.md.

Жизненный цикл пользователя

Статус хранится в users.status. Брошенные/истёкшие регистрации архивируются (isArchived, archivedAt), затем удаляются вместе с зависимостями (UserDeletionService.deleteWithDependencies).

stateDiagram-v2
    [*] --> registration_in_progress: регистрация начата
    registration_in_progress --> kyc_pending: профиль создан / отправлены данные
    kyc_pending --> active: KYC одобрен (авто или оператором)
    registration_in_progress --> registration_expired: истёк срок (крон)
    registration_expired --> [*]: hard delete
    active --> archived: пользователь удалён / деактивирован
    archived --> [*]: hard delete через N дней

Основные статусы: registration_in_progress → kyc_pending → active; ветка registration_expired для незавершённых; архив через isArchived=true.

Cleanup-кроны (Serverpod FutureCall, самоперепланируются)

Источник: projects/onewallet_base/onewallet_base_server/lib/src/future_calls/registration_cleanup.dart.

FutureCall Расписание Что делает Env (default)
deleteIncompleteRegistrations каждые 6 ч Удаляет users без user_profile старше TTL REGISTRATION_INCOMPLETE_TTL_HOURS (24)
archiveExpiredRegistrations ежедневно 02:00 UTC registration_in_progress с истёкшим сроком → архив, статус registration_expired —
sendRegistrationReminders ежедневно 09:00 UTC Напоминания пользователям с истекающей регистрацией REGISTRATION_REMINDER_DAYS_BEFORE_EXPIRY (2)
hardDeleteArchivedUsers раз в 7 дней Полное удаление давно архивированных REGISTRATION_HARD_DELETE_ARCHIVED_AFTER_DAYS (30)

Пример: путь от регистрации до active

  1. Пользователь открывает one_loop_app, регистрируется → создаётся users со status='registration_in_progress'.
  2. Заполняет профиль → RegistrationService создаёт user_profile (accountTier='BASIC') и переводит статус в kyc_pending.
  3. Загружает документы → kyc-service (OCR через Gemini/Ollama + CompreFace face match) выносит решение.
  4. KYC одобрен → KYCService ставит status='active'; если accountTierOverriddenByAdmin=false, tier повышается до STANDARD.
  5. Параллельно создаётся кошелёк (TigerBeetle-аккаунты через PM). Если регистрацию бросили — её через 24 ч удалит deleteIncompleteRegistrations.

Смежные документы