Descripción General del Sistema

Tabla de Contenidos

• Objetivo Comercial
• Los Tres Pilares del Sistema
• Alcance Funcional Completo
• Tipos de Usuarios y Roles (RBAC)
• Módulos del Backend (API)
• Módulos del Panel de Administración
• Funcionalidades del Frontend (Tienda Web)
• Stack Tecnológico
• Arquitectura del Sistema

---

Objetivo Comercial

Esta es una plataforma de comercio electrónico de nivel Enterprise diseñada para gestionar ventas tanto físicas (POS) como en línea para negocios minoristas con múltiples sucursales. El sistema es un ecosistema completo de tres aplicaciones integradas que funciona como un Mini-ERP Web.

Problemas Comerciales Clave Resueltos

Problema	Solución Implementada
Sobreventa de stock	Transacciones atómicas de base de datos + sistema de reservas con TTL configurable
Carritos abandonados bloquean inventario	Cron Job que libera reservas expiradas y cancela ventas PENDING automáticamente
Fraude en precios del carrito	El backend recalcula TODOS los precios, descuentos, impuestos y envíos desde cero. El frontend es un "cliente mentiroso"
Inconsistencia en ventas físicas vs online	Sistema de "Prioridad Física": las ventas POS pueden sobrescribir reservas en línea
Operación internacional	Motor multi-moneda con Geo-IP automático, precios en moneda local y snapshots del tipo de cambio en cada venta
Trazabilidad y auditoría	Log inmutable de cada movimiento de stock, cada acción administrativa y cada error del sistema
Escalabilidad	Validado para +100 usuarios simultáneos, +500 carritos activos, con control de concurrencia e idempotencia

---

Los Tres Pilares del Sistema

1. API Backend (Node.js + Express + PostgreSQL)

Servidor REST API central que maneja toda la lógica de negocio, operaciones de base de datos, integraciones externas y comunicaciones WebSocket en tiempo real.

• 42 servicios especializados (sale, stock, currency, discount, event, backup, etc.)
• 32 controladores de endpoints REST
• Cron Jobs automatizados (backups, limpieza de reservas expiradas)
• WebSocket (Socket.IO) para chat y notificaciones en tiempo real

2. Panel de Administración (Next.js + React + TypeScript)

Dashboard administrativo completo con 31 páginas para que el personal gestione toda la plataforma sin necesidad de un programador.

3. Web del Cliente / Frontend (Next.js + TailwindCSS)

Aplicación e-commerce orientada al cliente con 21 páginas, diseño premium con animaciones avanzadas, y experiencia de compra completa.

---

Alcance Funcional Completo

🏢 Gestión Multi-Sucursal

• ✅ Soporte para múltiples sucursales físicas con inventario independiente por cada una.
• ✅ Las sucursales se crean, editan y desactivan desde el panel de administración.
• ✅ Cada empleado puede ser asignado a una sucursal específica.
• ✅ Las ventas POS se realizan en el contexto de la sucursal activa del operador.
• ✅ Dashboard y reportes filtrables por sucursal.

💱 Multi-Moneda e Internacionalización

• ✅ Motor de monedas dinámico: Soporte para 20+ monedas (ARS, USD, EUR, MXN, BRL, CLP, COP, GBP, etc.).
• ✅ Detección automática por Geo-IP: Usa headers para determinar la moneda del visitante.
• ✅ Regla de conversión: Cliente local → moneda base configurada. Cliente extranjero → USD automáticamente.
• ✅ Tipo de cambio configurable: Desde el panel se define el exchangeRateToBase de cada moneda.
• ✅ PriceService inteligente: Busca primero un precio manual por moneda (ProductPrice), si no existe, convierte el basePrice usando el tipo de cambio.
• ✅ Snapshot inmutable: Al crear una venta, se guarda una "fotografía" del tipo de cambio exacto al momento de la transacción. Si el dólar cambia mañana, la contabilidad histórica no se altera.
• ✅ Impuestos condicionales: Solo se aplican si el comprador es del país de origen (validado por IP).

📊 Auditoría y Registro de Acciones

