Cómo funciona el panel NODO por dentro.

1. Alcance y entregables

2. Roles, login y acceso

Login provisional del prototipo

• 1 / 1 → Admin NODO (empieza en "Todas las marcas").
• <id de marca> / 1 → esa marca en rol dueño (ej. meno, tala, nativa-allura, purewall).
• Deep links para demos: portal.html?demo=1&brand=meno&view=envios&dev=1.

Login real

POST /auth/login {email, password}  → {access_token (JWT 15 min), refresh_token}
JWT payload: {user_id, role, brand_ids[], is_nodo_admin}
Toda consulta filtra por brand_id del token salvo is_nodo_admin.
Opcional: magic link por WhatsApp (el dueño casi nunca tiene la clave a mano).

3. Arquitectura

• Backend: API REST (o GraphQL) + base relacional (PostgreSQL) + cola de eventos (Redis/SQS) para webhooks e integraciones. Multi-tenant por brand_id.
• Frontend: SPA (React/Vue) con el mismo mapa de vistas que el prototipo. El prototipo ya define layout, componentes y textos.
• Tiempo real: WebSocket para mapa en vivo, pipeline y bandeja de atención.
• IA: servicio separado que expone /ai/chat (Capitán) y /ai/reply (atención al cliente) usando un modelo de lenguaje con tool use y RAG sobre la base de conocimiento de cada marca.
• Jobs: cron 06:30 planificación de rutas y colectas; nocturno recálculo de KPIs, score, reposición, cash flow; cada 2 min polling de canales sin webhook.

4. Modelo de datos

Tablas principales. Todas con brand_id, created_at, updated_at.

5. Estados de un envío

pending_pack ──► ready ──► admitted ──► in_transit ──► out_for_delivery ──► delivered
   │              │           (colecta        (troncal)        │        │
   │              │            escaneada)                      │        ├──► failed_visit ──► out_for_delivery (reprogramado)
   │              │                                            │        │                └──► at_branch ──► delivered | returned
   └── address_incomplete ──► ready (al corregir)              │        └──► rejected ──► returned
                                                               └──► returned ──► received_hub ──► restocked | discarded

6. Integraciones

7. Eventos y webhooks (bus interno)

Todo cambio relevante se publica como evento en la cola. Los consumidores son: notificaciones (WhatsApp/mail), motor de reglas (alertas), KPIs, tienda (fulfillment), IA (memoria).

8. Importar el consolidado Excel

NODO_Consolidado_Marcas.xlsx tiene tres tipos de hoja. El importador tiene que leerlas así:

Hoja BASE_DATOS (48.316 filas) → semilla de demanda

Hojas M01…M17 (una por marca)

• Períodos por canal (filas 4–7): canal, desde, hasta, días → brand_channels.
• Tabla 1 Ficha de productos: producto, SKU, medidas, m³, kg, packaging, bolsa, etiqueta, kit → skus. Cada "FALTA DATO" → data_gaps.
• Tabla 5 Calendario operativo: paquetes por día de semana → brand_weekday_profile (se usa para colectas hasta tener 8 semanas de datos reales).
• Tabla 6 Situación actual: ticket promedio, unidades por pedido, operador actual, dirección de origen, costo de envío actual → brands + brand_benchmarks.
• Lectura logística: texto → brand_notes (se muestra al admin).
• Tabla 7 Pendientes: dato, por qué, prioridad, estado → data_gaps.

Fórmulas del Excel que el sistema replica

Inicio

Reglas de alertas (motor)

• failed_visits_today ≥ 3 → severidad alta, impacto = n × ticket.
• stock_cover_days(sku) < 5 → alta, impacto = ventas perdidas estimadas.
• unused_labels > 10 → media, impacto = n × costo.
• pickup_tomorrow.status = scheduled → informativa.
• credit_line.available > 0 AND saldo_dias < 5 → oferta de financiación.

Capitán NODO (IA)

