Carteras (Funds)

El modulo de Carteras (/admin/funds) es donde el equipo de gestion crea fondos, carga el rendimiento mensual, aprueba retiros y monitorea las posiciones de los inversores.

Crear una cartera#

Desde /admin/funds/new:

El status se guarda como active por default. Solo los fondos active son visibles para inversores en el marketplace (/invertir/carteras).

Marketplace visible al inversor#

Los inversores ven los fondos como planes de inversion estilo plataforma de inversiones:

• Card con nombre centrado, interes mensual y plazo como metricas grandes.
• Lista: deposito min, TIR anual, retorno capital, inversores, AUM.
• Boton "Invertir Ahora" prominente.
• Detalle del fondo con hero stat-boxes, performance historica con color- coding (verde/rojo por mes), y CTA de suscripcion.

Cierre mensual (CORE)#

Pasos en /admin/funds/[id] → tab Periodos:

1. Mes a cerrar: por default, el primer mes abierto. Generalmente el mes anterior al actual.
2. Rendimiento %: el % real generado por la cartera ese mes.
3. Click en Preview cierre → muestra cuantas posiciones se afectan y el total a distribuir, sin escribir nada.
4. Click en Confirmar y enviar emails → atomicamente:
   • Calcula TWR de cada posicion activa.
   • Escribe fund_ledger con tipo monthly_return.
   • Actualiza fund_positions.currentBalance y totalReturns.
   • Crea fund_reports por inversor.
   • Envia emails Resend con el reporte.
   • Inserta notifications y activity_feed.
   • Actualiza el AUM del fondo.
   • Marca el periodo como closed.
   • Logea en audit_log (fund.close_period).

Flujo de aprobacion de retiros#

Los retiros de carteras requieren aprobacion del admin antes de ejecutarse:

1. El inversor solicita desde /dashboard/cartera/retirar.
2. La solicitud aparece en /admin/approvals (bandeja unificada).
3. El admin aprueba o rechaza. Si rechaza, los fondos vuelven.
4. Las solicitudes aprobadas se ejecutan el dia 1 via Vercel Cron.
5. Una vez ejecutado, el admin puede marcar como paid con referencia externa (transferencia bancaria, tx hash, etc.).

Posiciones#

Tab Posiciones: tabla con todos los inversores del fondo, ordenada por saldo descendente. Por cada posicion ves saldo, depositado, ganado, retirado y status.

Acciones disponibles:

• Ajuste manual: bonificacion, cargo, subscripcion o retiro directo a una posicion, con audit logging.
• Cierre forzado de posicion (futuro).
• Re-envio del ultimo reporte (futuro).

Solicitudes pendientes#

Tab Solicitudes: muestra subscripciones y retiros pendientes que se procesan automaticamente el dia 1 de cada mes via Vercel Cron (/api/cron/process-fund-requests).

Movimientos#

Tab Movimientos: ledger global del fondo. Util para auditoria. Cada entry tiene type, amount, description, occurredAt.

Tipos de movimiento:

• subscription — deposito ejecutado
• redemption — retiro ejecutado
• monthly_return — rendimiento mensual
• fee — comision
• adjustment — ajuste manual del admin

Convenciones del rendimiento mensual#

• Rango razonable: 0% a 5% mensual.
• Negativos permitidos pero el sistema te avisa si bajas de 0%.
• No cierres dos veces el mismo mes; el sistema rechaza si ya esta closed.
• TWR se aplica a movimientos intra-mes.

Resend / emails#

Cada cierre dispara emails desde admin@vlozity.com (dominio verificado en Resend). Si Resend falla, el cierre no se rompe: el email_log queda como failed y el periodo se completa igual. El admin puede re-disparar emails despues.

Auditoria#

Todo cierre genera entradas en audit_log:

action: "fund.close_period"
entity: "fund_period"
entityId: <period uuid>
metadata: { fundId, returnPct, positionsAffected, totalDistributed }

Verlas en /admin/audit.

UX del inversor#

El inversor ve su cartera en multiples puntos:

• Sidebar: saldo total + rendimiento promedio + Depositar/Retirar.
• Dropdown de usuario: saldo + accesos rapidos.
• Dashboard hero: balance grande con twin cards (Cuenta de Inversion
  • Monto Invertido).
• Cartera: 4 KPIs + tabs (Evolucion, Periodos, Movimientos, Reportes).
• Movimientos: historial con iconos y colores, filtrable por tipo.