# OQI-004: Análisis de Componentes Frontend - Cuentas de Inversión

**Módulo:** OQI-004 - Cuentas de Inversión
**Ubicación:** `apps/frontend/src/modules/investment/`
**Fecha:** 2026-01-25
**Status:** ANÁLISIS COMPLETO

---

## 1. PÁGINAS (8 Archivos)

| Página | Ruta | Líneas | Estado | Descripción | Funcionalidades Clave |
|--------|------|--------|--------|-------------|----------------------|
| **Investment.tsx** | `pages/Investment.tsx` | 100 | ✅ Funcional | Dashboard principal del módulo - landing page de inversiones | Listado de productos disponibles (Atlas, Orion, Nova), botón "Abrir Nueva Cuenta", aviso de riesgo |
| **Portfolio.tsx** | `pages/Portfolio.tsx` | 346 | ✅ Funcional | Vista del portafolio del usuario con resumen de inversiones | Resumen de cuentas activas, stats totales (balance, ganancias), listado de cuentas con P&L, acciones rápidas |
| **Products.tsx** | `pages/Products.tsx` | 276 | ✅ Funcional | Catálogo de productos de inversión con filtrado por riesgo | Filtro por perfil de riesgo (conservador/moderado/agresivo), tarjetas de productos, nav a detalles |
| **ProductDetail.tsx** | `pages/ProductDetail.tsx` | 447 | ✅ Funcional | Detalles de un producto específico + formulario de inversión | Gráfico de rendimiento histórico (canvas), selector de monto de inversión, botones de inversión rápida, características del producto |
| **AccountDetail.tsx** | `pages/AccountDetail.tsx` | 608 | ✅ Funcional | Vista detallada de una cuenta de inversión individual | Tabs (resumen/transacciones/distribuciones/depósito/retiro), gráfico de rendimiento, componentes DepositForm y WithdrawForm |
| **Withdrawals.tsx** | `pages/Withdrawals.tsx` | 269 | ✅ Funcional | Historial de solicitudes de retiro con filtrado de estado | Vista de tarjetas de retiros, filtro por estado (pending/approved/processing/completed/rejected), stats de retiros |
| **Transactions.tsx** | `pages/Transactions.tsx` | 328 | ✅ Funcional | Historial global de transacciones filtrable por tipo y cuenta | Filtro por tipo (depósito/retiro/distribución/comisión), selector de cuenta, filtro de fecha, tabla de transacciones |
| **Reports.tsx** | `pages/Reports.tsx` | 422 | ✅ Funcional | Reportes y análisis de inversiones con gráficos | Gráfico de distribución (donut), gráfico de rendimiento por cuenta (barras), tabla detalle, export JSON |

---

## 2. COMPONENTES (6 Archivos)

| Componente | Ruta | Líneas | Tipo | Props | Estado | Descripción |
|------------|------|--------|------|-------|--------|-------------|
| **DepositForm** | `components/DepositForm.tsx` | 318 | Form | `accounts`, `onSuccess?`, `onCancel?` | ✅ Prod | Formulario de depósito con integración Stripe (cardElement), selección de cuenta, monto, confirmación de pago |
| **WithdrawForm** | `components/WithdrawForm.tsx` | 471 | Form | `accounts`, `onSuccess?`, `onCancel?` | ✅ Prod | Formulario de retiro 2-paso (detalles/verificación), método (bank/crypto), 2FA, límite diario $10k, mínimo $50 |
| **AccountSummaryCard** | `components/AccountSummaryCard.tsx` | 286 | Card | `account`, `onViewDetails?`, `onManageSettings?`, `compact?`, `showActions?` | ✅ Prod | Tarjeta resumen de cuenta con balance, ganancias totales, retorno mensual, estado, riesgo, distribución próxima |
| **ProductComparisonTable** | `components/ProductComparisonTable.tsx` | 396 | Table | `products`, `selectedProductId?`, `onSelectProduct?`, `onViewDetails?`, `compact?` | ✅ Prod | Tabla comparativa de productos por (Returns, Fees, Terms, Strategies), expandible, seleccionable, 2 layouts |
| **PerformanceWidgetChart** | `components/PerformanceWidgetChart.tsx` | 238 | Chart | `data`, `period?`, `height?`, `showTrend?`, `showValue?`, `lineColor?`, `fillColor?`, `compact?`, `onClick?` | ✅ Prod | Gráfico sparkline con canvas, indica tendencia (up/down/neutral), relleno dinámico, compacto u expansión |
| **AccountSettingsPanel** | `components/AccountSettingsPanel.tsx` | 524 | Panel | `account`, `settings`, `onSave?`, `onCancel?`, `isLoading?`, `compact?` | ✅ Prod | Panel de configuración de cuenta (distribución, auto-reinversión, notificaciones, alertas riesgo, retiros), tabs, form state |

