Saga: Архитектура персонального пенсионного криптофонда

Версия: 2.6.296

Дата создания: 2025-11-13

Последнее обновление: 2025-11-20

Статус: Master Architecture Document

📋 Оглавление

1. Концепция системы
2. Полное описание функционала
3. Архитектура высокого уровня
4. Пользовательские сценарии
5. Проблемные сценарии и решения
6. Операторский workflow
7. Административные процессы
8. Интеграции
9. Операционная модель

Концепция системы

Saga — персональный пенсионный криптофонд, позволяющий пользователям максимально просто инвестировать свои криптовалютные активы и получать фиксированную доходность.

Ключевые принципы

• Простота: Инвестирование в один клик
• Прозрачность: Полная видимость движения средств
• Автоматизация: Минимальное участие пользователя в процессе
• Безопасность: Профессиональное управление активами через Fordefi
• Integration-Only: Никаких собственных smart contracts, только внешние интеграции

---

Полное описание функционала

🎯 Концепция и философия

Saga представляет собой персональный пенсионный криптофонд, построенный на принципе максимальной простоты использования. Основная идея заключается в том, чтобы позволить людям инвестировать свою криптовалюту с минимальными усилиями и получать стабильную доходность, аналогично традиционным пенсионным фондам.

Дух проекта — это персональный пенсионный фонд для криптовалютной эры, где пользователи могут накапливать средства для будущего, получая фиксированную доходность без необходимости разбираться в сложностях DeFi протоколов.

🏗️ Архитектурный подход

Система построена по Integration-Only архитектуре, что означает полный отказ от собственных smart contracts и блокчейн логики в пользу надежных внешних интеграций:

• Crypto2B — обрабатывает все депозиты и выводы
• Fordefi — профессиональное управление активами через операторов
• Supabase — аутентификация пользователей
• Resend — email уведомления
• Telegram Bot — алерты для операторов

🔄 Пользовательские сценарии

Базовый Happy Path

1. Вход и регистрация

Пользователь заходит на сайт и проходит аутентификацию через Google или email. Никаких сложных KYC процедур — достаточно подтвердить email адрес. Система автоматически создает профиль пользователя и подготавливает его к инвестированию.

2. Максимально упрощенный депозит с автоинвестированием

При входе пользователь сразу видит готовую к использованию систему:

• TRC20 сеть уже выбрана как наиболее экономичная (USDT)
• Автоинвестирование уже включено — не требует дополнительных настроек
• Депозитный адрес уже сгенерирован через интеграцию с Crypto2B
• Минимальная сумма $500 четко указана

Пользователю достаточно перевести USDT на предоставленный адрес. Система автоматически:

• Отслеживает поступление через webhooks Crypto2B
• Создает инвестицию с фиксированной доходностью 10% APY
• Активирует расчет доходности с даты инвестирования
• Отправляет уведомления оператору для сбора средств

🔧 Технические детали начислений:

• Расчет на бэкенде Saga: Crypto2B НЕ работает с начислением процентов - все расчеты ведутся в собственной базе данных
• Transaction-based расчеты: Баланс рассчитывается из transactions table как единый источник истины, используя формулу APY на любую дату
• CanonicalBalanceService: Единый интерфейс для всех финансовых расчетов через методы GetUserBalance, GetUserBalanceAsOf
• Аналитические вычисления: Система может рассчитать доходность на любую историческую дату без хранения промежуточных состояний
• Real-time отображение: Пользователь видит актуальный рост портфеля при каждом обращении

💰 Детальная логика расчета баланса

Архитектура расчетов:

Система использует simulation-based подход для вычисления балансов и доходности. Вместо хранения промежуточных состояний, каждый запрос баланса симулирует историю операций день за днём, применяя compound interest.

Формулы расчета баланса:

Total Balance = Deposits - Withdrawals + TotalYields
Available Balance = Total Balance - TotalInvested
TotalInvested = Sum(CurrentValue по всем активным инвестициям)
TotalYields = Sum(AccumulatedYields по всем стратегиям)

Принципиальные правила:

1. Total Balance включает ВСЕ деньги пользователя (свободные + в инвестициях)
2. Available Balance показывает деньги доступные для операций (не в инвестициях)
3. TotalYields НИКОГДА не уменьшается - это накопленный profit за всё время
4. Withdrawal операции НЕ влияют на TotalYields - только на Available/Invested

Пример расчета:

День 1: Deposit $1000 → Invest $1000 conservative
  Total: $1000, Available: $0, Invested: $1000, Yields: $0

День 10: Compound interest накопил $10
  Total: $1010, Available: $0, Invested: $1010, Yields: $10

День 15: Withdrawal $500 из инвестиции
  Total: $510, Available: $0, Invested: $510, Yields: $10
  ⚠️ Yields остаётся $10! Это уже заработанные деньги

📊 Accumulated Yields Tracking

Критическое исправление (v2.6.296):

До версии 2.6.296 система показывала текущий profit в инвестициях (CurrentValue - Invested), что приводило к исчезновению profit при withdrawal. Теперь система отслеживает накопленный profit за всё время.

Механизм отслеживания:

type StrategyAmount struct {
    Amount           decimal.Decimal // Текущая сумма в инвестиции
    Invested         decimal.Decimal // Principal (изначально вложенная сумма)
    AccumulatedYields decimal.Decimal // 🚨 Накопленный profit за всё время
    LastUpdate       time.Time       // Дата последнего обновления
}

Ежедневное накопление yields:

// Каждый день система симулирует compound interest
oldAmount := strategyBalance.Amount
newAmount := CompoundCalc.Calculate(oldAmount, rate, 1 day)

// Вычисляем и накапливаем yield за день
dailyYield := newAmount - oldAmount
strategyBalance.AccumulatedYields += dailyYield
strategyBalance.Amount = newAmount

Ключевые принципы:

• AccumulatedYields НИКОГДА не уменьшается - только растёт
• При каждом начислении процентов yield добавляется к AccumulatedYields
• Profit в API всегда равен AccumulatedYields, НЕ CurrentValue - Invested
• Withdrawal операции НЕ трогают AccumulatedYields

