1. Vision General del Ecosistema

1.1 Los 3 sistemas y como se conectan

Conexia opera con 3 sistemas que deben trabajar juntos. El CRM es el hub central que unifica la informacion de los otros dos.

+-----------------------------------+     +---------------------------+
| PRESUPUESTADOR (PHP)              |     | DoWISP API                |
| pedidos.conexiatec.com            |     | conexiatec.dowisp.com     |
|-----------------------------------|     |---------------------------|
| Presupuestos, Pedidos             |     | Clientes (54 campos)      |
| Pipeline Kanban distribuidores    |     | Suscripciones (58 campos) |
| Productos (36 mapeados DoWISP)    |     | Facturas + Lineas         |
| Agentes (1,638), Distrib. (1,456) |     | Efectos/Cobros (30 camp.) |
| Actividades comerciales           |     | Firma Contrato (50 camp.) |
| Scoring / Gamificacion            |     | Tickets (45 campos)       |
| Cobertura (iframe actual)         |     | Productos + Tarifas       |
|                                   |     | Email + SMS integrado     |
| Webhooks salientes (6 eventos)    |     |                           |
| API REST (X-API-Key, 7 endpoints) |     | Auth: Token header        |
+-----------------------------------+     +---------------------------+
          |                                         |
          | Webhooks + API REST                      | API REST (polling)
          | (bidireccional)                          | (lectura + escritura)
          v                                         v
+------------------------------------------------------------------+
|                    CRM CONEXIA (NUEVO)                            |
|                 crm.conexiatec.com - HUB CENTRAL                 |
|------------------------------------------------------------------|
| Contactos unificados (Presup + DoWISP vinculados por NIF)        |
| Vista 360: servicios + facturas + deuda + tickets + actividades  |
| Tickets con sub-tickets en cascada                                |
| Mensajeria multi-canal (WhatsApp, Telegram, PBX)                 |
| Cobertura multi-proveedor (Sarenet, Onivia, CableMovil)         |
| Gestion organizaciones (5 niveles)                                |
| Analytics y dashboards por rol                                    |
+------------------------------------------------------------------+

1.2 Que hace cada sistema (Regla de Oro)

1.3 Arquitectura tecnica

2. Roles y Permisos

2.1 Los 5 roles del CRM

El sistema tiene exactamente 5 roles. No mas.

2.2 Jerarquia de organizaciones

N0: CONEXIA (Super-Matriz)
  Control y visibilidad absoluta. Suplantacion de cualquier usuario.
  Roles internos: Super Admin, Admin, Agente
  |
  +-- N1: MASTER (distribuidor de alto nivel)
  |    Ve: sus distribuidores, clientes de estos, comisiones
  |    NO puede: suplantar distribuidores inferiores
  |    |
  |    +-- N2: DISTRIBUIDOR (1,456 existentes)
  |    |    Ve: clientes activos, suscripciones, servicios, importes
  |    |    Puede: modificar servicios, generar tickets en nombre de clientes
  |    |    Presupuestador: CRM ventas Kanban, generar pedidos, ver comisiones MR
  |    |    |
  |    |    +-- N2.5: DELEGACION (sucursales del distribuidor)
  |    |    |    Silo aislado: solo ve SUS presupuestos
  |    |    |    NO ve: otras delegaciones, datos economicos del distribuidor, 347
  |    |    |
  |    |    +-- N3: CLIENTE (empresa / autonomo / particular)
  |    |         Portal: facturas, servicios, tickets, contratos, datos
  |    |         |
  |    |         +-- CONTACTOS (personas sin acceso, solo datos)
  |    |
  |    +-- N2: DISTRIBUIDOR ...
  |
  +-- N1: MASTER ...

2.3 Permisos por rol (matriz completa)

2.4 Modelo multi-tenant

El sistema se basa en Organizaciones, no en usuarios sueltos. Cada entidad (Conexia, distribuidor, cliente) es una organizacion.