---

## 3. ANÁLISIS ESTRUCTURAL

### 3.1 Jerarquía de Componentes

```
App
├── Investment (landing page)
│   └── Product cards
├── Portfolio (lista de cuentas)
│   ├── AccountRow (iterado)
│   ├── StatCard
│   └── Quick Actions
├── Products (catálogo)
│   ├── RiskBadge
│   ├── ProductCard (iterado)
│   └── Filters
├── ProductDetail (detalles + inversión)
│   ├── PerformanceChart (canvas)
│   ├── StatCard
│   ├── AccountSettingsPanel (sidebar)
│   └── InvestForm (button only)
├── AccountDetail (cuenta individual)
│   ├── StatCard
│   ├── Tabs (5 opciones)
│   ├── PerformanceChart
│   ├── TransactionRow
│   ├── DistributionRow
│   ├── DepositForm (embedded)
│   └── WithdrawForm (embedded)
├── Withdrawals (historial retiros)
│   ├── WithdrawalCard
│   └── Filters
├── Transactions (historial transacciones)
│   ├── TransactionRow
│   ├── Filters
│   └── Stats
└── Reports (análisis)
    ├── AllocationChart (donut canvas)
    ├── PerformanceBarChart
    └── Table
```

### 3.2 Flujos de Datos

**Flujo Depósito:**
```
Investment.tsx → ProductDetail.tsx → DepositForm.tsx
                                   → (Stripe API)
                                   → /api/v1/payments/wallet/deposit
                                   → AccountDetail.tsx
```

**Flujo Retiro:**
```
Portfolio.tsx → AccountDetail.tsx → WithdrawForm.tsx
                                  → /api/v1/investment/accounts/{id}/withdraw
                                  → Withdrawals.tsx
```

**Flujo Visualización:**
```
Portfolio.tsx → AccountDetail.tsx → [Tabs]
                                  → Transactions.tsx (si "Ver todos")
                                  → Reports.tsx (si "Reportes")
```

### 3.3 APIs Consumidas

| Endpoint | Método | Componente | Estado |
|----------|--------|-----------|--------|
| `/api/v1/investment/accounts/summary` | GET | Portfolio.tsx | ✅ Activo |
| `/api/v1/investment/products` | GET | Products.tsx | ✅ Activo |
| `/api/v1/investment/products/{id}` | GET | ProductDetail.tsx | ✅ Activo |
| `/api/v1/investment/products/{id}/performance` | GET | ProductDetail.tsx | ✅ Activo |
| `/api/v1/investment/accounts/{id}` | GET | AccountDetail.tsx | ✅ Activo |
| `/api/v1/investment/accounts/{id}/transactions` | GET | AccountDetail.tsx, Transactions.tsx | ✅ Activo |
| `/api/v1/investment/accounts/{id}/withdrawals` | GET | Withdrawals.tsx | ✅ Activo |
| `/api/v1/investment/accounts/{id}/deposit` | POST | DepositForm.tsx | ✅ Activo |
| `/api/v1/investment/accounts/{id}/withdraw` | POST | WithdrawForm.tsx | ✅ Activo |
| `/api/v1/payments/wallet/deposit` | POST | DepositForm.tsx | ✅ Activo |

