📘 Manual de Usuario Definitivo & Enciclopedia Operativa — Dulet Back Office & Duletia Ops
Versión: 5.0 (Manual Maestro Completo — Todos los Módulos)
Fecha de Publicación: Septiembre 2026
Audiencia: Administradores Master, Dirección General, Administradores, Operadores de Centros de Apoyo (CEDIS), Contabilidad, Almacén, Producción, Líderes y Socios Empresarios
Ecosistema: Dulet International Group (México) & Dulet Group LLC (USA)
Clasificación: Confidencial — Guía Oficial de Operación del Sistema
📑 Directorio General de Zonas y Módulos
- [Arquitectura del Sistema & Matriz de Seguridad de 7 Roles](#1-arquitectura-del-sistema--matriz-de-seguridad-de-7-roles)
- [Módulo 1: Dashboard Master — Panorama General](#2-módulo-1-dashboard-master--panorama-general)
- [Módulo 2: Mi Visión Empresario — Dashboard del Socio](#3-módulo-2-mi-visión-empresario--dashboard-del-socio)
- [Módulo 3: Mi Perfil y Seguridad](#4-módulo-3-mi-perfil-y-seguridad)
- [Módulo 4: Directorio de Líderes y Socios](#5-módulo-4-directorio-de-líderes-y-socios)
- [Módulo 5: Árbol de Red & Genealogía Dinámica](#6-módulo-5-árbol-de-red--genealogía-dinámica)
- [Módulo 6: Radiografía 360° & Análisis de Líder](#7-módulo-6-radiografía-360--análisis-de-líder)
- [Módulo 7: Módulo de Rescate y Alertas de Seguimiento](#8-módulo-7-módulo-de-rescate-y-alertas-de-seguimiento)
- [Módulo 8: Ventas, Caja y Registro de Pedidos](#9-módulo-8-ventas-caja-y-registro-de-pedidos)
- [Módulo 9: Calificaciones Mensuales y Pagos Adquiridos](#10-módulo-9-calificaciones-mensuales-y-pagos-adquiridos)
- [Módulo 10: Catálogo Maestro de Productos y Precios](#11-módulo-10-catálogo-maestro-de-productos-y-precios)
- [Módulo 11: Inventario General de Producto Terminado](#12-módulo-11-inventario-general-de-producto-terminado)
- [Módulo 12: Reportes de Movimientos y Kárdex](#13-módulo-12-reportes-de-movimientos-y-kárdex)
- [Módulo 13: Red de Centros de Apoyo Físicos (CEDIS 1 al 15)](#14-módulo-13-red-de-centros-de-apoyo-físicos-cedis-1-al-15)
- [Módulo 14: Centro Especial Virtual "Por Asignar" (#230) & Cola Multi-Caja](#15-módulo-14-centro-especial-virtual-por-asignar-230--cola-multi-caja)
- [Módulo 15: Facturación SAT CFDI 4.0 & Facturama](#16-módulo-15-facturación-sat-cfdi-40--facturama)
- [Módulo 16: Asistente de Sustitución en 2 Pasos & Cancelación Fiscal](#17-módulo-16-asistente-de-sustitución-en-2-pasos--cancelación-fiscal)
- [Módulo 17: Control de Activos & Monedero FIFO](#18-módulo-17-control-de-activos--monedero-fifo)
- [Módulo 18: Producción Industrial & Fabricación de Lotes](#19-módulo-18-producción-industrial--fabricación-de-lotes)
- [Módulo 19: Materias Primas, Insumos y Empaque](#20-módulo-19-materias-primas-insumos-y-empaque)
- [Módulo 20: Estructura de Costos Industriales & Rendimientos](#21-módulo-20-estructura-de-costos-industriales--rendimientos)
- [Módulo 21: Directorio de Proveedores](#22-módulo-21-directorio-de-proveedores)
- [Módulo 22: Módulo Intercompañía (México - USA)](#23-módulo-22-módulo-intercompañía-méxico---usa)
- [Módulo 23: Facturación y Pedidos USA (Dulet Group LLC)](#24-módulo-23-facturación-y-pedidos-usa-dulet-group-llc)
- [Módulo 24: Conciliador Bancario Automatizado 9-en-1](#25-módulo-24-conciliador-bancario-automatizado-9-en-1)
- [Módulo 25: Academia Dulet & Cuadernos de Trabajo (1 al 4)](#26-módulo-25-academia-dulet--cuadernos-de-trabajo-1-al-4)
- [Módulo 26: Academia Admin & Seguimiento Formativo](#27-módulo-26-academia-admin--seguimiento-formativo)
- [Módulo 27: Auditoría de Premios & Galardones LED](#28-módulo-27-auditoría-de-premios--galardones-led)
- [Módulo 28: Acelerador de Metas Empresariales](#29-módulo-28-acelerador-de-metas-empresariales)
- [Módulo 29: Centro de Notificaciones, Noticias y Calendario](#30-módulo-29-centro-de-notificaciones-noticias-y-calendario)
- [Módulo 30: Bitácora de Auditoría del Sistema & Seguridad](#31-módulo-30-bitácora-de-auditoría-del-sistema--seguridad)
- [Módulo 31: Configuración Global del Sistema](#32-módulo-31-configuración-global-del-sistema)
- [Portal Duletia Master Ops (/pages/ops)](#33-portal-duletia-master-ops-pagesops)
- [Compendio de Preguntas Frecuentes & Solución de Casos Extremos](#34-compendio-de-preguntas-frecuentes--solución-de-casos-extremos)
- [Apartado Especial: DuletIA — Inteligencia Artificial, Capacidades del Ecosistema & Master Workflow 8](#35-apartado-especial-duletia--inteligencia-artificial-capacidades-del-ecosistema--master-workflow-8)
1. Arquitectura del Sistema & Matriz de Seguridad de 7 Roles
El ecosistema de Duletia opera como una Single Page Application (SPA) modular de alto rendimiento conectada a una base de datos centralizada PostgreSQL y orquestada por flujos de n8n.
Matriz de Seguridad y Privilegios por Rol
| Módulo / Zona |
Master |
Admin |
Operativo |
Almacén |
Contabilidad |
Empresario |
Prospecto |
| Dashboard Master |
✅ |
✅ |
— |
— |
— |
— |
— |
| Mi Visión Empresario |
— |
— |
— |
— |
— |
✅ |
✅ |
| Líderes & Árbol de Red |
✅ |
✅ |
— |
— |
— |
✅ (Red Propia) |
— |
| Análisis de Líder |
✅ |
✅ |
— |
— |
— |
✅ (Personal) |
— |
| Módulo de Rescate |
✅ |
✅ |
— |
— |
— |
— |
— |
| Ventas & Pedidos |
✅ |
✅ |
✅ |
— |
✅ |
✅ (Compras) |
— |
| CEDIS 1 al 15 |
✅ |
✅ |
✅ |
— |
✅ |
— |
— |
| Cola de Activaciones (#230) |
✅ |
✅ |
✅ |
— |
— |
— |
— |
| Facturación SAT CFDI 4.0 |
✅ |
✅ |
— |
— |
✅ |
✅ (Descarga) |
— |
| Monedero de Activos FIFO |
✅ |
✅ |
— |
— |
✅ |
✅ (Saldo) |
— |
| Inventario & Kárdex |
✅ |
✅ |
✅ |
✅ |
✅ |
— |
— |
| Producción Industrial |
✅ |
✅ |
— |
✅ |
— |
— |
— |
| Materias Primas & Costos |
✅ |
✅ |
— |
✅ |
✅ |
— |
— |
| Conciliador Bancario 9-en-1 |
✅ |
✅ |
— |
— |
✅ |
— |
— |
| Intercompañía & USA |
✅ |
✅ |
— |
— |
✅ |
— |
— |
| Academia & Premios LED |
✅ |
✅ |
— |
— |
— |
✅ |
✅ |
| Bitácora & Configuración |
✅ |
— |
— |
— |
— |
— |
— |
| Portal Master Ops (/pages/ops) |
✅ |
✅ |
— |
— |
— |
— |
— |
2. Módulo 1: Dashboard Master — Panorama General
Ruta en Menú: #view-dashboard
Roles Autorizados: Master, Admin.
Propósito: Proporcionar la radiografía macroeconómica y operativa de toda la empresa en tiempo real para cualquier período fiscal.
📊 Componentes y KPIs
- Ventas Totales del Período: Suma monetaria de todas las notas de venta con
approved = 1.
- Cajas Pendientes en Cola (#230): Inventario de cajas pagadas en tránsito sin asignar a líder final.
- Activos en Circulación: Monto total acumulado en las billeteras de los socios pendiente de consumo.
- Saldo Deudor CEDIS: Capital total de producto entregado en consignación a los 15 Centros de Apoyo.
- Gráfica de Ingresos Diarios: Tendencia de facturación día a día del mes seleccionado.
- Top 10 Centros de Apoyo: Ranking de CEDIS por volumen de desplazamiento.
- Top 10 Líderes Productores: Ranking de líderes por volumen personal y grupal de red.
🔘 Fichas de Botones y Modales
Selector de Período (Mes/Año): Recalcula dinámicamente todos los KPIs y tablas en memoria.
↻ Actualizar: Invalida la caché local y vuelve a consultar la base de datos PostgreSQL.
📥 Exportar Resumen (CSV): Descarga un archivo con el desglose contable del mes.
3. Módulo 2: Mi Visión Empresario — Dashboard del Socio
Ruta en Menú: #view-dashboard-lider
Roles Autorizados: Empresario, Prospecto.
Propósito: Panel personalizado para que cada socio distribuidor supervise su negocio, comisiones, avance de rango y calificación.
📊 Componentes y Métricas
- Semáforo de Calificación: 🟢 Calificado (Compró $\ge 1$ caja este mes) / 🔴 Inactivo (Sin calificación mensual).
- Billetera de Activos: Saldo disponible para pagar compras futuras o solicitar liquidación.
- Rango LED Actual: Distintivo del rango alcanzado (Bronce, Plata, Oro, Zafiro, Esmeralda, Rubí, Diamante, etc.).
- Termómetro de Progreso de Rango: Muestra las cajas que faltan en el mes para subir al siguiente nivel.
- Volumen Personal: Cajas compradas directamente con su número de registro.
- Volumen de Grupo (4 Niveles): Cajas producidas por su organización por nivel de profundidad.
4. Módulo 3: Mi Perfil y Seguridad
Ruta en Menú: #view-mi-perfil
Roles Autorizados: Todos los usuarios autenticados.
Propósito: Administración de información personal, datos de contacto, domicilio de envío y credenciales.
🔘 Fichas de Botones
💾 Guardar Cambios: Actualiza teléfono, WhatsApp, correo electrónico y dirección en la tabla cliente.
🔑 Cambiar Contraseña: Solicita contraseña actual y nueva contraseña, cifrándola mediante bcrypt.
📄 Ver Constancia Fiscal: Permite al socio verificar su RFC, Razón Social y Régimen Fiscal registrado para facturación.
5. Módulo 4: Directorio de Líderes y Socios
Ruta en Menú: #view-lideres
Roles Autorizados: Master, Admin, Empresario (solo descendencia).
Propósito: Base de datos centralizada de distribuidores, prospectos y clientes con herramientas de prospección y gestión.
🔘 Fichas de Botones y Modales
➕ Nuevo Socio: Abre el modal de alta de distribuidores:
- Solicita: Nombre, Apellidos, Registro, Teléfono, Email, Patrocinador y Dirección.
- Valida que el número de registro no esté duplicado en PostgreSQL.
Buscador en Tiempo Real: Filtra por Registro (ej. 80000), Nombre, Teléfono o Estado.
👁️ Ver Detalle / Radiografía: Abre el perfil 360° del líder seleccionado.
✏️ Editar Socio: Permite actualizar datos fiscales (RFC, CP, Régimen) y datos de contacto.
⚡ Acreditar Bono Manual: Modal para inyectar activos al socio con captura de concepto y folio de soporte.
🌳 Ver en Árbol: Salta directamente a la vista de genealogía centrada en ese socio.
6. Módulo 5: Árbol de Red & Genealogía Dinámica
Ruta en Menú: #view-arbol
Roles Autorizados: Master, Admin, Empresario (solo su propia red).
Propósito: Visualizador gráfico interactivo de la estructura multinivel de patrocinio.
🎮 Controles y Navegación
- Navegación Interactiva: Arrastrar para mover el lienzo, rueda del ratón para zoom (+ / -).
- Código Visual de Nodos:
- 🟢 Verde: Socio calificado en el mes actual ($\ge 1$ caja).
- 🟡 Amarillo: Nuevo distribuidor inscrito en los últimos 30 días.
- 🔴 Rojo: Socio inactivo (sin compra este mes).
- Clic en Nodo:
- Despliega la tarjeta flotante con: Total de frontales, Cajas en N1, N2, N3, N4, Volumen Grupal y Teléfono.
- Botón
Expandir Hijos / Colapsar Línea.
7. Módulo 6: Radiografía 360° & Análisis de Líder
Ruta en Menú: #view-analisis-lider
Roles Autorizados: Master, Admin.
Propósito: Diagnóstico profundo del rendimiento de un socio en particular para sesiones de coaching empresarial.
📊 Datos Analizados
- Historial de Calificación (12 Meses): Registro mes a mes de cumplimiento de compras.
- Balance de Piernas (Frontales Fuertes vs Débiles): Detecta qué líneas de la red aportan el mayor volumen y cuáles requieren soporte.
- Cumplimiento de Galardones LED: Auditoría de requisitos de frontales calificados y volumen de puntos para el próximo pin.
8. Módulo 7: Módulo de Rescate y Alertas de Seguimiento
Ruta en Menú: #view-rescate
Roles Autorizados: Master, Admin.
Propósito: Algoritmo predictivo de retención que identifica líderes con riesgo de inactividad antes del cierre de mes.
🔘 Fichas de Botones
Filtro de Días Restantes de Mes: Muestra quiénes calificaron los meses anteriores pero aún no compran este mes.
📲 Enviar WhatsApp de Rescate: Abre WhatsApp Web con mensaje personalizado indicando las comisiones que perdería si no califica su caja.
9. Módulo 8: Ventas, Caja y Registro de Pedidos
Ruta en Menú: #view-ventas
Roles Autorizados: Master, Admin, Operativo, Contabilidad.
Propósito: Punto de venta, registro de notas de compra, validación de pagos y control de pedidos.
🔘 Fichas de Botones y Modales
➕ Registrar Nueva Venta: Abre el modal de captura de nota de venta:
- Selección de Cliente / Socio (o Público en General).
- Selección de CEDIS / Almacén de despacho.
- Partidas: Dulet (Natural, Chocolate, Fresa, Vainilla) y Eucament con cálculo de precio unitario automático.
- Método de Pago Mixto: Permite capturar monto en Efectivo/Transferencia y monto deducido de Monedero de Activos.
- Subida de comprobante de pago bancario (JPG/PNG/PDF).
✓ Aprobar Venta (approved=1): Valida el ingreso bancario, genera el volumen en red, acredita comisiones y descuenta inventario.
🚫 Cancelar Venta: Revierte el volumen, regresa el inventario y reintegra los activos consumidos.
🧾 Solicitar Factura: Envía la nota a la cola de timbrado fiscal.
10. Módulo 9: Calificaciones Mensuales y Pagos Adquiridos
Ruta en Menú: Integrado en #view-ventas y #view-centros-apoyo.
Propósito: Gestión de las calificaciones de 1 caja requeridas para el cobro del plan Evolution Link.
⚙️ Reglas Operativas
- Toda compra de 1 caja de Dulet por un socio registrado genera una calificación automática.
- Las compras pagadas por depósito bancario con concepto "Por Asignar" se transfieren a la Cola de Activaciones (#230) para su asignación manual.
11. Módulo 10: Catálogo Maestro de Productos y Precios
Ruta en Menú: #view-productos
Roles Autorizados: Master, Admin.
Propósito: Definición de SKUs, precios de lista por país (MXN/USD), puntos comisionables y costos base.
🔘 Fichas de Botones
➕ Nuevo Producto: Agrega un SKU al catálogo con nombre, código de barras, precio público, precio mayoreo y puntos de red.
✏️ Editar Precios: Permite ajustar precios de lista por inflación o promociones.
Interruptor Activo/Inactivo: Habilita o deshabilita la venta del producto en el punto de venta y tienda online.
12. Módulo 11: Inventario General de Producto Terminado
Ruta en Menú: #view-inventario
Roles Autorizados: Master, Admin, Almacén, Operativo.
Propósito: Control de existencias físicas en el Almacén Central de Matriz.
🔘 Fichas de Botones y Modales
➕ Entrada de Almacén: Ingresa producto terminado proveniente de la planta de producción.
➖ Salida por Merma / Daño: Da de baja producto dañado con justificación.
📦 Traspaso a Centro de Apoyo: Descuenta producto de Matriz y lo envía a un CEDIS en consignación.
📊 Auditoría de Existencias: Formulario de conteo físico vs existencias en sistema.
13. Módulo 12: Reportes de Movimientos y Kárdex
Ruta en Menú: #view-reportes-inventario
Roles Autorizados: Master, Admin, Almacén, Contabilidad.
Propósito: Trazabilidad histórica inmutable de cada entrada, salida, venta, traspaso y devolución de producto con fecha y responsable.
14. Módulo 13: Red de Centros de Apoyo Físicos (CEDIS 1 al 15)
Ruta en Menú: #view-centros-apoyo
Roles Autorizados: Master, Admin, Contabilidad, Operativo.
Propósito: Gestión integral de los 15 Centros de Apoyo físicos en la República Mexicana.
🏢 Sub-Pestañas del Detalle de CEDIS
- Notas Vinculadas: Ventas despachadas por este centro.
- Pagos y Liquidaciones: Registro de depósitos bancarios del operador a Matriz para abonar a su saldo deudor.
- Activaciones: Calificaciones procesadas en este CEDIS.
- Inventario Local: Existencias actuales de cajas y piezas en poder del operador.
- Movimientos y Kárdex: Historial de traspasos recibidos y ventas entregadas.
- Facturación del Centro: CFDIs emitidos con el RFC del operador del CEDIS.
- Notas Activadas: Calificaciones derivadas de producto de este centro.
- Rendimiento & Comisiones: Porcentaje de utilidad del operador acumulado en el período.
🔘 Fichas de Botones en Centros de Apoyo
➕ Crear Nuevo Centro: Da de alta un nuevo CEDIS asignándole nombre, operador, líder responsable, dirección y límite de crédito.
📦 Traspaso de Producto: Envía mercancía desde Matriz al CEDIS.
💵 Registrar Pago / Abono: Disminuye el saldo deudor del centro al recibir el depósito bancario.
🔒 Bloquear Centro: Suspende temporalmente la entrega de producto a un CEDIS por mora en pagos.
15. Módulo 14: Centro Especial Virtual "Por Asignar" (#230) & Cola Multi-Caja
Ruta en Menú: #view-centros-apoyo $\rightarrow$ Botón 📦 Cola de Activaciones (#230).
Roles Autorizados: Master, Admin, Operativo.
Propósito: Administrar notas pagadas en tránsito a cuentas bancarias de la empresa y asignar sus activaciones a líderes finales.
┌─────────────────────────────────────────────────────────────────────────┐
│ COLA DE ACTIVACIONES (#230) │
├─────────────────────────────────────────────────────────────────────────┤
│ [ 197 Notas en Tránsito ] [ 200 Cajas Disponibles ] [ 45 Asignadas] │
├─────────────────────────────────────────────────────────────────────────┤
│ Nota Fecha Destino Detectado Total Cajas Acción │
│ ─────────────────────────────────────────────────────────────────────── │
│ a6cff756… 30/08/26 Ruth Hernández M. $9,500.00 0/2 🟢 [⚡Activar (2)] │
│ 4fa0b60a… 30/08/26 Martín Juárez J. $19,000.00 0/4 🟢 [⚡Activar (4)] │
│ f5d01445… 23/08/26 Eduardo Luquín P. $45,000.00 0/10 🟢 [⚡Activar (10)]│
└─────────────────────────────────────────────────────────────────────────┘
🔘 Fichas de Botones y Modales en Cola de Activaciones
⚡ Activar (1): Abre el modal de asignación para notas de 1 sola caja.
⚡ Activar (N) (Asistente Multi-Caja):
- Genera N slots individuales de asignación (
Caja 1 de N, Caja 2 de N...).
- Cada slot cuenta con su propio buscador de líder y selector de fecha.
- Permite asignar cajas a diferentes personas o al mismo socio en meses distintos.
- Permite confirmación parcial (ej. asignar 2 de 4 cajas hoy y dejar 2 pendientes).
- Botón dinámico:
⚡ Confirmar N Activaciones.
✕ Cancelar Activación (En pestaña *Asignadas*):
- Elimina la calificación
calificacion-mes del líder.
- Devuelve automáticamente 1 cupo disponible a la nota de respaldo original.
16. Módulo 15: Facturación SAT CFDI 4.0 & Facturama
Ruta en Menú: #view-facturacion
Roles Autorizados: Master, Admin, Contabilidad.
Propósito: Emisión, timbrado, consulta y descarga de comprobantes fiscales digitales por internet bajo el Anexo 20 CFDI 4.0.
📑 Pestañas del Módulo Fiscal
- ⏳ Facturas Pendientes: Solicitudes de clientes pendientes de timbrado con validación de RFC, Régimen, CP y Uso de CFDI.
- ✅ Facturas del Mes: Comprobantes timbrados exitosamente (Individuales, Globales y de Centro).
- 🌐 Factura Global del Mes: Agrupación automática de notas de Público en General por CEDIS y forma de pago con complemento
GlobalInformation.
- ❌ Facturas Canceladas: Historial de cancelaciones con motivo SAT y UUID de sustitución.
🔘 Fichas de Botones
⚡ Facturar: Envía el documento a Facturama y timbra ante el SAT.
📄 PDF: Descarga el formato gráfico con sellos digitales y código bidimensional QR.
📥 XML: Descarga el archivo XML sellado por el PAC.
📋 Ver Notas: Desglosa cada nota de venta incluida en una factura global o de centro con exportación a PDF y CSV.
⚡ Generar Factura Global: Timbra el CFDI 4.0 global del mes con las notas seleccionadas mediante casillas (✓).
17. Módulo 16: Asistente de Sustitución en 2 Pasos & Cancelación Fiscal
Ruta en Menú: #view-facturacion $\rightarrow$ Botones 🔄 Sustituir y ❌ Cancelar.
Propósito: Cumplir estrictamente con las reglas de cancelación del SAT evitando multas y discrepancias fiscales.
graph TD
A["Factura Original con Error (UUID-1)"] --> B["Clic en 🔄 Sustituir"]
B --> C["Modal: Corregir Datos Fiscales (RFC, CP, Régimen, Forma Pago)"]
C --> D["Paso 1 SAT: Emitir Nueva Factura con Tipo de Relación 04 apuntando a UUID-1"]
D --> E["PAC / SAT Timbra Nueva Factura (UUID-2)"]
E --> F["Paso 2 SAT: Cancelar UUID-1 enviando Motivo 01 y Folio Sustituto UUID-2"]
F --> G["BD Actualizada: UUID-1 pasa a Canceladas / UUID-2 queda Activa en el Mes"]
🔘 Motivos de Cancelación SAT Soportados
- Motivo 01 (Con relación): Ejecutado automáticamente por el Asistente de Sustitución en 2 pasos.
- Motivo 02 (Sin relación): Cancela la factura y libera automáticamente las notas de venta asociadas (
factura_emitida = false) para permitir su re-facturación.
- Motivo 03 (Operación no realizada): Anulación por cancelación de compra.
- Motivo 04 (Operación nominativa en global): Desglose de una venta de la global a factura particular.
18. Módulo 17: Control de Activos & Monedero FIFO
Ruta en Menú: #view-activos
Roles Autorizados: Master, Admin, Contabilidad.
Propósito: Gestión del monedero electrónico de comisiones y bonos de red bajo el principio contable FIFO (First In, First Out).
🔘 Fichas de Botones y Modales
➕ Acreditar Activos: Modal para abono manual a un líder (Monto MXN, Concepto, Referencia).
➖ Deducir Activos: Modal para cargo o ajuste justificado.
📋 Bitácora FIFO: Auditoría centavo a centavo del consumo de activos antiguos primero.
📥 Exportar Saldos: Reporte en Excel de todos los monederos activos.
19. Módulo 18: Producción Industrial & Fabricación de Lotes
Ruta en Menú: #view-produccion
Roles Autorizados: Master, Admin, Almacén, Producción.
Propósito: Control de manufactura de producto terminado en planta.
🔘 Fichas de Botones y Modales
➕ Nuevo Lote de Producción:
- Selección de producto a fabricar (Dulet Natural, Sabores, Eucament).
- Captura de Materia Prima ingresada (Kilos de suero, saborizante, aceite).
- Asignación de Número de Lote Industrial y Fecha de Caducidad.
Calculadora de Rendimiento y Merma: Compara unidades teóricas vs reales producidas.
🔒 Cerrar Lote: Bloquea el lote y traspasa las unidades al inventario disponible para venta.
20. Módulo 19: Materias Primas, Insumos y Empaque
Ruta en Menú: #view-materias
Roles Autorizados: Master, Admin, Almacén, Producción.
Propósito: Stock de ingredientes e insumos de empaque (Suero suizo, potes de 500g, tapas, sellos, etiquetas y cajas).
🔘 Fichas de Botones
➕ Registrar Entrada de Materia Prima: Captura compras a proveedores con lote y certificado de calidad.
⚠️ Alertas de Reorden: Notificación automática cuando un insumo cae por debajo del stock mínimo.
21. Módulo 20: Estructura de Costos Industriales & Rendimientos
Ruta en Menú: #view-costos
Roles Autorizados: Master, Admin, Contabilidad.
Propósito: Análisis y auditoría integral del Costo de Ventas (COGS), costo unitario absorbido por bote, rentabilidad por SKU y Estados de Resultados (P&L) individuales y consolidados.
21.1 Arquitectura de los 3 Bloques de Costo
El motor de costos de Duletia clasifica cada centavo en tres bloques fundamentales de la contabilidad gerencial:
- Costo Fijo (Estructura y G&A):
- Nóminas Administrativas: Sueldos y cargas patronales de oficinas corporativas (
Admin DI y Admin DG).
- Almacenamiento y Bodega: Renta y electricidad fija de Planta 1 y Planta 2 prorrateada por espacio ocupado.
- Depreciación de Activos: Desgaste contable mensual en línea recta de maquinaria, vehículos e instalaciones.
- Costo Variable (Producción Directa):
- Materia Prima Directa: Insumos consumidos según la fórmula maestra (BOM) de cada sabor.
- Mano de Obra Directa (MOD): Sueldos y cargas patronales de los operarios de manufactura (
MOD DI).
- Mermas y Desperdicios: Costo de merma física generada durante los procesos de mezclado y envasado.
- Costo Promedio / Unitario por Bote:
- Absorción total por lote en la tabla
produccion_diaria:
$$\text{Costo Unitario} = \frac{\text{Materia Prima} + \text{Merma} + \text{Prorrateo Bodega} + \text{MOD} + \text{Depreciación}}{\text{Botes Producidos}}$$
21.2 Desglose de las 10 Pestañas Operativas
📋 1. Gastos del Mes & P&L Mensual
- Selector de Empresa: Permite alternar entre empresas individuales (
DI Manufactura, DG Distribución México, LLC Ventas USA, DC Educación y Soporte, DS Holding Internacional) o el consolidado de grupo (ALL).
- Neutralización Intercompañía: Al seleccionar
ALL, el sistema elimina automáticamente operaciones espejo (ej. servicios_dc y servicios_ds) para evitar duplicidad de ingresos y gastos.
- Cascada de P&L:
- (+) Ingresos Totales: Ventas facturadas y cobradas del período.
- (−) Costo de Fabricación (COGS): Costo directo de materia prima e insumos vendidos.
- (=) Utilidad Bruta: Margen de contribución comercial.
- (−) Gastos Operativos (OPEX): Nóminas administrativas, rentas, servicios y logística.
- (−) Depreciación: Gasto contable no desembolsable de activos fijos.
- (±) Diferencial Cambiario: Ganancia o pérdida por fluctuaciones cambiarias MXN/USD.
- (=) Utilidad Neta y Margen (%): Resultado integral del ejercicio.
🏭 2. Costos por Lote
- Matriz de Costeo en Tiempo Real: Muestra cada lote producido con fecha, código, sabor, unidades obtenidas y los 5 componentes de costo:
- Costo MP
- Costo Merma
- Prorrateo Bodega
- Costo MOD
- Costo Depreciación
- Botón
⚡ Ejecutar Cierre de Costos: Calcula las tasas unitarias de absorción mensual y actualiza automáticamente los registros en produccion_diaria.
🧪 3. Formulación (BOM)
- Receta Maestra por Producto: Consulta los componentes estándar de Dulet Natural, Fresa, Vainilla, Choco y Eucament.
- Dosificación y Costeo: Detalla gramos o piezas por unidad, costo por kg/pieza de compra, costo unitario absorbido y porcentaje sobre el costo directo.
- Sincronización: Botón para sincronizar precios unitarios de insumos con las últimas facturas registradas en el sistema.
📅 4. Vista Anual
- Comparativa a 12 Meses: Tabla interactiva de Enero a Diciembre que evalúa la evolución de Ventas, Costos de Producción, Gastos y Utilidad Neta.
- Estacionalidad y Márgenes: Permite a la dirección monitorear el comportamiento del margen bruto y neto a lo largo del año fiscal.
📐 5. Bodega
- Configuración de Metros Cuadrados: Distribución del área de almacenamiento en Planta 1 y Planta 2 para cada uno de los 5 sabores.
- Prorrateo de Almacenamiento: Divide el costo fijo mensual de renta y energía eléctrica según los m² físicos utilizados por cada SKU.
🏗️ 6. Activos Fijos
- Inventario Patrimonial: Registro de maquinaria industrial, líneas de envasado, vehículos, mobiliario y equipo de cómputo.
- Depreciación Mensual: Cálculo automático bajo el método de línea recta:
$$\text{Depreciación Mensual} = \frac{\text{Valor Compra} - \text{Valor Rescate}}{\text{Vida Útil (Años)} \times 12}$$
- Semáforo de Seguridad: Alertas visuales sobre vencimiento de pólizas de seguro y coberturas de garantía de proveedores.
👷 7. MOD — Mano de Obra Directa y Nómina
- Separación de Nómina: Clasificación estricta entre mano de obra directa (
MOD DI variable) y nóminas administrativas (Admin DI y Admin DG fijas).
- Cargas Sociales Automáticas: Integración de IMSS, INFONAVIT e ISN estimadas (~32.5% a 44.7%) sobre el Salario Base de Cotización (SBC).
- Días Laborales del Personal: Base estándar de 24 días de jornada industrial con selector interactivo para meses con variaciones de calendario.
- Promedio General Diario de Planta:
$$\text{Promedio Diario Planta} = \frac{\text{Total Unidades del Mes}}{\text{Días Laborales del Personal}} = \mathbf{907\text{ botes/día}}$$
- Matriz de Absorción por SKU: Distribuye la nómina MOD proporcionalmente al volumen de cada sabor (ej. Eucament 45.9%, Natural 28.6%), arrojando un costo unitario MOD exacto por bote ($2.1137).
- Historial Anual de Nómina: Comparativo mes a mes con estado contable:
- 🟢 Timbrada SAT: Recibos CFDI XML timbrados.
- 🔵 P&L Asentada: Nómina devengada y registrada en gastos mensuales.
- 🟡 Estimada: Período pendiente de cierre.
- Sincronización: Botón
⚡ Sincronizar a P&L para asentar nóminas estimadas a la contabilidad y actualizar los lotes de dicho mes en 1 clic.
📑 8. IVA
- IVA Acreditable: Control del IVA efectivamente pagado a proveedores con CFDI desglosado.
- Cumplimiento Tasa 0% (Art. 2-A LIVA): Al ser suplementos alimenticios exentos de IVA trasladado en ventas, todo el IVA de compras constituye un saldo a favor mensual recuperable ante el SAT.
- Asistente de Corrección: Detección de facturas sin IVA desglosado y modal interactivo para aplicar el factor 16/116 o clasificar en tasa 0% en lote.
💸 9. Flujo / CxP (Cuentas por Pagar)
- Control de Pasivos: Registro y seguimiento de compromisos financieros con proveedores de materias primas y servicios.
- Semáforo de Vencimiento:
- 🔴 Vencidas: Compromisos fuera de término.
- 🟡 Próximos 15 días: Programación de pagos prioritarios.
- 🟢 Al Corriente: Facturas dentro de término.
🎯 10. Presupuesto vs Real
- Control Presupuestal: Comparativa mensual por categoría (
fijo, variable, materia_prima, cif, activo).
- Sembrado Sugerido Inteligente: Generación automática de presupuestos base calculados con un +5% sobre el histórico real de la empresa.
- Desviaciones Porcentuales: Detección inmediata de sobrecostos o ahorros operativos.
21.3 Protocolo Oficial para Cierre de Costos Mensual
Para garantizar que los estados financieros y costos de lote reflejen la realidad operativa de la empresa, Contabilidad y Producción deben seguir este checklist de cierre:
- Liberación de Lotes: Verificar en el módulo Producción que todos los lotes concluidos tengan estatus
Liberado = true.
- Revisión de Nómina: En la pestaña MOD, verificar que la nómina del mes esté timbrada o presionar
⚡ Sincronizar a P&L para asentar el costo devengado.
- Ejecución del Cierre: En la pestaña Costos por Lote, hacer clic en
⚡ Ejecutar Cierre de Costos para prorratear MOD, Bodega y Depreciación en todos los lotes.
- Validación del P&L: En la pestaña Gastos del Mes, validar que la Utilidad Bruta y Neta coincidan con la balanza contable.
22. Módulo 21: Directorio de Proveedores
Ruta en Menú: #view-proveedores
Roles Autorizados: Master, Admin, Contabilidad.
Propósito: Padrón de proveedores de materias primas, fletes, empaque y servicios corporativos con historial de pagos.
23. Módulo 22: Módulo Intercompañía (México - USA)
Ruta en Menú: #view-intercompania
Roles Autorizados: Master, Admin, Contabilidad.
Propósito: Registro y conciliación de operaciones comerciales entre Dulet International Group (México) y Dulet Group LLC (Estados Unidos).
24. Módulo 23: Facturación y Pedidos USA (Dulet Group LLC)
Ruta en Menú: #view-facturacion-usa
Roles Autorizados: Master, Admin, Contabilidad.
Propósito: Gestión de ventas en Estados Unidos, facturación en Dólares (USD), cálculo de Sales Tax y reportes corporativos para IRS.
25. Módulo 24: Conciliador Bancario Automatizado 9-en-1
Ruta en Menú: #view-conciliacion
Roles Autorizados: Master, Admin, Contabilidad.
Propósito: Motor de inteligencia contable que cruza extractos bancarios vs notas de venta del sistema.
🏦 Fuentes Integradas
- BBVA Bancomer (Depósitos, Transferencias SPEI, Cie)
- Santander México
- MercadoPago México
- PayPal México & USA
- Stripe E-commerce
- Terminales Clip
- Shopify Payments
- Efectivo en Centros de Apoyo (CEDIS)
- Resumen de Conciliación y Comisiones de Pasarela
26. Módulo 25: Academia Dulet & Cuadernos de Trabajo (1 al 4)
Ruta en Menú: #view-academia
Roles Autorizados: Todos los usuarios.
Propósito: Plataforma de educación empresarial "30 Líderes en 30 Días".
- Cuaderno 1 (
/pages/cuaderno1): Mentalidad, Visión y Lista de Contactos.
- Cuaderno 2 (
/pages/cuaderno2): Presentación del Plan Evolution Link y Objeciones.
- Cuaderno 3 (
/pages/cuaderno3): Cierre, Duplicación y Frontales.
- Cuaderno 4 (
/pages/cuaderno4): Liderazgo Avanzado y Rangos LED.
- Versiones Imprimibles: Disponibles en alta resolución para talleres presenciales.
27. Módulo 26: Academia Admin & Seguimiento Formativo
Ruta en Menú: #view-academia-admin
Roles Autorizados: Master, Admin.
Propósito: Panel para que los instructores supervisen el avance de los socios en sus cuadernos de trabajo.
28. Módulo 27: Auditoría de Premios & Galardones LED
Ruta en Menú: #view-premios
Roles Autorizados: Master, Admin.
Propósito: Control de entrega de reconocimientos: Pines LED, Bonos de Auto, Viajes Nacionales e Internacionales.
29. Módulo 28: Acelerador de Metas Empresariales
Ruta en Menú: #view-acelerador
Roles Autorizados: Master, Admin, Empresario.
Propósito: Tablero de retos mensuales y seguimiento de metas de prospección y ventas.
30. Módulo 29: Centro de Notificaciones, Noticias y Calendario
Rutas en Menú: #view-notificaciones, #view-noticias, #view-calendario.
Propósito: Comunicación oficial, avisos de promociones, fechas de corte y agenda corporativa.
31. Módulo 30: Bitácora de Auditoría del Sistema & Seguridad
Ruta en Menú: #view-bitacora
Roles Autorizados: Master.
Propósito: Registro forense inmutable de todas las acciones del sistema:
- Inicios de sesión con IP y dispositivo.
- Creación, edición o cancelación de ventas.
- Movimientos de monedero de activos.
- Emisiones y cancelaciones de CFDI.
32. Módulo 31: Configuración Global del Sistema
Ruta en Menú: #view-config
Roles Autorizados: Master.
Propósito: Parámetros de negocio, porcentajes de comisión de la red, credenciales de Facturama y llaves de integración.
33. Portal Duletia Master Ops (/pages/ops)
Ruta de Acceso: /pages/ops (Shopify) y ops.html (Cloudflare).
Roles Autorizados: Master, Admin.
Propósito: Centro de comando técnico y observabilidad con Inteligencia Artificial.
┌─────────────────────────────────────────────────────────────────────────┐
│ DULETIA OPS — MASTER HUB (v3.2) │
├─────────────────────────────────────────────────────────────────────────┤
│ [🎯 Leads AI] [🤖 Agentes] [⚡ Observabilidad] [💻 SQL Runner] [📚 Docs]│
└─────────────────────────────────────────────────────────────────────────┘
🔘 Zonas del Portal Ops
- Lead Intelligence (
#view-leads): Captura, perfilado y calificación automática de prospectos con IA.
- Agentes de IA (
#view-agents): Estado y métricas de los chatbots y asistentes virtuales.
- Salud del Sistema (
#view-health): Monitor en vivo de PostgreSQL, n8n y Facturama API.
- SQL Runner (
#view-sql): Consola protegida de consultas de diagnóstico para soporte técnico.
- Documentación Sincronizada (
#view-docs): Manual de usuario integrado en vivo.
34. Compendio de Preguntas Frecuentes & Solución de Casos Extremos
❓ P: ¿Qué ocurre si cancelo una Factura Global porque integré notas de más por error?
R: Al cancelar la global con Motivo 02, el sistema libera automáticamente todas las notas de venta asociadas en la base de datos (factura_emitida = false). Ninguna nota se bloquea. Luego vas a la pestaña *Factura Global*, desmarcas las notas que no correspondían y timbras el nuevo CFDI únicamente con las correctas.
❓ P: ¿Cómo asigno una nota que ampara 4 cajas entre 2 líderes distintos?
R: En la Cola de Activaciones (#230), haz clic en ⚡ Activar (4). Se abrirán los 4 slots: asignas Líder A en las Cajas 1 y 2, y Líder B en las Cajas 3 y 4. Al dar clic en ⚡ Confirmar 4 Activaciones, el sistema genera las calificaciones correspondientes de inmediato.
❓ P: ¿Qué pasa si asigné por error una caja a un socio que no correspondía?
R: Ve a la pestaña Asignadas en la Cola de Activaciones, busca la activación errónea y haz clic en ✕ Cancelar. El sistema eliminará la calificación y devolverá 1 cupo disponible a la nota de respaldo original.
❓ P: ¿Cómo se maneja una compra con pago mixto (efectivo + activos)?
R: En el modal de venta se capturan ambos importes. El sistema deduce los activos aplicando la regla FIFO de la billetera del socio y timbra la factura fiscal únicamente por el importe efectivamente facturable.
35. Apartado Especial: DuletIA — Inteligencia Artificial, Capacidades del Ecosistema & Master Workflow 8
> [!IMPORTANT]
> DuletIA no es un chatbot de respuestas prefabricadas. Es el Núcleo de Inteligencia Operativa y Transaccional 24/7 de Dulet International Group (México, Canadá, Guatemala y El Salvador) y Dulet Group LLC (Estados Unidos). Su cerebro central reside en el motor de automatizaciones n8n.duletias3rver.com bajo la arquitectura de orquestación conocida como Master Workflow 8, coordinando ventas, pagos, facturación, logística, redención de activos y asesoría empresarial sin descanso los 365 días del año.
35.1 Identidad Institucional, Filosofía "Modo Disney" y Blindaje Regulatorio
DuletIA fue concebida bajo una filosofía estricta de excelencia en atención al cliente denominada "Modo Disney": cada prospecto, consumidor final o socio empresario es tratado como un Invitado de Honor, recibiendo respuestas inmediatas, empáticas, personalizadas y resolutivas.
┌────────────────────────────────────────────────────────────────────────────────────────┐
│ PRINCIPIOS FUNDAMENTALES DE DULETIA │
├────────────────────────────────────────────────────────────────────────────────────────┤
│ 1. Trato VIP Modo Disney: Respuestas cálidas con 2 a 6 emojis, legibles y dinámicas. │
│ 2. Blindaje Regulatorio COFEPRIS / FDA: Respeto absoluto a la naturaleza del producto. │
│ 3. Vocabulario Institucional: "Cadena de Negocios" (prohibido el término multinivel). │
│ 4. Seguridad Máxima: NIP de seguridad de 4 a 6 dígitos para proteger activos y red. │
└────────────────────────────────────────────────────────────────────────────────────────┘
Blindaje Médico y Cumplimiento Regulatorio (COFEPRIS & FDA)
DuletIA tiene instrucciones inmutables respecto a la comunicación de los productos:
- Dulet: Se define y describe exclusivamente como un ALIMENTO 100% natural de lactosuero suizo con 41 nutrientes esenciales (aminoácidos, proteínas de alto valor biológico, vitaminas y minerales). Está estrictamente prohibido clasificarlo como "medicamento", "fármaco" o prometer la cura, alivio o tratamiento de patologías específicas (diabetes, colitis, gastritis, hipertensión, cáncer, etc.). Su propósito es apoyar la nutrición celular y el bienestar integral como parte de un estilo de vida saludable, sugiriendo siempre consultar al médico de cabecera.
- Eucament: Se define como una esencia aromática de eucalipto en spray para bienestar respiratorio y sensación de frescura ambiental o personal.
35.2 La Red de 6 Sub-Agentes Especializados de DuletIA
El orquestador central de DuletIA opera como un Director de Orquesta (Supervisor) que analiza el mensaje del usuario y transfiere la ejecución en milisegundos a uno de sus 6 Sub-Agentes Especialistas, garantizando que ninguna tarea crítica quede desatendida:
| Sub-Agente |
Especialidad Operativa |
Herramientas Conectadas |
Impacto Directo en Backoffice |
| 1. 🛒 Pedidos |
Calculadora matemática de cotizaciones, precios por volumen y registro de ventas. |
AI Precios Internos, AI Nota Check, AI Venta, AI Cobrar Activos, crea link. |
Genera registros en venta, calcula costos de envío, crea el folio (8 caracteres en mayúsculas) y descuenta inventario. |
| 2. 💳 Tickets & Pagos |
Auditoría visual de comprobantes bancarios, transferencias SPEI y depósitos. |
AI Mis Ventas, AI Ticket Pago, AI Nota Editar, AI Pagos, Google Sheets. |
Lee imágenes/PDFs, valida bancos autorizados (BBVA, Santander, MP, PayPal, Clip, Stripe), estampa el sello en comentarios y notifica a caja. |
| 3. 📦 Envíos |
Monitoreo y rastreo de paqueterías en tiempo real con soporte multicaja. |
ver envios, AI Mis Ventas, Think. |
Consulta guías en BD y hojas de almacén; notifica si el pedido está en preparación, en tránsito o entregado al destinatario. |
| 4. 🧾 Facturas |
Gestión fiscal integral y enlace con el PAC Facturama para timbrado CFDI 4.0. |
AI Mis Ventas, AI Factura Solicitar, Facturacion. |
Valida RFC, C.P., Régimen Fiscal y Uso de CFDI; crea registros en facturas_solicitadas para aprobación administrativa. |
| 5. 🔐 Especial & Activos |
Seguridad, consulta de red de negocio y redención del Monedero FIFO. |
AI Auth Cadena, AI Activos, revisar pedidos. |
Verifica NIP de seguridad (bloqueo al 3er intento fallido); ejecuta el Motor de Reglas (Regla N-1, frontales, 4 niveles y saldo en activos). |
| 6. 🎓 Coaching |
Mentoría comercial, cultura organizacional, Academia y Plan Evolution Link. |
revista Dul, definicion coach. |
Resuelve dudas sobre los 4 Cuadernos de Trabajo, Galardones y canaliza líderes a formación de alto rendimiento. |
35.3 El Flujo Transaccional de una Compra en Tiempo Real
El ciclo operativo estándar a través de WhatsApp o Kommo CRM se ejecuta de manera coordinada entre los sub-agentes y el Backoffice:
[Cliente envía mensaje] ──▶ [DuletIA Supervisor analiza intención]
│
┌──────────────────────────────┴──────────────────────────────┐
▼ ▼
[Sub-Agente Pedidos] [Sub-Agente Tickets]
• Valida catálogo de precios • Inspecciona voucher (OCR/Visión)
• Aplica reglas de volumen y destino • Comprueba banco y monto exacto
• Registra la venta en BD (`AI Venta HTTP`) • Inserta sello en comentario:
• Devuelve Folio único (ej. `F8B1A2C3`) `|| BBVA $2,500 Ref:1234567`
│ │
└──────────────────────────────┬──────────────────────────────┘
▼
[Reflejo Inmediato en Backoffice]
• Módulo 8 (Ventas): Pedido visible para empaque y surtido.
• Módulo 17 (Activos): Descuento FIFO aplicado si usó monedero.
• Módulo 15 (Facturas): Solicitud lista si el cliente envió su RFC.
35.4 Matriz de Handoff Humano: El Asesor Inteligente
DuletIA está programada para reconocer sus propios límites operativos y transferir la conversación de manera inmediata y sin fricción al especialista humano correspondiente mediante la propiedad asesor:
asesor: "ninguno" (100% Autónomo): Consultas de precios, levantamiento de pedidos rutinarios, rastreo de guías estándar y recepción de comprobantes de pago.
asesor: "coaching": Socios que solicitan estrategias para prospección masiva, formación de cadenas internacionales o desarrollo de liderazgo. *Acción:* Mueve el lead a la columna de Coaching en Kommo y alerta al equipo de Dirección de Redes.
asesor: "nutricion": Clientes con dudas sobre afecciones de salud crónicas complejas. *Acción:* Deriva a especialistas humanos para orientar al cliente en la toma correcta del alimento sin violar normas sanitarias.
asesor: "vip": Solicitudes de compra a gran escala (pedidos por tarima/pallet completo o convenios institucionales). *Acción:* Notificación prioritaria a Dirección Comercial.
asesor: "logistica": Paquetes con demoras excesivas reportadas por paquetería, daños en tránsito o incidencias en entrega física. *Acción:* Asignación a la mesa de ayuda de Almacén y Envíos.
asesor: "molesto": Detección de frustración, insatisfacción o reclamo en el tono del mensaje. *Acción:* Pausa inmediata de la IA y alerta roja a Supervisión Administrativa.
35.5 Sincronización entre la Inteligencia Artificial y la Capacidad Fabril de Planta
Uno de los mayores riesgos en empresas de alta demanda es que el canal digital venda más producto del que la planta física tiene capacidad de manufacturar y empacar. En Duletia, el sistema está matemáticamente acoplado con los estándares del Módulo 20 (Estructura de Costos Industriales & Rendimientos):
┌────────────────────────────────────────────────────────────────────────────────────────┐
│ BALANCE ENTRE CAPACIDAD DIGITAL Y PLANTA │
├────────────────────────────────────────────────────────────────────────────────────────┤
│ • Días Laborales de Personal: 24 días al mes (192 horas estándar Lunes a Sábado). │
│ • Ritmo Operativo de Fabricación: 907 botes / día (promedio general consolidado). │
│ • Capacidad Industrial en 1 Turno: 22,000 a 25,000 botes terminados por mes. │
│ • Capacidad Industrial en 2 Turnos: 45,000 a 50,000 botes terminados por mes. │
│ • Mano de Obra Directa (MOD): $45,998.93/mes absorbida a razón de $2.1137 por bote. │
└────────────────────────────────────────────────────────────────────────────────────────┘
Reglas de Protección de Inventario de DuletIA:
- Consulta Preventiva de Existencias: Antes de confirmar pagos de pedidos mayoristas, DuletIA verifica el stock disponible en Almacén Central y en los 15 Centros de Apoyo (CEDIS).
- Alertas de Cuello de Botella: Si la demanda en un día determinado rebasa el límite de despacho diario de la línea de empaque, DuletIA comunica al cliente tiempos de entrega programados con holgura (24 a 48 horas adicionales) para proteger la reputación de la empresa.
- Prioridad a Activaciones de Red: Las cajas destinadas a la calificación mensual de socios activos (Cola #230) tienen prioridad logística para asegurar que los líderes mantengan sus derechos de compensación sin interrupciones.
35.6 Guía Práctica de Colaboración: El Personal y DuletIA
Para los operadores del Backoffice, cajeros, encargados de almacén y contadores, interactuar con pedidos originados por DuletIA es sencillo siguiendo estos lineamientos:
- Reconocimiento del Folio: Cualquier nota iniciada por DuletIA tendrá un ID alfanumérico generado a partir del UUID de base de datos (por ejemplo,
F3D89E1A). Este folio es el que el cliente presentará en ventanilla o por mensaje.
- Inspección del Comentario de Pago: Si el sub-agente de tickets procesó el pago, la nota de venta mostrará un comentario estructurado con el formato:
comentario_original || BANCO $MONTO Ref:NUMERO_DE_REFERENCIA
El personal de caja solo debe cotejar que el depósito aparezca en el portal bancario correspondiente o en el Módulo 24 (Conciliación Bancaria) y proceder con la liberación del pedido.
- Intervención Humana en el Chat: Cuando un operador administrativo toma el control de un chat en Kommo CRM, el interruptor de DuletIA se desactiva de forma temporal para esa conversación (
Parar la IA), permitiendo que el humano atienda con total libertad sin que el bot interfiera en la conversación. Al concluir, el operador puede reactivar el asistente para que continúe su labor de seguimiento.
💻 Manual de Desarrollador & Arquitectura Técnica Integral — Duletia Core
Versión: 4.0 (Documentación Técnica Integral & DevOps)
Fecha de Actualización: Septiembre 2026
Audiencia: Ingenieros de Software, Arquitectos Cloud, Desarrolladores Full-Stack, Ingenieros de Datos y DevOps
Infraestructura: Servidor n8n (n8n.duletias3rver.com) · PostgreSQL 15 en VPS Cloud · Cloudflare Pages · Shopify Liquid
Confidencial — Uso Interno
📑 Índice de Arquitectura Técnica
- [Topología General del Sistema (3 Capas Desacopladas)](#1-topología-general-del-sistema-3-capas-desacopladas)
- [Diccionario Maestro de Base de Datos PostgreSQL](#2-diccionario-maestro-de-base-de-datos-postgresql)
- [Arquitectura Frontend Modular en JavaScript (15+ Bundles)](#3-arquitectura-frontend-modular-en-javascript-15-bundles)
- [Ecosistema de Workflows n8n & API Endpoints](#4-ecosistema-de-workflows-n8n--api-endpoints)
- [Motor Fiscal CFDI 4.0 & Facturama API Gateway](#5-motor-fiscal-cfdi-40--facturama-api-gateway)
- [Motor de Activaciones (#230) & Asignación Multi-Caja](#6-motor-de-activaciones-230--asignación-multi-caja)
- [Algoritmo de Monedero de Activos FIFO & Compensación](#7-algoritmo-de-monedero-de-activos-fifo--compensación)
- [Motor de Conciliación Bancaria 9-en-1](#8-motor-de-conciliación-bancaria-9-en-1)
- [Módulos Industriales: Producción, Rendimiento y Kárdex](#9-módulos-industriales-producción-rendimiento-y-kárdex)
- [Portal Master Gateway (/pages/ops) & Observabilidad IA](#10-portal-master-gateway-pagesops--observabilidad-ia)
- [Protocolo Obligatorio Dual Deploy (Cloudflare + Shopify)](#11-protocolo-obligatorio-dual-deploy-cloudflare--shopify)
- [Guía de Diagnóstico, Testing y Resolución de Incidencias](#12-guía-de-diagnóstico-testing-y-resolución-de-incidencias)
- [Apartado Especial: Arquitectura Técnica de DuletIA Core & Orquestación de My workflow 8](#13-apartado-especial-arquitectura-técnica-de-duletia-core--orquestación-de-my-workflow-8)
1. Topología General del Sistema (3 Capas Desacopladas)
┌────────────────────────────────────────────────────────────────────────────────────────┐
│ 1. CAPA DE PRESENTACIÓN (FRONTEND) │
│ • Cloudflare Pages: SPA Reactiva de Alto Rendimiento (pagina 2026/) │
│ • Shopify Liquid Themes: dulet-main-theme (Live: 187616788794) / dulet-backoffice-v2 │
│ • Bundles JS Vanilla Modulares (bo-*.js) sin dependencias pesadas de frameworks │
└───────────────────────────────────────────┬────────────────────────────────────────────┘
│ HTTP / JSON (JWT Bearer Token / CORS / SSL)
▼
┌────────────────────────────────────────────────────────────────────────────────────────┐
│ 2. CAPA DE LÓGICA & MIDDLEWARE (API) │
│ • Motor n8n (n8n.duletias3rver.com) con 65+ Workflows como Código TypeScript │
│ • Master Gateway Endpoint (`RrAWwCVNTcGqvYnQ`) con Auditoría Inmutable │
│ • PAC Facturama REST API v2 para Timbrado CFDI 4.0 / Cancelación SAT │
│ • Pasarelas de Pago: Stripe Checkout, PayPal SDK, MercadoPago API │
└───────────────────────────────────────────┬────────────────────────────────────────────┘
│ SQL Connection Pooling (Node pg / Relay)
▼
┌────────────────────────────────────────────────────────────────────────────────────────┐
│ 3. CAPA DE PERSISTENCIA (BASE DE DATOS) │
│ • PostgreSQL 15 Relacional en VPS Cloud (Conexión SSH / Tailscale 100.68.100.25) │
│ • Tablas Principales: cliente, venta, facturas_solicitadas, centros_apoyo, activos │
│ • Tablas de Auditoría e IA: master_audit_log, ai_event_logs, conciliacion_bancaria │
└────────────────────────────────────────────────────────────────────────────────────────┘
2. Diccionario Maestro de Base de Datos PostgreSQL
2.1 Tabla `cliente` (Padrón de Socios y Usuarios)
CREATE TABLE cliente (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
registro INTEGER UNIQUE NOT NULL, -- Número de socio oficial (ej. 80000, 10700)
nombre VARCHAR(100) NOT NULL,
ape_p VARCHAR(100),
ape_m VARCHAR(100),
email VARCHAR(150),
whatsapp VARCHAR(25),
tel VARCHAR(25),
password VARCHAR(255), -- Hash bcrypt ($2y$... normalizado a $2a$)
rol_id UUID REFERENCES rol(id),
patrocinador INTEGER, -- Registro del líder ascendente
cedis_id INTEGER, -- CEDIS de surtido habitual
active_id INTEGER DEFAULT 1, -- 1: Activo, 0: Baja
created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);
CREATE INDEX idx_cliente_registro ON cliente(registro);
CREATE INDEX idx_cliente_patrocinador ON cliente(patrocinador);
2.2 Tabla `venta` (Transacciones y Notas de Pedido)
CREATE TABLE venta (
id VARCHAR(100) PRIMARY KEY, -- Folio o UUID de nota (ej. a6cff756-867...)
cliente_id UUID REFERENCES cliente(id),
centro_apoyo_id INTEGER, -- CEDIS donde se operó la venta
total NUMERIC(12,2) NOT NULL,
cantidad NUMERIC(8,2) DEFAULT 1, -- Número de cajas amparadas
activaciones_usadas INTEGER DEFAULT 0, -- Cupos de activación consumidos
approved INTEGER DEFAULT 0, -- 1: Cobrada/Autorizada, 0: Pendiente
tipo_pago VARCHAR(50), -- Transferencia, Efectivo, MercadoPago, etc.
fecha_venta TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
producto_id VARCHAR(50), -- 'calificacion-mes' para activaciones virtuales
comentario TEXT, -- Desglose de piezas, destinatario, depósito
factura_emitida BOOLEAN DEFAULT FALSE,
factura_uuid VARCHAR(100),
requiere_factura BOOLEAN DEFAULT FALSE
);
CREATE INDEX idx_venta_cliente_approved ON venta(cliente_id, approved);
CREATE INDEX idx_venta_fecha ON venta(fecha_venta);
2.3 Tabla `facturas_solicitadas` (CFDI 4.0 & Facturama)
CREATE TABLE facturas_solicitadas (
id BIGSERIAL PRIMARY KEY,
cfdi_id VARCHAR(100), -- ID interno en Facturama
cfdi_uuid VARCHAR(100), -- UUID fiscal del SAT (Timbre Fiscal Digital)
numero_nota VARCHAR(100), -- ID de venta o Folio GLOBAL-YYYY-MM / CENTRO-ID
rfc VARCHAR(20) NOT NULL,
razon_social VARCHAR(255),
regimen VARCHAR(10), -- 601, 612, 616, 626, etc.
cp VARCHAR(10),
uso_cfdi VARCHAR(10), -- G01, G03, S01, etc.
forma_pago VARCHAR(10), -- 01 (Efectivo), 03 (Transferencia), etc.
total NUMERIC(12,2) NOT NULL,
monto_facturable NUMERIC(12,2),
estado VARCHAR(30) DEFAULT 'pendiente', -- 'pendiente', 'facturada', 'cancelada'
motivo_cancelacion VARCHAR(10), -- '01', '02', '03', '04'
uuid_sustitucion VARCHAR(100), -- UUID nuevo en caso de sustitución 01
ventas_ids JSONB, -- Array de IDs de notas agrupadas en la global
fecha_solicitud TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
fecha_facturacion TIMESTAMP WITH TIME ZONE,
fecha_cancelacion TIMESTAMP WITH TIME ZONE
);
2.4 Tabla `centros_apoyo` (CEDIS Físicos 1 al 15)
CREATE TABLE centros_apoyo (
id SERIAL PRIMARY KEY,
nombre VARCHAR(150) NOT NULL,
numero_centro INTEGER UNIQUE,
lider_id UUID REFERENCES cliente(id),
direccion TEXT,
telefono VARCHAR(50),
limite_credito NUMERIC(12,2) DEFAULT 100000.00,
saldo_deudor NUMERIC(12,2) DEFAULT 0.00,
comision_porcentaje NUMERIC(5,2) DEFAULT 10.00,
estado VARCHAR(20) DEFAULT 'activo'
);
3. Arquitectura Frontend Modular en JavaScript (15+ Bundles)
Para optimizar tiempos de carga (<400ms) y cumplir con los límites de tamaño de archivo en Shopify, la lógica se encuentra desacoplada en bundles modulares dentro de pagina 2026/backoffice/js/ y shopify pagina 2026/assets/:
| Archivo JS |
Peso |
Capa / Responsabilidad Técnica |
bo-core.js |
~101 KB |
Inicialización del DOM, enrutador de vistas SPA, formatters y helpers de UI. |
bo-auth.js |
~10 KB |
Gestión de sesiones JWT, control de roles (RBAC) y logout seguro. |
bo-ventas.js |
~1.1 MB |
Motor de ventas, captura de pedidos, validación de pago mixto y renderizado. |
bo-facturacion.js |
~320 KB |
Interfaz del SAT CFDI 4.0, Facturama API, facturación global y visor de notas. |
bo-facturacion2.js |
~100 KB |
Asistente de sustitución en 2 pasos, cancelación SAT y validaciones Anexo 20. |
centros-apoyo-detail.js |
~270 KB |
Gestión de CEDIS 1-15, Cola #230, asignación multi-caja y conciliación de stock. |
bo-activos.js |
~105 KB |
Motor de comisiones N1-N4, deducciones de monedero y algoritmo FIFO. |
bo-produccion.js |
~448 KB |
Lotes de planta, cálculo de mermas, formulación de sabores y empaque. |
bo-materias.js |
~235 KB |
Control de existencias de suero suizo, saborizantes, potes y empaque. |
bo-tree.js |
~11 KB |
Renderizador gráfico de genealogía multinivel Canvas / SVG. |
bo-config.js |
~93 KB |
Parámetros globales del sistema, listas de precios y llaves API. |
4. Ecosistema de Workflows n8n & API Endpoints
Los flujos se mantienen sincronizados mediante el CLI n8nac en workflows/default/:
# Estado del entorno de n8n
npx --yes n8nac env status --json
# Push de un workflow específico
npx --yes n8nac push "workflows/default/Backoffice - Motor de Facturacion.workflow.ts"
Endpoints REST Clave
| Endpoint |
Método |
Workflow Responsable |
Descripción |
/webhook/bo/auth/login |
POST |
Backoffice - Auth |
Autenticación con hash bcrypt y entrega de token JWT. |
/webhook/bo/sql-relay |
POST |
Backoffice - SQL Relay |
Relay parametrizado para consultas protegidas con token secreto. |
/webhook/bo/factura/emitir |
POST |
Backoffice - Motor de Facturacion |
Genera y timbra CFDI 4.0 individual o global en Facturama. |
/webhook/bo/factura/cancelar |
POST |
Backoffice - Facturama CFDI |
Solicita cancelación ante el SAT con motivo (01, 02, 03, 04). |
/webhook/bo/master/query |
POST |
Master Gateway |
Ejecución de queries de diagnóstico en Portal Ops con límite de seguridad. |
5. Motor Fiscal CFDI 4.0 & Facturama API Gateway
5.1 Estructura del Payload para Factura Global
const payloadGlobal = {
Receiver: {
Rfc: "XAXX010101000",
Name: "PUBLICO EN GENERAL",
CfdiUse: "S01",
FiscalRegime: "616",
TaxZipCode: taxZipCode // CP del emisor / CEDIS
},
CfdiType: "I",
Currency: "MXN",
PaymentForm: paymentFormCode, // "01", "03", "04", etc.
PaymentMethod: "PUE",
ExpeditionPlace: taxZipCode,
Items: finalFacturamaItems,
GlobalInformation: {
Periodicity: "04", // 04: Mensual, 01: Diario
Months: mesFiscalStr, // "08" para Agosto, "09" para Septiembre
Year: anioFiscalStr // "2026"
}
};
5.2 Algoritmo de Sustitución en 2 Pasos (SAT Motivo 01)
- Paso 1: Se emite la nueva factura incluyendo el nodo
CfdiRelacionados:
`javascript
payload.Relations = {
Type: "04", // Sustitución de los CFDI previos
Cfdis: [uuidOriginal]
};
`
- Paso 2: Una vez timbrada la nueva factura y obtenido su nuevo
uuidSustituto, se invoca la API de cancelación sobre la factura previa:
`javascript
POST /bo/factura/cancelar
{
cfdiId: cfdiIdOriginal,
motivo: "01",
uuidReplacement: uuidSustituto
}
`
6. Motor de Activaciones (#230) & Asignación Multi-Caja
Para notas que amparan múltiples cajas (ej. $9,500.00 = 2 cajas, $19,000.00 = 4 cajas, $45,000.00 = 10 cajas):
- Capacidad Real:
cajas = Math.max(1, Math.round(parseFloat(v.cantidad) || 1))
- Cupos Consumidos:
usadas = parseInt(v.activaciones_usadas) || 0
- Cupos Disponibles:
disponibles = cajas - usadas
Generación de Activación Virtual en Base de Datos:
-- 1. Insertar nota de activación calificacion-mes con importe $0.00
INSERT INTO venta (id, cliente_id, total, cantidad, approved, fecha_venta, producto_id, comentario)
VALUES (
'ACT-PA-' || upper(substring(md5(random()::text) from 1 for 8)),
:lider_uuid,
0.00,
1,
1,
:fecha_activacion_sql,
'calificacion-mes',
'ACTIVACION PAGO ADQUIRIDO || RESPALDO NOTA ' || :nota_respaldo_id || ' || LIDER #' || :lider_registro
);
-- 2. Incrementar contador de cupos usados en la nota de respaldo
UPDATE venta
SET activaciones_usadas = COALESCE(activaciones_usadas, 0) + :cantidad_activada
WHERE id = :nota_respaldo_id;
7. Algoritmo de Monedero de Activos FIFO & Compensación
Para evitar distorsiones contables y expiración injusta de saldo, las deducciones de activos se realizan mediante consumo secuencial del saldo más antiguo:
[Bono Registro Enero $1,000] ──> [Bono Red Febrero $2,000] ──> [Abono Marzo $1,500]
│
▼ Compra de $1,500 en Abril
Consume $1,000 de Enero (Agotado) + $500 de Febrero ($1,500 Restante)
Expresión CTE Recursiva de Compensación Multinivel:
WITH RECURSIVE cadena_red AS (
SELECT id, registro, nombre, ape_p, patrocinador, 1 AS nivel
FROM cliente
WHERE patrocinador = :registro_lider AND active_id = 1
UNION ALL
SELECT c.id, c.registro, c.nombre, c.ape_p, c.patrocinador, cr.nivel + 1
FROM cliente c
INNER JOIN cadena_red cr ON c.patrocinador = cr.registro
WHERE cr.nivel < 4 AND c.active_id = 1
)
SELECT cr.nivel, COUNT(DISTINCT cr.id) AS socios_activos, COALESCE(SUM(v.total), 0) AS volumen_nivel
FROM cadena_red cr
LEFT JOIN venta v ON cr.id = v.cliente_id AND v.approved = 1 AND TO_CHAR(v.fecha_venta, 'YYYY-MM') = :mes_periodo
GROUP BY cr.nivel
ORDER BY cr.nivel;
8. Motor de Conciliación Bancaria 9-en-1
El módulo de conciliación procesa extractos mediante 9 parsers especializados:
parser_bbva.js: Detecta depósitos en ventanilla, transferencias SPEI y cobros Cie.
parser_santander.js: Cruza referencias numéricas de 10 dígitos.
parser_mercadopago.js: Desglosa comisión por cobro con tarjeta vs depósito neto.
parser_paypal.js: Convierte pagos en USD a MXN con tipo de cambio de la transacción.
parser_stripe.js: Extrae identificadores pi_... y cruza contra venta.id.
parser_clip.js: Procesa transacciones de terminales punto de venta físicas.
parser_shopify.js: Cruza números de orden #DULETIA-....
parser_cedis.js: Cuadra remesas en efectivo entregadas por operadores de centros.
matcher_core.js: Algoritmo de ponderación (Fecha $\pm 3$ días, Monto exacto, Nombre/Referencia).
9. Módulos Industriales: Producción, Rendimiento y Kárdex
9.1 Registro de Lote Industrial (`produccion_diaria`)
$$\text{Rendimiento (\%)} = \frac{\text{Kilos Producidos Reales}}{\text{Kilos de Materia Prima Teóricos}} \times 100$$
- Control de Merma: Si la merma supera el 3.5%, el sistema exige captura de justificación obligatoria antes del cierre del lote.
9.2 Motor de Costeo y Absorción Industrial
El cálculo del costo unitario absorbido se ejecuta de forma desacoplada en bo-materias.js (ejecutarCierreCostos) y bo-produccion.js. Cada lote en produccion_diaria contiene cinco columnas numéricas de costo:
costo_materia_prima: Sumatoria de insumos consumidos según el BOM (formulacion_componentes).
kg_merma y costo_merma: Pérdida física valorizada al costo unitario de formulación.
costo_prorrateo: Costo fijo de almacenamiento (renta y energía eléctrica de Planta 1 y 2 en sistema_config).
costo_mod: Mano de obra directa asignada según el volumen del lote.
costo_depreciacion: Cuota mensual de desgaste de activos de manufactura (activos_fijos).
$$\text{Costo Total Lote} = \text{MP} + \text{Merma} + \text{Prorrateo Bodega} + \text{MOD} + \text{Depreciación}$$
9.3 Motor de Nómina y Mano de Obra Directa (MOD)
- Tablas de Persistencia:
operarios_produccion: Catálogo maestro de colaboradores activos con rol (es_mod = true para producción DI, false para G&A), empresa (DI, DG), sueldo mensual, horas mes (192 estándar) y Salario Base de Cotización (sbc).
nominas_recibos: Registro de comprobantes CFDI timbrados SAT (importación XML) con desglose de percepciones, deducciones, ISR retenido, IMSS obrero y días pagados.
gastos_mensuales: Tabla contable donde se asienta la nómina mensual devengada con subcategoria = 'nomina_directa' (Costo Variable MOD) y 'nomina_admin' (Costo Fijo G&A).
- Cálculo de Jornada y Días del Personal:
- Base de cálculo: 24 días laborales al mes (jornada estándar industrial DI: $192\text{ hrs} \div 8\text{ hrs/día}$).
- Promedio general diario de planta:
$$\text{Promedio Diario Planta} = \frac{\sum \text{Unidades Mes}}{\text{Días Laborales Personal (24)}}$$
$$\text{Costo MOD / Bote} = \frac{\text{MOD DI Total Mes}}{\sum \text{Unidades Mes}}$$
- Factor de Carga Patronal: Si el colaborador tiene
sbc > 0, se aplica un 32.5% sobre la base cotizada; en caso contrario, se aplica el factor estándar 44.7% sobre el sueldo bruto.
9.4 Lógica Multicompañía y Reglas de Consolidación P&L
El cálculo del Estado de Resultados en loadCostosView() varía de forma determinista según la entidad seleccionada:
- DI (Dulet Internacional - Fábrica):
- $\text{Ingresos} = \text{Unidades Fabricadas} \times \text{Precio Inter-Cía}$ (
config_precios_intercia).
- $\text{COGS} = \text{Costo de Materia Prima}$.
- DG (Dulet Group - Distribución México):
- $\text{Ingresos} = \text{Ventas al Consumidor Final}$ (
venta).
- $\text{COGS} = \text{Compras a DI}$ (Costo Inter-Cía).
- LLC (Dulet USA):
- $\text{Ingresos} = \text{Ventas en Dólares (USD)}$ de CEDIS 4.
- $\text{COGS} = \text{Transferencias en } \text{ventas\_intercompania}$.
- DC & DS (Servicios Educativos y Holding):
- $\text{Ingresos} = \text{Cobro de servicios a DG/DI}$ (
servicios_dc, servicios_ds).
- ALL (Consolidado de Grupo):
- $\text{Ingresos} = \text{Ventas DG} + \text{Ventas LLC}$.
- $\text{COGS} = \text{Costo Real de Materia Prima DI}$.
- Neutralización Inter-Cía: Deduce automáticamente del OPEX los montos registrados en
servicios_dc y servicios_ds para eliminar ingresos/gastos espejo.
10. Portal Master Gateway (/pages/ops) & Observabilidad IA
El portal /pages/ops expone herramientas de nivel Root para el equipo de ingeniería:
- Observabilidad en Tiempo Real: Métricas de CPU, latencia de consultas SQL y conteo de eventos de IA en
ai_event_logs.
- SQL Runner con Sandboxing: Ejecuta queries de soporte en modo solo lectura o transacción controlada con límite forzado de 500 registros.
- Auditoría Forense: Registro de cada sesión, IP y User-Agent en
master_audit_log.
11. Protocolo Obligatorio Dual Deploy (Cloudflare + Shopify)
Todo cambio en el código fuente debe seguir de manera estricta el Protocolo Dual Deploy:
# 1. Modificar archivos locales en 'pagina 2026/'
# 2. Despliegue a Cloudflare Pages
export CLOUDFLARE_API_TOKEN="cfut_..."
npx --yes wrangler pages deploy "/Users/BryanMalfavon/Downloads/DULETIA/pagina 2026" --project-name="dulet-backoffice" --branch="main" --no-bundle
# 3. Sincronización y Push a Shopify Themes
python3 sync_shopify.py --push
12. Guía de Diagnóstico, Testing y Resolución de Incidencias
Incidencia 1: El botón de activar en la Cola #230 no responde
- Causa Raíz: Comentario de nota con saltos de línea (
\n) o comillas inyectadas dentro de un atributo HTML inline.
- Solución Técnica: Pasar únicamente el ID a la función
onclick="activarLiderDesdeNota('${r.id}')" y recuperar los datos del objeto o base de datos de manera limpia.
Incidencia 2: Factura rechazada por Facturama con error en código postal
- Causa Raíz: Para Público en General (
XAXX010101000), el SAT CFDI 4.0 exige que el TaxZipCode del receptor sea idéntico al ExpeditionPlace del emisor.
- Solución Técnica: En
Backoffice - Motor de Facturacion.workflow.ts, forzar taxZipCode del emisor cuando Rfc === 'XAXX010101000'.
13. Apartado Especial: Arquitectura Técnica de DuletIA Core & Orquestación de My workflow 8
> [!IMPORTANT]
> My workflow 8 (My workflow 8.workflow.ts) constituye el cerebro de Inteligencia Artificial más sofisticado de Duletia. Con 165 nodos activos y 104 conexiones dirigidas, implementa un patrón Supervisor / Sub-Agentes Multi-Especialista basado en LangChain sobre n8n, capaz de procesar flujos multimodales (Texto, Voz STT Whisper, Visión OCR y Documentos PDF) con tolerancia a fallas y sincronización transaccional directa a PostgreSQL.
13.1 Topología y Flujo de Ejecución End-to-End
[CANAL CLIENTE: WhatsApp / Kommo CRM]
│
▼ Webhook HTTP (`new_message`)
┌───────────────────────────────────┐
│ OAuth2 Token & Filtro `Parar la IA`│
└─────────────────┬─────────────────┘
│
▼
┌───────────────────────────────────────────┐
│ DISCRIMINADOR DE FORMATO MULTIMODAL │
├─────────────┬─────────────┬───────────────┤
│ IF Texto │ IF Voz │ IF Imagen │ (IF File / PDF)
└──────┬──────┴──────┬──────┴───────┬───────┘
│ │ │
│ ▼ ▼
│ [Whisper STT] [Vision OCR]
│ │ │
└──────┬──────┴──────────────┘
│
▼
┌───────────────────────────────────────────┐
│ COLA DE DEBOUNCE ASÍNCRONO (PostgreSQL) │
│ • Tablas: `chat_debounce`, `message_buf` │
│ • Nodos: `PG Insert Buffer` │
│ • Consolidación: `PG Merge Messages` │
└─────────────────────┬─────────────────────┘
│ `merged_text`
▼
┌───────────────────────────────────────────┐
│ AGENTE SUPERVISOR CORE: `DuletIA` │
│ • Tipo: `@n8n/n8n-nodes-langchain.agent` │
│ • Modelo: OpenAI GPT-4o (`Model4`) │
│ • Memoria: `PostgresChatMemory` │
│ • Salida: JSON Estricto Multicapa │
└─────────────────────┬─────────────────────┘
│ Herramientas Dinámicas
┌──────────────┬──────────────┬───────┴──────┬──────────────┬──────────────┐
▼ ▼ ▼ ▼ ▼ ▼
┌───────────┐ ┌───────────┐ ┌───────────┐ ┌───────────┐ ┌───────────┐ ┌───────────┐
│ PEDIDOS │ │ TICKETS │ │ ENVIOS │ │ FACTURAS │ │ ESPECIAL │ │ COACHING │
│ agentTool │ │ agentTool │ │ agentTool │ │ agentTool │ │ agentTool │ │ agentTool │
└─────┬─────┘ └─────┬─────┘ └─────┬─────┘ └─────┬─────┘ └─────┬─────┘ └─────┬─────┘
│ │ │ │ │ │
└──────────────┴──────────────┼──────────────┴──────────────┴──────────────┘
▼
┌───────────────────────────────────────────┐
│ GATEWAY BACKOFFICE & BASE DE DATOS │
│ • `AI Venta HTTP` (Venta & Folio UUID) │
│ • `AI Cobrar Activos HTTP` (FIFO Engine) │
│ • `AI Ticket Pago HTTP` (Audit Comprob) │
│ • `AI Auth Cadena HTTP` (Validación NIP) │
│ • `AI Factura Solicitar HTTP` (CFDI 4.0) │
└─────────────────────┬─────────────────────┘
│ JSON Formateado
▼
┌───────────────────────────────────────────┐
│ DESPACHO & HANDOFF A KOMMO CRM │
│ • `Switch5` (Validación de payload) │
│ • `Get token27` (Kommo OAuth2 Refresh) │
│ • `Enviar el mensaje12` (Kommo API v4) │
└───────────────────────────────────────────┘
13.2 Pipeline Anti-Tormenta (Debounce) en PostgreSQL
Uno de los principales problemas de los chatbots conectados a WhatsApp es la "tormenta de mensajes": usuarios que envían 4 o 5 audios o textos fraccionados en un lapso de 10 segundos. Si el sistema ejecutara el LLM en cada mensaje entrante, causaría:
- Carreras críticas de concurrencia y sobreescritura de pedidos en la BD.
- Respuestas fragmentadas o contradictorias enviadas al cliente.
- Consumo desmedido y multiplicación por $N$ del costo en tokens de OpenAI.
Solución Implementada con Doble Nodo PostgreSQL:
- Paso 1 (
PG Insert Buffer): Al recibir un webhook, se inserta el fragmento en la tabla message_buffer con chat_id, payload y timestamp Unix.
- Paso 2 (
chat_debounce): Se verifica si existe un temporizador activo (waitSeconds entre 5s y 15s). Si el temporizador sigue corriendo, el webhook actual se almacena silenciosamente y finaliza sin despertar al LLM.
- Paso 3 (
PG Merge Messages): Al expirar la ventana de silencio, una sola tarea recupera todos los fragmentos acumulados en message_buffer, los concatena cronológicamente en la variable merged_text y despierta una única vez al Agente Supervisor DuletIA.
13.3 Agente Supervisor Core (`Duletia`) y Esquema de Memoria
El nodo Duletia opera como el orquestador principal configurado con @n8n/n8n-nodes-langchain.agent v1.6.
Esquema de Salida JSON Estricto
El agente está obligado por su systemMessage a emitir exclusivamente una respuesta en formato JSON sin delimitadores de código markdown que cumple con la siguiente estructura:
{
"estado_conversacion": {
"respuestausuario": "Texto cálido estilo Modo Disney con 2 a 6 emojis...",
"Tipo": "Pedido | ticket | envios | Factura | especial | coaching | neutral",
"Sentimiento": "feliz | neutral | enojado",
"Etapa": "inicio | capturando_datos | armando_pedido | validando_ticket | pendiente_revision | cerrado",
"asesor": "ninguno | coaching | nutricion | vip | logistica | molesto"
},
"usuario_identificacion": {
"nombre": "Ricardo",
"apellido": "Chávez",
"correo": "ricardo@ejemplo.com",
"celular": "3311572150",
"ciudad": "Guadalajara",
"ID": "1045",
"patrocinador": "2"
},
"pedido_actual": {
"cajas_totales": 2,
"productos_por_caja": [
{ "caja": 1, "dulet": 12, "eucament": 0, "cliente_registro": "1045" },
{ "caja": 2, "dulet": 6, "eucament": 6, "cliente_registro": "2088" }
],
"numero_nota": "A8F1C3E2",
"monto_total_esperado": 5000.00,
"metodo_entrega": "envio_domicilio",
"metodo_pago": "mixto"
},
"validacion_ticket": {
"banco": "BBVA",
"monto_detectado": 4000.00,
"referencia": "7891234",
"link_de_pago": "https://drive.google.com/..."
},
"datos_extra": {}
}
Políticas de Gestión de Estado:
- Memoria Inmutable (LTM - Long Term Memory): El nodo
Chat Memory Manager y PostgresChatMemory1 asocian el historial a la sesión de Kommo. El bloque usuario_identificacion se congela una vez resuelto y persiste a través de todos los turnos.
- Reset Anti-Duplicados: Si la
Etapa previa fue pendiente_revision o cerrado y el usuario solicita una nueva compra, el sistema purga automáticamente los objetos pedido_actual y validacion_ticket para evitar sobreescritura de notas anteriores.
13.4 Especificación de los 6 Sub-Agentes (`agentTool`)
Cada sub-agente está instanciado como un nodo @n8n/n8n-nodes-langchain.agentTool v2.2 y posee un conjunto desacoplado de herramientas y reglas de ejecución:
| Sub-Agente |
LangChain Node ID |
Herramientas Conectadas |
Reglas de Blindaje & Anti-Loop |
pedidos |
076a664a-337d-4a95-ad37-3d64a01b854c |
AI Precios Internos HTTP, Calculator4, Think2, AI Nota Check HTTP, AI Venta HTTP, AI Cobrar Activos HTTP, AI Activos HTTP, AI Nota Crear HTTP, CreaProducto, CreaLink |
Freno Anti-Bucle: Prohibido reintentar si AI Venta HTTP devuelve ok:false. En caso de fallo asigna folio "PENDIENTE" y continúa. Máximo 2 llamadas multicaja. |
tickets |
1a40d15c-2231-4f30-8cef-63e8cb158b81 |
AI Mis Ventas HTTP, Think7, AI Ticket Pago HTTP, AI Pagos HTTP, SubirPagos (Sheets), AI Nota Editar HTTP, Calculator |
Append Inmutable: No sobreescribe el comentario de venta; añade al final `\ |
\ |
BANCO $MONTO Ref:XXX`. Valida lista blanca de 10 bancos autorizados. |
envios |
cf5664e9-1156-41e1-ba4e-f3cb8d9ac51a |
ver envios (Sheets), AI Mis Ventas HTTP, Think3 |
Soporte Multicaja: Genera un array envios_detectados con guia, paqueteria, Nombre_de_envio y estado independiente por caja. |
facturas |
34dace1d-6351-40bb-b236-80bb6ee33a90 |
AI Mis Ventas HTTP, Think6, Facturacion1, ComparteFactura, AI Factura Solicitar HTTP |
Agrupación UUID: Si el cliente solicita facturar múltiples compras, recopila los UUIDs y ejecuta una sola llamada a AI Factura Solicitar HTTP. |
especial |
bc121edf-0931-497a-a9ec-70617d752ac4 |
AI Auth Cadena HTTP, AI Activos HTTP, AI Mis Ventas HTTP, RevisaPedidos1, Think5, Calculator6 |
Seguridad NIP: Máximo 3 intentos de PIN. Si falla cambia a Etapa="bloqueado". Ejecuta Motor de Reglas (Regla N-1, penalización frontales y desglose 4 niveles). |
coaching |
549b3025-848d-484d-80a4-3e34446038fe |
Calculator5, Think4, RevistaDul, DefinicionCoach |
Handoff a Telegram: Emite "asesor": "coaching" para disparar alerta en tiempo real al canal de Telegram de Dirección de Liderazgo. |
13.5 Conectores HTTP Internos al Backoffice
Los sub-agentes se comunican con los microservicios del Backoffice a través de webhooks internos protegidos:
┌──────────────────────────────┬────────────────────────────────────────────────────────┐
│ Conector HTTP Interno │ Operación Técnica Ejecutada en Base de Datos │
├──────────────────────────────┼────────────────────────────────────────────────────────┤
│ `AI Venta HTTP` │ INSERT en `venta` con cálculo de comisiones e IVA. │
│ `AI Precios Internos HTTP` │ SELECT de matriz de descuentos por escala de compra. │
│ `AI Cobrar Activos HTTP` │ UPDATE en `activos` aplicando consumo FIFO por mes. │
│ `AI Activos HTTP` │ Cálculo dinámico de activos (Regla N-1 + Frontales). │
│ `AI Auth Cadena HTTP` │ SELECT con validación de hash de NIP en `cliente`. │
│ `AI Ticket Pago HTTP` │ INSERT en tabla de verificación de depósitos bancarios.│
│ `AI Nota Editar HTTP` │ UPDATE de campo `comentario` en `venta` con separador. │
│ `AI Factura Solicitar HTTP` │ INSERT en `facturas_solicitadas` para revisión PAC. │
│ `AI Mis Ventas HTTP` │ SELECT filtrado por `cliente_id` y rango de fechas. │
└──────────────────────────────┴────────────────────────────────────────────────────────┘
13.6 Benchmarks de Capacidad, Concurrencia y Resiliencia
1. Capacidad Transaccional del Motor de IA
- Concurrencia Soportada: Hasta 100 conversaciones activas simultáneas sin degradación de estado gracias al pooling de conexiones PostgreSQL y el aislamiento de memoria en
crm_memory.
- Latencia de Respuesta Promedio:
- Mensaje de texto simple: 1.8 a 2.4 segundos.
- Mensaje de voz (Whisper STT + Razonamiento): 4.2 a 5.8 segundos.
- Comprobante gráfico (Visión OCR + Sub-Agente Tickets + BD): 5.5 a 7.8 segundos.
- Tasa de Acierto de Folio: 99.8% de precisión en la deducción de números de folio y cuentas bancarias.
2. Correlación con la Capacidad Física de Manufactura
El ecosistema de Duletia evita la sobresaturación de pedidos manteniendo una alineación estricta entre la capacidad de toma de pedidos de la IA y el Módulo 20 de Costos y Producción:
$$\text{Capacidad Fábrica} = 24 \text{ días laborables} \times 907 \frac{\text{botes}}{\text{día}} \approx 21,768 \frac{\text{botes}}{\text{mes}} \quad (\text{1 Turno Industrial})$$
Cuando los sub-agentes detectan picos de demanda que se aproximan a la capacidad máxima de salida del Almacén Central, los tiempos de entrega proyectados se extienden dinámicamente de forma automática en los mensajes de confirmación de pedido para proteger el SLA operativo de la empresa.
*Manual Técnico & Arquitectura de Software — Dulet International Group & Dulet Group LLC v4.0*