• ✅ AuditService: Registro centralizado de TODAS las acciones administrativas: quién, qué, cuándo, desde qué IP y diff técnico de los cambios.
• ✅ Log de errores (ErrorLog): Cada error del servidor se guarda con severidad (CRITICAL, HIGH, MEDIUM, LOW), stack trace, contexto JSON y referencia al usuario afectado.
• ✅ StockMovement inmutable: Cada movimiento de stock (venta, compra, transferencia, ajuste manual) se registra con tipo, cantidad, stock resultante y usuario responsable.
• ✅ Panel de exploración: Buscador integrado con filtros por administrador, tipo de acción y rango de fechas.

🚨 Sistema de Alertas

• ✅ Listado paginado de errores técnicos del servidor (ErrorLog).
• ✅ Filtros por severidad (CRITICAL, HIGH, MEDIUM, LOW) y rango de fechas.
• ✅ Diálogo de detalles con visualización de stack trace y contexto JSON.
• ✅ Acción de "Resolver" para seguimiento de incidentes.
• ✅ Alertas de stock bajo y stock crítico (umbrales configurables).

🔔 Sistema de Notificaciones

• ✅ Notificaciones en tiempo real via WebSocket (Socket.IO).
• ✅ Centro de notificaciones en el panel admin con campana, badge de no leídas y historial.
• ✅ Notificaciones por email: Confirmación de pedido, restablecimiento de contraseña, bienvenida.
• ✅ InAppNotificationService: Notificaciones persistentes en base de datos con estados de lectura.

👥 Sistema de Roles (RBAC)

• ✅ 4 roles jerarquizados: SUPER_ADMIN > ADMIN > EMPLOYEE > CLIENT.
• ✅ Control de acceso granular en cada endpoint del backend (authorize middleware).
• ✅ SUPER_ADMIN: Acceso total, configuración del sistema, no puede ser eliminado.
• ✅ ADMIN: Gestiona productos, ventas, stock, descuentos, proveedores. No puede crear otros ADMINs.
• ✅ EMPLOYEE: Opera el POS, ve inventario, atiende chat. No puede modificar productos ni precios.
• ✅ CLIENT: Navega, compra, gestiona su perfil y favoritos. Sin acceso al panel admin.

📦 Gestión de Productos con Variantes

• ✅ Modelo Producto-SKU: Cada producto base puede tener múltiples variantes (SKUs) con combinaciones de atributos (talle, color, material, etc.).
• ✅ Cada SKU tiene su propio stock, precio, código de barras y código interno.
• ✅ Opciones de variante dinámicas (VariantOption): Nombre y valor libres (ej: "Color: Rojo", "Talle: 42").
• ✅ Flags de visibilidad: isTrending, isRecommended, isNew para secciones destacadas.
• ✅ Diferenciación entre productos físicos y digitales.
• ✅ Carga de imágenes múltiples vía Cloudinary.
• ✅ Categorías jerárquicas (padre-hijo) con metadatos SEO.

📊 Gestión de Stock

• ✅ Inventario por sucursal (BranchInventory): Cada SKU tiene un stock independiente por cada sucursal.
• ✅ Ajustes manuales de stock con registro automático de StockMovement.
• ✅ Prioridad Física: Las ventas POS pueden sobrescribir reservas de compras en línea.
• ✅ Stock de seguridad web: Cuando el stock baja a cierto nivel, el producto se oculta del frontend para priorizar ventas en tienda.
• ✅ Alertas de stock bajo y crítico con umbrales configurables.
• ✅ Prevención de sobreventa configurable.

🔄 Transferencias de Stock entre Sucursales

• ✅ Crear transferencia con sucursal origen y destino.
• ✅ Agregar items (SKU + cantidad).
• ✅ Flujo de estados: PENDIENTE → COMPLETADA.
• ✅ Ajuste automático de stock en ambas sucursales al recibir.
• ✅ StockMovement registrada como TRANSFER_OUT y TRANSFER_IN.
• ✅ Auditoría completa de cada transferencia.

📈 Dashboard y Reportes