Creacion de organizaciones

• Solo CONEXIA (Super Admin o Admin) puede crear organizaciones de nivel N1-N3.
• El primer usuario creado en una organizacion es automaticamente Admin de esa organizacion.
• El Admin de una organizacion puede crear, bloquear y "eliminar" (soft-delete) usuarios dentro de su organizacion.

Reglas de la ficha de organizacion

Datos de la ficha de empresa

• ID DoWISP (vinculacion API)
• Tipo: Master / Distribuidor / Distribuidor Potencial (CRM sin acceso) / Cliente
• Jerarquia: ID del Master/Distribuidor padre
• Nombre fiscal, nombre comercial, NIF, logo
• Direccion fiscal + direcciones adicionales (sedes, envio)
• Web, email facturacion
• Listado de contactos + contacto tecnico
• Impuestos: IVA/IGIC/IPSI (auto-deteccion por CP)
• IBAN + certificado bancario

3. Flujo por Rol: Super Admin

El Super Admin es el unico rol con vision completa del negocio. Tiene acceso a todo el sistema sin restricciones.

Acceso

Sidebar completo: Dashboard, Contactos, Vista 360, Tickets, Pipeline, Catalogo, Presupuestos, Pedidos, Cobertura, Facturacion, Comunicaciones, Centro de Control, Analytics, Configuracion, Portal Cliente (vista previa).

Dashboard

KPIs financieros: MRR (ingresos recurrentes mensuales), ARPU (ingreso medio por cliente), Churn (tasa abandono), Deuda vencida. Graficos: evolucion MRR 12 meses, pipeline funnel, nuevos vs bajas, mix productos. Tablas: tickets urgentes, actividad reciente.

Flujo de trabajo diario tipico

Acciones exclusivas del Super Admin

• Ver datos financieros (MRR, ARPU, churn, deuda global, analytics financiero)
• Configuracion del sistema (integraciones, sync DoWISP, SMTP, seguridad)
• Crear/modificar organizaciones de cualquier nivel
• Suplantar cualquier usuario del sistema
• Aprobar cambios de IBAN (ticket automatico)
• Bloquear acceso a organizaciones (activo/inactivo)
• Gestionar catalogo de productos (familias, subfamilias, margenes, datasheets)

4. Flujo por Rol: Admin

El Admin gestiona operaciones diarias sin acceso a datos financieros globales.

Acceso

Todo excepto: Configuracion del sistema, Analytics, datos financieros.

Dashboard

KPIs operativos: Tickets abiertos (criticos), SLA cumplido, Contactos activos, Tareas equipo.

Flujo de trabajo diario tipico

5. Flujo por Rol: Agente

El Agente atiende clientes, gestiona tickets y consulta informacion.

Acceso

Dashboard (sus KPIs), Contactos (asignados), Tickets (asignados), Presupuestos (lectura), Cobertura, Facturacion (sus clientes), Comunicaciones.

Dashboard

KPIs personales: Mis tickets (criticos), SLA mis tickets, Tareas pendientes, Contactos asignados.

Flujo de trabajo diario tipico

6. Flujo por Rol: Distribuidor

El Distribuidor gestiona sus clientes y usa el Presupuestador para ventas.

Acceso CRM

Dashboard (sus KPIs), Contactos (SUS clientes), Tickets (de sus clientes), Facturacion (de sus clientes), Cobertura.

Acceso Presupuestador (sistema separado)

El distribuidor accede al Presupuestador (pedidos.conexiatec.com) para crear presupuestos, gestionar pedidos y ver su pipeline Kanban. Desde el CRM, un boton redirige al Presupuestador con inicio de sesion automatico.

Dashboard

KPIs: Mis clientes (nuevos este mes), Tickets (criticos), Presupuestos pendientes, Servicios activos.

Gestion de usuarios del Distribuidor (Admin de org)

