dh-inspeccion-v2/docs/PHASE_D5_3_3.md

D5.3.3 · Modelo operativo definitivo

Versión: 0.19.3-3

Objetivo

Cerrar el modelo de Maestro antes de implementar hallazgos por activo y antes del rediseño UX. La fase mantiene la jerarquía padre/hijo como contención física y separa explícitamente:

• Área territorial;
• Organización (empresa, UTE u otra figura);
• rol operativo de una organización sobre un Área;
• permiso/concesión/derecho legal sobre un Área;
• estado de calidad del dato;
• estado operativo del activo;
• identificadores oficiales/externos;
• documentos fuente;
• composición histórica de una UTE.

Compatibilidad

No se renombran columnas históricas como operator_company_id ni se reemplaza la tabla area_company_relations. Se amplían para conservar compatibilidad con D5.3–D5.3.2.1. La API incorpora alias semánticos de Organización sin romper las rutas existentes de Empresa.

Reglas centrales

1. parent_id representa sólo jerarquía física.
2. El tipo Área / Concesión pasa a mostrarse como Área.
3. El tipo Empresa / Operadora pasa a mostrarse como Organización.
4. Una Organización puede perfilarse como Empresa, UTE, entidad pública u otra figura.
5. Una UTE conserva participantes, porcentaje, vigencia y documento fuente de forma histórica.
6. Una relación Área–Organización tiene rol (OPERATOR, CONCESSIONAIRE, etc.).
7. Sólo una relación activa con rol OPERATOR habilita la asignación exclusiva de activos.
8. Las concesiones/permisos se registran como derechos legales separados del Área.
9. information_status sigue indicando calidad/validación del registro.
10. operational_status indica situación física/operativa y no reemplaza la calidad del dato.
11. Un activo puede tener múltiples identificadores externos y múltiples documentos fuente.
12. Cuenca y Departamento son clasificaciones del Área, no niveles obligatorios del árbol.

Estado operativo

• UNKNOWN
• IN_SERVICE
• TEMPORARILY_OUT_OF_SERVICE
• OUT_OF_SERVICE
• DECOMMISSIONED
• ABANDONED

Registro documental

Se agregan:

• source_documents
• asset_source_documents
• asset_external_identifiers
• organization_profiles
• organization_memberships
• area_legal_rights
• area_legal_right_organizations

Todas las relaciones sensibles conservan vigencia histórica y no dependen de borrado físico en operación normal.

UI de esta fase

D5.3.3 sólo expone el estado operativo y actualiza la semántica Área/Organización en las pantallas existentes. La administración intuitiva de documentos, UTE, derechos e identificadores se realizará en D5.3.4 dentro del nuevo Asset Center, para no agregar una pantalla técnica temporal que luego haya que descartar.

Datos de desarrollo

El caso DH-DEV-DEMO se actualiza para:

• registrar el Informe Técnico 124/2026 como documento fuente de prueba;
• vincular ese documento con Área, Organización, Planta y Tanques;
• registrar la Organización de prueba con perfil COMPANY;
• utilizar una relación Área–Organización con rol OPERATOR;
• marcar TK-57 y TK-58 como OUT_OF_SERVICE, según el caso de prueba.

El limpiador protegido incorpora las nuevas tablas y sigue siendo dry-run por defecto.