### 3.4 Librerías y Dependencias

| Librería | Uso | Versión | Status |
|----------|-----|---------|--------|
| `react` | Core | 18.2.0 | ✅ |
| `react-router-dom` | Routing | Actuales | ✅ |
| `lucide-react` | Iconos | Actuales | ✅ |
| `@stripe/react-stripe-js` | Pagos | Actuales | ✅ |
| `@stripe/stripe-js` | Pagos | Actuales | ✅ |
| `react-hook-form` | Forms | Actuales | ✅ |
| Canvas API | Gráficos | Nativa | ✅ |

---

## 4. TIPOS DE DATOS DEFINIDOS

### 4.1 Investment Account
```typescript
interface InvestmentAccount {
  id: string;
  productId: string;
  product: { code: string; name: string; riskProfile: string };
  status: 'active' | 'suspended' | 'closed';
  balance: number;
  initialInvestment: number;
  totalDeposited: number;
  totalWithdrawn: number;
  totalEarnings: number;
  unrealizedPnl: number;
  unrealizedPnlPercent: number;
  openedAt: string;
}
```

### 4.2 Account Summary
```typescript
interface AccountSummary {
  totalBalance: number;
  totalEarnings: number;
  totalDeposited: number;
  totalWithdrawn: number;
  overallReturn: number;
  overallReturnPercent: number;
  accounts: InvestmentAccount[];
}
```

### 4.3 Investment Product
```typescript
interface InvestmentProduct {
  id: string;
  code: string;
  name: string;
  description: string;
  riskProfile: 'conservative' | 'moderate' | 'aggressive';
  targetReturnMin: number;
  targetReturnMax: number;
  maxDrawdown: number;
  minInvestment: number;
  managementFee: number;
  performanceFee: number;
  features: string[];
  strategy: string;
  assets: string[];
  tradingFrequency: string;
}
```

### 4.4 Transaction
```typescript
interface Transaction {
  id: string;
  type: 'deposit' | 'withdrawal' | 'distribution' | 'fee' | 'adjustment';
  amount: number;
  status: 'pending' | 'completed' | 'failed' | 'cancelled';
  createdAt: string;
  description?: string;
  balanceAfter: number;
}
```

### 4.5 Withdrawal
```typescript
interface Withdrawal {
  id: string;
  amount: number;
  status: 'pending' | 'approved' | 'processing' | 'completed' | 'rejected';
  requestedAt: string;
  processedAt?: string;
  bankInfo?: { bankName: string; accountLast4: string };
  cryptoInfo?: { network: string; addressLast8: string };
  rejectionReason?: string;
}
```

### 4.6 Account Settings
```typescript
interface AccountSettings {
  distributionFrequency: 'weekly' | 'biweekly' | 'monthly' | 'quarterly';
  autoReinvest: boolean;
  reinvestPercentage: number;
  notifications: {
    distributionAlert: boolean;
    performanceAlert: boolean;
    riskAlert: boolean;
    newsAlert: boolean;
  };
  riskAlerts: {
    enabled: boolean;
    drawdownThreshold: number;
    dailyLossThreshold: number;
  };
  withdrawalSettings: {
    preferredMethod: 'bank' | 'crypto' | 'wallet';
    autoWithdraw: boolean;
    autoWithdrawThreshold: number;
  };
}
```

---

## 5. PATRONES UTILIZADOS

### 5.1 Componentes Funcionales con Hooks
- **useState** para manejo de estado local (loading, error, activeTab, filters)
- **useEffect** para efectos secundarios (cargar datos, dibujar canvas)
- **useRef** para referencias a canvas en gráficos
- **useMemo** para optimización de cálculos costosos

### 5.2 Custom Hooks (Implícitos)
- `investmentService.getAccountSummary()`
- `investmentService.getProductById(productId)`
- `investmentService.getProductPerformance(productId, period)`
- `investmentService.getAccountById(accountId)`
- `investmentService.getTransactions(accountId, filters)`
- `investmentService.getWithdrawals(status?)`
- `investmentService.createAccount(productId, amount)`
- `investmentService.getUserAccounts()`