• ✅ Dashboard en tiempo real: KPIs (Ingresos brutos, cantidad de órdenes, ticket promedio).
• ✅ Gráficos interactivos con Recharts (ventas por día/semana/mes).
• ✅ Alertas de stock bajo visibles en el dashboard.
• ✅ Reportes exportables: Ventas por fecha/sucursal/empleado, productos más vendidos, valoración de inventario, historial de movimientos.
• ✅ Exportación PDF y CSV de tablas y datos.
• ✅ Rendimiento de empleados (cantidad de ventas procesadas).

🏭 Proveedores, Órdenes de Compra y Pagos

• ✅ CRUD de proveedores: Nombre, email, teléfono, dirección, notas.
• ✅ Vinculación SKU-Proveedor: Cada SKU puede tener un proveedor asignado con precio de costo (SupplierSKU).
• ✅ Órdenes de compra: Crear OC con selección de proveedor → agregar items (SKU + cantidad + costo) → flujo PENDIENTE → PAGADA → RECIBIDA.
• ✅ Recepción de mercadería: Al marcar una OC como recibida, el stock se incrementa automáticamente en la sucursal seleccionada con StockMovement de tipo PURCHASE.
• ✅ Pagos a proveedores: Registro de pagos parciales o totales con seguimiento del saldo pendiente.
• ✅ Historial de compras y pagos por proveedor.

🛒 Gestión de Ventas Avanzado

• ✅ Punto de Venta (POS): Búsqueda por nombre/escáner de código de barras, selección de variante, descuentos automáticos, múltiples métodos de pago.
• ✅ Checkout online multi-paso: Identificación → Entrega (envío o retiro) → Pago (MercadoPago, Stripe, PayPal) → Confirmación.
• ✅ Idempotencia: Previene ventas duplicadas verificando si se creó una venta similar recientemente.
• ✅ Concurrencia controlada: Transacciones atómicas Prisma ($transaction) para reservas de stock. El sistema deduce stock dentro de la misma transacción que crea la venta, evitando race conditions.
• ✅ Reservas con TTL: Las reservas de stock expiran automáticamente si el pago no se completa, liberando el inventario.
• ✅ Cleanup automático: Cron Job que busca ventas PENDING con más de 1 hora y las cancela, liberando reservas.
• ✅ Flujo de estados: PENDING → CONFIRMED → SHIPPED → DELIVERED / CANCELLED.
• ✅ Actualización de estado de envío (PREPARING, SHIPPED, DELIVERED).

🧾 Impresión de Facturas y Tickets

• ✅ Generación de facturas PDF con PDFKit: Incluye datos del negocio, items detallados, descuentos, impuestos y totales.
• ✅ Ticket térmico 80mm: Formato optimizado para impresoras térmicas de punto de venta.
• ✅ Descarga de factura desde el historial de compras del cliente y desde el panel admin.
• ✅ Generación automática de factura al confirmar una venta (configurable).

📱 QR y Código de Barras

• ✅ Código QR por producto (qr field en el modelo Product).
• ✅ Código de barras por SKU (barcode field en el modelo SKU).
• ✅ Exportación masiva a PDF: Controlador code-export que genera un PDF con grilla de etiquetas (3x7 = 21 por página) usando bwip-js.
• ✅ Soporte para QR Code y Code128.
• ✅ Filtros: exportar todos, por categoría o por selección manual.

👤 Gestión Avanzada de Usuarios

• ✅ Listar usuarios con filtro por rol, búsqueda y paginación.
• ✅ Cambiar roles de usuario (requiere permisos).
• ✅ Suspender/reactivar cuentas.
• ✅ Ver historial de compras del usuario.
• ✅ Asignar usuarios a sucursales.
• ✅ Panel lateral de detalles de usuario sin perder contexto.

🏷️ Gestión Avanzada de Productos y Categorías

• ✅ Formulario completo de producto con imágenes, variantes (SKUs), precios, stock por sucursal.
• ✅ Categorías jerárquicas con relaciones padre-hijo (árbol).
• ✅ Asignación de ícono y metadatos SEO por categoría.
• ✅ Flags de visibilidad: trending, recomendado, nuevo.
• ✅ Operaciones masivas de stock.

🎫 Cupones y Descuentos

