dh-inspeccion-v2/docs/PHASE_D5_3_7.md

Fase D5.3.7 — Plan e importación transaccional

Versión: 0.19.3-7.1

Objetivo

D5.3.7 agrega la capa de seguridad que faltaba entre la conciliación fila-a-fila de D5.3.6 y la escritura del Maestro. Un archivo analizado ya no se interpreta como una colección directa de INSERT: primero se transforma en un plan de entidades únicas y relaciones, se resuelven revisiones obligatorias y recién entonces un usuario con permiso explícito puede aplicar el lote en una sola transacción.

El flujo queda:

1. Análisis.
2. Normalización.
3. Conciliación preliminar contra Maestro.
4. Plan de importación por entidad.
5. Confirmación explícita.
6. Aplicación transaccional.

Principios de seguridad

• WARNING y CONFLICT nunca se convierten silenciosamente en altas automáticas.
• Un plan con cualquier ítem REVIEW queda bloqueado.
• La confirmación utiliza el plan_hash; si el plan cambió, la aplicación se rechaza como obsoleta.
• La aplicación completa corre dentro de una única transacción PostgreSQL.
• Los identificadores externos se vuelven a validar justo antes de insertar para reducir carreras entre planificación y aplicación.
• Una coincidencia exacta no se acepta si el activo existente pertenece a otra Área/Operadora; D5.3.7 no reubica ni reasigna activos existentes silenciosamente.
• Las reglas de jerarquía y el contexto Área + Operadora se vuelven a verificar antes de escribir activos.
• La API separa asset_imports.manage de asset_imports.apply. Aplicar/revertir queda reservado inicialmente a Admin y Director.
• La reversión es lógica: no borra activos del Maestro.

Plan territorial Área / Yacimiento

El perfil MENDOZA_YACIMIENTOS_V1 deduplica las filas en entidades y relaciones reales:

• Organizaciones.
• Áreas.
• Yacimientos.
• Relaciones Área ↔ Operadora.

Por eso 230 filas no significan 230 altas. El mismo Área u Operadora puede participar en muchas filas y se representa una sola vez dentro del plan.

La coincidencia sigue siendo conservadora y normalizada para mayúsculas, signos y acentos. El nombre de Yacimiento no se trata como clave global: se evalúa dentro del Área.

Tipo Concesión y Departamento se preservan en el payload del plan y en la trazabilidad, pero D5.3.7 no crea derechos legales automáticamente porque el padrón no aporta por sí solo instrumento, vigencia y evidencia suficientes para construir esa capa con seguridad.

Cuando una organización comienza por UTE, el plan propone perfil de organización UTE; la composición interna y porcentajes de participación no se infieren de un nombre concatenado.

El valor fuente Sin Empresa Operadora se interpreta como ausencia explícita de operadora, no como una empresa. Esos Yacimientos pueden quedar registrados en DRAFT dentro de su Área, sin contexto operativo Área + Operadora, preservando el literal fuente para una asignación posterior. Nunca se crea una organización ficticia con ese nombre.

Como referencia de validación del archivo real recibido (sin considerar coincidencias ya existentes en el Maestro), las 230 filas se descomponen en 64 Áreas, 230 pares Área/Yacimiento, 12 Organizaciones reales y 47 relaciones Área↔Operadora: 353 ítems de entidad/relación. Además, 26 Yacimientos traen explícitamente Sin Empresa Operadora. Los conteos que muestre producción pueden ser menores en CREATE si existen coincidencias válidas.

Plan de inventario técnico

El perfil MENDOZA_INVENTORY_V1 exige antes de planificar:

• seleccionar la Organización operadora existente;
• confirmar/definir un namespace de identificadores externos, por ejemplo PSENERGY.

El plan usa ese namespace para distinguir inventarios que pueden reutilizar el mismo número de identificación en fuentes distintas.

Los contenedores físicos se crean sólo cuando la fuente permite identificar una instancia concreta. Por ejemplo, de una ubicación como:

MENDOZA / VIZCACHERAS / PTC / PTCVIZ01

se puede proponer PTCVIZ01. En cambio categorías genéricas como SET, EM, TRANSPORTE, OFICINA o ALMACEN no se convierten silenciosamente en un activo por cada fila. Se agrupan en un único ítem estructural [A VALIDAR] ... por contexto, que requiere decidir si corresponde crear o vincular un contenedor real.

Las cantidades agrupadas, estados ambiguos y conflictos de fuente quedan en revisión obligatoria.

Acciones del plan

Cada ítem puede quedar en:

• CREATE: crear una entidad nueva.
• MATCH: reutilizar una entidad existente del mismo tipo.
• REVIEW: requiere intervención antes de aplicar.
• IGNORE: sólo permitido para activos técnicos; no se permite romper la estructura ignorando Áreas, Organizaciones, Yacimientos o contenedores estructurales.

Las resoluciones manuales quedan registradas con usuario, fecha y motivo.

Aplicación

El endpoint de aplicación exige:

• plan activo;
• estado READY;
• mismo plan_hash confirmado en pantalla;
• permiso asset_imports.apply;
• coincidencias todavía activas;
• Operadora todavía activa;
• IDs externos todavía disponibles;
• tipos y reglas padre/hijo vigentes;
• contexto operativo completo.

La aplicación crea en orden las entidades raíz, relaciones operativas, Yacimientos, instalaciones y activos técnicos. Las altas quedan en estado de información DRAFT, origen IMPORT, con documento fuente, procedencia e historial inicial.

Los ítems que ya coinciden con Maestro no son modificados por esta fase.

Reversión

Revertir lote funciona sólo sobre el plan aplicado activo y dentro de una transacción.

La reversión:

• cierra identificadores externos creados por el lote;
• inactiva lógicamente los activos creados por el lote;
• retira su contexto operativo antes de inactivarlos;
• cierra las relaciones Área ↔ Operadora creadas por el lote;
• registra nuevas versiones de estado;
• limpia la referencia imported_asset_id de las filas del lote;
• conserva toda la trazabilidad del plan.

La reversión se bloquea si activos posteriores, relaciones externas, relevamientos o inspecciones ya dependen de entidades creadas por el lote.

Limitaciones deliberadas

D5.3.7 no intenta todavía:

• interpretar automáticamente integrantes y porcentajes de una UTE a partir del nombre;
• crear concesiones/permisos legales sin instrumento y vigencia verificables;
• modificar activos existentes que hagan MATCH;
• resolver de forma probabilística alias o nombres parecidos;
• convertir todos los términos del inventario fuente en niveles de jerarquía;
• persistir una taxonomía completa de condición técnica cuando la fuente sólo trae textos ambiguos.

Estas restricciones son intencionales para evitar contaminación masiva del Maestro.