docs: consolidar modelo canónico de Inventarios F6.1
This commit is contained in:
+131
-1
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user