• ✅ Cupones: Código alfanumérico (ej: "VERANO2026"), tipo PORCENTAJE o FIJO, con restricciones: monto mínimo, usos máximos por cliente, usos totales, fecha de expiración.
• ✅ Descuentos: Por producto, por categoría, globales, por método de pago, por cantidad mínima, por monto mínimo.
• ✅ Sistema de prioridad: Producto > Categoría > Global.
• ✅ Acumulables vs no acumulables: Control de si los descuentos se combinan.
• ✅ Protección contra solapamiento: El sistema valida que la suma total de descuentos no supere el 100%.

🎪 Sistema de Eventos

• ✅ Eventos temporales con fecha de inicio y fin que sobrescriben la configuración estándar del sistema.
• ✅ Un evento puede modificar: qué métodos de pago están habilitados, qué métodos de envío, si se aceptan cupones, si se aplican puntos, si se cobran impuestos.
• ✅ Contenido visual propio: Cada evento puede tener sus propios banners hero, marquee text, publicidades secundarias y mensajes promocionales.
• ✅ Descuentos propios del evento: Los descuentos vinculados a un evento tienen prioridad sobre los descuentos estándar.
• ✅ Regla de evento único activo: Solo un evento puede estar activo a la vez (se desactivan automáticamente los demás).

🚚 Envíos por Ciudad/Estado

• ✅ Zonas de envío configurables: Crear zonas (ej: "Centro", "Zona Sur", "Interior") con costo base.
• ✅ Niveles de precio por peso (opcional).
• ✅ Umbral de envío gratuito configurable.
• ✅ Activar/desactivar envíos globalmente.
• ✅ Selección de zona en el checkout con cálculo automático del costo.

💳 Pasarelas de Pago

• ✅ Payment Factory Pattern: PaymentFactory delega dinámicamente a MercadoPagoStrategy, PayPalStrategy o StripeStrategy.
• ✅ Activar/desactivar cada pasarela desde la configuración del panel.
• ✅ Webhooks seguros: Endpoints que reaccionan a notificaciones asíncronas de las pasarelas para mutar estados automáticamente.
• ✅ Soporte para pagos en efectivo, tarjeta y transferencia bancaria.
• ✅ Gestión de monedas asociadas a cada pasarela desde el panel de configuración de Gateways.

💬 Gestión de Comentarios y Reseñas

• ✅ Los clientes pueden dejar reseñas en productos con puntuación (rating).
• ✅ Panel de gestión de comentarios en el admin.
• ✅ Moderación de comentarios.

⭐ Sistema de Puntos de Lealtad

• ✅ Tasa de ganancia configurable: Cuántos puntos se ganan por unidad de moneda gastada.
• ✅ Tasa de canje configurable: Valor monetario de 1 punto.
• ✅ Canje en checkout: Los clientes pueden usar puntos como descuento parcial o total.
• ✅ Otorgamiento automático: processPostPaymentActions otorga puntos solo después de que la venta esté totalmente pagada.
• ✅ Historial de movimientos de puntos visible en el perfil del cliente.
• ✅ Interruptores globales para activar/desactivar el sistema entero.

📐 Sistema de Unidades de Medida

• ✅ Campo measurementUnit en el modelo Product: soporta "UNIDAD", "KG", "METRO", "LITRO" y más.
• ✅ Flag allowFractional para productos que se venden por peso o medida (permite cantidades como 0.5, 1.75).
• ✅ Unidades personalizables desde la configuración del sistema.

🎨 Edición de Contenido Web (CMS)

• ✅ Banners promocionales: Gestión del banner hero principal con imágenes y textos.
• ✅ Publicidades secundarias: Slots de publicidad configurables.
• ✅ Marquee text: Cinta deslizante personalizable en la parte superior de la web.
• ✅ Logo de la tienda: Subida y gestión del logo corporativo.
• ✅ Blog: Artículos SEO-friendly con editor completo, gestionados desde el panel admin.
• ✅ Horarios de apertura: Estandarizados para cada día de la semana.

💬 Sistema de Chat en Tiempo Real

