From ae7326f20a49fdc3cefa4d387babfb70bf269146 Mon Sep 17 00:00:00 2001 From: enlineawork Date: Wed, 9 Sep 2026 14:47:52 -0300 Subject: [PATCH] =?UTF-8?q?docs:=20consolidar=20modelo=20can=C3=B3nico=20d?= =?UTF-8?q?e=20Inventarios=20F6.1?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/F6_INVENTORY_MODEL.md | 132 ++++++++++++++++++++++++++++++++++++- 1 file changed, 131 insertions(+), 1 deletion(-) diff --git a/docs/F6_INVENTORY_MODEL.md b/docs/F6_INVENTORY_MODEL.md index 78933cc..3ef8a1f 100644 --- a/docs/F6_INVENTORY_MODEL.md +++ b/docs/F6_INVENTORY_MODEL.md @@ -1 +1,131 @@ -# F6 · Modelo definitivo de Inventarios +# F6.1 · Modelo canónico de Inventarios + +Este documento es la referencia funcional y técnica del modelo de Inventarios de DH Inspección V2. Ante una contradicción con documentación histórica, prevalecen este documento, las migraciones vigentes y los contratos automatizados de F6.1. + +## 1. Jerarquía física + +La estructura territorial y física es única: + +**Departamento → Área → Yacimiento → Instalación → Subinstalación** + +Reglas: + +- `Departamento` es raíz. +- `Área` requiere un Departamento padre. +- `Yacimiento` requiere un Área padre. +- `Instalación` requiere un Yacimiento padre. +- `Subinstalación` requiere una Instalación padre. +- La base de datos rechaza combinaciones de padre/hijo que no respeten esta secuencia. +- El campo `parent_id` expresa exclusivamente esta pertenencia física. + +## 2. Empresa no pertenece al árbol físico + +`Empresa` es un maestro independiente. No es padre de Departamento, Área, Yacimiento, Instalación ni Subinstalación. + +La Operadora vigente de un Área se expresa mediante `area_company_relations`, con `relation_role = 'OPERATOR'` y vigencia temporal. Esta relación es la fuente de verdad para saber qué Empresa opera un Área en una fecha determinada. + +`assets.operator_company_id` puede existir como fotografía de compatibilidad del contexto actual, pero no debe utilizarse para reconstruir la historia ni para reparentar Inventario. + +**Cambiar de Operadora nunca mueve la jerarquía física.** Se finaliza la relación temporal anterior y se crea la nueva relación Empresa ⇄ Área. + +## 3. Contexto transversal de Área + +Los elementos bajo un Área conservan `operational_area_id` como contexto transversal para consultas, planificación y trazabilidad. El Yacimiento forma parte del alcance físico, pero no sustituye al Área como contexto operativo de una Inspección. + +Por lo tanto, la planificación de una Inspección trabaja con: + +**Área + Operadora vigente + Inspector responsable + fecha/hora de inicio**. + +## 4. Clasificación técnica + +Los niveles territoriales no usan clasificación técnica: + +- Departamento: sin familia técnica. +- Área: sin familia técnica. +- Yacimiento: sin familia técnica. + +Los niveles físicos sí la requieren: + +- Instalación: una familia de nivel `INSTALLATION`. +- Subinstalación: una familia de nivel `SUBINSTALLATION` compatible con la familia de la Instalación padre. + +La compatibilidad se almacena en `inventory_family_parent_rules` y se valida también en PostgreSQL. Una misma familia de Subinstalación puede ser compatible con varias familias de Instalación. + +Los campos técnicos específicos de cada familia se definen en `inventory_family_attribute_definitions` y sus valores por Inventario en `asset_inventory_attribute_values`. + +## 5. Hallazgos + +Un Hallazgo puede asignarse directamente a: + +- Yacimiento. +- Instalación. +- Subinstalación. + +No se asignan Hallazgos directos a Departamento ni Área. + +`OTROS / Agregar otro` debe estar siempre disponible. Permite describir un Hallazgo que no exista todavía en el catálogo aplicable y dejarlo registrado para revisión posterior. + +Para Yacimiento, la aplicabilidad del catálogo puede resolverse por tipo de Inventario y por excepciones del objeto concreto. Yacimiento no necesita una familia técnica para recibir Hallazgos. + +Instalación y Subinstalación deben estar clasificadas antes de recibir un Hallazgo. + +## 6. Inventario nacido en campo + +La APK puede incorporar Inventario encontrado durante una Inspección. Un registro creado en campo conserva su trazabilidad de origen y, antes de permitir Hallazgos sobre él, debe tener como mínimo: + +- GPS capturado para la creación. +- al menos una fotografía de campo. +- clasificación técnica cuando se trate de Instalación o Subinstalación. + +La excepción transitoria que permite crear un registro `FIELD_SURVEY + DRAFT` sin familia existe únicamente para completar la transacción de alta; no habilita Hallazgos sin clasificación. + +## 7. Carga manual recomendada + +El orden seguro para construir una estructura desde cero es: + +1. Crear las Empresas necesarias como maestros independientes. +2. Crear Departamento. +3. Crear Área dentro del Departamento. +4. Registrar la Operadora vigente del Área, si ya se conoce. +5. Crear Yacimiento dentro del Área. +6. Crear Instalación dentro del Yacimiento y seleccionar su familia técnica. +7. Crear Subinstalación dentro de la Instalación y seleccionar una familia compatible. + +La importación de archivos no debe definir la arquitectura del modelo. Los datos externos se adaptan a este contrato; el contrato no se deforma para adaptarse a cada planilla. + +## 8. Historia y consulta temporal + +DH conserva dos conceptos separados: + +- historia física/contextual del Inventario; +- historia temporal de la relación Área ⇄ Empresa. + +Los cambios relevantes generan versiones y eventos de auditoría. Las consultas históricas deben utilizar la vigencia correspondiente a la fecha consultada, no sólo la fotografía actual de las columnas de `assets`. + +## 9. Barreras de integridad + +La consistencia no depende sólo de la interfaz. Se protege en varias capas: + +- DTO y servicios de API validan niveles y padres. +- PostgreSQL valida la jerarquía canónica. +- PostgreSQL valida nivel y compatibilidad de familias técnicas. +- la planificación valida una relación Operadora ⇄ Área vigente. +- los Hallazgos validan nivel permitido, clasificación técnica y pertenencia a la Inspección/Acta. +- CI ejecuta la cadena completa de migraciones sobre PostGIS limpio y los contratos transversales. + +## 10. Corte limpio F5.1 + +`F51CleanManualInventory1790087400000` fue un corte intencional de inicio limpio. Eliminó datos operativos/importados de desarrollo y dejó los maestros técnicos necesarios para reconstruir manualmente una estructura confiable. + +Es una migración deliberadamente no reversible mediante `migration:revert`. Su recuperación depende del backup PRE del despliegue. No debe copiarse este patrón para migraciones normales sin una decisión explícita y una estrategia de restauración probada. + +## 11. Regla para cambios futuros + +Cualquier modificación del modelo debe mantener simultáneamente: + +1. la jerarquía física canónica; +2. Empresa fuera del árbol; +3. relación temporal Área ⇄ Empresa como fuente de verdad operativa; +4. compatibilidad técnica de familias; +5. trazabilidad histórica; +6. protección en base de datos y tests, no sólo en la UI.