Agente conversacional con acceso a los datos de la marca y capacidad de ejecutar acciones. Equivale al módulo Mindy de QuadMinds, ampliado con tienda, stock, cobros y financiación.

POST /ai/chat {brand_id, conversation_id, message}
System prompt: contexto de marca (nombre, tono, políticas, KPIs del día) + memoria (ai_memory)
Tools (JSON schema):
  get_pipeline(brand_id)                         → conteos por estado
  list_shipments(brand_id, {status, zone, since}) → lista
  get_kpis(brand_id, days)                        → KPIs del período
  reschedule_visits(shipment_ids[], window)       → QuadMinds PUT /visits + WhatsApp   [requiere confirmación]
  send_whatsapp(template_id, shipment_ids[], vars)→ WhatsApp API                        [requiere confirmación]
  create_pickup(brand_id, date, window, items)    → pickups + QuadMinds                 [requiere confirmación]
  stock_forecast(brand_id, days)                  → unidades a comprar por SKU
  advance_offer(brand_id)                         → línea disponible y costo
  open_ticket(brand_id, subject, order_id)        → tickets
Respuesta: texto + acciones propuestas (botones) → action_requests (proposed) → al confirmar: executed

• Nivel de autonomía por marca (ai_autonomy_level): 0 = solo propone; 1 = ejecuta acciones de bajo riesgo (avisos, reprogramaciones); 2 = ejecuta también colectas y compras sugeridas.
• Todo queda en ai_actions y se muestra en "Lo que hizo hoy solo".
• Memoria: ai_memory por marca con preferencias del dueño ("no me avises los sábados", "siempre ventana de mañana en Rosario").

Órdenes

Envíos (QuadMinds)

Módulos de QuadMinds que se usan

• Planificador de rutas (optimización multi-restricción, multi-depósito).
• Seguimiento de rutas (GPS, cumplimiento de secuencia, alertas, agregar/quitar/transferir órdenes en ruta).
• Driver App (secuencia, llegada, entrega/falla con motivo, foto, firma, cobranza).
• Torre de control (viajes troncales entre hubs, kanban).
• Portal de órdenes (link público de seguimiento por pedido).
• Add-ons: módulo de cobranzas (contra reembolso), liquidación de viajes (transportes terceros), control de emisiones, IoT (temperatura).

Colectas

• Generación: cron nocturno crea la colecta del día siguiente por marca según pickup_days; est_items = COUNT(orders paid AND shipment.status IN (pending_pack, ready) AND pickup_id IS NULL); est_m3/est_kg desde skus; vehículo por regla de m³. Se reajusta a las 06:30 con las ventas de la noche.
• Ruta de colectas: todas las colectas de la zona se envían a QuadMinds como visitas tipo pickup en una ruta de colectas separada de la de reparto.
• Ejecución: Driver App escanea cada QR → pickup.scanned → shipment pasa a admitted. Declarados vs escaneados → discrepancies con foto. Remito digital firmado.
• Colecta en fabricante: pickup_points.type = manufacturer con expected_items[] (remito). Al ingresar al hub: stock_movements inbound por SKU y comparación con remito.
• Tu semana operativa: perfil por día de semana (Tabla 5 del consolidado, luego promedio móvil 8 semanas).
• Pedir colecta extra / cambiar ventana: POST /pickups, PUT /pickups/{id}; confirmación por WhatsApp a la marca.

Inventario

• Stock unificado: available = on_hand − reserved por SKU (suma de hubs). Se empuja a todos los canales en < 60 s en cada cambio. Race entre canales → backorder + aviso IA al cliente.
• Comprometido: suscripciones a 7 días + órdenes pagas no despachadas.
• Cobertura: on_hand / AVG(units_out_per_day, 14d). Semáforo: ≤ 5 rojo, ≤ 12 ámbar.
• Reposición sugerida: punto de pedido = lead_time_days × salida_dia + stock_seguridad; cantidad = salida_dia × 21 + comprometido. Un clic → pickup en fabricante con remito.
• Depósitos: distribución sugerida por % de envíos por región; posiciones de rack = ROUNDUP(m³ 7 días / 1,2).
• Ficha de SKU: medidas, kg, packaging, bolsa, etiqueta, kit, costo, días de consumo (para recompra). Los flags en "FALTA DATO" se muestran como pendientes.
• Kits: si needs_kit, el picking lista componentes y descuenta SKUs hijos.