• ✅ Chat cliente-administración: WebSocket bidireccional (Socket.IO) entre el frontend y el panel admin.
• ✅ CX Inbox estilo Zendesk: Los administradores y empleados ven una bandeja de chats entrantes con historial.
• ✅ Detección de presencia: El sistema detecta si hay un administrador o empleado en línea. Si no hay nadie, responde el bot automático.
• ✅ Respuestas automáticas gestionables: Desde el panel se gestionan las respuestas automáticas del chatbot (triggers, respuestas, prioridades).

📝 Gestión de Blog

• ✅ CRUD de artículos de blog desde el panel admin.
• ✅ Blog público en el frontend con diseño tipo magazine.
• ✅ SEO-friendly: títulos, descripciones meta, URLs amigables.

📥 Descarga de Tablas y PDFs

• ✅ Exportación de tablas: Descarga de datos en formato CSV desde los listados del panel.
• ✅ Generación de PDFs: Facturas, tickets, reportes de ventas, etiquetas de códigos de barras/QR.
• ✅ Exportación de reportes: Financieros, inventario, movimientos de stock.

💾 Backups Automáticos de Base de Datos

• ✅ BackupService: Extrae todas las tablas de la base de datos a formato JSON y las comprime en un archivo ZIP.
• ✅ Cron Job configurable: Se ejecuta diariamente a las 02:00 AM y verifica la frecuencia configurada (DAILY, WEEKLY, MONTHLY).
• ✅ Backup manual: Endpoint para generar y descargar un backup ZIP bajo demanda.
• ✅ Activar/desactivar backups automáticos desde la configuración del sistema.

⚙️ Configuración del Sistema

• ✅ Identidad del negocio: Nombre, email, teléfono, dirección, redes sociales.
• ✅ Horarios de atención por día de la semana.
• ✅ Unidades de medida: Personalizables ("Kg", "Mts", "Packs", etc.).
• ✅ Métodos de pago: Activar/desactivar efectivo, tarjeta, transferencia, MercadoPago, PayPal, Stripe.
• ✅ Moneda base y tipo de cambio con USD.
• ✅ Impuestos: Tasa global configurable (ej: 21%).
• ✅ Envíos: Activar/desactivar, umbral de envío gratuito, zonas de envío.
• ✅ Puntos de lealtad: Activar/desactivar, tasas de ganancia y canje.
• ✅ Sucursales: Activar/desactivar multi-sucursal.
• ✅ Control de stock: Umbrales de stock bajo y crítico, prevención de sobreventa, stock de seguridad web.
• ✅ Modo mantenimiento: Interruptor global que bloquea el acceso público a la tienda con página personalizada.

🛒 Punto de Venta (POS) - Sistema de Concurrencia

• ✅ Transacciones atómicas: prisma.$transaction() asegura que la reserva de stock y la creación de la venta ocurran en la misma transacción de base de datos, eliminando race conditions.
• ✅ Idempotencia: findRecentDuplicate() verifica si existe una venta idéntica creada en los últimos minutos, previniendo duplicados por doble-click o envíos repetidos.
• ✅ Prioridad Física: Las ventas POS pueden forzar la deducción de stock incluso si hay reservas en línea, asegurando que un cajero nunca se quede sin poder vender.
• ✅ Reservas con TTL: El stock se reserva temporalmente; si el pago no se completa, el StockCleanupService libera las unidades automáticamente.
• ✅ Cleanup automático: cleanupAbandonedSales() busca ventas PENDING con más de 1 hora y las cancela, liberando reservas y revertiendo stock.
• ✅ Validación bidireccional: Aunque el frontend envíe precios, el backend los ignora y recalcula todo (precios, descuentos, impuestos, envío) desde cero, eliminando cualquier posibilidad de fraude.

---

Tipos de Usuarios y Roles (RBAC)

Rol	Acceso	Capacidades Principales
SUPER_ADMIN	Total	Configuración del sistema, gestión de todos los usuarios, logs de auditoría, seguridad. No puede ser eliminado.
ADMIN	Alto	Productos, ventas, stock, descuentos, proveedores, reportes. No puede crear otros ADMINs.
EMPLOYEE	Limitado	POS, ver inventario, atender chat. No puede modificar productos ni precios.
CLIENT	Básico	Navegar, comprar, perfil, favoritos, puntos. Sin acceso al panel admin.

Matriz de Permisos

