Business Services - Servicios de Negocio

Los Business Services implementan la lógica de negocio específica de SwapBits: trading, verificación de identidad y administración.

📈 Exchange Service

Trading de Criptomonedas

Puerto: 3008
Responsabilidad: Integración con exchanges para trading
Tecnología: NestJS + Bybit API

Propósito

El Exchange Service permite a los usuarios hacer trading de criptomonedas mediante integración con exchanges externos (principalmente Bybit).

¿Qué hace exactamente?

1. Obtener Market Data en Tiempo Real

Datos que proporciona:

Precio actual (last price)
Bid/Ask (mejor oferta compra/venta)
Volumen 24h
Cambio 24h (%)
Máximo/Mínimo 24h

2. Crear Órdenes de Trading

Orden Market (compra/venta inmediata):

Orden Limit (precio específico):

3. Order Book (Libro de Órdenes)

Estructura del Order Book:

{
  "symbol": "BTCUSDT",
  "bids": [
    {"price": "45000.00", "quantity": "1.5"},
    {"price": "44999.50", "quantity": "2.3"},
    ...
  ],
  "asks": [
    {"price": "45001.00", "quantity": "0.8"},
    {"price": "45002.50", "quantity": "1.2"},
    ...
  ]
}

4. Gestión de Órdenes Activas

Responsabilidades Detalladas

Acción	Descripción
Market Data	Precios, volúmenes, tickers en tiempo real
Order Placement	Crear órdenes market, limit, stop-loss
Order Management	Listar, cancelar, modificar órdenes
Order Book	Obtener libro de órdenes actual
Trade History	Historial de trades ejecutados
Balance Management	Sincronizar balances con exchange
Webhooks	Recibir eventos de Bybit

Endpoints Principales

GET    /exchange/tickers             - Listar todos los tickers
GET    /exchange/ticker/:symbol      - Obtener ticker específico
GET    /exchange/orderbook/:symbol   - Order book
POST   /exchange/order/market        - Crear orden market
POST   /exchange/order/limit         - Crear orden limit
POST   /exchange/order/stop          - Crear stop-loss
GET    /exchange/orders              - Listar órdenes activas
GET    /exchange/orders/:id          - Obtener orden específica
DELETE /exchange/orders/:id          - Cancelar orden
GET    /exchange/trades              - Historial de trades
GET    /exchange/balance             - Balance en exchange

Integración con Bybit

class BybitAdapter {
  private ws: WebSocket;
  
  async subscribeMarketData(symbols: string[]) {
    this.ws.send({
      op: 'subscribe',
      args: symbols.map(s => `tickers.${s}`)
    });
  }
  
  async placeOrder(order: CreateOrderDto) {
    return await this.http.post('/v5/order/create', {
      category: 'spot',
      symbol: order.symbol,
      side: order.side,
      orderType: order.type,
      qty: order.quantity,
      price: order.price
    });
  }
}

Consideraciones Importantes

Rate Limiting de Bybit:

10 requests/segundo para market data
5 requests/segundo para órdenes
Exchange Service maneja el throttling

Sincronización de Balances:

Los balances del exchange NO son los mismos que las wallets propias
Usuario debe transferir crypto a exchange para tradear
Proceso: Wallet → Exchange (deposit) → Trade → Exchange → Wallet (withdraw)

🆔 KYC Service

Verificación de Identidad

Puerto: 3006
Responsabilidad: Know Your Customer (KYC/AML)
Tecnología: NestJS + Proveedores KYC

Propósito

El KYC Service maneja todo el proceso de verificación de identidad para cumplir con regulaciones y prevenir fraude.

¿Qué hace exactamente?

1. Flujo Completo de Verificación

Estados posibles:

not_started: Usuario no ha iniciado KYC
in_progress: Usuario está llenando formulario
under_review: Documentos siendo revisados
approved: Verificación aprobada
rejected: Verificación rechazada (con razón)

2. Iniciar Sesión KYC

3. Documentos Requeridos

Nivel 1 (Básico):

✅ Nombre completo
✅ Fecha de nacimiento
✅ País de residencia
✅ Selfie

Límites: $1,000 / día

Nivel 2 (Intermedio):

✅ Todo de Nivel 1
✅ Documento de identidad (ID/Pasaporte)
✅ Prueba de dirección (recibo de servicios)

Límites: $10,000 / día

Nivel 3 (Avanzado):

✅ Todo de Nivel 2
✅ Información financiera
✅ Fuente de fondos
✅ Video verificación

Límites: Ilimitado

4. Validaciones Automáticas

async validateKYC(userId: string): Promise<boolean> {
  const kyc = await this.getKYCStatus(userId);
  
  // Verificar estado
  if (kyc.status !== 'approved') return false;
  
  // Verificar que no haya expirado (algunos países requieren renovación anual)
  if (kyc.expiresAt && new Date() > kyc.expiresAt) return false;
  
  // Verificar que no esté en lista negra
  if (await this.isBlacklisted(kyc.documentNumber)) return false;
  
  return true;
}

