# Módulo Investment

**Epic:** OQI-004 - Cuentas de Inversión
**Progreso:** 35%
**Responsable:** Investment + Backend Teams

## Descripción

El módulo de inversión proporciona una plataforma completa de cuentas de inversión gestionadas por trading agents con inteligencia artificial (Atlas, Orion, Nova). Permite a los usuarios depositar capital, seleccionar perfiles de riesgo, recibir distribuciones de ganancias, y monitorear performance en tiempo real.

Los trading agents ejecutan estrategias automatizadas diversificadas, y los usuarios reciben distribuciones de ganancias monthly o quarterly según configuración. El sistema integra Stripe para deposits y soporta withdrawals vía bank transfer y crypto.

## Componentes

### Páginas

- `Investment.tsx` - Landing page con showcase de productos (Atlas/Orion/Nova) y disclosure de riesgos
- `Portfolio.tsx` - Dashboard principal con portfolio summary stats, account list, y quick action links
- `AccountDetail.tsx` - Vista detallada de cuenta con tabs (overview, transactions, distributions, deposits, withdrawals) y performance chart
- `Products.tsx` - Listing de productos con filtrado por risk profile y comparison table
- `ProductDetail.tsx` - Detalle individual de producto con historical performance chart, features, y investment CTA widget
- `Reports.tsx` - Analytics dashboard con allocation pie chart, performance bar chart, account comparison table, export a JSON
- `Transactions.tsx` - Historial global de transacciones cross-accounts con filtrado por tipo y cuenta
- `Withdrawals.tsx` - Gestión de withdrawal requests con status progression y destination details

### Componentes Reutilizables

- `AccountSummaryCard.tsx` - Card de overview de cuenta con balance, gains, status badge; modos compact y full con action menu
- `PerformanceWidgetChart.tsx` - Sparkline canvas chart mostrando trends de balance/value con color coding automático (green/red), diseño responsive
- `ProductComparisonTable.tsx` - Tabla de comparación side-by-side de productos con secciones expandibles (returns, fees, terms, strategies); badge "Popular"
- `AccountSettingsPanel.tsx` - Panel de settings tabulado para distribution frequency, auto-reinvest, notificaciones, risk alerts, withdrawal preferences
- `DepositForm.tsx` - Formulario de pago integrado con Stripe: amount presets, currency field, card element, success confirmation
- `WithdrawForm.tsx` - Formulario multi-step de withdrawal (details → verification) con soporte bank transfer y crypto withdrawal methods

## Hooks

### useMLAnalysis

**Ubicación:** `hooks/useMLAnalysis.ts`

Hook para obtener señales de trading ML (ICT analysis, ensemble signals) con caching inteligente.

**Características:**
- Cache duration de 1 minuto con validity checking
- Parámetros: symbol, timeframe
- Auto-refresh capability con intervalos configurables
- Health check del ML engine

**Uso:**
```typescript
const {
  ictAnalysis,
  ensembleSignal,
  scanResults,
  loading,
  error,
  isHealthy,
  refreshICT,
  refreshEnsemble,
  refreshScan,
  refreshAll,
  setSymbol,
  setTimeframe
} = useMLAnalysis({
  symbol: 'BTCUSDT',
  timeframe: '1h',
  autoRefresh: true,
  refreshInterval: 60000
});
```

### useQuickSignals

**Ubicación:** `hooks/useQuickSignals.ts`

Hook para polling rápido de señales para múltiples símbolos.

**Uso:**
```typescript
const {
  signals,    // Map<symbol, QuickSignal>
  loading,
  refresh
} = useQuickSignals(
  ['BTCUSDT', 'ETHUSD', 'EURUSD'],  // Symbols array
  30000                               // Poll interval (30s)
);
```

## Estructura de Carpetas

```
modules/investment/
├── components/
│   ├── AccountSummaryCard.tsx
│   ├── PerformanceWidgetChart.tsx
│   ├── ProductComparisonTable.tsx
│   ├── AccountSettingsPanel.tsx
│   ├── DepositForm.tsx
│   ├── WithdrawForm.tsx
│   └── index.ts
├── pages/
│   ├── Investment.tsx
│   ├── Portfolio.tsx
│   ├── AccountDetail.tsx
│   ├── Products.tsx
│   ├── ProductDetail.tsx
│   ├── Reports.tsx
│   ├── Transactions.tsx
│   └── Withdrawals.tsx
├── hooks/
│   ├── useMLAnalysis.ts
│   └── useQuickSignals.ts
└── README.md
```

**Servicios y estado compartidos:**
- **Service:** `services/investment.service.ts` (Axios)
- **Store:** `stores/portfolioStore.ts` (Zustand con WebSocket)
- **Types:** `types/investment.types.ts`

## APIs Consumidas

### Products APIs (Base URL: `/api/v1`)

| Endpoint | Método | Descripción |
|----------|--------|-------------|
| `/investment/products` | GET | Obtener todos los productos (opcional: filtro por riskProfile) |
| `/investment/products/{productId}` | GET | Detalle de producto por ID |
| `/investment/products/{productId}/performance` | GET | Performance histórico del producto (params: period) |

### Accounts APIs

| Endpoint | Método | Descripción |
|----------|--------|-------------|
| `/investment/accounts` | GET | Cuentas de inversión del usuario |
| `/investment/accounts/summary` | GET | Summary de todas las cuentas (total balance, P&L) |
| `/investment/accounts/{accountId}` | GET | Detalle de cuenta individual |
| `/investment/accounts` | POST | Crear nueva cuenta (params: productId, initialDeposit) |
| `/investment/accounts/{accountId}/close` | POST | Cerrar cuenta |