🔄 Логика Withdrawal операций

Три сценария withdrawal:

1. Withdrawal >= CurrentValue (полное изъятие):

Было: Amount=$1180, Invested=$1000, AccumulatedYields=$180
Withdrawal: -$1180
Стало: Amount=$0, Invested=$0, AccumulatedYields=$180 ✅

Profit показывается как $180 - деньги уже заработаны!

2. Withdrawal >= Invested, но < CurrentValue:

Было: Amount=$1085, Invested=$1000, AccumulatedYields=$85
Withdrawal: -$1000 (весь principal)
Стало: Amount=$85, Invested=$0, AccumulatedYields=$85 ✅

Principal выведен, profit остался в инвестиции

3. Withdrawal < Invested (частичное изъятие):

Было: Amount=$662, Invested=$500, AccumulatedYields=$162
Withdrawal: -$300 (60% от principal)
Стало: Amount=$397, Invested=$200, AccumulatedYields=$162 ✅

Изымается пропорциональная доля, AccumulatedYields не трогается

Критическое правило: При withdrawal Amount и Invested могут обнулиться, НО AccumulatedYields сохраняется для показа исторического profit.

⚙️ Compound Interest Calculations

Daily Simulation Process:

// 1. Начинаем с самой ранней операции
earliestDate := findEarliestInvestment(investments)

// 2. Симулируем каждый день до targetDate
for currentDate := earliestDate; currentDate <= targetDate; currentDate++ {

    // Шаг A: Обрабатываем операции этого дня
    for inv := range investmentsOnDate(currentDate) {
        if inv.Amount > 0 {
            // Положительная инвестиция - добавляем к балансу
            strategyBalance.Amount += inv.Amount
            strategyBalance.Invested += inv.Amount
        } else {
            // Отрицательная инвестиция - withdrawal
            processWithdrawal(strategyBalance, inv.Amount)
        }
    }

    // Шаг B: Начисляем compound interest на остаток
    oldAmount := strategyBalance.Amount
    newAmount := calculateCompoundInterest(oldAmount, rate, 1)

    dailyYield := newAmount - oldAmount
    strategyBalance.AccumulatedYields += dailyYield
    strategyBalance.Amount = newAmount
}

Формула compound interest:

newAmount = principal × (1 + rate/365)^days

Для ежедневного начисления days = 1, поэтому:

dailyYield = amount × (rate/365)

Пример для 10% APY:

Day 1: $1000 × (1 + 0.10/365) = $1000.274
Day 2: $1000.274 × (1 + 0.10/365) = $1000.548
...
Day 365: ≈ $1105.16 (compound эффект)

🎯 API Response Format

Структура баланса пользователя:

{
  "totalBalance": 1436.10,      // Все деньги (свободные + в инвестициях)
  "availableBalance": 858.34,   // Доступны для операций
  "totalInvested": 577.76,      // CurrentValue всех инвестиций
  "totalYields": 436.10,        // AccumulatedYields (НИКОГДА не уменьшается)

  "investments": {
    "conservative": {
      "invested": 200.00,       // Principal в этой стратегии
      "currentValue": 262.99,   // Текущая стоимость
      "profit": 162.99          // AccumulatedYields для conservative
    },
    "balanced": {
      "invested": 500.00,
      "currentValue": 593.11,
      "profit": 93.11
    },
    "aggressive": {
      "invested": 0.00,         // Полностью выведен
      "currentValue": 0.00,
      "profit": 180.00          // 🚨 Profit СОХРАНЁН!
    }
  }
}

Критические правила валидации:

✅ totalBalance >= totalInvested (всегда)
✅ totalYields НИКОГДА не уменьшается между запросами
✅ profit по стратегии = AccumulatedYields (НЕ currentValue - invested)
✅ Сумма profits по стратегиям = totalYields

3. Мониторинг роста портфеля

Пользователь может заходить на сайт и наблюдать за ростом своего портфеля через простой и понятный график:

• Текущая стоимость портфеля
• Размер инвестированных средств
• Полученная прибыль в абсолютных и процентных значениях
• Количество дней в инвестиции
• Прогноз доходности на различные периоды

4. Простой вывод средств

Когда пользователь хочет вывести средства, процесс максимально упрощен:

• Выбор активной инвестиции для частичного или полного закрытия
• Ввод суммы для вывода (с автоматическим расчетом процентов)
• Выбор сети (TRC20 по умолчанию) и ввод адреса получателя
• Подтверждение операции одним кликом

Система автоматически рассчитывает итоговую сумму включая накопленные проценты и передает запрос оператору для обработки. В течение 24-48 часов средства поступают на указанный адрес.

Расширенные сценарии

1. Раздельные депозит и инвестирование

Для пользователей, которые хотят больше контроля:

• Возможность завести средства на внутренний баланс без автоинвестирования
• Просмотр доступных типов инвестиций (в будущем — разные стратегии)
• Ручной выбор суммы и типа инвестиции
• Возможность частично инвестировать баланс, оставив часть в резерве

2. Гибкое управление инвестициями

• Закрытие инвестиций без немедленного вывода (возврат на баланс)
• Реинвестирование средств в другие типы стратегий
• Комбинирование частичного закрытия и новых инвестиций
• Вывод свободных средств с баланса без затрагивания инвестиций

3. Комбинированные операции

• Запрос вывода суммы больше доступного баланса с автоматическим предложением закрыть необходимую часть инвестиций
• Выбор конкретных инвестиций для закрытия при множественных позициях
• Оптимизация налогообложения через выбор позиций FIFO/LIFO

🚨 Проблемные сценарии и их обработка

Проблемы с депозитами

1. Неправильная сеть или валюта

• Пользователь отправил ETH USDC вместо TRC20 USDT
• Пользователь отправил Bitcoin вместо стейблкоинов
• Система автоматически мониторит альтернативные сети через Crypto2B
• Операторы получают алерт и вручную конвертируют средства
• Пользователь получает email уведомление о конвертации с объяснением

