ADR: Zonal_Gestora como columna derivada, no física en la fuente

Estado

Aceptada — 2026-05-14

Contexto

El pipeline de IngelCoding maneja dos dimensiones zonales:

• Zonal_Ejecutora: de dónde se ejecuta físicamente el trabajo. Viene de la hoja FACTURACIÓN en Google Sheets. Es dato de origen.
• Zonal_Gestora: qué oficina regional administra el contrato/proyecto. Su fuente autoritativa es el Control de OTs (hojas CT OSORNO, CT CASTRO, CT ANCUD en la planilla maestra).

Ambas coinciden en ~95% de los casos. Ejemplo de discrepancia: una cuadrilla de Osorno ejecuta un trabajo, pero el proyecto pertenece administrativamente a Chiloé (Castro o Ancud).

Regla de negocio: Castro → CHILOÉ, Ancud → CHILOÉ, Osorno → OSORNO.

La pregunta surgió durante la implementación de Zonal_Ejecutora (rename de la antigua columna Zonal): ¿debería Zonal_Gestora ser una columna física mantenida manualmente en la hoja fuente, o una columna derivada computada en el pipeline?

Opciones evaluadas

Opción A: Columna física en Google Sheets

Agregar Zonal_Gestora como columna manual en FACTURACIÓN y/o en las hojas CT.

Descartada porque:

• Crea dos fuentes de verdad para el mismo dato (la relación OT→Zonal ya está implícita en la estructura de las hojas CT).
• La redundancia al 95% entrena al usuario a ignorarla. Justamente en el 5% donde ejecutora ≠ gestora (el caso que más importa), nadie la revisaría.
• Cualquier cambio en el mapeo requiere editar la planilla manualmente (coordinación con usuarios) en vez de un commit.
• Introduce riesgo de inconsistencia humana (alguien escribe “Chiloe” sin tilde).

Opción B: Columna derivada en pipeline (ELEGIDA)

Computar Zonal_Gestora en tiempo de pipeline mediante lookup: OT → hoja CT de origen → GESTORA_MAP.

Elegida porque:

• Single source of truth: Control de OTs ES la autoridad; la relación se lee de ahí, no se duplica.
• Cero lecturas adicionales: se construye en el mismo loop que ya itera las 3 hojas CT para ot_proceso_map.
• Columna puramente aditiva: no modifica ninguna columna existente.
• Rollback trivial: revertir el commit elimina la columna de los Excel de salida.
• Regla de negocio centralizada en una constante Python (GESTORA_MAP), versionada en git.

Opción C: Hardcoded en reportes (Power BI, Excel)

Cada consumidor (dashboard, reporte) implementa su propia lógica ad-hoc.

Descartada porque:

• Duplica la regla de negocio en N consumidores.
• No escala: agregar un nuevo valor a GESTORA_MAP requiere tocar cada consumidor.
• Genera inconsistencias entre dominios.

Decisión

Opción B — Zonal_Gestora se computa en el pipeline Python como columna derivada.

Fundamento teórico

Desde Kimball (modelado dimensional), Zonal_Gestora es un atributo de la dimensión “Proyecto/OT”, no un hecho de la tabla de facturación. Su fuente de verdad es el Control de OTs. Duplicarlo manualmente en la fact table viola el principio de single source of truth.

Es un role-playing dimension textbook: la misma dimensión geográfica (Zonal) jugando dos roles. Igual que no tendrías Fecha y Fecha_Envío sino Fecha_Orden y Fecha_Envío, lo correcto es Zonal_Ejecutora y Zonal_Gestora con semántica explícita.

En data warehousing, la práctica correcta es hacer el JOIN en el pipeline y materializar en la capa analítica (Excel salida, SQLite, Power BI), no duplicar en la fuente.

Implementación

GESTORA_MAP = {"OSORNO": "OSORNO", "CASTRO": "CHILOÉ", "ANCUD": "CHILOÉ"}

• core/build_cloud_dataframes.py: get_ot_maps() retorna (ot_proceso_map, ot_gestora_map) en single-pass. apply_ot_zonal_gestora(df, gestora_map) como función pública reutilizable (DRY).
• domains/pedidos_hes/business_pedidos_HES.py: paso 8d aplica Zonal_Gestora a los 4 sub-DataFrames.
• domains/facturacion/business_facturacion.py: enriquece df_NF y df_LF cuando tienen columna OT.
• No se toca: Google Sheets (ni FACTURACIÓN ni hojas CT).

Consecuencias

• Los Excel de salida y dashboards Power BI tendrán la columna Zonal_Gestora disponible.
• Si una OT no está en Control de OTs, Zonal_Gestora queda como None (no se infiere desde Ejecutora).
• Power BI necesitará actualizar sus modelos para consumir la nueva columna (migración pendiente).
• Futura evolución: si el fallback None → Zonal_Ejecutora se necesita, es un cambio de una línea en apply_ot_zonal_gestora.

Ver también

• Decisiones-Tecnicas — tabla resumen
• Dim_OT-Modelo-Explicacion — modelo dimensional de OTs
• Engram: adr/zonal-gestora-derived-not-physical (ID #1220)
• SDD artifacts: sdd/zonal-gestora/design (Engram #1218), sdd/zonal-gestora/tasks (#1219)