Glosario de Negocio — IngelCoding
Términos de dominio usados en el pipeline, el DW y los informes de INGELSUR/SAESA. Cada definición indica su fuente de certeza. Los términos marcados con (?) o “por confirmar” son inferencias — validar con Manuel.
Identificadores de proyecto / obra
Sección titulada «Identificadores de proyecto / obra»| Término | Definición |
|---|---|
| OT (Orden de Trabajo) | Identificador principal de una obra o proyecto de INGELSUR. Es la llave universal de cruce entre todos los dominios. Se canoniza vía dim_ot.Ot_Limpia (confiabilidad ~95%). Puede aparecer en subject, body o filename del correo. |
| OA | Subtipo de identificador de obra. Aparece como prefijo en dim_ot (ej. OA-123456). Usado para obras de alumbrado u otras categorías específicas. (por confirmar: distinción funcional exacta vs OT) |
| MAN | Subtipo de identificador que aparece como prefijo en dim_ot. (por confirmar: uso y categoría de negocio que representa) |
| LITERAL | Texto libre o descripción larga de la obra. A veces contiene la OT embebida. No es un identificador numérico formal. (por confirmar: rol exacto en el flujo de negocio) |
Documentos del ciclo de cobro
Sección titulada «Documentos del ciclo de cobro»| Término | Definición |
|---|---|
| Valorización | Documento (planilla xlsx) que INGELSUR elabora tras ejecutar una obra. Detalla las actividades realizadas, materiales usados, HH, y los montos que INGELSUR cobra al mandante. Es el punto de partida del ciclo de cobro. Una valorización puede originar 1..N pedidos. |
| EDP (Estado de Pago) | Tipo de planilla de valorización. Representa una entrega de cobro, potencialmente parcial (EDP N°1, EDP N°2…). Estructura interna: hojas {Materiales SAP, Disponibilidad BBPP, Valorizacion de Actividades, Resumen Cobros, Desplazamientos, Otros Costos}. |
| EP (Estado de Proyecto) | Tipo de planilla de valorización. Comparte estructura interna con EDP (firma idéntica de sheet_names); el nombre del archivo varía (EP OT*, EDP*). Clasificar por estructura > por filename. |
| valorizacion_final | Tipo de planilla xlsx de valorización con estructura {Cuadratura Actividades, Imputación por clase de costes, Esquema Señaletica, Servicios HH Obras, V. Otros Costos, Datos}. Suele llevar “valoriza” en el filename. Contiene el bloque ‘Pedido Servicios’ que registra el N° Pedido y HES asociado. |
| Pedido (Pedido de Compra / Pedido SAP) | Orden de compra que emite el mandante (SAESA) en su ERP (SAP) tras revisar y visar la valorización. Identificado por un N° Pedido. Una valorización puede originar varios pedidos. La relación pedido↔valorización se traza vía OT + bloque ‘Pedido Servicios’. |
| HES (Hoja de Entrada de Servicios) | Documento que emite el mandante (SAESA) en SAP para confirmar la recepción del servicio. Número de ~10 dígitos (series 100xxxxxx / 200xxxxxx). Condición necesaria para facturar: INGELSUR no puede emitir factura sin una HES. El par (N° Pedido, HES) es la llave de cruce con la tabla fact_facturacion. |
| Visación | Proceso de aprobación de la valorización/pedido por parte del mandante (SAESA). Ocurre por correo electrónico en el hilo INGELSUR↔SAESA. Estados posibles: visado / con_observaciones / pendiente. ⚠ No está modelado como entidad persistida en el DW actual (se infiere: si hay HES, hubo visación). |
| Factura | Documento tributario que INGELSUR emite al mandante una vez que existe HES. Registrada en fact_facturacion con columnas OT, Proceso, N°_Pedido, HES, Monto. |
| Nota de Crédito | Documento que anula parcial o totalmente una factura emitida. (por confirmar: si el dominio facturación las captura y cómo se cruzan con fact_facturacion) |
| Cobro de desplazamiento | Monto que INGELSUR cobra al mandante por el traslado de brigadas hasta la obra (viáticos, movilización, tiempo de viaje). Se registra dentro de la valorización (hoja Desplazamientos en EDP/EP). En el control de gestión se agrega por zonal y por mes; cada valorización con desplazamiento puede tener o no una OT individual asociada. |
| Consolidado sin OT | Valorización con cobro de desplazamiento en la que NO se detecta una OT individual (n_ot=0). Típicamente corresponde a contratos marco o cotizaciones que agrupan varias obras bajo un mismo documento sin desglose por OT. Se reporta como bucket propio (sin_OT) en el panel de cobros de desplazamiento porque su trazabilidad a una obra específica es nula. |
Actores y mandantes
Sección titulada «Actores y mandantes»| Término | Definición |
|---|---|
| Mandante | El cliente que encarga y paga las obras a INGELSUR. Son distribuidoras eléctricas. En el sistema: SAESA, Frontel, Luz Osorno. Emiten el pedido, visa la valorización y la HES. |
| SAESA | Sociedad Austral de Electricidad S.A. Mandante principal. Opera en el sur de Chile. |
| Frontel | Filial de SAESA. Mandante secundario. (por confirmar: distinción geográfica/operativa exacta vs SAESA) |
| Luz Osorno | Distribuidora de la región de Osorno. Mandante del sistema. (por confirmar: si opera con el mismo flujo de correos/HES que SAESA) |
| INGELSUR | La empresa constructora/ejecutora. Ejecuta obras eléctricas en terreno, valoriza y factura al mandante. |
Dimensiones geográficas y organizacionales
Sección titulada «Dimensiones geográficas y organizacionales»| Término | Definición |
|---|---|
| Zonal Ejecutora | La zona geográfica donde se ejecuta físicamente la obra (ej. Castro, Ancud, Osorno). Se deriva del código de brigada o de la OT. |
| Zonal Gestora | La oficina administrativa que gestiona el proyecto/contrato. Ejemplo: obras ejecutadas en Castro y Ancud son gestionadas por la oficina de Chiloé. Distinción importante para reportes gerenciales. |
| BBOO (Brigadas de Operaciones) | Tipo de brigada de trabajo de INGELSUR. Realiza operaciones de mantenimiento y conexión. El código de brigada codifica tipo + zonal + número (ej. BBOO-OS-01 = operaciones / Osorno / 01). Registradas en dim_personal_brigadas. |
| BBPP (Brigadas Pesadas) | Tipo de brigada de trabajo de INGELSUR. Realiza obras de mayor envergadura. Código análogo a BBOO (ej. BBPP-OS-01 = pesada / Osorno / 01). Los gastos de brigada (sobretiempo, EPD) pertenecen al dominio costos, no a valorizaciones. (por confirmar: si algún consolidado BBPP/BBOO debe incluirse en el informe de valorizaciones o siempre excluir) |
Tipos de proceso / negocio
Sección titulada «Tipos de proceso / negocio»| Término | Definición |
|---|---|
| Proceso | Clasificación del tipo de actividad o línea de negocio de una obra. Ejemplos: Obras Menores-NNSS, Obras Medianas, MC (Mantenimiento Correctivo), EE.RR. (Energías Renovables). Normalizado vía dim_proceso y config/proceso_aliases.yaml. |
| NNSS (Nuevos Suministros) | Proceso de conexión de nuevos clientes a la red eléctrica. Tipo de proceso frecuente en las valorizaciones. |
| MC (Mantenimiento Correctivo) | Tipo de proceso: reparaciones y correcciones en la red. (por confirmar: si se separa de Obras Menores en el informe final) |
| EE.RR. (Energías Renovables) | Tipo de proceso relacionado con instalaciones de energía solar u otras renovables. (por confirmar: frecuencia e importancia en el universo de valorizaciones) |
Estados de facturación
Sección titulada «Estados de facturación»| Término | Definición |
|---|---|
| CF (Con Factura) | Estado de un pedido/HES que ya tiene factura emitida en el sistema. |
| SF (Sin Factura / Sin HES) | Estado de un pedido que aún no tiene HES ni factura. Puede significar que el ciclo está en curso (brecha temporal SAP↔HES). |
| SIN_HES | Variante del estado SF: el pedido existe en SAP pero no tiene HES asociada todavía. Estos estados se calculan en memoria; no están persistidos como campo en el DW. |
Ventanas temporales de análisis
Sección titulada «Ventanas temporales de análisis»| Término | Definición |
|---|---|
| Ventana reciente | Los 2 meses calendario COMPLETOS previos al mes actual (ventana MÓVIL, relativa a la fecha de cómputo). Si el mes actual es junio 2026, “reciente” = facturas con fecha_emision en [2026-04-01, 2026-06-01) (abril y mayo completos). Excluye el mes actual (parcial). Implementado en calcular_ventana_reciente(hoy) en domains/valorizaciones/control_gestion.py. Definición confirmada por Manuel (2026-06-15). |
| Histórico | Todas las facturas detectables por el pipeline, sin corte inferior de fecha. Sirve de referencia de comparación vs. la ventana reciente. Sin límite superior salvo la fecha máxima de los datos. |
Principios Aplicados
Sección titulada «Principios Aplicados»- Single-Source-of-Truth: cada término tiene una definición canónica aquí; los pipelines y docs deben referenciar este glosario, no redefinir localmente.
- Separation-of-Concerns: los términos de negocio se documentan en el vault (capa de conocimiento), separados de su implementación en el código (dominio Python / DW).