1. Arquitectura del Sistema

1.1 Stack Tecnologico EXISTE

1.2 Estructura de Archivos EXISTE

presupuestador_new/
  admin/                         <-- Portal administracion
    clases/                      <-- OOP: BaseModel.php, AgenteModel.php, BudgetModel.php,
                                       ContactModel.php, DocumentModel.php, EmailModel.php,
                                       ListModel.php, UserModel.php + legacy cls_*.php
    php/                         <-- Endpoints AJAX (~45 archivos _bd.php)
      agentes_bd.php               Gestion agentes/usuarios configurador
      alertas_bd.php               CRUD alertas
      budget_bd.php                Presupuestos admin
      comerciales_bd.php           Gestion comerciales
      company_bd.php               Datos empresa
      configuracion_bd.php         Config general unificada
      contacts_bd.php              CRUD clientes
      email_templates_bd.php       Templates email
      familias_bd.php              Familias de productos
      producto_bd.php              CRUD productos
      subfamilias_bd.php           Subfamilias
      webhooks_bd.php              Config webhooks admin
      ...
    js/                          <-- Frontend JS: app.js, csrf.js, budget.js, contacts.js, etc.
    content/                     <-- Vistas HTML parciales (configuraciones.php, etc.)
    inc/                         <-- Includes: _sidebar.php (UNIFICADO), _top.php, _footer.php
    config/                      <-- config.php (BD, constantes, includes funciones)
    functions/                   <-- crypt.php, Security.php, db.php, helpers.php, logins.php
    migrations/                  <-- SQL migrations
    pdf/                         <-- Generacion PDF: invoice.php, budget.php, border.php, advice.php

  distribuidor/                  <-- Portal operaciones
    api/                         <-- REST API: index.php (router principal)
    php/                         <-- Endpoints AJAX
      index_bd.php                 Nuevo presupuesto (~93KB, archivo central)
      presupuestos_bd.php          Listado presupuestos + substatus
      pipeline_bd.php              Pipeline kanban distribuidores
      actividades_bd.php           Actividades comerciales
      dashboard_director_bd.php    KPIs direccion
      estadisticas_bd.php          Estadisticas detalladas
      scoring_bd.php               Gamificacion y puntos
      permisos_helper.php          Sistema RBAC (deteccion rol + permisos)
      webhooks_helper.php          Motor webhooks (dispatch, send, log, retry, API auth)
      ...
    js/                          <-- Frontend JS
      index.js                     Nuevo presupuesto (familias, productos, carrito)
      presupuestos.js              Listado presupuestos
      actividades.js               Actividades comerciales
      estadisticas.js              Graficos estadisticas
      realizar.js                  Realizar pedido
      pedidos.js                   Gestion pedidos
      ...
    inc/                         <-- _topbar.php, _head.php, _sidebar.php (proxy a admin)
    assets/css/                  <-- app.css v2.0 (design system completo)
    content/                     <-- Vistas HTML: cobertura.php, etc.

  sql/                           <-- Migraciones SQL
    pipeline.sql                   Columnas pipeline + tablas umbrales/log
    actividades_comercial.sql      Tabla actividades comerciales
    scoring_actividad.sql          Config scoring por actividad
    sprint19_potenciales.sql       Pipeline potenciales vs activos
    zoho_sync_columns.sql          Columnas sincronizacion Zoho
    calendar_sync.sql              Sincronizacion calendario

1.3 Dos Portales, Una Base de Datos EXISTE

2. Roles y Permisos

2.1 Roles actuales EXISTE

Sistema RBAC implementado en distribuidor/php/permisos_helper.php con tabla config_roles que almacena permisos como JSON. Actualmente 4 roles:

Cadena de deteccion de rol (permisos_helper.php)

La funcion get_rol_usuario() sigue esta prioridad estricta:

1. agentes.rol (BD) - Asignado desde panel admin_permisos. Si el campo tiene valor, se usa directamente.
2. comerciales.role (legacy) - Si agentes.rol esta vacio, busca en tabla comerciales por email. Soporte para directores/jefes historicos.
3. @conexiatec.com - Si el email contiene @conexiatec.com y no tiene rol asignado en los pasos anteriores, se asigna admin_super.
4. Admin en session - Si $_SESSION['admin_user'] tiene valor y no se detecto rol, se asigna admin_super.
5. Agente con distribuidor - Si no es @conexiatec.com ni admin, se asigna distribuidor.
6. Default - Si nada aplica: agente (sin permisos extra).

2.2 Permisos granulares EXISTE

Almacenados en tabla config_roles como JSON en columna permisos. La funcion tiene_permiso($permiso) verifica contra el array decodificado. admin_super tiene siempre ['*'] (failsafe).

Funciones de verificacion disponibles

2.3 Super Admin EXISTE FASE 0

3. Menus y Navegacion

Todo el sistema de navegacion se controla desde un unico archivo: admin/inc/_sidebar.php. El sidebar detecta automaticamente si esta en /admin/ o /distribuidor/ y renderiza las secciones correspondientes.

3.1 Sidebar del Distribuidor EXISTE

Se muestra cuando $_inDist = true (URL contiene /distribuidor/).

Seccion Principal (todos los roles)

Seccion Comercial (requiere actividad.leer o pipeline.leer)

Seccion Direccion (requiere dashboard.director o stats.leer)

Seccion Administracion (requiere admin.config)

3.2 Sidebar del Admin EXISTE

Se muestra cuando $_inAdmin = true (URL contiene /admin/ pero no /distribuidor/).

Seccion Principal

Seccion Contactos

Seccion Administracion

4. Funcionalidades - Portal Distribuidor

4.1 Presupuestos Realizados EXISTE

Estados de presupuesto

Endpoints AJAX

Operaciones batch disponibles

• Rechazar / Eliminar seleccionados
• Cambiar agente asignado
• Cambiar fecha creacion / modificacion / tramitacion
• Tramitar / Volver en curso

Webhooks disparados

Al cambiar substatus: _wh_fire($res, 'substatus_cambiado', [...]) - funcion inline que busca en config_webhook y envia con HMAC-SHA256, timeout 5s/2s connect, log a webhook_log.

4.2 Nuevo Presupuesto EXISTE FASE 0

Flujo completo paso a paso [EXISTE]

4.3 Pipeline (Kanban comercial) EXISTE

Dos vistas

Las etapas se cargan dinamicamente desde tabla config_pipeline_etapas (company, pipeline_tipo, nombre, codigo, color, orden, es_final). Si la tabla esta vacia, se usan los fallback hardcoded.

Tablas BD involucradas

• config_edistribuidor - campos: pipeline_etapa, pipeline_etapa_manual, dist_tipo
• config_pipeline_etapas - definicion de etapas
• config_pipeline_umbrales - reglas automaticas (primera_actividad, presupuestos_mes, dias_sin_presupuesto, etc.)
• pipeline_log - historial de cambios de etapa con distribuidor_uuid, etapa_anterior, etapa_nueva, motivo, usuario

Endpoints API pipeline_bd.php

4.4 Mi Actividad EXISTE

Tipos de actividad

nota | llamada | visita | email | reunion

Resultados posibles

contactado | interesado | no_interesado | no_disponible

Scoring vinculado

• Registrar cualquier actividad: 3 puntos (actividad_registrada)
• Visita presencial (bonus): 5 puntos (actividad_visita)

Seguimiento

Campos: siguiente_accion_fecha, siguiente_accion_tipo, siguiente_accion_completada

Endpoints actividades_bd.php

4.5 Dashboard Director EXISTE

Endpoints dashboard_director_bd.php

Soporta autenticacion por session Y por API key (para n8n via X-API-Key).

4.6 Estadisticas EXISTE

Filtros disponibles

