Qué hace: abre cada Excel crudo de Salesforce con tolerancia a fallos: tipos mixtos, AutoFilters problemáticos y errores de XML interno. Salta las filas de metadata iniciales (skiprows) hasta encontrar los encabezados reales.

Por qué: los archivos exportados de Salesforce traen 2-4 filas de metadata (fecha de exportación, usuario, totales) antes del header real. Si se leyera "directo" pandas tomaría esas filas como encabezados y todo lo demás reventaría.

Archivo

backend/pipeline.py

Función

_leer_excel_robusto() + procesar_excel() paso 1

Qué hace: remueve acentos, reemplaza espacios y caracteres especiales por guiones bajos, deja todo en un formato canónico. "Cliente de Venta: Nombre" se vuelve Cliente_de_Venta_Nombre.

Por qué: Salesforce exporta encabezados con espacios, dos puntos, signos y acentos. Estos son difíciles de manejar en código (escapes, codificación) y rompen joins con el directorio oficial. La normalización vuelve las columnas referenciables sin ambigüedad.

Archivo

backend/pipeline.py

Función

limpiar_nombre_columna()

Qué hace: detecta la fila donde la columna centinela contiene la palabra "Total" y corta el DataFrame justo antes. Si no hay total, se queda con todo.

Por qué: Salesforce concatena una fila resumen al final de cada export ("Total: 142"). Si no se eliminara, sería procesada como un registro real y produciría estados inválidos en la cascada de validación.

Archivo

backend/pipeline.py · procesar_excel() paso 3

Param

col_total — columna centinela (varía por reporte)

Qué hace: aplica mapeos globales de valores categóricos (sexo M/F → 1/2, permisos Sí/No → 1/0, etc.), limpia teléfonos eliminando notación científica y caracteres no numéricos, normaliza fechas a formato MX YYYYMMDD.

Por qué: Excel convierte teléfonos largos a notación científica (5.5512e+9) o a float (5551234567.0) si la celda no está en formato texto. La limpieza preserva los 10 dígitos como string y la celda final en el Excel queda con formato '@' (texto) para que VW pueda usarla tal cual.

Archivo

backend/pipeline.py · procesar_excel() pasos 6, 13b, 14

Constante

MAPEOS_GLOBALES (valores categóricos)

Qué hace: primero intenta usar el valor de la columna Modelo directamente. Si está vacío, busca el modelo en un catálogo VIN→modelo precalculado (data/concentrado_modelos.csv, ~10 000 entradas). Si encuentra coincidencia, completa el modelo automáticamente. Después normaliza el resultado a uno de los 5 modelos válidos.

Por qué: el campo "Modelo" en Salesforce viene vacío en ~5-8% de los registros, pero el VIN siempre está. El catálogo histórico permite recuperar la información sin perder al registro en la cascada de validación. Modelos no comerciales (Jetta, Polo, etc.) se filtran fuera.

Archivos

backend/pipeline.py (validar_y_completar_modelo(), normalizar_modelo())

Modelos válidos

AMAROK, CADDY, CRAFTER, EUROVAN, TRANSPORTER

Catálogo

backend/vin_model_dict.json + data/concentrado_modelos.csv

Qué hace: aplica 11 reglas de evaluación en orden estricto. La primera que matche "gana" — un registro solo recibe un motivo de penalización, no se acumulan.

1. Red no oficial — dealer fuera del directorio VW vigente
2. Fecha no válida (no penalizado) — fuera del rango de la ola
3. Órdenes internas (no penalizado) — tipos 3,5,7,8,9,10,11,12 en postventa
4. Chasis repetido (no penalizado) — VIN duplicado intra-reporte
5. Otros modelos (no penalizado) — Jetta, Polo, etc.
6. Sin permiso (penalizado) — cliente no autorizó contacto
7. Sin modelo (penalizado) — modelo vacío + VIN no rescatable por catálogo
8. Sin nombre (penalizado) — nombre vacío, basura o "Volkswagen"/"SAPI de CV"/etc.
9. Sin email (penalizado) — ninguna de las 4 columnas alternativas de correo tiene un email válido
10. Cargado — pasa todas las reglas, se entrega a la encuesta
11. Cliente repetido (no penalizado) — mismo cliente ya cargado en este lote

Por qué cascada y no flags independientes: el SP original en SQL Server tenía esta lógica de exclusión mutua. Si un registro no tiene modelo y tampoco nombre, queremos reportarlo UNA sola razón (la primera detectada) — replicar el comportamiento original es clave para no romper auditoría histórica.

Archivo

scripts/validador.py

Función

validar_plantilla() — líneas 716-806

Origen

migración de stored procedures SQL Server (SP_ins_upd_*)

Qué hace: traduce el _estatus interno a 2 columnas user-facing:

• Status = CARGADO si _estatus="Cargado", sino NO CARGADO.
• Observaciones = el texto exacto del _estatus (e.g. "Sin email (penalizado)").

Por qué: el operador ve dos columnas claras: una para filtrar (Status binario) y otra para auditar el motivo (texto descriptivo). VW solo recibe los registros con Status=CARGADO en el MX final, pero la Base de Limpieza conserva los NO CARGADO con su razón para análisis.

Archivo

scripts/validador.py líneas 808-812

Qué hace: genera dos archivos Excel para el operador interno con TODOS los registros (CARGADO + NO CARGADO) más hojas auxiliares:

• Base_limpieza_ventas_YYYYMMDD.xlsx: Hoja1 (datos), NADIN (DWH), ARCO, td
• Base_limpieza_postventa_YYYYMMDD.xlsx: Hoja1 (físicas + morales unificadas), ARCO, TD

Por qué: es el entregable que revisa el operador antes de mandar a VW. La hoja ARCO traza los derechos de cliente (Aplicación de derechos ARCO según LFPDPPP), la hoja TD/td lista las redes territoriales, NADIN es referencia del DWH histórico.

Archivo

scripts/generar_bases_limpieza.py

Función

generar_bases_limpieza()

Qué hace: filtra SOLO los registros con Status=CARGADO y los proyecta a la estructura exacta que VW espera para la encuesta CEM:

• MX_CV_SA_YYYY_YYYYMMDD.xlsx — Ventas (63 columnas)
• MX_CV_AS_YYYY_YYYYMMDD.xlsx — Postventa (Físicas + Morales consolidadas, 64 columnas)

El nombre incluye el número de "ola" (001 si día ≤ 15, 002 si día ≥ 16) y un consecutivo que se calcula leyendo el último MX previo del directorio.

Por qué solo CARGADO: los NO CARGADO no van a encuesta — solo los registros elegibles que pasaron todas las reglas. El consecutivo y el wave son requeridos por VW para correlacionar con su lado.

Archivos

scripts/generar_mx_ventas.py, scripts/generar_mx_pv.py

Qué hace: inserta los registros (TODOS, no solo CARGADO) en la BD local SQLite db/concentrado.db, creando una fila padre en ejecuciones y filas hijas en ventas y postventa. Registra un rollback disponible por 30 días.

Por qué: sin esta etapa cada ejecución se perdería. El concentrado permite consultar cualquier registro procesado en el pasado, exportar rangos de fechas, detectar VINs duplicados entre ejecuciones, y hacer rollback de una carga errónea. El rollback de 30 días balancea seguridad operativa vs. crecimiento de tabla.

Archivo

backend/db_concentrado.py

Funciones

insertar_ejecucion(), insertar_ventas(), insertar_postventa(), registrar_rollback()

El pipeline consulta el catálogo histórico data/concentrado_modelos.csv (VIN → modelo) y completa el campo automáticamente. Si el VIN tampoco está en el catálogo, el registro se marca como "Sin modelo (penalizado)" en la cascada de validación y su Status queda en NO CARGADO.

Cualquiera de estas razones, en orden de prioridad:

• Red no oficial — el dealer no aparece en el directorio VW del periodo.
• Fecha no válida — fuera del rango de la ola.
• Órdenes internas — tipos administrativos de servicio (solo postventa).
• Chasis repetido — el mismo VIN aparece más de una vez en el archivo.
• Otros modelos — no es AMAROK/CADDY/CRAFTER/EUROVAN/TRANSPORTER.
• Sin permiso — el cliente no autorizó contacto (penaliza al dealer).
• Sin modelo — modelo vacío y VIN no rescatable.
• Sin nombre — nombre vacío, basura o lista negra (Volkswagen, SAPI, etc.).
• Sin email — ninguna de las 4 columnas alternativas tiene un email válido.
• Cliente repetido — mismo cliente ya cargado en este lote (solo si pasó todo lo anterior).

La columna Observaciones indica el motivo exacto.

Los valores literales que pueden aparecer son:

• Cargado — pasó todas las reglas, va a encuesta.
• Red no oficial
• Fecha no válida (no penalizado)
• Órdenes internas (no penalizado)
• Chasis repetido (no penalizado)
• Otros modelos (no penalizado)
• Sin permiso (penalizado)
• Sin modelo (penalizado)
• Sin nombre (penalizado)
• Sin email (penalizado)
• Cliente repetido (no penalizado)

El sufijo (penalizado) indica que el dealer responsable recibe puntos en contra en el índice de calidad. Las marcas (no penalizado) son filtros operativos sin impacto en el KPI del dealer.

1. Abre la etapa con error en la pestaña Pipeline.
2. Revisa el panel de logs — la última línea típicamente describe el error (e.g. [ERROR] Plantilla intermedia no encontrada).
3. Causas comunes:
   • Archivo corrupto — el Excel exportado de Salesforce quedó truncado; re-exportarlo.
   • Columna esperada faltante — Salesforce cambió el nombre de una columna; revisar los mapeos en backend/pipeline.py (config_fisicas, etc.).
   • Catálogo no encontrado — data/concentrado_modelos.csv o Directorio_Febrero_2026.xlsx ausentes.
4. Si necesitas re-correr solo desde una etapa, sube los archivos de nuevo en modo manual y avanza etapa por etapa.
5. Si el error persiste, contacta al equipo de plataforma con el ID del proceso (visible en la tarjeta del proceso).

1. Si la importación se completó pero los datos están mal: ejecuta Rollback desde el historial de ejecuciones (disponible los primeros 30 días).
2. El rollback elimina todos los registros de ventas y postventa de esa ejecución; la fila padre en ejecuciones se conserva pero queda marcada como eliminada en rollbacks.
3. Si pasaron más de 30 días: el rollback no está disponible. Hay que limpiar manualmente con SQL en db/concentrado.db (requiere acceso al servidor).
4. Si la importación falló a media inserción: el sistema usa transacciones, así que NO debería quedar estado parcial. Revisa los logs de la ejecución para confirmar.