2. Сумма меньше минимума

• Депозит менее $500 автоматически зачисляется на баланс без инвестирования
• Пользователь получает email с предложением довнести до минимальной суммы
• Возможность накопления нескольких мелких депозитов до достижения минимума

💰 Бонусная схема от компании (в разработке)

Компания может предоставить бонусы пользователям для различных депозитов:

• Подтверждение пользователя: Оператор верифицирует активность и историю пользователя
• Перевод средств DeFi-операторам: Компания переводит бонусные средства напрямую управляющим
• Активация режима x2 в админке: Оператор включает специальный режим повышенной доходности
• Отображение бонуса пользователю: Пользователь видит улучшенный процент и уведомление о бонусе

Административный контроль: - Индивидуальный подход к размеру бонуса (не обязательно x2 для крупных сумм) - Tracking бонусов в админке для прозрачности - Ограничения по общему объему бонусов в месяц

3. Депозит не привязан к пользователю

• Средства поступили на адрес, но невозможно определить владельца
• Операторы получают Telegram алерт с деталями транзакции
• Поиск владельца по timestamp и сумме среди активных пользователей
• Email рассылка всем пользователям с запросом подтверждения транзакции

Проблемы с выводами

1. Некорректный адрес получателя

• Предварительная валидация адреса при вводе (checksum, формат)
• Блокировка операции при обнаружении невалидного адреса
• Предоставление образцов правильных адресов для каждой сети

2. Санкционные ограничения

• Автоматическая проверка через Chainalysis API
• Блокировка вывода на адреса из санкционных списков
• Предложение альтернативных адресов или KYC процедуры

3. Технические сбои

• Retry логика с экспоненциальной задержкой при временных проблемах
• Ручная обработка через альтернативные каналы при длительных сбоях
• Уведомление пользователей о задержках с указанием причин

Проблемы с доступом

1. Потеря доступа к аккаунту

• Восстановление через верификацию личности (документы + видеозвонок)
• Временная заморозка аккаунта при подозрительной активности
• Fallback аутентификация через email links при сбоях Supabase

👨‍💼 Операторский workflow

Ежедневные операции

Утренняя рутина (9:00 - 10:00)

1. Проверка Telegram уведомлений о ночных депозитах
2. Анализ накопленных сумм на депозитных адресах Crypto2B
3. Планирование операций на день: сборы vs выводы vs реинвестирование

Основной рабочий день (10:00 - 18:00)

1. Мониторинг входящих операций: новые депозиты, запросы на вывод
2. Delta-анализ: расчет чистого потока средств за период
3. Оптимизация операций: использование входящих депозитов для покрытия выводов
4. DeFi операции через Fordefi: размещение излишков, изъятие при необходимости

Вечерние операции (18:00 - 19:00)

1. Сбор накопленных средств на операционные кошельки
2. Размещение чистого притока в DeFi протоколы (Curve, Pendle)
3. Подготовка отчетности и планов на следующий день

Delta-based оптимизация

Принцип работы

Операторы анализируют совокупный поток операций за период (обычно день) и оптимизируют их выполнение:

• Positive flow (+$10K): 15K депозитов, 5K выводов — нужно только разместить излишки в DeFi
• Negative flow (-$3K): 5K депозитов, 8K выводов — нужно изъять средства из DeFi
• Balanced flow (≈0): равные депозиты и выводы — прямая переадресация без DeFi операций

Группировка операций

Система автоматически группирует пользовательские запросы в операторские задачи:

• "Собрать $25,000 с адресов: addr1 ($5K), addr2 ($12K), addr3 ($8K)"
• "Разместить $20,000 в Curve 3pool через Fordefi"
• "Вывести $5,000: user1 → 0x123abc ($2K), user2 → TRX456def ($3K)"

Подтверждение операций

Операторы подтверждают выполнение через админку:

• Ввод transaction hash для блокчейн операций
• Upload скриншотов из Fordefi для DeFi операций
• Указание финальных сумм с учетом комиссий сети
• Автоматическая верификация через блокчейн API

📱 Коммуникации и уведомления

Пользовательские уведомления

Email (через Resend)

• Подтверждение депозита: "Получен депозит $1,500 USDT, инвестиция создана"
• Уведомления о росте: еженедельная сводка по доходности
• Подтверждение вывода: "Вывод $800 USDT выполнен, tx: 0x123..."
• Проблемы и их решения: "Депозит в неправильной сети, конвертируем в течение 24ч"

In-app уведомления

• Real-time обновления баланса при поступлении депозитов
• Уведомления о завершении операций вывода
• Системные сообщения о технических работах

Операторские алерты

Telegram Bot - ОСНОВНОЙ ИНСТРУМЕНТ ОПЕРАТОРОВ

Telegram является первичным каналом коммуникации для операционной команды:

• Мгновенные уведомления: Немедленные push-уведомления о новых депозитах >$1,000
• Критические алерты: Срочные уведомления о запросах вывода >$5,000
• Проблемные ситуации: Неопознанные депозиты, технические сбои, превышения лимитов
• Ежедневные сводки: Автоматические отчеты о операциях в 19:00
• Дублирование уведомлений: Все критические события отправляются и в Telegram, и на email, и отображаются в админке для гарантированной доставки
• Оперативная коммуникация: Основной канал для координации между операторами

Админка

• Dashboard с real-time метриками
• Очередь задач с приоритизацией
• История операций с фильтрацией и поиском
• Настройки уведомлений и автоматизации

🔒 Безопасность и compliance

Встроенная безопасность

AML/KYC через интеграции

• Crypto2B обеспечивает первичный AML скрининг
• Fordefi предоставляет institutional-grade custody
• Автоматическая проверка санкционных списков через Chainalysis

Operational Security

• Многофакторная аутентификация для операторов
• Разделение ролей: наблюдатели, операторы, администраторы
• Audit trail всех операций с временными метками
• Регулярное резервное копирование данных

Risk Management

Лимиты и ограничения