• Ano: parametro year (default: ano actual)
• Rango fechas: parametros from / to (override year)
• dist_tipo: activos / potenciales / inactivos (Sprint 20)
• Cartera comercial: filtro automatico segun getAuthComercial()

9 Endpoints de estadisticas

4.7 Scoring / Gamificacion EXISTE

Acciones puntuadas

Sistema de Badges

Tipos de condicion: puntos_total (suma total ≥ valor), tram_total (tramitaciones totales), ptos_mes (presupuestos este mes), conversion_alta (% conversion con min 10 presupuestos), racha_dias (dias consecutivos activo).

Evaluacion automatica via checkBadges() despues de cada registro de puntos.

Endpoints scoring_bd.php

4.8 Cobertura EXISTE FASE 0

5. Funcionalidades - Portal Admin

5.1 Dashboard Admin EXISTE

Pagina principal del portal admin con calendario de eventos.

5.2 Configuraciones (Hub) EXISTE

Hub central de configuracion organizado en 3 secciones:

Sistema

Productos

Gestor Documental

5.3 Productos EXISTE FASE 0

[EXISTE] Campos: Referencia, Nombre, Precio ALTA con IVA, Dto ALTA %, Precio con IVA, Dto %, Subvencion gobierno, imagenes, servicios extras (JSON), y mas. 36 productos con mapeo DoWISP (dowisp_producto_id, dowisp_tarifa_id).

5.4 Familias EXISTE FASE 0

[EXISTE] Campos actuales: Nombre, Tipo (AUTONOMOS Y EMPRESAS / PARTICULARES / PRUEBA), Orden, Descripcion, imagen.

ALTER TABLE config_familias ADD COLUMN margen_master_pct DECIMAL(5,2) NULL;
ALTER TABLE config_familias ADD COLUMN margen_distrib_pct DECIMAL(5,2) NULL;

ALTER TABLE config_subfamilias ADD COLUMN margen_master_pct DECIMAL(5,2) NULL;
ALTER TABLE config_subfamilias ADD COLUMN margen_distrib_pct DECIMAL(5,2) NULL;

5.5 Webhooks EXISTE FASE 0

5.6 Alertas EXISTE

Tipos de alerta: budget (presupuestos), activity (actividad), performance (rendimiento). Gestion via admin/php/configuracion_bd.php (action=alertas, alerta_toggle).

5.7 Email Templates EXISTE

Campos: nombre, tipo (sistema/custom), subject, body_html, body_text, variables (JSON con placeholders disponibles). Envio via admin/php/MailerService.php usando PHPMailer.

5.8 Config General EXISTE FASE 0

[EXISTE] Configuracion unificada con secciones accesibles via parametro action:

• substatus: Estados de pedido desde config_estadopedidos
• webhooks: Vista y toggle de webhooks activos
• alertas: Vista y toggle de alertas
• objetivos: CRUD de objetivos (tabla config_objetivos)
• scoring: Configuracion de puntos por accion
• badges: Catalogo de badges
• smtp: Configuracion SMTP
• general: Parametros generales del sistema

5.9 Agentes / Usuarios Configurador EXISTE FASE 0

[EXISTE] Campos: ID CRM, Nombre, DNI, Email, Password (hash SHA-256 + salt), Puede modificar precios (SI/NO), IVA (SI/NO), Agente comercial, Distribuidor (edistribuidor UUID), activo/inactivo.

5.10 Clientes EXISTE FASE 0

[EXISTE] Campos: Nombre comercial, NIF, Contacto, Email, Telefono. Tabs: Facturacion | Contacto General. Sub-endpoints: comments, contactslist, direcciones, documents.

ALTER TABLE contacts ADD COLUMN dowisp_cliente_id INT NULL;
ALTER TABLE contacts ADD INDEX idx_dowisp_id (dowisp_cliente_id);

6. API REST

6.1 API actual EXISTE

Autenticacion