5. Integración con Guards

// En otros servicios
@UseGuards(JwtAuthGuard, KycGuard)
@Post('withdraw')
async withdraw(@User() user, @Body() dto: WithdrawDto) {
  // Solo llega aquí si KYC está aprobado
}

Responsabilidades Detalladas

Acción	Descripción
Start KYC	Iniciar sesión de verificación
Submit Documents	Subir documentos requeridos
Check Status	Consultar estado de verificación
Webhook Processing	Recibir resultados de proveedores
Level Management	Gestionar niveles de verificación
AML Screening	Verificar contra listas negras
Document Storage	Almacenar documentos de forma segura

Endpoints Principales

POST   /kyc/start              - Iniciar proceso KYC
GET    /kyc/status             - Consultar estado
POST   /kyc/documents          - Subir documento
GET    /kyc/documents          - Listar documentos subidos
POST   /kyc/webhooks/:provider - Webhook de proveedor
GET    /kyc/levels             - Información de niveles
POST   /kyc/resend-link        - Reenviar link de verificación

Proveedores Soportados

Onfido (Principal):

Verificación de identidad automática
Detección de vida (liveness)
Verificación de documentos

Sumsub (Alternativo):

Verificación de identidad
AML screening
Monitoreo continuo

Consideraciones de Seguridad

// Los documentos se almacenan encriptados
const encryptedDocument = await this.encrypt(documentBuffer);
await this.s3.upload({
  Bucket: 'swapbits-kyc-docs',
  Key: `${userId}/${documentId}`,
  Body: encryptedDocument,
  ServerSideEncryption: 'AES256'
});

// Los documentos se auto-eliminan después de 7 años (requisito legal)
const expirationDate = new Date();
expirationDate.setFullYear(expirationDate.getFullYear() + 7);

🛡️ Admin Service

Panel de Administración

Puerto: 3001 (Backend), 3000 (Frontend)
Responsabilidad: Administración completa del sistema
Tecnología: NestJS (Backend) + React (Frontend)

Propósito

El Admin Service es el centro de control de SwapBits. Permite a administradores gestionar usuarios, revisar transacciones, moderar chat y ver analytics.

Arquitectura

¿Qué hace exactamente?

1. Dashboard Analytics en Tiempo Real

Datos mostrados:

Total de usuarios registrados
Usuarios activos (últimos 30 días)
Wallets creadas por blockchain
Transacciones (pending/confirmed/failed)
Volumen de trading (USD)
Depósitos/Retiros pendientes
Tickets de soporte abiertos

Actualización: Vía WebSocket cada 10 segundos

2. Gestión de Usuarios

Acciones disponibles:

Buscar usuarios por email, username, ID
Ver perfil completo (datos personales, KYC, wallets)
Suspender cuenta (con razón)
Activar cuenta suspendida
Aprobar/Rechazar KYC manualmente
Ver historial de transacciones
Ver log de auditoría del usuario
Cerrar sesiones remotamente

3. Sistema de Chat Bidireccional

Características del chat:

Threads: Conversaciones organizadas por usuario
Estados: open, assigned, resolved
Asignación: Asignar conversación a admin específico
Typing indicators: "Admin está escribiendo..."
Historial: Ver toda la conversación
Notificaciones: Sonido cuando llega mensaje nuevo

4. Sistema de Logs en Tiempo Real

// Los logs se muestran en tiempo real vía WebSocket
interface LogEntry {
  timestamp: Date;
  level: 'info' | 'warn' | 'error';
  service: 'auth' | 'user' | 'wallet' | 'bank' | 'exchange';
  userId?: string;
  action: string;
  message: string;
  metadata?: any;
}

Filtros disponibles:

Por servicio
Por nivel (info/warn/error)
Por usuario
Por acción
Por rango de fechas

5. Gestión de Transacciones

Vista de admin sobre transacciones:

Transacciones que requieren revisión:

Montos muy altos (> $10,000)
Múltiples transacciones en poco tiempo
Transacciones a addresses en blacklist
Transacciones desde IPs sospechosas

Responsabilidades Detalladas

Acción	Descripción
Analytics	Dashboard con métricas en tiempo real
User Management	CRUD y gestión de usuarios
Chat Support	Chat bidireccional con usuarios
Logs Viewing	Ver logs de todos los servicios
Transaction Review	Revisar y aprobar transacciones
KYC Review	Revisar verificaciones manualmente
System Configuration	Configurar parámetros del sistema
Audit Trail	Ver historial de acciones admin

Endpoints Backend

