01 system overview

Что такое OneWallet Auth Center и три Flutter-приложения.

Что такое OneWallet Auth Center¶

Auth Center — Serverpod-сервис, выпускающий JWT-токены и управляющий жизненным циклом пользователей (регистрация, KYC, архивация). Сервис оркестрирует верификацию личности через kyc-service и является тонким HTTP-фасадом к Payment Manager для всех финансовых операций. PII-данные (имя, телефон, паспорт) хранятся зашифрованными в PostgreSQL.

Приложения¶

Приложение	Папка	Аккаунт-тип	Назначение
OneWallet (кошелёк)	`onewallet_base_flutter/`	`consumer` / `wallet`	Пополнение, P2P-переводы, QR-оплата, история, KYC
Closeloop	`closeloop_app_flutter/`	`consumer`	Замкнутый контур: корпоративные / campus / event платежи. Упрощённый онбординг, без KYC. [PLAN]
Merchant POS	`merchant_app_flutter/`	`merchant` / `agent`	Создание инвойсов, приём оплаты по QR, NFC-терминал, запрос settlement. [PLAN]
Shared UI	`onewallet_shared_ui/`	—	Общие виджеты и тема для всех трёх приложений

Все три приложения используют один и тот же onewallet_base_client (Serverpod-generated) и общаются с Auth Center через него.

Роль Auth Center в системе¶

flowchart LR
    loop[one_loop_app] --> AC[Auth Center\nServerpod :8080]
    merchant[one_merchant_app] --> AC
    AC -->|HMAC| PM[Payment Manager]
    AC -->|HTTP| KYC[kyc-service]
    AC -->|S3| Garage[Garage S3]
    AC -->|Redis XADD| Notif[notifications-service]
    nginx -->|auth_request| AC

Auth Center — единственная точка входа для Flutter-приложений. nginx валидирует JWT через auth_request → Auth Center перед проксированием запросов к PM. Auth Center никогда не обращается к TigerBeetle напрямую — только через PM.

Что делает Auth Center¶

JWT — выпускает и валидирует токены; JWKS-endpoint доступен для nginx и других сервисов
KYC оркестрация — принимает документы от пользователя, передаёт в kyc-service, обновляет статус аккаунта
PM facade — проксирует запросы баланса, истории, создания intents в Payment Manager через HMAC-подписанные вызовы
PII шифрование — имя, телефон, паспортные данные хранятся зашифрованными; расшифровка только по явному запросу с аудитом

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

Auth Center управляет жизненным циклом каждого пользователя через четыре основные стадии:

Регистрация (registration_in_progress → kyc_pending)
Пользователь вводит email и подтверждает OTP (6-значный код)
Задаёт пароль и 6-значный PIN (требование NatBank)
Аккаунт переходит в статус kyc_pending, готов к верификации личности
KYC-верификация (in_review → pending_operator_review → fully_verified)
Пользователь загружает фото документа и селфи
kyc-service выполняет OCR и сравнение лиц (faceMatchScore)
При автоматическом одобрению (score ≥ 0.85) → auto_approved
Оператор финализирует верификацию; статус становится fully_verified
Создаётся TigerBeetle-аккаунт (через Payment Manager)
Активный кошелёк (active)
Пользователь может выполнять P2P-переводы, пополнения, QR-платежи
Account Tier = STANDARD (полные лимиты)
PII-данные зашифрованы в PostgreSQL
Архивирование (при необходимости)
Пользователь запрашивает удаление или аккаунт неактивен долго
Статус → archived, операции блокируются
PII может быть удалена по требованию регулятора (GDPR)

Подробно: User Journeys и KYC Flow.

Ключевые инварианты¶

Инвариант	Правило	Проверка
PII	Только через `PiiProfileWriter` с шифрованием	`onewallet_base_server/lib/src/services/pii_service.dart`
PM вызовы	Только через `PspHmacClient` с HMAC-подписью	`onewallet_base_server/lib/src/services/pm_client.dart`
TigerBeetle	Только через Payment Manager (никогда напрямую)	nginx proxy → PM → TB
*pm. схема**	Только чтение через views в public.* context	`onewallet_base_server/lib/src/models/`
Account Type Guard	`requireAccountType(session, [...])` в каждом endpoint	`onewallet_base_server/lib/src/endpoints/`
Idempotency	Все финансовые операции идемпотентны через `idempotencyKey`	PM spec

Эти инварианты гарантируют безопасность и целостность системы. Никогда не обходи эти правила.

Где читать дальше¶

Тема	Документ
Все пользовательские сценарии	User Journeys
KYC процесс подробно	KYC Flow
Уровни аккаунтов	Account Types
Платёжные сценарии	Payment Scenarios
Технические детали	dev/README.md