Módulo	SUPER_ADMIN	ADMIN	EMPLOYEE	CLIENT
Dashboard	✅	✅	✅	❌
Productos / Categorías	✅	✅	❌	❌
Ventas (Historial)	✅	✅	✅	❌
Punto de Venta (POS)	✅	✅	✅	❌
Inventario / Stock	✅	✅	❌	❌
Transferencias	✅	✅	❌	❌
Compras a Proveedores	✅	✅	❌	❌
Proveedores / Pagos	✅	✅	❌	❌
Descuentos / Cupones	✅	✅	❌	❌
Eventos Promocionales	✅	✅	❌	❌
Envíos / Shipping	✅	✅	❌	❌
Usuarios	✅	✅	❌	❌
Reportes	✅	✅	❌	❌
Contenido Web (CMS)	✅	✅	✅	❌
Chat / Soporte	✅	✅	✅	❌
Alertas del Sistema	✅	✅	❌	❌
Auditoría	✅	✅	❌	❌
Monedas / Gateways	✅	❌	❌	❌
Configuración General	✅	❌	❌	❌

---

Módulos del Backend (API)

Servicios Core (42 servicios)

Servicio	Propósito
sale.service.js	Procesamiento completo de ventas (1198 líneas): idempotencia, reservas, checkout, cleanup
price.service.js	Resolución de precios multi-moneda (manual → conversión automática)
currency.service.js	Motor multi-moneda con Geo-IP (20+ monedas)
discount.service.js	Motor de descuentos con prioridades y reglas de acumulación
event.service.js	Eventos temporales que sobrescriben configuración del sistema
stock-movement.service.js	Log inmutable de movimientos de stock
stock-transfer.service.js	Transferencias entre sucursales
stock-cleanup.service.js	Limpieza de reservas expiradas
payment.service.js + strategies	Factory Pattern para MercadoPago, PayPal, Stripe
payment-webhook.service.js	Procesamiento de webhooks asíncronos de pasarelas
invoice.service.js	Generación de facturas PDF
backup.service.js	Backups ZIP de toda la base de datos
audit.service.js	Registro de acciones administrativas
logger.service.js	Logging de errores con severidad
blog.service.js	Gestión de artículos de blog
chat.service.js	Sistema de chat en tiempo real
in-app-notification.service.js	Notificaciones persistentes en DB
notification.service.js	Notificaciones por email
coupon.service.js	Gestión y validación de cupones
shipping.service.js	Cálculo de costos de envío por zonas
purchase.service.js	Órdenes de compra a proveedores
supplier.service.js	Gestión de proveedores
supplier-payment.service.js	Pagos a proveedores
report.service.js	Generación de reportes
cart.service.js	Gestión del carrito server-side
branch.service.js	Gestión de sucursales
upload.service.js	Subida de archivos a Cloudinary
category.service.js	Categorías jerárquicas
product.service.js	CRUD de productos
sku.service.js	Gestión de variantes (SKUs)
comment.service.js	Reseñas y comentarios
user.service.js	Gestión de usuarios
auth.service.js	Autenticación JWT con refresh tokens

Controladores Especiales

Controlador	Propósito
code-export.controller.js	Exportación masiva de QR y códigos de barras a PDF (bwip-js)
webhook.controller.js	Recepción de webhooks de MercadoPago/Stripe/PayPal
auto-response.controller.js	CRUD de respuestas automáticas del chatbot
system.controller.js	Health checks y estado del sistema

Cron Jobs

Cron	Frecuencia	Función
backup.cron.js	Diario 02:00 AM	Verifica configuración (DAILY/WEEKLY/MONTHLY) y ejecuta backup ZIP
Stock Cleanup	Periódico	Libera reservas expiradas y cancela ventas abandonadas

---

Módulos del Panel de Administración

31 Páginas Organizadas por Secciones

Operaciones

• /management - Dashboard con KPIs en tiempo real
• /sales - Punto de Venta (POS) con búsqueda y escáner
• /management/sales - Historial de ventas con filtros y detalles
• /management/stock-control - Control de inventario por sucursal
• /management/transfers - Transferencias de stock entre sucursales
• /management/purchases - Órdenes de compra a proveedores
• /management/supplier-payments - Pagos a proveedores