El Admin del distribuidor puede:

• Crear usuarios empleados (con restricciones configurables)
• Capar acceso: ver clientes, modificar servicios, ver 347, ver comisiones
• Crear sub-delegaciones (N2.5) con silo aislado

Delegaciones (N2.5)

Sucursales del distribuidor con entorno aislado. El usuario master de la delegacion solo puede crear, ver y tramitar presupuestos de SU delegacion. No ve otras delegaciones ni datos economicos del distribuidor principal.

7. Flujo por Rol: Cliente

El Cliente accede a un portal simplificado. Layout diferente (sin sidebar completo).

Acceso

Portal Cliente: Mis servicios, Mis facturas, Soporte, Mis datos.

Primer login obligatorio

• Aceptacion RGPD
• Aceptacion/rechazo comunicaciones comerciales

Funcionalidades del Portal

8. Modulos del CRM (detalle funcional)

8.1 Dashboard

El dashboard se adapta segun el rol del usuario. Solo Super Admin ve datos financieros.

8.2 Contactos y Vista 360

La pagina mas importante del CRM. Toda la informacion del cliente en una sola pantalla.

Lista de contactos

• Busqueda por POST (datos sensibles nunca en URL)
• Filtros: Todos, Leads, Activos, Empresas, Con deuda, Score alto
• Score semaforo: verde >70, amarillo 40-70, rojo <40
• Tags como badges de color
• Paginacion

Vista 360 (9 tabs)

Vinculacion entre sistemas

Un contacto del CRM se vincula con el cliente de DoWISP y el contacto del Presupuestador mediante el NIF/CIF como clave natural. El campo dowisp_cliente_id almacena el ID de DoWISP. El campo presup_uuid almacena el UUID del Presupuestador.

8.3 Tickets y Sub-tickets

Ticket principal

Estructura: sidebar (estado, prioridad, asignado, SLA, cliente, servicio afectado, tags, acciones) + conversacion (hilos de respuestas y notas internas).

Sistema de sub-tickets en cascada

Cuando un ticket necesita involucrar a terceros (proveedor, distribuidor, equipo interno), se crean sub-tickets con numeracion #parent-N.

TICKET #1234 - "Sin conexion FTTH zona norte"
  Creado por: Cliente (Juan Perez)
  Asignado a: Ana Garcia (Agente)
  Conversacion: cliente <-> agente
  |
  |-- SUB-TICKET #1234-1 (Proveedor: Sarenet)
  |   Hilo propio: Back Office <-> Sarenet (via email)
  |   Cada respuesta email del proveedor se integra en el hilo
  |
  |-- SUB-TICKET #1234-2 (Distribuidor: Alpha)
  |   Hilo propio: Agente <-> Distribuidor
  |   Notificacion al distribuidor sobre clientes afectados
  |
  |-- SUB-TICKET #1234-3 (Interno: Tecnico)
      Hilo propio: solo equipo interno
      Verificacion post-restauracion

Reglas de los sub-tickets

• Cada sub-ticket tiene su propio hilo de conversacion independiente
• Cada equipo solo ve los sub-tickets que le corresponden
• El ticket padre muestra el estado global de todos los sub-tickets
• Se puede responder por email directamente desde el sub-ticket
• Expandir/colapsar cada sub-ticket en la vista
• Solo Agentes, Admins y Super Admin pueden crear sub-tickets

SLA (Service Level Agreement)

8.4 Pipeline comercial

Kanban de oportunidades de venta. Solo visible para Super Admin y Admin.

Etapas: Prospecto (10%) -> Contactado (25%) -> Propuesta (50%) -> Negociacion (75%) -> Ganado (100%) / Perdido.

Cada tarjeta muestra: nombre oportunidad, empresa, valor MRR, agente asignado. Drag & drop para mover etapas.

8.5 Catalogo de productos

Gestion del catalogo de productos con jerarquia de 3 niveles.

