126 lines
6.6 KiB
Markdown
126 lines
6.6 KiB
Markdown
# 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.
|