chore: import DH V2 D5.6.4 production baseline

docs/PHASE_D5_3_7.md

@@ -0,0 +1,125 @@
+# 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.