Jerarquia

FAMILIA (ej: "Pack Fibra+Movil")
  |-- Segmento: Empresa / Residencial / Ambos
  |-- Margen Master: 8%
  |-- Margen Distribuidor: 5%
  |-- Visibilidad: Todos / Solo Masters / Solo CONEXIA
  |
  +-- SUBFAMILIA (ej: "Pack Fibra 600Mb")
  |    |-- Hereda margenes de Familia (puede sobrescribir)
  |    |
  |    +-- PRODUCTO (ej: "Fibra 600Mb + Movil 30GB")
  |         |-- Ref DoWISP (vinculacion)
  |         |-- Ref Herramienta (auto-generada)
  |         |-- es_servicio: true (genera MRR)
  |         |-- Precio coste (solo visible Gerencia/Super Admin)
  |         |-- PVP (Base Imponible)
  |         |-- Descuento por defecto
  |         |-- Importe alta + descuento alta
  |         |-- Margenes (hereda o sobrescribe)
  |         |-- DataSheets PDF vinculados
  |         +-- Imagenes (galeria)

Reglas de precios

• Regla de Oro: Precio de venta NUNCA por debajo del precio de coste. Validacion en servidor.
• Segmento Empresa: Precios Base Imponible (sin IVA)
• Segmento Residencial: Precios IVA incluido (auto-calculo segun CP: IVA 21% / IGIC 7% / IPSI)
• Permisos edicion precios: Nivel 1 (ficha distribuidor: si/no + % max descuento) > Nivel 2 (ficha producto: editable si/no)

DataSheets y generacion PDF

• DataSheet Maestro ("Presentacion CONEXIA"): obligatorio al inicio de todo presupuesto
• DataSheets por producto: con orden de prelacion numerico
• Generacion PDF presupuesto: Presentacion + DataSheets productos + Oferta Economica

Desactivacion en cascada

Si se desactiva una Familia, se ocultan automaticamente todas sus subfamilias y productos.

8.6 Presupuestos

Los presupuestos se crean en el Presupuestador (pedidos.conexiatec.com) y se leen en el CRM via API REST.

Que muestra el CRM

• Lista de presupuestos con filtros (pendientes, aceptados, rechazados)
• Detalle: cliente, productos, cuota MRR, altas, agente, estado, fecha
• Vinculacion con contacto en Vista 360

Que hace el Presupuestador (no el CRM)

• Crear presupuesto: seleccionar tipo (particular/empresa), familias, productos, carrito, cliente, agente
• Logica IVA/IGIC/IPSI
• Descuentos y precios editables (segun permisos)
• Generacion PDF (Presentacion + DataSheets + Oferta)
• Flujo: Presupuesto -> Aceptado -> Pedido -> Tramitado (contrato DoWISP)

Sincronizacion

• Presupuestador -> CRM: Webhook presupuesto_creado y substatus_cambiado
• CRM -> Presupuestador: API REST GET presupuesto/listar, GET presupuesto/ver/{uuid}

8.7 Pedidos y Aclaradores

Los pedidos se tramitan en el Presupuestador y se consultan en el CRM.

Aclaradores (formularios dinamicos)

Al tramitar un pedido, el Presupuestador muestra formularios dinamicos segun el producto:

Multiplicidad: Si el cliente contrata 5 lineas moviles, el sistema exige rellenar 5 aclaradores de movil.

Campos condicionales: Si es portabilidad -> pedir numero actual. Si es eSIM -> pedir email. Si es SIM fisica -> pedir direccion envio.

8.8 Cobertura multi-proveedor

Check de cobertura consultando 3 proveedores desde una sola pantalla.

Flujo

1. Usuario introduce direccion + codigo postal
2. Auto-relleno: poblacion, provincia (API publica de CP)
3. Click "Buscar cobertura": consulta en paralelo los 3 proveedores
4. Resultados: tabla comparativa con disponibilidad, velocidad, estado por proveedor
5. Boton "Crear presupuesto con esta direccion": rellena automaticamente el formulario de presupuesto

