chore: import DH V2 D5.6.4 production baseline

2026-09-05 10:12:35 -03:00
commit 82213e72f5
757 changed files with 84218 additions and 0 deletions
@@ -0,0 +1,110 @@
+# DH V2 · Fase D5.3.5 — Centro de Importaciones y escalabilidad
+
+Versión: `0.19.3-5`
+
+## Objetivo
+
+D5.3.5 parte de D5.3.4 ya desplegada y adapta el Maestro a volúmenes y formatos reales recibidos por la Dirección de Hidrocarburos.
+
+La fase tiene dos objetivos:
+
+1. evitar que el Asset Center intente cargar árboles completos de miles de activos;
+2. incorporar un Centro de Importaciones que permita analizar XLSX/CSV de forma trazable antes de decidir qué registros se incorporan al Maestro.
+
+## Regla de seguridad de esta fase
+
+**D5.3.5 NO crea ni modifica activos desde una importación.**
+
+Un archivo subido:
+
+1. se conserva con SHA-256;
+2. se registra como documento fuente;
+3. se inspecciona y detecta el formato;
+4. se normalizan las filas en una capa de staging;
+5. se detectan advertencias y conflictos;
+6. se muestra una vista previa en el dashboard.
+
+La aplicación efectiva al Maestro queda deliberadamente fuera de esta fase.
+
+## Perfiles iniciales
+
+### `MENDOZA_INVENTORY_V1`
+
+Reconoce el esquema general utilizado en inventarios de instalaciones con campos equivalentes a:
+
+- Item;
+- Área / Yacimiento;
+- Instalación;
+- Sub instalación;
+- Equipo;
+- Denominación;
+- Ubicación;
+- N° ID / Inventario;
+- Cantidad;
+- Especificaciones técnicas;
+- Estado.
+
+El análisis conserva el valor original y propone, cuando es seguro, normalizaciones auxiliares para:
+
+- familia técnica;
+- clase/tipo de fuente;
+- fabricante/modelo;
+- estado operativo sugerido;
+- condición sugerida.
+
+Los valores ambiguos (`SI/NO`, `S/N`, `Bueno`, etc.) no se transforman automáticamente en un estado operativo definitivo.
+
+### `MENDOZA_YACIMIENTOS_V1`
+
+Reconoce tablas de referencia con Yacimiento, Área, Departamento, tipo de derecho y Operadora.
+
+## Conflictos detectables
+
+Entre otros:
+
+- campos estructurales faltantes;
+- cantidad inválida;
+- cantidad agrupada mayor a uno;
+- estado fuente que requiere mapeo;
+- ID de inventario repetido;
+- mismo ID de inventario en ubicaciones diferentes;
+- formato no reconocido.
+
+La repetición de un ID no se interpreta automáticamente como duplicado real, traslado o error: se deriva a revisión.
+
+## Persistencia
+
+Se incorporan:
+
+- `asset_import_batches`;
+- `asset_import_rows`;
+- permisos `asset_imports.read` y `asset_imports.manage`;
+- índices trigram para búsqueda del Maestro.
+
+Los lotes no tienen DELETE para el rol de ejecución de la aplicación. Cancelar un lote cambia su estado y conserva evidencia y archivo para auditoría.
+
+## Asset Center escalable
+
+D5.3.4 incluía un árbol completo con límite de seguridad. D5.3.5 mantiene ese endpoint por compatibilidad, pero el dashboard utiliza ahora `GET /assets/tree-children`.
+
+La jerarquía:
+
+- carga sólo el primer nivel;
+- consulta hijos al expandir;
+- limita cada nivel a 200 filas;
+- usa filtros y búsqueda del servidor;
+- no intenta renderizar miles de nodos simultáneamente.
+
+La búsqueda del Maestro se amplía a datos relevantes como identificadores externos y ciertos atributos configurables (fabricante, modelo, número de serie y ubicación fuente).
+
+## Fuera de alcance
+
+D5.3.5 no:
+
+- crea activos desde filas de importación;
+- decide automáticamente jerarquías ambiguas por empresa;
+- crea 70+ tipos de activo a partir de denominaciones crudas;
+- modifica hallazgos/checklists;
+- reemplaza el valor original de una fuente.
+
+Estos puntos se resolverán progresivamente con perfiles específicos y taxonomía normalizada antes de D5.4.