La funcion api_authenticate() en webhooks_helper.php busca la API key en config_api_keys, verifica IP whitelist si configurada, actualiza ultimo_uso y total_peticiones, y decodifica los permisos JSON.

Endpoints existentes

Ejemplo de uso

curl -H "X-API-Key: tu_api_key" \
  "https://pedidos.conexiatec.com/presupuestador_new/distribuidor/api/index.php?endpoint=distribuidor/listar&dist_tipo=activo&limit=50"

6.2 Endpoints a agregar FASE 0

7. Integraciones

7.1 DoWISP EXISTE FASE 0

7.2 Webhooks salientes EXISTE FASE 0

Payload de webhook (formato estandar)

{
  "evento": "presupuesto_creado",
  "timestamp": "2026-04-09T10:30:00+02:00",
  "ref_tipo": "presupuesto",
  "ref_uuid": "abc123...",
  "datos": {
    "uuid": "abc123...",
    "cliente": "Empresa SL",
    "total": 1200.00,
    ...
  }
}

7.3 Cobertura multi-proveedor FASE 0

8. Cambios en Base de Datos FASE 0

Todos los cambios son ALTER TABLE aditivos (columnas NULL o con DEFAULT). No rompen queries existentes. Rollback: DROP COLUMN.

-- =============================================
-- 1. Vincular contactos con DoWISP
-- =============================================
ALTER TABLE contacts ADD COLUMN dowisp_cliente_id INT NULL;
ALTER TABLE contacts ADD INDEX idx_dowisp_id (dowisp_cliente_id);

-- =============================================
-- 2. Margenes en familias
-- =============================================
ALTER TABLE config_familias ADD COLUMN margen_master_pct DECIMAL(5,2) NULL;
ALTER TABLE config_familias ADD COLUMN margen_distrib_pct DECIMAL(5,2) NULL;

-- =============================================
-- 3. Margenes en subfamilias (herencia: NULL = hereda de familia)
-- =============================================
ALTER TABLE config_subfamilias ADD COLUMN margen_master_pct DECIMAL(5,2) NULL;
ALTER TABLE config_subfamilias ADD COLUMN margen_distrib_pct DECIMAL(5,2) NULL;

-- =============================================
-- 4. Producto: flag servicio para calculo MRR
-- =============================================
ALTER TABLE product ADD COLUMN es_servicio BOOLEAN DEFAULT false;

-- =============================================
-- 5. Motor IGIC/IPSI en distribuidores
-- =============================================
ALTER TABLE config_edistribuidor ADD COLUMN tipo_impuesto
    ENUM('IVA','IGIC','IPSI') DEFAULT 'IVA';
ALTER TABLE config_edistribuidor ADD COLUMN porcentaje_impuesto
    DECIMAL(5,2) DEFAULT 21.00;

-- =============================================
-- 6. Jerarquia organizativa (ampliar distribuidores)
-- =============================================
ALTER TABLE config_edistribuidor ADD COLUMN parent_uuid VARCHAR(40) NULL;
ALTER TABLE config_edistribuidor ADD COLUMN org_tipo
    ENUM('conexia','master','distribuidor','delegacion') DEFAULT 'distribuidor';
ALTER TABLE config_edistribuidor ADD COLUMN observaciones_privadas TEXT NULL;
ALTER TABLE config_edistribuidor ADD INDEX idx_parent (parent_uuid);

9. Seguridad

Medidas existentes EXISTE

Medidas a agregar FASE 0

10. Plan de Implementacion Fase 0

Semana 1 - Riesgo nulo (solo cosas nuevas)

Semana 2 - Riesgo bajo (cambios aditivos)

Semana 3 - Riesgo medio (toca logica existente)

Apendice A: Mapa de archivos modificados en Fase 0

Apendice B: Tabla de permisos por rol

Matriz completa de permisos. SI = tiene acceso. NO = no tiene acceso.

Manual Tecnico del Presupuestador Conexia - Version 1.0 - Abril 2026
Conexia Telecomunicaciones | pedidos.conexiatec.com