trading-platform-frontend-v2/src/modules/investment/OQI-004-ANALISIS-COMPONENTES.md

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

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

interface AccountSummary {
  totalBalance: number;
  totalEarnings: number;
  totalDeposited: number;
  totalWithdrawn: number;
  overallReturn: number;
  overallReturnPercent: number;
  accounts: InvestmentAccount[];
}

4.3 Investment Product

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

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

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

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