• Максимальная сумма вывода без дополнительной верификации: $10,000
• Дневной лимит операций на одного оператора: $50,000
• Автоматическая эскалация для операций >$25,000

Мониторинг подозрительной активности

• Алерты при множественных депозитах с одного IP
• Блокировка аккаунтов при подозрении на взлом
• Временная заморозка при резком изменении паттернов использования

Архитектура высокого уровня

graph TB
    %% Пользователи
    subgraph "👤 Пользователи"
        USER[Обычный пользователь - Email/Google вход]
    end

    subgraph "👨‍💼 Операторы"
        OP[Оператор - Telegram + Админка]
        FORDEFI_MANUAL[Fordefi Platform - Ручное управление DeFi]
    end

    %% Saga Platform
    subgraph "🏢 Saga Platform"
        WEBAPP[🌐 User App - app.saga.surf]
        ADMINAPP[🔧 Admin App - admin.saga.surf]
        API[🚀 Backend API - Go + PostgreSQL]
        DB[(📊 Database - Users Transactions Investments)]
    end

    %% Внешние интеграции
    subgraph "🔗 Внешние интеграции"
        SUPA[🔐 Supabase Auth - Google OAuth + Email]
        CRYPTO2B[💳 Crypto2B - Deposits and Withdrawals - TRC20 USDT]
        FORDEFI[💼 Fordefi - Custody and DeFi - Manual Operations]
        EMAIL[📧 Resend - Email Notifications]
        TG[📱 Telegram Bot - Operator Alerts]
    end

    %% Blockchain (только через интеграции)
    subgraph "⛓️ Blockchain (через интеграции)"
        TRON[🌐 TRON/TRC20 - USDT Primary]
        ETH[🌐 Ethereum - USDC Backup]
        DEFI[🏦 DeFi Protocols - Curve Pendle via Fordefi]
    end

    %% Основные потоки
    USER -->|1. Google/Email Login| SUPA
    USER -->|2. Access App| WEBAPP
    WEBAPP -->|3. API Calls| API
    API -->|4. Auth Verify| SUPA
    API -->|5. Generate Deposit Address| CRYPTO2B

    USER -->|6. Send USDT| CRYPTO2B
    CRYPTO2B -->|7. Webhook: Deposit Confirmed| API
    API -->|8. Auto-create Investment| DB
    API -->|9. Notify Operators| TG

    %% Operator flow
    OP -->|10. View Tasks| ADMINAPP
    ADMINAPP -->|11. Admin API| API
    OP -->|12. Manual DeFi Operations| FORDEFI_MANUAL
    FORDEFI_MANUAL -->|13. Stake in DeFi| DEFI

    %% Daily operations
    API -->|14. Daily APY Accrual| DB
    USER -->|15. View Portfolio Growth| WEBAPP

    %% Withdrawal flow
    USER -->|16. Request Withdrawal| WEBAPP
    API -->|17. Create Withdrawal Task| TG
    OP -->|18. Process via Crypto2B| CRYPTO2B
    CRYPTO2B -->|19. Send USDT| USER
    API -->|20. Email Confirmation| EMAIL

    %% Styling
    style USER fill:#e3f2fd
    style OP fill:#fff3e0
    style WEBAPP fill:#e8f5e8
    style ADMINAPP fill:#fff8e1
    style API fill:#f3e5f5
    style CRYPTO2B fill:#ffebee
    style FORDEFI fill:#e1f5fe
    style SUPA fill:#f1f8e9

Пользовательские сценарии

🎯 Happy Path: Основной пользовательский сценарий

1. Вход и подготовка

sequenceDiagram
    participant U as 👤 User
    participant W as 🌐 WebApp
    participant S as 🔐 Supabase
    participant A as 🚀 API
    participant C as 💳 Crypto2B

    U->>W: Заходит на app.saga.surf
    W->>S: Google/Email вход
    S-->>W: JWT токен
    W->>A: Авторизация с токеном
    A-->>W: Профиль пользователя

    Note over W: Показать интерфейс<br/>TRC20 сеть выбрана<br/>Автоинвестирование включено<br/>Адрес уже сгенерирован

    W->>A: Запрос депозитного адреса
    A->>C: Генерация TRC20 адреса
    C-->>A: USDT адрес для депозитов
    A-->>W: Готовый адрес + инструкции

2. Депозит и автоинвестирование

sequenceDiagram
    participant U as 👤 User
    participant C as 💳 Crypto2B
    participant A as 🚀 API
    participant TG as 📱 Telegram
    participant O as 👨‍💼 Operator
    participant F as 💼 Fordefi

    U->>C: Перевод USDT на адрес
    Note over C: Мониторинг blockchain<br/>через Crypto2B API

    C->>A: Webhook: Депозит 1000 USD USDT
    A->>A: Автосоздание инвестиции<br/>10% APY фиксированная

    A->>TG: 📥 Уведомление оператору<br/>Новый депозит 1000 USD USDT
    TG-->>O: Push уведомление

    Note over O: Operator видит задачу в админке<br/>собрать средства

    O->>F: Ручной сбор средств<br/>с Crypto2B адресов
    F->>F: Размещение в DeFi<br/>(Curve, Pendle)

    A->>A: Запуск ежедневных<br/>начислений 10% APY

3. Рост портфеля и мониторинг

sequenceDiagram
    participant U as 👤 User
    participant W as 🌐 WebApp
    participant A as 🚀 API
    participant DB as 📊 Database

    Note over A,DB: Daily APY Accrual Process

    A->>DB: Ежедневное начисление<br/>1000 USD × 10% ÷ 365 = 2.74 USD

    U->>W: Заходит посмотреть портфель
    W->>A: Запрос баланса и истории
    A->>DB: Получение transactions + investments
    DB-->>A: Данные для расчёта баланса
    A-->>W: График роста<br/>1000 USD to 1027.40 USD

    Note over W: Показать<br/>Current Value 1027.40 USD<br/>Invested 1000.00 USD<br/>Profit +27.40 USD (+2.74%)<br/>14 дней инвестирования

4. Вывод средств (одним кликом)