GET    /admin/dashboard           - Métricas del dashboard
GET    /admin/users               - Listar usuarios
GET    /admin/users/:id           - Ver usuario específico
PUT    /admin/users/:id/suspend   - Suspender usuario
PUT    /admin/users/:id/activate  - Activar usuario
GET    /admin/transactions        - Listar transacciones
PUT    /admin/transactions/:id    - Actualizar transacción
GET    /admin/kyc-pending         - KYCs pendientes
PUT    /admin/kyc/:id/approve     - Aprobar KYC
PUT    /admin/kyc/:id/reject      - Rechazar KYC
GET    /admin/logs                - Ver logs
WS     /admin/ws                  - WebSocket admin

Seguridad del Admin

// Todos los endpoints requieren rol ADMIN
@UseGuards(JwtAuthGuard, RolesGuard)
@Roles('ADMIN', 'SUPER_ADMIN')
export class AdminController {
  // ...
}

// Autenticación Multi-Factor obligatoria
@UseGuards(WebAuthnGuard, TotpGuard)
async sensitiveAction() {
  // Acciones críticas requieren 2FA
}

// Todas las acciones se auditan
@UseInterceptors(AdminAuditInterceptor)
async suspendUser(@Param('id') userId: string) {
  // Se registra: quién, cuándo, qué, por qué
}

Frontend (React)

Componentes principales:

<Dashboard />: Métricas y gráficas
<UsersTable />: Lista de usuarios con búsqueda
<UserDetails />: Perfil completo de usuario
<ChatPanel />: Sistema de chat
<LogsViewer />: Visor de logs en tiempo real
<TransactionsReview />: Revisión de transacciones
<KycQueue />: Cola de KYCs pendientes

Tecnologías:

React + TypeScript
Redux para estado global
Socket.io-client para WebSocket
Recharts para gráficas
Ant Design para UI

Comunicación Entre Business Services

Resumen

Servicio	Puerto	Función Principal
Exchange Service	3008	Trading con Bybit
KYC Service	3006	Verificación de identidad
Admin Service	3001/3000	Panel de administración

Para Desarrolladores

Business Services implementan la lógica de negocio específica. A diferencia de Core Services (que son genéricos), estos servicios son únicos de SwapBits.

Si necesitas agregar una nueva feature de negocio, probablemente va en uno de estos servicios o necesitas crear un nuevo Business Service.

Patrón común: Business Services orquestan Core Services. Ejemplo: Exchange Service usa Wallet Service para verificar balances.

📈 Exchange Service​

Trading de Criptomonedas

Propósito​

¿Qué hace exactamente?​

1. Obtener Market Data en Tiempo Real​

2. Crear Órdenes de Trading​

3. Order Book (Libro de Órdenes)​

4. Gestión de Órdenes Activas​

Responsabilidades Detalladas​

Endpoints Principales​

Integración con Bybit​

Consideraciones Importantes​

🆔 KYC Service​

Verificación de Identidad

Propósito​

¿Qué hace exactamente?​

1. Flujo Completo de Verificación​

2. Iniciar Sesión KYC​

3. Documentos Requeridos​

4. Validaciones Automáticas​

5. Integración con Guards​

Responsabilidades Detalladas​

Endpoints Principales​

Proveedores Soportados​

Consideraciones de Seguridad​

🛡️ Admin Service​

Panel de Administración

Propósito​

Arquitectura​

¿Qué hace exactamente?​

1. Dashboard Analytics en Tiempo Real​

2. Gestión de Usuarios​

3. Sistema de Chat Bidireccional​

4. Sistema de Logs en Tiempo Real​

5. Gestión de Transacciones​

Responsabilidades Detalladas​

Endpoints Backend​

Seguridad del Admin​

Frontend (React)​

Comunicación Entre Business Services​

Resumen​

Para Desarrolladores

📈 Exchange Service

Propósito

¿Qué hace exactamente?

1. Obtener Market Data en Tiempo Real

2. Crear Órdenes de Trading

3. Order Book (Libro de Órdenes)

4. Gestión de Órdenes Activas

Responsabilidades Detalladas

Endpoints Principales

Integración con Bybit

Consideraciones Importantes

🆔 KYC Service

Propósito

¿Qué hace exactamente?

1. Flujo Completo de Verificación

2. Iniciar Sesión KYC

3. Documentos Requeridos

4. Validaciones Automáticas

5. Integración con Guards

Responsabilidades Detalladas

Endpoints Principales

Proveedores Soportados

Consideraciones de Seguridad

🛡️ Admin Service

Propósito

Arquitectura

¿Qué hace exactamente?

1. Dashboard Analytics en Tiempo Real

2. Gestión de Usuarios

3. Sistema de Chat Bidireccional

4. Sistema de Logs en Tiempo Real

5. Gestión de Transacciones

Responsabilidades Detalladas

Endpoints Backend

Seguridad del Admin

Frontend (React)

Comunicación Entre Business Services

Resumen