### Transactions APIs

| Endpoint | Método | Descripción |
|----------|--------|-------------|
| `/investment/accounts/{accountId}/transactions` | GET | Transacciones de cuenta (params: type, status, limit, offset) |
| `/investment/accounts/{accountId}/deposit` | POST | Crear deposit (params: amount) |
| `/investment/accounts/{accountId}/withdraw` | POST | Crear withdrawal (params: amount, bankInfo o cryptoInfo) |

### Distributions & Withdrawals

| Endpoint | Método | Descripción |
|----------|--------|-------------|
| `/investment/accounts/{accountId}/distributions` | GET | Distribuciones de ganancias de cuenta |
| `/investment/withdrawals` | GET | Withdrawal requests del usuario (opcional: filtro por status) |

## Uso Rápido

```tsx
import {
  Investment,
  Portfolio,
  AccountDetail,
  Products
} from '@/modules/investment';
import { usePortfolioStore } from '@/stores/portfolioStore';

// Uso en router
<Route path="/investment" element={<Investment />} />
<Route path="/portfolio" element={<Portfolio />} />
<Route path="/account/:accountId" element={<AccountDetail />} />
<Route path="/products" element={<Products />} />

// Uso de store
function MyComponent() {
  const {
    portfolios,
    selectedPortfolio,
    stats,
    fetchPortfolios,
    selectPortfolio,
    executeRebalance
  } = usePortfolioStore();

  useEffect(() => {
    fetchPortfolios();
  }, []);

  const handleRebalance = async () => {
    await executeRebalance();
  };

  return (
    <div>
      <h2>Portfolios: {portfolios.length}</h2>
      {selectedPortfolio && (
        <>
          <p>Balance: ${selectedPortfolio.totalValue}</p>
          <p>P&L: ${stats?.unrealizedPnl}</p>
          <button onClick={handleRebalance}>Rebalance</button>
        </>
      )}
    </div>
  );
}
```

## Características Principales

### Trading Agents
- **Atlas (Conservative):** Low volatility, capital preservation, diversified allocation
- **Orion (Moderate):** Balanced risk/reward, trend following strategies
- **Nova (Aggressive):** High leverage, short-term momentum trading

### Deposit Flow
- **Stripe Integration:** Secure card payment via Stripe Elements
- **Payment Intent:** Creates `/api/v1/payments/wallet/deposit` intent
- **Client Confirmation:** `stripe.confirmCardPayment()`
- **Metadata:** Incluye `accountId` y `type: 'investment_deposit'`

### Withdrawal Flow
- **Dual Methods:**
  - Bank Transfer (1-3 días): name, account number, routing number, holder name
  - Crypto (24-48 horas): network (Ethereum/Bitcoin/Tron/BSC), wallet address
- **Two-Step:** Details collection → 2FA verification
- **Limits:** Daily limit $10,000, Min $50
- **Endpoint:** `POST /api/v1/investment/accounts/{accountId}/withdraw`

### Real-time Updates
- **WebSocket Integration:** `portfolioStore` conecta a WebSocket para updates en tiempo real
- **Live Data:** Balance, P&L, allocations, positions
- **Connection Status:** Indicador visual de conexión WebSocket

### Performance Tracking
- **Multi-period Returns:** Daily, weekly, monthly, all-time
- **Visual Charts:** Sparklines con Canvas API
- **Export:** JSON export de reports completos

### Account Settings
- **Distribution Frequency:** Monthly o Quarterly
- **Auto-reinvest:** Toggle para reinversión automática de ganancias
- **Notifications:** Email y push notifications
- **Risk Alerts:** Alertas de pérdidas o drawdown
- **Withdrawal Preferences:** Default method y account

## Tests

```bash
# Tests unitarios del módulo
npm run test modules/investment

# Tests de integración con Stripe
npm run test:integration investment/stripe

# Tests E2E de flujos de inversión
npm run test:e2e investment
```

## Roadmap

### Pendientes - Alta Prioridad (P0-P1)
- [ ] **KYC Integration** (45h) - Verificación de identidad con Persona/Onfido
- [ ] **Tax Reporting** (30h) - 1099 forms y tax documents
- [ ] **Withdrawal Approval Workflow** (20h) - Approval manual para withdrawals grandes
- [ ] **Custody Integration** (60h) - Integración con custodio regulado

### Mediano Plazo (P2)
- [ ] **Auto-compound Settings** (8h) - Configuración granular de auto-reinvest
- [ ] **Performance Benchmarking** (25h) - Comparación vs S&P500, BTC
- [ ] **Risk Questionnaire** (15h) - Cuestionario de perfil de riesgo
- [ ] **Referral Program** (40h) - Referral bonuses para investors

### Largo Plazo (P3)
- [ ] **Custom Strategies** (80h) - Permitir estrategias personalizadas
- [ ] **Copy Trading** (90h) - Copiar otros investors exitosos
- [ ] **DeFi Integration** (120h) - Yield farming y staking

## Dependencias

- `@stripe/stripe-js` - Stripe payment integration
- `@stripe/react-stripe-js` - React Stripe components
- `zustand` - State management
- `axios` - HTTP client
- `lucide-react` - Icons
- `socket.io-client` - WebSocket client

## Documentación Relacionada

- **ET Specs:** No aplica (funcionalidad base)
- **User Stories:** US-INV-001 a US-INV-012
- **Backend API Docs:** `/docs/api/investment.md`
- **Trading Agents Docs:** `/docs/agents/trading-bots.md`
- **Stripe Integration:** `/docs/integrations/stripe.md`

---

**Última actualización:** 2026-01-25
**Autor:** Claude Opus 4.5