Suscripciones

• Modelo y eventos: ver tabla de datos. Cobro D-2 vía Mercado Pago; OK → orden con channel = Suscripción y prioridad alta en ruteo; falla → reintento 24h + WhatsApp con link de tarjeta.
• Calendario: GROUP BY next_ship_date; detalle del día = suscripciones, facturación comprometida, unidades a preparar, distribución por provincia, rutas sugeridas (n = ceil(envíos/40)).
• Recompra predicha: por SKU consumption_days; por cliente ajuste con su historial; probabilidad ≥ 70% dispara "se te está por acabar". Botón "ofrecer suscripción" = campaña WhatsApp con 15% off.
• Señales: tarjeta por vencer (< 30 d), sin stock para la fecha, top 5% LTV, riesgo de baja (pago fallido o 2 saltos), puede subir de plan (compra extra recurrente).
• KPIs: activas, MRR, churn mensual, LTV = ticket × margen / churn.
• Si la marca usa Puentify, NODO solo despacha (webhook subscription.upcoming).

Atención al cliente con IA

KPIs

• Conversaciones del período; % resueltas por IA (closed_by = ai); tiempo de primera respuesta; CSAT; reclamos evitados (consultas de estado resueltas sin humano); ventas recuperadas (carritos + fallidas recuperadas + recompras atribuidas).

Rentabilidad

• Insumos: ventas por línea, costo de envío real, costo de producto por SKU (carga la marca), gasto en ads (manual o API Meta/Google), CAC por primera compra.
• Por producto: facturación, envío prorrateado, CAC atribuido, margen real = (fact − producto − envío − CAC) / fact. Señal: > 40% escalar · > 30% sostener · > 18% revisar precio · else no rinde.
• Por zona: GROUP BY zone, margen después del envío.
• Jugadas: playbook_items por reglas (zona con margen bajo → mínimo de envío gratis; SKU rentable fuera de suscripción → crear plan; clientes one-shot > 90 d → campaña; densidad kg/m³ alta → cotizar por peso) revisadas en la sesión de escala; estado y medición de impacto a 30 días.

Saldo y cobros

• Prepago: carga por transferencia / Mercado Pago / débito automático. Débito por envío al evento admitted. Alerta saldo < 3 días; con cuenta corriente activa se cubre automáticamente.
• Liquidaciones (si NODO cobra por la marca): semanal = cobros − fee pasarela − envíos − adelantos. Factura AFIP por liquidación.
• Movimientos: balance_movements con tipo y referencia. Export Excel.
• Cash flow proyectado: tendencia 12 semanas × estacionalidad + MRR comprometido; recálculo nocturno.
• Tarifa: brand_tariffs con vigencia; los conceptos incluidos (inversa, colecta, panel, IA) se listan en $0.

Financiación

• Score (0–100, semanal): antigüedad, volumen, tasa de entrega, regularidad de colectas, saldo promedio, reclamos. ≥ 65 habilita adelanto y cuenta corriente; ≥ 75 stock y campañas.
• Simulador: cuota francesa M·i·(1+i)^n / ((1+i)^n − 1); adelanto M·(1+i).
• Flujo: credit_requests requested → approved (auto si dentro de límite, si no revisión) → disbursed → repaid. Contrato con firma electrónica; validación de identidad RENAPER la primera vez; CFT informado.
• Fondeo: propio o fintech partner por API.

Comex