Catálogo

• /management/products - Listado y gestión de productos
• /management/products/[id] - Detalle y edición de producto con SKUs
• /management/categories - Árbol jerárquico de categorías
• /management/suppliers - Gestión de proveedores

Comercial

• /management/discounts - Motor de descuentos con reglas
• /management/coupons - Gestión de cupones
• /management/events - Eventos promocionales temporales
• /management/shipping - Zonas y costos de envío

Gestión

• /management/users - Administración de usuarios y roles
• /management/comments - Moderación de comentarios
• /management/reports - Reportes y exportaciones

Contenido (CMS)

• /management/content - Banners, publicidades, marquee
• /management/content/blog - Artículos de blog
• /management/content/bot - Respuestas automáticas del chatbot
• /management/content/chat - Soporte en tiempo real (CX Inbox)

Sistema

• /management/settings - Configuración general del negocio
• /management/settings/branches - Gestión de sucursales
• /management/settings/currencies - Monedas y tipos de cambio
• /management/settings/gateways - Pasarelas de pago
• /management/system/alerts - Alertas y errores del sistema
• /management/system/audit - Log de auditoría

---

Funcionalidades del Frontend (Tienda Web)

Diseño y Experiencia Visual

• 🎨 Diseño premium alejado del minimalismo tradicional, con gradientes, glassmorphism y colores vibrantes.
• ✨ Animaciones avanzadas con Framer Motion en transiciones, hover effects y micro-interacciones.
• 🎵 Reproductor de música ambiental integrado en la experiencia.
• 📱 Diseño Mobile-First completamente responsivo.

Páginas y Funcionalidades (21 páginas)

Home (/)

• Banner Hero animado con slider promocional.
• Secciones de productos: Tendencia, Nuevos, Recomendados.
• Reseñas destacadas.
• Navegación con buscador en tiempo real.

Catálogo (/products)

• Filtro avanzado: Por categoría (árbol), rango de precio, atributos (talle, color), búsqueda.
• Ordenamiento: menor precio, mayor precio, más recientes.
• Grilla responsiva con animaciones de entrada.

Detalle de Producto (/products/[slug])

• Galería de imágenes con zoom.
• Selector de variantes (color, talle) con stock en tiempo real.
• Precio dinámico con descuento si aplica.
• Productos relacionados.

Favoritos (/favorites)

• Agregar/eliminar productos favoritos.
• Lista de deseos persistente.

Perfil de Usuario (/profile)

• Datos de perfil: Edición de información personal.
• Mis compras: Historial de pedidos con estados y descarga de factura PDF.
• Historial de puntos: Movimientos de puntos de lealtad con saldo actual.
• Comentarios y reseñas: Historial de reviews publicadas.

Carrito (/cart)

• Sincronización en tiempo real con el backend para evitar fraudes e inconsistencias.
• Canjear puntos de lealtad como descuento.
• Aplicar cupones de descuento.
• Seleccionar tipo de envío (retiro o domicilio con zona).
• Seleccionar tipo de pago (Stripe, PayPal, MercadoPago).
• Verificación de stock antes de proceder al checkout.

Checkout (/checkout)

• Flujo multi-paso: Identificación → Entrega → Pago → Confirmación.
• Páginas de resultado: /checkout/success, /checkout/failure, /checkout/pending.

Chat en Tiempo Real

• Widget flotante de chat con soporte estilo Zendesk.
• Detección inteligente: si hay un administrador/empleado en línea, se conecta; sino, responde el bot.
• Contextualización: envía al agente lo que el cliente tiene en su carrito.

Notificaciones

• Sistema de notificaciones in-app con historial.
• Actualizaciones de estado de pedidos en tiempo real.

Blog (/blog)

• Listado de artículos con diseño tipo magazine.
• Páginas de artículo individuales (/blog/[slug]).

FAQ (/faq)

• Preguntas frecuentes con acordeones interactivos.
• Buscador de dudas comunes.

Contacto (/contact)

• Localizador de sucursal más cercana: Utiliza la geolocalización en tiempo real del usuario para comparar coordenadas con las sucursales y mostrar la más cercana.
• Formulario de contacto.