8.9 Facturacion (cache DoWISP)

El CRM no genera facturas. Lee y cachea datos de DoWISP para mostrarlos.

4 tabs

Sincronizacion DoWISP (Celery)

8.10 Comunicaciones y Mensajeria

Mensajeria en tiempo real

Interfaz tipo chat con panel izquierdo (lista conversaciones) y panel derecho (chat activo). Canales integrados:

Cada conversacion se vincula al contacto (Vista 360) y opcionalmente a un ticket.

Historial

Log de todas las comunicaciones: fecha, canal, direccion (entrante/saliente), destino, asunto, estado entrega, usuario.

Plantillas

Templates con variables: {{nombre}}, {{empresa}}, {{deuda}}, {{url_cobro}}, etc. Tipos: Email, SMS, WhatsApp.

Campanas

Envio masivo segmentado: seleccionar audiencia (filtros), plantilla, canal, programar envio. Metricas: enviados, abiertos, clicks, conversiones.

8.11 Analytics

Solo visible para Super Admin.

8.12 Centro de Control (Super Admin)

Solo visible para Super Admin (N0). Panel unificado que consolida datos de los 3 sistemas (CRM, Presupuestador, DoWISP) en una unica vista. Permite controlar todos los procesos que se estan desarrollando a traves de los tres sistemas.

Ruta de acceso

/control-center - Icono "capas" en el sidebar, entre Comunicaciones y Analytics. Solo aparece para rol Super Admin.

Indicadores de estado de sistemas

En la parte superior se muestran los 3 sistemas con su estado en tiempo real (Online/Offline/Degradado). Permite saber de un vistazo si alguna integracion esta caida.

5 Tabs del Centro de Control

Tab 1: Resumen global

Fuente: Los 3 sistemas combinados

• 5 KPIs cruzados: MRR (DoWISP), Presupuestos mes (Presupuestador), Clientes activos (DoWISP), Tickets abiertos (CRM), Deuda vencida (DoWISP)
• Flujo de negocio end-to-end: Presupuestos creados -> Aceptados -> Tramitados -> Altas DoWISP -> Facturando
• Alertas activas cruzadas con origen (CRM/Presup./DoWISP)
• Timeline unificada en tiempo real de los 3 sistemas

Tab 2: Comercial

Fuente: Presupuestador API (pedidos.conexiatec.com)

• KPIs: Presupuestos/mes, Pedidos tramitados, Conversion, Red distribuidores activos
• Pipeline distribuidores (6 etapas: prospecto -> top performer / en riesgo)
• Top 5 distribuidores con scoring
• Distribuidores que necesitan atencion (dias inactivos, comercial asignado)

Tab 3: Operaciones

Fuente: DoWISP (cache billing en PostgreSQL)

• KPIs: Clientes DoWISP, Suscripciones activas, Facturado mes, Cobrado/Facturado %
• Suscripciones por producto (FTTH, Pack Converg., Movil, VoIP, Otros)
• Estado de cobros: cobrado, deuda vencida, devoluciones, pendiente
• Firmas de contrato pendientes (dias sin firmar)
• Antiguedad de deuda (0-30d, 30-60d, 60-90d, >90d)

Tab 4: Soporte

Fuente: CRM interno + DoWISP cache

• KPIs: Tickets abiertos, SLA cumplido, Tiempo resolucion, Churn mensual
• Tickets por estado (abierto, en proceso, critico, esperando)
• Carga de agentes (asignados, resueltos, SLA, CSAT)
• Clientes en riesgo de churn: datos cruzados CRM + DoWISP (score, senales, MRR en riesgo)

Tab 5: Procesos

Fuente: n8n API + sync_state + webhook_log

