Модуль Investment (Стратегии, Участия)

Обзор

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

Зоны ответственности

• Управление инвестиционными стратегиями
• Категоризация и поиск стратегий
• Многошаговый мастер участия
• Отслеживание жизненного цикла инвестиций
• Агрегация и отчетность по портфелю
• Расчет и распределение доходности
• Обработка досрочного вывода
• Реферальная атрибуция для инвестиций

---

Доменные сущности

Strategy

Определение инвестиционной стратегии.

Поле	Тип	Описание
id	UUID	Идентификатор стратегии
category_id	UUID	Ссылка на категорию
name	VARCHAR(200)	Название стратегии
code	VARCHAR(50)	Уникальный код стратегии
slug	VARCHAR(200)	URL-дружественный идентификатор
short_description	VARCHAR(500)	Краткое описание
description	TEXT	Полное описание
terms	TEXT	Юридические условия
risk_level	ENUM	LOW, MEDIUM, HIGH, VERY_HIGH
min_amount	DECIMAL	Минимальная инвестиция
max_amount	DECIMAL	Максимальная инвестиция (опционально)
duration_months	INT	Срок инвестиции
expected_return_min	DECIMAL	Минимальная ожидаемая доходность %
expected_return_max	DECIMAL	Максимальная ожидаемая доходность %
image_url	VARCHAR(500)	Изображение стратегии
documents_urls	JSONB	Связанные документы
status	ENUM	Статус стратегии
participants_count	INT	Активных участников
total_invested	DECIMAL	Общая сумма инвестиций
published_at	TIMESTAMP	Дата публикации

StrategyCategory

Категория для организации стратегий.

Поле	Тип	Описание
id	UUID	Идентификатор категории
name	VARCHAR(100)	Название категории
slug	VARCHAR(100)	URL-дружественный идентификатор
description	TEXT	Описание категории
parent_id	UUID	Родительская категория
sort_order	INT	Порядок отображения
is_active	BOOLEAN	Статус активности

ParticipationStep

Конфигурация шага мастера для стратегии.

Поле	Тип	Описание
id	UUID	Идентификатор шага
strategy_id	UUID	Ссылка на стратегию
step_number	INT	Порядок шага
title	VARCHAR(200)	Заголовок шага
description	TEXT	Инструкции по шагу
step_type	ENUM	Тип шага
config	JSONB	Конфигурация шага
is_required	BOOLEAN	Флаг обязательности

Participation

Участие пользователя в инвестиции.

Поле	Тип	Описание
id	UUID	Идентификатор участия
user_id	UUID	Ссылка на инвестора
strategy_id	UUID	Ссылка на стратегию
current_step	INT	Текущий шаг мастера
step_data	JSONB	Собранные данные мастера
amount	DECIMAL	Сумма инвестиции
currency	VARCHAR(3)	Код валюты
status	ENUM	Статус участия
referring_partner_id	UUID	MLM атрибуция
started_at	TIMESTAMP	Время начала мастера
submitted_at	TIMESTAMP	Время подачи
approved_at	TIMESTAMP	Время одобрения
completed_at	TIMESTAMP	Время завершения

Portfolio

Запись активного инвестиционного портфеля пользователя.

Поле	Тип	Описание
id	UUID	Идентификатор записи портфеля
user_id	UUID	Ссылка на инвестора
participation_id	UUID	Исходное участие
strategy_id	UUID	Ссылка на стратегию
invested_amount	DECIMAL	Первоначальная инвестиция
current_value	DECIMAL	Текущая стоимость
total_returns	DECIMAL	Накопленная доходность
currency	VARCHAR(3)	Код валюты
status	ENUM	Статус портфеля
start_date	DATE	Дата начала инвестиции
maturity_date	DATE	Ожидаемый срок погашения
last_updated_at	TIMESTAMP	Последнее обновление стоимости

---

Типы стратегий и конфигурация

Уровни риска

Уровень риска	Ожидаемая доходность	Волатильность	Подходит для
LOW	5-8% годовых	Низкая	Консервативных инвесторов
MEDIUM	8-15% годовых	Умеренная	Сбалансированных портфелей
HIGH	15-25% годовых	Высокая	Ищущих рост
VERY_HIGH	25%+ годовых	Очень высокая	Толерантных к риску инвесторов

Поток статусов стратегии

Пример конфигурации стратегии

