---
id: "RF-INV-002"
title: "Gestion de Cuentas de Inversion"
type: "Requirement"
status: "Done"
priority: "Alta"
epic: "OQI-004"
project: "trading-platform"
version: "1.0.0"
created_date: "2025-12-05"
updated_date: "2026-01-04"
---

# RF-INV-002: Gestión de Cuentas de Inversión

## Metadata

| Campo | Valor |
|-------|-------|
| **ID** | RF-INV-002 |
| **Épica** | OQI-004 - Cuentas de Inversión |
| **Tipo** | Requerimiento Funcional |
| **Prioridad** | P0 |
| **Story Points** | 10 |
| **Estado** | Aprobado |
| **Última actualización** | 2025-12-05 |

---

## Descripción

El sistema debe permitir a los usuarios abrir, gestionar y cerrar cuentas de inversión asociadas a los productos de trading automático (Atlas, Orion, Nova).

---

## Funcionalidades Requeridas

### RF-INV-002.1: Apertura de Cuenta

**Requisitos previos:**
- Usuario autenticado
- Email verificado
- Plan de suscripción compatible con el producto
- No tener cuenta activa en el mismo producto

**Proceso de apertura:**
1. Seleccionar producto de inversión
2. Revisar términos y condiciones
3. Aceptar disclaimers de riesgo
4. Confirmar apertura
5. Opcional: Proceder a depósito inicial

**Datos capturados:**
- Timestamp de aceptación de términos
- IP del usuario
- User Agent del navegador
- Versión de los términos aceptados

### RF-INV-002.2: Estados de Cuenta

| Estado | Descripción | Transiciones Permitidas |
|--------|-------------|-------------------------|
| `pending_deposit` | Cuenta creada, esperando primer depósito | → active, closed |
| `active` | Cuenta operativa con balance > 0 | → paused, closing |
| `paused` | Trading pausado temporalmente | → active, closing |
| `closing` | En proceso de cierre (liquidando posiciones) | → closed |
| `closed` | Cuenta cerrada permanentemente | (terminal) |

### RF-INV-002.3: Gestión de Cuenta Activa

El usuario debe poder:
- Ver balance actual y rendimiento
- Pausar/reanudar trading automático
- Ver historial de operaciones
- Realizar depósitos adicionales
- Solicitar retiros
- Iniciar proceso de cierre

### RF-INV-002.4: Cierre de Cuenta

**Proceso de cierre:**
1. Usuario solicita cierre
2. Sistema detiene nuevas operaciones
3. Sistema liquida posiciones abiertas (máx 24 horas)
4. Balance final se transfiere a wallet del usuario
5. Cuenta se marca como cerrada

**Restricciones:**
- No se puede cerrar si hay operaciones pendientes
- Se requiere confirmación por email
- Período de espera de 24 horas (cancelable)

---

## Modelo de Datos

### Entidad: InvestmentAccount

```typescript
interface InvestmentAccount {
  id: string;                    // UUID
  userId: string;                // FK a users
  productId: string;             // FK a investment_products

  status: AccountStatus;

  // Balances
  balance: number;               // Balance actual en USD
  totalDeposited: number;        // Total depositado históricamente
  totalWithdrawn: number;        // Total retirado históricamente
  totalProfit: number;           // Ganancias totales realizadas

  // Métricas
  highWaterMark: number;         // Máximo balance alcanzado
  currentDrawdown: number;       // Drawdown actual desde HWM

  // Timestamps
  openedAt: Date;
  firstDepositAt: Date | null;
  pausedAt: Date | null;
  closedAt: Date | null;

  // Términos
  termsAcceptedAt: Date;
  termsVersion: string;
  ipAddress: string;
  userAgent: string;
}
```

### Entidad: AccountSnapshot

```typescript
interface AccountSnapshot {
  id: string;
  accountId: string;

  balance: number;
  equity: number;               // Balance + P&L no realizado
  unrealizedPnl: number;

  openPositions: number;
  dailyTrades: number;
  dailyPnl: number;

  snapshotAt: Date;             // Se toma cada hora
}
```

---

## Reglas de Negocio

1. **RN-010**: Una cuenta solo puede estar asociada a un producto
2. **RN-011**: El balance de una cuenta nunca puede ser negativo
3. **RN-012**: Las pausas de cuenta se registran para auditoría
4. **RN-013**: El cierre de cuenta es irreversible después de 24 horas
5. **RN-014**: Los snapshots se toman cada hora para métricas de rendimiento
6. **RN-015**: El high water mark solo se actualiza cuando el balance supera el anterior

---

## Criterios de Aceptación

```gherkin
Escenario: Abrir cuenta exitosamente
DADO que el usuario tiene plan Pro
Y no tiene cuenta en Orion
CUANDO acepta los términos y condiciones de Orion
Y confirma la apertura
ENTONCES se crea una cuenta en estado "pending_deposit"
Y recibe email de confirmación
Y se redirige a la página de depósito

Escenario: Intento de cuenta duplicada
DADO que el usuario ya tiene cuenta activa en Atlas
CUANDO intenta abrir otra cuenta en Atlas
ENTONCES recibe error "Ya tienes una cuenta activa en Atlas"
Y se muestra link al dashboard de la cuenta existente

Escenario: Pausar trading
DADO que el usuario tiene cuenta activa
CUANDO hace click en "Pausar trading"
Y confirma la acción
ENTONCES el estado cambia a "paused"
Y se detienen nuevas operaciones
Y las posiciones abiertas se mantienen

Escenario: Cerrar cuenta
DADO que el usuario tiene cuenta activa
Y no tiene posiciones abiertas
CUANDO solicita cerrar la cuenta
ENTONCES recibe email de confirmación
Y tiene 24 horas para cancelar
DESPUÉS de 24 horas, la cuenta se cierra
Y el balance se transfiere a su wallet
```

---

## API Endpoints

| Método | Endpoint | Descripción |
|--------|----------|-------------|
| POST | /investment/accounts | Crear cuenta |
| GET | /investment/accounts | Listar cuentas del usuario |
| GET | /investment/accounts/:id | Detalle de cuenta |
| PATCH | /investment/accounts/:id/pause | Pausar trading |
| PATCH | /investment/accounts/:id/resume | Reanudar trading |
| POST | /investment/accounts/:id/close | Iniciar cierre |
| DELETE | /investment/accounts/:id/close | Cancelar cierre |

---

## Notificaciones

| Evento | Canal | Contenido |
|--------|-------|-----------|
| Cuenta abierta | Email | Confirmación + siguiente pasos |
| Primer depósito | Email + Push | Trading iniciado |
| Cuenta pausada | Email | Confirmación de pausa |
| Cierre solicitado | Email | Confirmación + instrucciones para cancelar |
| Cuenta cerrada | Email | Resumen final + balance transferido |

---

## Referencias

- [US-INV-002: Abrir cuenta](../historias-usuario/US-INV-002-abrir-cuenta.md)
- [ET-INV-001: Database](../especificaciones/ET-INV-001-database.md)

---

**Autor:** Requirements-Analyst
**Fecha:** 2025-12-05