• Operaciones: comex_ops con etapas quote → booking → shipped → in_transit → customs → cleared → in_warehouse. Tracking del forwarder por API o carga manual. Al llegar: stock_movements inbound. Stock en tránsito visible en Inventario.
• Cotizador: flete (tarifas de forwarders por ruta y modo) + seguro + derechos (tabla NCM por posición) + tasa estadística 3% + IVA/percepciones (separados como crédito fiscal) + despachante y puerto (tabla NODO) + flete interno. Devuelve desglose y ETA.
• Vender en LATAM: activación por país en checkout; pedidos con country ≠ AR se agrupan semanalmente en una operación de exportación courier simplificada (factura E); última milla con partners locales; cobro en moneda local (dLocal / MP país) y liquidación a la marca.
• Documentos: checklist obligatorio por tipo y modo (proforma, factura comercial, packing list, BL/AWB, certificado de origen, despacho, seguro). El Capitán reclama faltantes.
• Habilitaciones: registro importador/exportador, clave fiscal, ANMAT/INAL/SENASA según rubro, poder al despachante, cuenta en USD. Se inician en el onboarding.
• Cruce con financiación: la línea de stock puede pagar directamente al proveedor del exterior.

Referidos

• referrals por link nodo.ar/r/{brand_id} o código en onboarding. Crédito = 10% de los envíos del referido en su primer mes, para ambos, como balance_movements type=referral_credit. 3 referidos activos → sesión extra de escala.

Soporte

• tickets con categoría, pedido asociado, asignado, SLA (primera respuesta 30 min en horario; resolución 24h). Se abren desde el panel, desde un pedido, desde WhatsApp del ejecutivo o los abre el Capitán al escalar.
• Estado de servicios: GET /status con hubs, troncales, integraciones.
• Ejecutivo asignado por marca (brands.account_manager) con WhatsApp directo.

Configuración

• Conexiones: integrations con OAuth por proveedor, estado, última sincronización, secreto de webhook.
• Datos de la marca: brand_settings (origen del stock, operador actual, días y ventana de colecta, stock nacional/importado, lead time, costo de envío actual). Cada campo vacío corresponde a un data_gap; al completarlo se cierra solo.
• Ficha de productos: edición de skus con los 4 flags de packaging.
• Equipo: memberships con rol.
• Notificaciones: notification_prefs por evento y canal.
• Facturación: datos fiscales y facturas mensuales (PDF).

Admin · Marcas

• Réplica de la hoja DASHBOARD: por marca paq/día, paq/mes, unidades, m³/sem, kg/sem, vehículo, canales, localidades, ticket, pendientes alta. Ordenable y buscable. Click → entra al panel de la marca (setBrand + Inicio).
• Ranking por volumen, mapa de la cartera, lecturas clave.
• Onboarding: alta → conexión de canales (importa 90 días) → ficha de SKUs → punto de retiro y días → tarifa 90 días → WhatsApp y voz → usuarios.
• Importador del consolidado (sección 8).
• "Todas las marcas" = sumas de volumen y promedios ponderados por paquetes.

Admin · Torre de control

• Demanda por región (agrupación de provincias) → input para hubs y troncales.
• Viajes troncales del día (TMS larga distancia de QuadMinds): carga por región = Σ paquetes de todas las marcas con destino ahí.
• Semana de la red (Σ perfiles semanales), flota por marca, capacidad usada = paquetes hoy / capacidad diaria (Σ vehículos × paradas máx.).
• Alertas de red: cortes de ruta, hubs al límite, datos faltantes que bloquean cotización.

Admin · Pendientes de datos

• data_gaps de todas las marcas (Tabla 7 del consolidado), filtrable por marca y prioridad. Cada gap está mapeado a un campo real (brand_settings o skus). Resolver = completar el campo o marcar manualmente.
• "Pedir todos por WhatsApp": el Capitán manda a cada marca la lista con la explicación de por qué se necesita.
• Los 3 datos que más faltan en la cartera: costo de envío actual, operador actual, dirección de origen. Son las primeras preguntas del onboarding.

Glosario de KPIs

Roadmap de implementación sugerido