{
  "name": "Growth Portfolio 2024",
  "code": "GROWTH_2024",
  "risk_level": "HIGH",
  "min_amount": 50000,
  "max_amount": 5000000,
  "duration_months": 12,
  "expected_return_min": 15.0,
  "expected_return_max": 25.0,
  "terms": "Investment terms and conditions...",
  "documents_urls": [
    {"type": "prospectus", "url": "/docs/growth-2024-prospectus.pdf"},
    {"type": "risk_disclosure", "url": "/docs/risk-disclosure.pdf"}
  ]
}

---

Мастер участия

Многошаговый процесс

Мастер участия проводит пользователей через процесс инвестирования:

Типы шагов

Тип	Описание	Конфигурация
INFO	Отображение информации только для чтения	content, acknowledgement
FORM	Форма сбора данных	fields, validation rules
DOCUMENT_UPLOAD	Требование загрузки файла	document_types, max_size
KYC_CHECK	Проверка KYC верификации	required_level
PAYMENT	Обработка платежа	payment_methods
CONFIRMATION	Финальная проверка и подтверждение	summary_fields

Примеры конфигурации шагов

Шаг INFO:

{
  "step_type": "INFO",
  "config": {
    "content": "Strategy overview and risk disclosure...",
    "acknowledgement_required": true,
    "acknowledgement_text": "I have read and understood the risks"
  }
}

Шаг FORM:

{
  "step_type": "FORM",
  "config": {
    "fields": [
      {
        "name": "investment_amount",
        "type": "number",
        "label": "Investment Amount",
        "min": 50000,
        "max": 5000000,
        "required": true
      },
      {
        "name": "investment_goal",
        "type": "select",
        "label": "Investment Goal",
        "options": ["retirement", "education", "wealth_growth"],
        "required": true
      }
    ]
  }
}

Шаг KYC_CHECK:

{
  "step_type": "KYC_CHECK",
  "config": {
    "required_level": "STANDARD",
    "allow_skip": false,
    "redirect_to_kyc": true
  }
}

Валидация на каждом шаге

---

Жизненный цикл инвестиции

Поток статусов участия

Определения статусов

Статус	Описание
IN_PROGRESS	Пользователь проходит шаги мастера
PENDING_APPROVAL	Подано, ожидает одобрения
ACTIVE	Инвестиция активна
COMPLETED	Инвестиция успешно погашена
WITHDRAWN	Обработан досрочный вывод
CANCELLED	Пользователь отменил до активации
REJECTED	Администратор отклонил заявку

Поток статусов портфеля

---

Агрегация портфеля

Расчеты портфеля

Метрики портфеля

Метрика	Расчет
Всего инвестировано	Сумма всех invested_amount
Текущая стоимость	Сумма всех current_value
Общая доходность	Сумма всех total_returns
ROI	(Текущая стоимость - Всего инвестировано) / Всего инвестировано * 100
Активные инвестиции	Количество где status = ACTIVE

Портфель по стратегиям

SELECT
    s.name as strategy_name,
    COUNT(*) as investments,
    SUM(p.invested_amount) as total_invested,
    SUM(p.current_value) as current_value,
    SUM(p.total_returns) as returns
FROM portfolios p
JOIN strategies s ON p.strategy_id = s.id
WHERE p.user_id = :userId
GROUP BY s.id, s.name;

---

Распределение доходности

Процесс распределения

Методы расчета доходности

Метод	Описание	Применение
Fixed	Фиксированный процент за период	Консервативные стратегии
Variable	На основе рыночной доходности	Стратегии роста
Tiered	Разные ставки в зависимости от суммы	Стимулы для крупных инвесторов
Compound	Реинвестирование доходности	Долгосрочные стратегии

Расписание распределения доходности

Частота	Описание
Monthly	Доходность рассчитывается и распределяется ежемесячно
Quarterly	Каждые 3 месяца
At Maturity	Единовременное распределение в конце срока
Continuous	Ежедневное начисление, ежемесячное распределение

Зачисление доходности

Доходность может быть зачислена на:

1. Баланс пользователя - Доступно для вывода или реинвестирования
2. Реинвестирование - Автоматически добавляется в портфель
3. MLM баланс - Если пользователь также является партнером

---

Досрочный вывод

Правила вывода