About (/about)

• Página institucional del negocio.

Autenticación

• Login con email y contraseña.
• Registro de nuevo usuario.
• Recuperación de contraseña: Envío de email con link de restablecimiento.

Modo Mantenimiento y Errores

• Modo mantenimiento automático si no puede conectarse a la API o a la red.
• Sistema de avisos de errores amigable (no técnicos) para el usuario.
• Páginas de error con diseño visual consistente.

---

Stack Tecnológico

Backend API

Tecnología	Propósito
Node.js 20+	Entorno de ejecución
Express.js 5	Framework web
PostgreSQL 13+	Base de datos relacional
Prisma 7	ORM y constructor de consultas
Socket.IO 4	Comunicación en tiempo real
MercadoPago SDK	Pasarela de pagos LATAM
Stripe SDK	Pasarela de pagos global
PayPal SDK	Pasarela de pagos global
PDFKit	Generación de facturas PDF
bwip-js	Generación de QR y códigos de barras
Cloudinary	Almacenamiento de imágenes en la nube
Nodemailer	Envío de emails transaccionales
node-cron	Tareas programadas (backups, cleanup)
Archiver	Compresión ZIP para backups

Frontend y Admin

Tecnología	Propósito
Next.js 16	Framework de React (App Router)
React 19	Biblioteca de UI
TypeScript 5	JavaScript con tipado estático
TailwindCSS 4	Framework de CSS
Zustand 5	Gestión de estado del cliente
TanStack Query 5	Estado del servidor (cache, sync)
shadcn/ui	Componentes de interfaz pre-construidos
Recharts	Gráficos interactivos (dashboard)
Framer Motion	Animaciones avanzadas
react-to-print	Impresión de tickets térmicos
Zod	Validación de esquemas
React Hook Form	Gestión de formularios

---

Arquitectura del Sistema

flowchart TB
    subgraph Presentacion["Capa de Presentación"]
        AdminPanel["Panel Admin<br/>(Next.js 16 + React 19)"]
        FrontendWeb["Web Cliente<br/>(Next.js + TailwindCSS)"]
    end
    
    subgraph Aplicacion["Capa de Aplicación (42 Servicios)"]
        API["API Express.js<br/>Puerto 8000"]
        Socket["Servidor Socket.IO<br/>Tiempo Real"]
        Cron["Cron Jobs<br/>(Backups, Cleanup)"]
    end
    
    subgraph Datos["Capa de Datos"]
        PostgreSQL[("PostgreSQL<br/>30+ Tablas")]
    end
    
    subgraph Externos["Servicios Externos"]
        Cloudinary["Cloudinary<br/>(Imágenes)"]
        MercadoPago["MercadoPago<br/>(Pagos LATAM)"]
        Stripe["Stripe<br/>(Pagos Global)"]
        PayPal["PayPal<br/>(Pagos Global)"]
        SMTP["Servidor SMTP<br/>(Emails)"]
    end
    
    AdminPanel <-->|REST API + WS| API
    FrontendWeb <-->|REST API + WS| API
    
    API <-->|Prisma ORM| PostgreSQL
    
    API -->|Carga Imágenes| Cloudinary
    API -->|Procesa Pagos| MercadoPago
    API -->|Procesa Pagos| Stripe
    API -->|Procesa Pagos| PayPal
    API -->|Envía Emails| SMTP
    Cron -->|Backups ZIP| PostgreSQL

---

Siguientes Pasos

Para información detallada sobre aspectos específicos, consulte:

1. Arquitectura - Patrones de diseño, middleware pipeline.
2. Panel Admin - Guía completa del panel de administración.
3. Web Cliente - Documentación de la tienda.
4. Referencia API - Endpoints REST documentados.
5. Modelo de Datos - Esquema de base de datos y relaciones.
6. Autenticación y Seguridad - JWT, RBAC, medidas de seguridad.
7. Flujos y Diagramas - Diagramas de secuencia.
8. Despliegue - Guía de producción.

---

Última Actualización: 3 de marzo de 2026. Estado: ✅ COMPLETO, SEGURO Y LISTO PARA PRODUCCIÓN.