### 5.3 Patrones de Formularios
- **React Hook Form** para validación
- **Stripe CardElement** para pagos
- **Two-step verification** en WithdrawForm

### 5.4 Patrones de Gráficos
- **Canvas API** para dibujo de líneas y áreas
- **Dip pixel ratio** (DPR) para retina displays
- **Gradient fills** con semitransparencia

### 5.5 Patrones de Estado
- Loading states globales
- Error handling con mensajes
- Success states con confirmación visual
- Optimistic updates (parcial)

---

## 6. CARACTERÍSTICAS DESTACADAS

| Característica | Componentes | Descripción |
|---|---|---|
| **Stripe Integration** | DepositForm | CardElement embebido, confirmCardPayment |
| **2FA/Verification** | WithdrawForm | Step-by-step flow con código verificación |
| **Canvas Charts** | ProductDetail, AccountDetail, Reports, PerformanceWidgetChart | Gráficos de rendimiento custom |
| **Tab Navigation** | AccountDetail | 5 tabs: Overview, Transactions, Distributions, Deposit, Withdraw |
| **Dynamic Forms** | WithdrawForm | Campos condicionales (bank vs crypto) |
| **Comparison Tables** | ProductComparisonTable | Expandible, seleccionable, 2 layouts |
| **Risk Visualization** | Componentes varios | Badges, colores (verde/amarillo/rojo) |
| **Localization** | Componentes varios | Formato de fecha/moneda por locale |
| **Dark Mode Ready** | Todos | Clases Tailwind dark: |
| **Responsive Design** | Todos | Grid/Flex con breakpoints md, lg |

---

## 7. ESTADOS Y TRANSICIONES

### 7.1 Account State Machine
```
PENDING → ACTIVE ↔ SUSPENDED
                    ↓
                 CLOSED
```

### 7.2 Withdrawal State Machine
```
PENDING → APPROVED → PROCESSING → COMPLETED
    ↓         ↓          ↓
  REJECTED  REJECTED  REJECTED
```

### 7.3 Transaction State Machine
```
PENDING → COMPLETED
   ↓
 FAILED    CANCELLED
```

---

## 8. VALIDACIONES

### 8.1 DepositForm
- Monto mínimo: $10
- Monto máximo: $100,000
- Incremento: $0.01
- Token JWT requerido

### 8.2 WithdrawForm
- Monto mínimo: $50
- Monto máximo: Balance o $10k (lo que sea menor)
- Incremento: $0.01
- Verificación 2FA requerida
- Límite diario: $10,000

### 8.3 ProductDetail Investment
- Monto >= minInvestment del producto
- Token JWT requerido
- Producto debe existir

---

## 9. ACCESIBILIDAD Y UX

| Aspecto | Implementación |
|--------|-----------------|
| Loading States | Spinners, disabled buttons |
| Error States | Mensajes en rojo, iconos AlertCircle |
| Success States | Checkmark, mensaje confirmación |
| Empty States | Iconos emoji grandes, CTAs claros |
| Keyboard Nav | Links y buttons nativos |
| ARIA Labels | Labels en formularios |
| Color Contrast | Tailwind dark: para legibilidad |
| Responsive | Grid/Flex, responsive typography |

---

## 10. RESUMEN DE COBERTURA

| Elemento | Cantidad | Coverage |
|----------|----------|----------|
| Páginas | 8 | 100% |
| Componentes | 6 | 100% |
| Tipos TypeScript | 6+ | 100% |
| Endpoints API | 10 | 100% |
| Líneas de Código | ~3,500 | Total |
| Archivos | 14 | Total |

---

**Fecha de Análisis:** 2026-01-25
**Módulo OQI-004 Status:** 35% Implementado
**Análisis Realizado por:** Claude Code
**Próximo Paso:** Análisis de Contratos API y Gaps