sequenceDiagram
    participant U as 👤 User
    participant W as 🌐 WebApp
    participant A as 🚀 API
    participant TG as 📱 Telegram
    participant O as 👨‍💼 Operator
    participant C as 💳 Crypto2B
    participant E as 📧 Email

    U->>W: Запрос вывода 500 USD
    W->>W: Выбор закрыть инвестицию или вывести свободные средства

    U->>W: Выбирает закрыть 50% инвестиции
    U->>W: Указывает TRC20 адрес
    W->>A: Создание withdrawal request

    A->>A: Частичное закрытие инвестиции<br/>500 USD + проценты = 513.70 USD
    A->>TG: 📤 Вывод 513.70 USDT
    TG-->>O: Задача на обработку

    O->>C: Ручная инициация вывода на указанный адрес
    C->>U: Перевод USDT
    C->>A: Webhook: вывод выполнен

    A->>E: Уведомление пользователю
    E-->>U: Вывод 513.70 USD выполнен

    Note over U,E: SLA: до 24-48 часов

💰 Расширенные сценарии

Scenario A: Раздельные депозит и инвестирование

flowchart TD
    A[Пользователь выбирает Депозит без автоинвестирования] --> B[Средства поступают на внутренний баланс]
    B --> C[Пользователь видит доступные стратегии]
    C --> D[Выбирает стратегию и сумму для инвестирования]
    D --> E[Создается инвестиция из внутреннего баланса]
    E --> F[Оператор получает задачу на размещение]

Scenario B: Закрытие без вывода

flowchart TD
    A[Пользователь закрывает инвестицию частично/полностью] --> B[Средства возвращаются на внутренний баланс]
    B --> C{Что делать дальше?}
    C -->|Реинвестировать| D[Открытие новой инвестиции другого типа]
    C -->|Вывод позже| E[Средства остаются на балансе]
    C -->|Немедленный вывод| F[Запрос вывода свободных средств]

Scenario C: Комбинированный вывод

flowchart TD
    A[Запрос вывода 1500 USD] --> B{Доступно на балансе?}
    B -->|200 USD доступно| C[Недостаточно свободных средств]
    C --> D[Предложение закрыть 1300 USD из инвестиций]
    D --> E[Пользователь выбирает какие инвестиции закрыть]
    E --> F[Комбинированный вывод 200 USD баланс + 1300 USD закрытие]

---

Проблемные сценарии и решения

🚨 Error Scenarios: Обработка ошибок

1. Проблемы с депозитами

flowchart TD
    A[❌ Проблема] --> B{Тип ошибки}
    B -->|Неправильная сеть| C[ETH вместо TRC20]
    B -->|Неправильная валюта| D[BTC вместо USDT]
    B -->|Малая сумма| E[Меньше минимума 500 USD]
    B -->|Адрес не найден| F[Депозит не связан с пользователем]

    C --> C1[🔍 Crypto2B мониторинг других сетей]
    C1 --> C2[📧 Email: Обнаружен ETH депозит - будет конвертирован]
    C2 --> C3[👨‍💼 Оператор: ручная конвертация через bridge]

    D --> D1[🔍 Мониторинг BTC адресов если настроено]
    D1 --> D2[📧 Email: Неподдерживаемая валюта - свяжитесь с поддержкой]

    E --> E1[💰 Зачисление на баланс без автоинвестирования]
    E1 --> E2[📧 Email: Сумма меньше минимума - добавьте средства для инвестирования]

    F --> F1[📱 Telegram alert оператору]
    F1 --> F2[👨‍💼 Ручной поиск владельца по transaction details]
    F2 --> F3[📧 Email всем пользователям с запросом подтверждения]

2. Проблемы с выводами

flowchart TD
    A[❌ Ошибка вывода] --> B{Причина}
    B -->|Неправильный адрес| C[Невалидный/неактивный адрес]
    B -->|Заблокированный адрес| D[Адрес в санкционном списке]
    B -->|Технический сбой| E[Crypto2B недоступен]
    B -->|Недостаток ликвидности| F[DeFi средства заблокированы]

    C --> C1[⚠️ Pre-validation при вводе]
    C1 --> C2[📧 Email: Проверьте адрес - validation не прошёл]

    D --> D1[🛡️ Chainalysis проверка]
    D1 --> D2[❌ Блокировка вывода]
    D2 --> D3[📧 Email: Compliance требования - альтернативные варианты]

    E --> E1[🔄 Retry logic с exponential backoff]
    E1 --> E2[📱 Telegram оператору если retry failed]
    E2 --> E3[👨‍💼 Ручная обработка через альтернативные каналы]

    F --> F1[⏱️ Queue запроса до availability DeFi средств]
    F1 --> F2[📧 Email: Обработка задержана до 72 часов]
    F2 --> F3[👨‍💼 Emergency liquidation если критичная ситуация]

3. Проблемы с доступом

flowchart TD
    A[❌ Потеря доступа] --> B{Проблема}
    B -->|Забыл email| C[Не может войти через Google]
    B -->|Смена email| D[Старый email недоступен]
    B -->|Взлом аккаунта| E[Подозрительная активность]
    B -->|Технические проблемы| F[Supabase Auth недоступен]

    C --> C1[🆔 KYC verification process]
    C1 --> C2[📄 Документы + видео подтверждение]
    C2 --> C3[👨‍💼 Manual review оператором]
    C3 --> C4[🔄 Account recovery]

    D --> D1[📧 Email на оба адреса с confirmation link]
    D1 --> D2[⏱️ 48-hour waiting period]
    D2 --> D3[✅ Email change если confirmed]

    E --> E1[🔒 Временная заморозка аккаунта]
    E1 --> E2[📞 Phone verification]
    E2 --> E3[🛡️ Enhanced security setup]

    F --> F1[🔄 Fallback auth через email links]
    F1 --> F2[📱 Telegram notification админу]
    F2 --> F3[⚡ Emergency access procedure]

---

Операторский workflow

👨‍💼 Operator Dashboard: Управление операциями

Ключевые функции админки