Время вывода	Штраф	Условия
0-3 месяца	10% от доходности	Возвращается полная сумма вложения
3-6 месяцев	5% от доходности	Возвращается полная сумма вложения
6-12 месяцев	2% от доходности	Возвращается полная сумма вложения
После погашения	Без штрафа	Доступна полная стоимость

Процесс досрочного вывода

Расчет штрафа

function calculateWithdrawalAmount(
  portfolio: Portfolio,
  currentDate: Date
): WithdrawalResult {
  const monthsInvested = differenceInMonths(currentDate, portfolio.start_date);

  let penaltyRate = 0;
  if (monthsInvested < 3) penaltyRate = 0.10;
  else if (monthsInvested < 6) penaltyRate = 0.05;
  else if (monthsInvested < 12) penaltyRate = 0.02;

  const returns = portfolio.current_value - portfolio.invested_amount;
  const penalty = returns * penaltyRate;
  const finalAmount = portfolio.current_value - penalty;

  return {
    invested_amount: portfolio.invested_amount,
    returns: returns,
    penalty: penalty,
    final_amount: finalAmount
  };
}

---

Публикуемые события

Событие	Триггер	Payload
StrategyCreated	Создана новая стратегия	strategyId, code, name
StrategyPublished	Стратегия опубликована	strategyId, publishedAt
StrategyStatusChanged	Переход статуса	strategyId, fromStatus, toStatus
ParticipationStarted	Пользователь начал мастер	participationId, userId, strategyId
ParticipationStepCompleted	Шаг мастера завершен	participationId, stepNumber, stepData
ParticipationSubmitted	Мастер завершен	participationId, userId, amount
ParticipationApproved	Администратор одобрил	participationId, approvedBy
ParticipationRejected	Администратор отклонил	participationId, reason
ParticipationActivated	Инвестиция активна	participationId, portfolioId
ParticipationCancelled	Пользователь отменил	participationId, reason
InvestmentMatured	Срок завершен	portfolioId, finalValue
ReturnsDistributed	Доходность зачислена	portfolioId, amount, period
WithdrawalRequested	Пользователь запросил вывод	portfolioId, amount
WithdrawalCompleted	Вывод обработан	portfolioId, amount, penalty
PortfolioValueUpdated	Стоимость пересчитана	portfolioId, previousValue, newValue

---

Потребляемые события

Событие	Источник	Обработчик
ReferralAttributed	MLM	Сохранить реферала в участии
PaymentReceived	Commerce	Активировать участие
PaymentFailed	Commerce	Отменить участие
KycApproved	Core	Разблокировать участия, ожидающие KYC

---

Бизнес-правила и инварианты

Правила стратегий

1. Минимальная сумма должна быть положительной
2. Максимальная сумма должна быть больше минимальной (если задана)
3. Максимальная ожидаемая доходность должна быть >= минимальной
4. Срок должен быть положительным (если задан)
5. Только стратегии со статусом ACTIVE принимают новые участия

Правила участия

1. Пользователь не может иметь несколько участий IN_PROGRESS для одной стратегии
2. Сумма должна быть в пределах min/max стратегии
3. Все обязательные шаги должны быть завершены перед подачей
4. Уровень KYC должен соответствовать требованиям стратегии
5. Платеж должен быть получен для активации

Правила портфеля

1. Текущая стоимость не может быть отрицательной
2. Сумма инвестиции неизменна после создания
3. Доходность зачисляется в total_returns
4. Статус должен следовать определенной машине состояний
5. Дата погашения рассчитывается как start_date + duration

Правила доходности

1. Доходность рассчитывается на основе конфигурации стратегии
2. Штрафы за досрочный вывод применяются согласно правилам
3. Доходность зачисляется на баланс пользователя или реинвестируется
4. MLM комиссии начисляются при активации (не с доходности)

---

Точки интеграции

Предоставляет другим модулям

Интерфейс	Потребители	Назначение
IInvestmentService	MLM	Получить детали инвестиции для комиссии
IPortfolioService	Core	Сводка портфеля пользователя

Потребляет от других модулей

Интерфейс	Провайдер	Назначение
IUserLookupService	Core	Получить данные инвестора
IKycStatusService	Core	Проверить уровень KYC для участия
IAttributionService	MLM	Получить реферального партнера для инвестиции
IPaymentService	Commerce	Обработать платежи по инвестиции

---

Связанные документы

• Investment Schema
• Module Architecture
• Commission Engine