Operación - DS_cuota

Objetivo

Documentar los aspectos operativos del proceso NB_Silver_DS_Cuota, incluyendo su ejecución, dependencias, monitoreo básico y acciones de atención inicial ante incidencias.

Alcance

Dentro del alcance

• Ejecución manual del notebook.
• Configuración de parámetros requeridos por el proceso.
• Identificación de dependencias operativas.
• Detección básica de fallos.
• Acciones iniciales de revisión.
• Escalamiento operativo.

Contenido principal

Descripción general

El proceso NB_Silver_DS_Cuota construye la tabla as4_fact_vtas_cuota a partir de una tabla de cuotas cargada previamente en Bronze.

Durante la ejecución se realizan enriquecimientos mediante dimensiones de canal, producto, grupo cliente, depósito, tiempo, categoría y subcategoría. Adicionalmente, se incorpora la clasificación frío/seco y se calcula la métrica PLAN_PIEZAS antes de persistir la información en Silver.

Información Operativa

Elemento	Valor
Nombre del proceso	NB_Silver_DS_Cuota
Qué hace	Lee el archivo de cuota mensual de ventas cargado en Bronze, lo enriquece con dimensiones de canal, producto, grupo cliente, depósito, tiempo y categoría, calcula plan en piezas y escribe la tabla Silver as4_fact_vtas_cuota particionada por mes/año.
Workflow asociado	No se identifica workflow automático en el código analizado. Ejecución manual o por pipeline externo.
Capa objetivo	Bronze → Silver
Catalogo	cat_master_alpura
Tabla final	sch_silver_layer.as4_fact_vtas_cuota
Plataforma de ejecución	Databricks
Frecuencia	Mensual (un archivo por mes de cuota)

Nota: Esta tabla representa los detalles operativos del proceso de NB_Silver_DS_Cuota, Runbook L1

Gobierno y trazabilidad

Elemento	Valor
Catálogo	cat_master_alpura
Capa destino	Silver (sch_silver_layer)
Tabla destino	as4_fact_vtas_cuota
Formato	Delta Lake
Modo escritura	overwrite (replaceWhere por CVE_PART)
Run ID	Generado con uuid.uuid4() en cada ejecución
Parámetros	w_StartDate, w_EndDate, w_catalog, w_schema origin, w_schema destiny
Framework	NB_FRAMEWORK_LIBRARIES
Notebook	NB_Silver_DS_Cuota

Parametros de ejecución

El notebook requiere la configuración de los siguientes widgets:

Parametro	Descripción
w_StartDate	Mes a procesar en formato YYYYMM (ej: 202604).
w_EndDate	Parámetro disponible durante la ejecución.
w_catalog	cat_master_alpura
w_schema origin	sch_bronze_layer
w_schema destiny	sch_silver_layer

Dependencias Operativas

Se identifican las siguientes dependencias para la ejecución del proceso, deben ejecutarse antes:

• DIM_CATEGORIA → snw_dim_categoria
• DIM_SUBCATEGORIA → snw_dim_subcategoria
• Carga manual del archivo de cuota en Bronze
• oon_fact_indi_vb_frios_secos actualizada
• v_dim_date_esp con el mes a procesar

Procedimiento de Ejecución Manual

1. Verificar que existe la tabla Bronze de cuota del mes: cat_master_alpura.sch_bronze_layer.27_03_cuota_abril_2026, (o el nombre correspondiente al mes a procesar)
2. Actualizar el nombre de la tabla fuente en la celda 6 del notebook si cambió respecto al mes anterior
3. Configurar widgets:
   • w_StartDate = YYYYMM (ej: 202604)
   • w_catalog = cat_master_alpura
   • w_schema origin = sch_bronze_layer
   • w_schema destiny = sch_silver_layer
4. Ejecutar el notebook completo (Run All)
5. Validar resultados con las celdas de verificación al final

Deteccion de fallos

Se identifican los siguientes criterios de revisión operativa:

• El notebook retorna error en la celda de escritura
• La tabla destino no tiene registros para el CVE_PART esperado
• La validación final muestra 0 registros o suma de PLAN_LITROS = 0
• La tabla Bronze fuente no existe → AnalysisException: Table not found

Acciones Básicas

Ante una incidencia, se recomienda realizar las siguientes revisiones:

Error	Acción
Error "Table not found"	Verificar que la tabla Bronze fue cargada. Contactar al equipo de carga de archivos.
CVE_PART nulo	Verificar que v_dim_date_esp contiene el mes. Si no existe, agregar el registro en la dimensión de tiempo.
PLAN_PIEZAS = 0 masivo	Verificar que snw_dim_productos tiene FCONKL != 0 para los productos de la cuota.
Escritura fallida	Revisar permisos sobre sch_silver_layer.
Registros bajos	Comparar count con tabla Bronze origen.

Escalamiento

Nivel	Acción
Nivel 1 (L1)	Verificar existencia de tablas fuente y widgets
Nivel 2 (L2)	Ingeniero de datos — revisar joins y lógica de transformación
Nivel 3 (L3)	Arquitecto de datos — cambios estructurales en dimensiones o esquema de tabla destino

Consideraciones Operativas

1. Carga manual: La tabla Bronze 27_03_cuota_abril_2026 se genera mediante carga manual de archivo. Es necesario que este archivo exista antes de ejecutar el notebook.
2. Nombre de tabla hardcodeado: El nombre de la tabla fuente (27_03_cuota_abril_2026) está hardcodeado en el código y no usa los parámetros de widget. Cada mes se deberá modificar este nombre.
3. Escritura doble: Existen dos escrituras a la misma tabla destino. La primera usa replaceWhere (carga incremental por partición). La segunda usa overwrite sin replaceWhere (sobrescribe todo). Verificar si la segunda escritura es intencional.
4. Campo con punto: El campo "." es eliminado con fuente.drop(".") al leer la fuente. Indica que el archivo CSV/Excel origen tiene una columna sin nombre o con punto.
5. Partición CVE_PART: Debe existir en v_dim_date_esp para el mes procesado. Si no existe, los registros serán filtrados y no se cargarán.
6. Dependencia de Silver: oon_fact_indi_vb_frios_secos debe estar actualizada antes de ejecutar este proceso.

Artefactos relacionados

Artefacto	Descripción
Diseño Funcional - DS_cuota	Documenta la arquitectura funcional, componentes y dependencias del proceso.
Diseño Técnico - DS_cuota	Documenta la arquitectura técnica, componentes y dependencias del proceso.
Fuentes - DS_cuota	Documenta las fuentes de información consumidos por el proceso.
Pipelines - DS_cuota	Describe la secuencia de ejecución y procesamiento de datos.
Reglas de Negocio - DS_cuota	Describe las reglas apliacadas durante la conformación de la dimensión.
Tablas - DS_cuota	Documenta las tablas origen, intermedias y destino involucradas.
Validaciones - DS_cuota	Documenta controles y validaciones asociados al proceso.

Próximos pasos

• Revisar si la segunda escritura en modo overwrite sin la cláusula replaceWhere corresponde al comportamiento esperado o si requiere una corrección en la implementación.