132 lines
6.3 KiB
Markdown
132 lines
6.3 KiB
Markdown
# 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.
|