• Workflows automatizados (Skynet n8n): estado, ultima ejecucion, errores 24h, frecuencia
• Sincronizacion DoWISP: estado por modulo (clientes, suscripciones, facturas, etc.), registros, frecuencia
• Webhooks recibidos 24h: fuente, evento, recibidos/OK/error
• Audit log: ultimas acciones del sistema (syncs, webhooks, celery, APIs)

Datos cruzados exclusivos del Centro de Control

A diferencia del Dashboard (que muestra KPIs del rol) y Analytics (que profundiza en una dimension), el Centro de Control cruza datos entre sistemas:

• Flujo end-to-end: Presupuesto (Presupuestador) -> Pedido (Presupuestador) -> Alta (DoWISP) -> Facturacion (DoWISP). Muestra la conversion real de todo el proceso.
• Score churn cruzado: Combina datos CRM (tickets, actividad) con DoWISP (impagos, devoluciones) para calcular riesgo de baja.
• Alertas unificadas: Distribuidor en riesgo (Presupuestador) + ticket critico (CRM) + efecto devuelto (DoWISP) en una sola lista priorizada.
• Estado de procesos: Workflows n8n + sync DoWISP + webhooks: todo lo que conecta los 3 sistemas.

8.13 Configuracion del sistema

Solo visible para Super Admin.

8.14 Portal Cliente

Descrito en seccion 7. Layout diferente al back-office. 4 tabs: Servicios, Facturas, Soporte, Mis datos.

9. Integraciones

9.1 CRM <-> Presupuestador (API REST bidireccional)

Presupuestador -> CRM (webhooks)

El Presupuestador emite webhooks (HMAC-SHA256) cuando ocurren eventos:

El CRM recibe estos webhooks en POST /webhooks/presupuestador, verifica firma HMAC, y actualiza sus datos.

CRM -> Presupuestador (API REST)

El CRM consulta datos del Presupuestador via su API (auth: X-API-Key):

Acceso al Presupuestador desde el CRM

9.2 CRM <-> DoWISP (API + polling)

Lectura (DoWISP -> CRM)

Celery tasks hacen polling periodico a la API de DoWISP y cachean los datos en PostgreSQL:

• Clientes (cada 5 min)
• Suscripciones (cada 5 min)
• Facturas (cada 15 min)
• Efectos/Cobros (cada 10 min)
• Firmas/Contratos (cada 10 min)
• Productos/Tarifas (cada 1 hora)

Escritura (CRM -> DoWISP)

Al tramitar un pedido, el flujo es: Presupuestador llama a DoWISP POST /contratador/crea_contrato/. El CRM no escribe directamente en DoWISP (lo hace el Presupuestador).

9.3 Cobertura: Sarenet, Onivia, CableMovil

9.4 Canales: WhatsApp, Telegram, PBX

9.5 n8n (automatizaciones)

n8n Skynet (skynet-n8n.conexiatec.com) para automatizaciones que conectan el CRM con otros sistemas:

• Recibir webhooks del Presupuestador y procesarlos
• Notificaciones a Zoho Cliq cuando se crean tickets criticos
• Workflow de cobranza automatizado (SMS -> email -> llamada -> suspension)
• Sync periodicos y alertas

Auth: API Key con scope limitado. Red interna Docker.

10. Seguridad

OWASP Top 10

Autenticacion

GDPR/LOPD

• Campos sensibles cifrados en BD: IBAN, twofa_secret, tokens API (pgcrypto AES-256)
• Audit log en CADA operacion: quien, que, cuando, desde donde (IP)
• Derecho al olvido: endpoint DELETE /api/v1/contacts/{id}/gdpr
• Exportacion datos: GET /api/v1/contacts/{id}/export (JSON/CSV)
• NIF, email, IBAN, tokens: SIEMPRE por POST body, NUNCA en URL

11. Fases de desarrollo

12. Preguntas abiertas y decisiones pendientes