trading-platform/docs/02-definicion-modulos/OQI-004-investment-accounts/requerimientos/RF-INV-002-cuentas.md

id	title	type	status	priority	epic	project	version	created_date	updated_date
RF-INV-002	Gestion de Cuentas de Inversion	Requirement	Done	Alta	OQI-004	trading-platform	1.0.0	2025-12-05	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

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

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

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
• ET-INV-001: Database

---

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