mindmap
  root)👨‍💼 Operator Dashboard(
    📥 Deposits
      New Deposits Queue
      Auto-investment Status
      Collection Tasks
      Problem Deposits

    💰 Balances
      User Balances Overview
      Total TVL Tracking
      Available vs Invested
      Currency Breakdown

    📤 Withdrawals
      Pending Withdrawal Queue
      Processing Status
      Failed Withdrawals
      Manual Approval Required

    🔄 Operations
      DeFi Position Tracking
      Rebalancing Tasks
      Yield Monitoring
      Performance Reports

    📱 Communications
      User Contact Tools
      Telegram Integration
      Email Templates
      Support Ticket System

    ⚙️ Settings
      Notification Preferences
      Alert Thresholds
      Auto-processing Rules
      Integration Status

Operator Workflow

sequenceDiagram
    participant TG as 📱 Telegram
    participant O as 👨‍💼 Operator
    participant ADM as 🔧 Admin Dashboard
    participant F as 💼 Fordefi
    participant C as 💳 Crypto2B
    participant API as 🚀 API

    Note over TG,API: Daily Operations Cycle

    TG->>O: 🔔 "5 новых депозитов: 12500 USD"
    O->>ADM: Открывает dashboard
    ADM->>API: Получение списка задач
    API-->>ADM: Collection Task: 12500 USD USDT

    O->>F: Ручной сбор с адресов Crypto2B
    F->>F: Перевод на операционный кошелёк
    F->>F: Размещение в DeFi (Curve/Pendle)
    O->>ADM: ✅ Подтверждение размещения

    TG->>O: 🔔 "3 запроса вывода: 8200 USD"
    O->>ADM: Проверка withdrawal queue
    ADM->>API: Детали выводов + addresses

    Note over O: Анализ:<br/>можно ли покрыть выводы новыми депозитами?

    alt Покрытие депозитами
        O->>C: Прямой перевод с новых депозитов
    else Нужны DeFi средства
        O->>F: Частичное изъятие из DeFi
        F->>C: Перевод на Crypto2B для вывода
    end

    O->>C: Инициация выводов пользователям
    C->>API: Webhooks: выводы выполнены
    O->>ADM: ✅ Закрытие задач вывода

🎯 Task Management: Группировка операций

Delta-based операции

graph TD
    subgraph "📊 Daily Operations Analysis"
        A["Новые депозиты: +15000 USD USDT"] --> E[Calculate Net Flow]
        B["Запросы вывода: -8000 USD USDT"] --> E
        C["Закрытие инвестиций: -5000 USD USDT"] --> E
        D["Новые инвестиции: +12000 USD USDT"] --> E
    end

    E --> F{Net Analysis}
    F -->|Positive Flow +14000 USD| G["✅ Minimal DeFi operations<br/>Use incoming deposits<br/>for outgoing withdrawals"]
    F -->|Negative Flow -3000 USD| H["⚠️ Need DeFi liquidation<br/>Withdraw from positions<br/>Bridge/swap as needed"]
    F -->|Zero/Balanced| I["🔄 Internal rebalancing<br/>No external operations<br/>Direct user-to-user flow"]

    G --> J["📋 Simple Tasks"]
    H --> K["📋 Complex Tasks"]
    I --> L["📋 Rebalancing Tasks"]

    J --> J1["🔹 Route 8 USD deposits → withdrawals<br/>🔹 Invest remaining 7 USD in DeFi<br/>🔹 Process 5 USD reinvestment"]

    K --> K1["🔹 Withdraw 3 USD from Curve<br/>🔹 Bridge ETH→TRC if needed<br/>🔹 Swap USDC→USDT if needed<br/>🔹 Execute pending withdrawals"]

    L --> L1["🔹 Close 5 USD from Strategy A<br/>🔹 Open 5 USD in Strategy B<br/>🔹 Update user allocations<br/>🔹 No external operations"]

Task Confirmation System

sequenceDiagram
    participant S as 🚀 System
    participant O as 👨‍💼 Operator
    participant F as 💼 Fordefi
    participant ADM as 🔧 Admin

    S->>ADM: 📋 Task: "Collect 15 USD from addresses"
    S->>ADM: 📋 Detailed breakdown:<br/>User1: 3 USD from addr_123<br/>User2: 7 USD from addr_456<br/>User3: 5 USD from addr_789

    O->>F: Bulk collection operation
    F-->>O: Transaction hashes:<br/>tx_abc123 (collected 15 USD)

    O->>ADM: ✅ Confirm with tx hashes
    ADM->>S: Verify transactions on-chain
    S->>S: ✅ Mark collection complete<br/>Update user balances

    S->>ADM: 📋 New Task: "DeFi placement 15 USD"
    O->>F: Stake in Curve 3pool
    F-->>O: tx_def456 (staked 15 USD)
    O->>ADM: ✅ Confirm DeFi placement

---

Административные процессы

👥 Роли операторов

1. Наблюдатель: Просмотр балансов, транзакций, уведомлений
2. Оператор: Обработка запросов, управление выводами
3. Администратор: Полный доступ + настройка системы

💰 Административные процессы для бонусов

Процедура докидывания средств пользователю:

1. Верификация пользователя
2. Проверка активности аккаунта и депозитной истории
3. Подтверждение легитимности депозита <$500

4. Документирование причины предоставления бонуса

5. Перевод средств

6. Компания переводит бонусные средства напрямую на Fordefi (DeFi операторам)
7. Альтернативно: перевод на общий счет Crypto2B для дальнейшего распределения

8. Уведомление DeFi-операторов о дополнительных средствах

9. Активация в админке

10. Оператор включает режим повышенной доходности (x2 или кастомный %)
11. Создание записи о бонусе в системе tracking

12. Привязка бонуса к конкретному пользователю и депозиту

13. Уведомление пользователя

14. Автоматическое email уведомление о получении бонуса
15. Отображение специальной плашки в интерфейсе
16. Обновленные проценты доходности в дашборде

Система отслеживания: - Ведение реестра всех бонусов с привязкой к пользователям - Мониторинг лимитов бонусной программы - Отчетность по распределенным бонусам для финансовой отчетности

📊 Операционная панель

graph LR
    subgraph "Входящие операции"
        DEP[Депозиты - +50000 USD]
        INV[Новые инвестиции - +45000 USD]
    end

    subgraph "Исходящие операции"
        WITH[Запросы выводов - -20000 USD]
        CLOSE[Закрытые позиции - -15000 USD]
    end

    subgraph "Балансировка"
        DELTA[Чистый приток - +60000 USD]
        ACTION{Действие оператора}
    end

    DEP --> DELTA
    INV --> DELTA
    WITH --> DELTA
    CLOSE --> DELTA

    DELTA --> ACTION

    ACTION -->|Приток > Отток| COLLECT[Сбор на холодный кошелек]
    ACTION -->|Отток > Приток| BRIDGE[Бридж с платформ DeFi]
    ACTION -->|Дельта ≈ 0| REBALANCE[Только реаллокация]

🔄 Жизненный цикл операций

stateDiagram-v2
    [*] --> UserRequest: Пользовательский запрос
    UserRequest --> SystemValidation: Валидация системой

    SystemValidation --> AutoProcess: Автоматическая обработка
    SystemValidation --> ManualReview: Ручная проверка

    AutoProcess --> Pending: В обработке
    ManualReview --> Approved: Одобрено
    ManualReview --> Rejected: Отклонено

    Approved --> Pending
    Pending --> InProgress: В работе оператора

    InProgress --> FordefiExecution: Выполнение в Fordefi
    FordefiExecution --> BlockchainConfirmation: Подтверждение блокчейн

    BlockchainConfirmation --> Completed: Завершено
    BlockchainConfirmation --> Failed: Ошибка

    Failed --> ManualIntervention: Ручное вмешательство
    ManualIntervention --> InProgress: Повтор
    ManualIntervention --> Cancelled: Отменено

    Completed --> [*]
    Rejected --> [*]
    Cancelled --> [*]

Интеграции

🔗 Integration Details

Crypto2B Integration

• Функции: Deposit address generation, webhook notifications, withdrawal processing
• Сети: TRC20 (primary), ETH (backup)
• Валюты: USDT (primary), USDC (backup)
• SLA: Deposits <2h, Withdrawals <24h
• API: REST endpoints + webhook callbacks
• Security: API keys, signature verification

Fordefi Integration

• Функции: Custody, manual DeFi operations, security
• Протоколы: Curve Finance, Pendle Finance
• Управление: MPC wallets, manual approval workflow
• Доходность: Target 12-15% to deliver 10% to users
• Interface: Web dashboard для операторов

Supabase Auth

• Методы: Google OAuth, Email/Password, Magic Links
• JWT: 24-hour expiration, automatic refresh
• Security: Rate limiting, MFA support
• Integration: SDK для frontend, API для backend

Notifications

• Email: Resend для user notifications (регистрация, депозиты, выводы)
• Telegram: Custom bot для operator alerts (новые депозиты, проблемы)
• In-app: Real-time через WebSocket (balance updates)

📊 Integration Status

Сервис	Назначение	Тип интеграции	Статус
Crypto2B	Депозиты/выводы криптовалют	REST API + Webhooks	✅ Integration-Ready
Supabase Auth	Аутентификация пользователей	SDK + JWT	✅ Ready
Fordefi	Управление корпоративными активами	Web Interface	🔄 Manual Operations
Resend SMTP	Email уведомления	REST API	✅ Ready
Telegram Bot	Push уведомления операторам	Bot API	🚧 MVP Phase 2

🌐 Поддерживаемые сети

graph TD
    subgraph "Предпочтительные сети"
        TRC20[TRC20 / USDT - 💚 Основная сеть]
        ETH[Ethereum / USDC - 💛 Альтернативная]
    end

    subgraph "Дополнительные сети"
        BSC[BSC / BUSD]
        POLY[Polygon / USDC]
        ARB[Arbitrum / USDC]
        SOL[Solana / USDC]
    end

    TRC20 -.->|Низкие комиссии| PREFERRED[Рекомендуется пользователям]
    ETH -.->|Высокие комиссии| FALLBACK[Для крупных сумм]

Проблемные сценарии

⚠️ Типичные проблемы и решения

Проблема	Обнаружение	Решение	Автоматизация
Депозит в неправильной сети	Отсутствие подтверждения 2+ часа	Ручная проверка блокчейна → Возврат/Кредит	❌ Ручная
Неверный адрес вывода	Валидация при вводе	Предварительная проверка + подтверждение	✅ Частично
Потеря доступа к аккаунту	Обращение в поддержку	Верификация личности + восстановление	❌ Ручная
Малая сумма депозита	Автоматическая валидация	Уведомление + инструкции	✅ Автоматически
Высокие комиссии сети	Мониторинг gas цен	Отложенная обработка до снижения	✅ Автоматически
Санкционный адрес	Проверка через Chainalysis API	Блокировка + эскалация	✅ Автоматически

🆘 Эскалационная матрица

graph TD
    ISSUE[Проблема пользователя] --> AUTO{Автоматическое - решение?}

    AUTO -->|Да| RESOLVE[Автоматическое - решение]
    AUTO -->|Нет| L1[Поддержка L1 - Стандартные вопросы]

    L1 --> L1_OK{Решено?}
    L1_OK -->|Да| RESOLVE
    L1_OK -->|Нет| L2[Поддержка L2 - Технические операторы]

    L2 --> L2_OK{Решено?}
    L2_OK -->|Да| RESOLVE
    L2_OK -->|Нет| L3[Администратор - Сложные случаи]

    L3 --> DEV[Разработчики - Системные проблемы]

    RESOLVE --> FEEDBACK[Обратная связь - пользователю]

Операционная модель

💼 Ежедневные процессы операторов

gantt
    title График операционных процессов
    dateFormat  HH:mm
    axisFormat %H:%M

    section Утренние задачи
    Проверка ночных депозитов    :active, morning1, 09:00, 30m
    Анализ балансов кошельков    :morning2, after morning1, 20m
    Планирование сборов          :morning3, after morning2, 15m

    section Дневные операции
    Обработка выводов           :day1, 10:00, 4h
    Мониторинг транзакций       :active, day2, 10:00, 8h
    Балансировка позиций        :day3, 14:00, 2h

    section Вечерние задачи
    Сбор средств на холодные кошельки :evening1, 18:00, 1h
    Отчетность по операциям           :evening2, after evening1, 30m
    Подготовка к следующему дню       :evening3, after evening2, 15m

📈 Метрики и KPI

Метрика	Цель	Частота измерения
Время обработки депозита	< 2 часа	В реальном времени
Время обработки вывода	< 24 часа	В реальном времени
Успешность операций	> 99.5%	Ежедневно
Объем входящих средств	Рост 10% мес.	Еженедельно
Средний размер депозита	Увеличение	Еженедельно
Удержание пользователей	> 80% за 3 мес.	Ежемесячно

---

📋 MVP Спецификация (Ultra-Simplified)

🎯 Инвестиционная модель (Integration-Only)

ЕДИНСТВЕННЫЙ тип инвестиции:

• ✅ Ликвидные — досрочное закрытие без штрафов
• ✅ Неубывающие — капитал защищен от потерь
• ✅ Фиксированный процент — предсказуемая доходность
• ✅ Без lock-up — вывод средств в любое время
• ✅ Минимум $500 — для инвестирования и пополнения
• 🔥 БЕЗ ВЫБОРА — никаких настроек, стратегий, опций

Управление активами (ТОЛЬКО внешние интеграции):

• 🔹 Crypto2B — обработка всех депозитов и выводов
• 🔹 Fordefi — профессиональное управление активами
• 🔹 Операторы — ручные решения по размещению средств
• ❌ Saga НЕ управляет криптой — только отслеживание

💰 Финансовая модель

Комиссионная структура:

• 📊 Management Fee — фиксированная комиссия за управление
• 📈 Performance Fee — процент от полученной прибыли
• 💸 Комиссии блокчейна — покрывает платформа

AML/Compliance:

• ✅ AML на контрагенте — Crypto2B обеспечивает compliance
• ❌ KYC не требуется — упрощенная регистрация
• 🛡️ Все легальные вопросы — на стороне контрагента

🔧 Техническое MVP

Интеграции (Integration-Only):

• 🔄 Crypto2B API — полная интеграция для депозитов/выводов
• 💼 Fordefi — ручное управление активами операторами
• 📧 Email ОБЯЗАТЕЛЕН — каждый пользователь должен иметь email
• 📱 PWA приложение — адаптивный веб-сайт (НЕ native apps)
• 🇷🇺 Только русский язык — локализация для РФ
• ❌ БЕЗ КРИПТОВАЛЮТНОЙ ЛОГИКИ — только интеграции + tracking

Telegram уведомления операторам:

📥 Новая инвестиция: +$1,500 USDT (пользователь #12345)
📤 Запрос вывода: -$2,000 USDC → 0x123...abc (пользователь #67890)
🆘 Обращение пользователя: "Не получил подтверждение вывода" (#12345)
⚠️ Подозрительная транзакция: $50,000 с нового аккаунта

Аналитика MVP:

• 📊 В админке — базовые метрики для операторов
• 📈 Для пользователей — простой P&L отчет
• ❌ Внешняя аналитика — не требуется для MVP

🚀 Приоритеты разработки

Phase 1: Core Foundation (1-2 недели)

graph LR
    A[Crypto2B интеграция] --> B[Базовый UI депозитов]
    B --> C[Автоинвестирование]
    C --> D[Простой дашборд]

Phase 2: Operations (2-3 недели)

graph LR
    E[Админка операторов] --> F[Telegram уведомления]
    F --> G[Процесс выводов]
    G --> H[Мониторинг транзакций]

Phase 3: Polish (1 неделя)

graph LR
    I[PWA оптимизация] --> J[Email уведомления]
    J --> K[Error handling]
    K --> L[Performance]

Итого: 4-6 недель до MVP

---

---

📋 Связанная документация

Обзор и навигация

• 📖 Главная документация - Точка входа в документацию Saga
• 🏛️ Architecture Overview - Clean Architecture принципы и золотые правила
• 📊 Диаграммы архитектуры - Все архитектурные диаграммы проекта
• 👨‍💻 Developer Documentation - Документация для разработчиков

Документы, обновленные согласно этой архитектуре:

Архитектурные документы

• ✅ MVP Simplified Flow - Упрощенный поток MVP
• ✅ Authentication Flow - Email-first аутентификация
• ✅ Deposits Flow - Crypto2B integration
• ✅ Database Schema - Integration-Only schema
• ✅ Integration-Only Architecture - Основные принципы

Бизнес документы

• ✅ Ultra-Simplified MVP Scope - Минималистичный scope
• ✅ Economic Model - Обновленная финансовая модель
• ✅ Onboarding Flow - Email-first процесс

API документация

• ✅ Authentication API - Supabase integration
• ✅ Auth Endpoints - JWT workflow
• ✅ Deposits Endpoints - Crypto2B integration
• ✅ Investments Endpoints - Упрощенная логика
• ✅ Withdrawals Endpoints - Manual processing

Удаленные/deprecated документы

• ❌ HD Wallet Architecture - УДАЛЕН (противоречит Integration-Only)
• 📄 HD Wallet Deprecation Notice - Уведомление об устаревании

---

✅ Архитектурные решения приняты

Это центральный архитектурный документ - все остальные должны ссылаться на него и быть с ним согласованы.

Все критические вопросы решены. Система готова к детальному планированию и разработке MVP с фокусом на простоту, надежность и Integration-Only подход.

Последнее обновление: 2025-11-20 Согласованность: ✅ Все process flows проверены на Integration-Only соответствие Последние изменения (v2.6.296): Добавлена детальная документация логики расчета баланса с AccumulatedYields tracking