dh-inspeccion-v2/docs/PHASE_D5_3.md

Fase D5.3 — Contexto operativo Área–Empresa

Versión: 0.19.3

Objetivo

Separar definitivamente la jerarquía física del Maestro de Activos de las relaciones operativas que determinan qué empresa explota activos dentro de un área.

D5.3 prepara el contrato de datos que después utilizarán la planificación web (D5.5) y la APK. No modifica todavía el flujo de inicio de inspecciones.

Modelo funcional

La jerarquía física existente continúa usando assets.parent_id:

Área
└── Instalación
    └── Estación
        └── Equipo

Sobre esa jerarquía se agrega el contexto operativo:

Área ↔ Empresa
       └── activos explotados por esa empresa dentro de esa área

Reglas:

• una empresa puede explotar varias áreas;
• un área puede estar explotada por varias empresas;
• un activo operativo tiene como máximo una combinación activa Área + Empresa;
• el área asignada debe ser ancestro físico del activo;
• el activo sólo puede asignarse a una empresa con vínculo activo con el área;
• Área y Empresa son roles configurables del tipo de activo;
• un activo Área o Empresa no recibe a su vez una asignación operativa;
• la relación Área–Empresa no se borra físicamente: se finaliza y conserva vigencia, motivo y auditoría.

Cambios de datos

asset_types

Se agrega operational_role:

• GENERIC: instalación, estación, equipo u otro activo operativo;
• AREA: activo que funciona como área/concesión;
• COMPANY: activo que funciona como empresa explotadora.

La migración deja todos los tipos existentes en GENERIC. No intenta deducir roles por nombre o código, para evitar clasificaciones automáticas erróneas.

area_company_relations

Nueva tabla histórica con:

• área;
• empresa;
• fecha de inicio;
• fecha de finalización;
• motivo de alta;
• motivo de finalización;
• usuario que creó el vínculo;
• usuario que lo finalizó;
• timestamps de auditoría.

Sólo puede existir un vínculo activo por cada par Área–Empresa.

assets

Se agregan:

• operational_area_id;
• operator_company_id.

Ambos campos son nulos o están completos juntos. La pareja representa la asignación operativa exclusiva del activo.

Integridad

La API y PostgreSQL validan que:

1. el Área y la Empresa existan y estén activos;
2. sus tipos tengan roles AREA y COMPANY respectivamente;
3. exista un vínculo Área–Empresa activo;
4. el activo asignado sea de un tipo GENERIC;
5. el Área pertenezca a la cadena de ancestros físicos del activo;
6. mover una rama de la jerarquía no deje descendientes fuera de su Área;
7. no se pueda finalizar una relación mientras existan activos asignados;
8. no se pueda inactivar un Área o Empresa mientras siga en uso.

Dashboard

Tipos de activo

El administrador puede indicar el rol operativo de cada tipo:

• Genérico;
• Área;
• Empresa.

No se permite cambiar un rol si eso rompería relaciones o asignaciones ya existentes.

Activos Área / Empresa

En la ficha se muestra Relaciones operativas:

• vincular Área ↔ Empresa;
• indicar motivo;
• consultar vínculos vigentes e históricos;
• ver cuántos activos dependen del vínculo;
• finalizar el vínculo con motivo, sólo cuando ya no tenga activos asignados.

Activos operativos

En activos de tipo GENERIC aparece Contexto operativo:

1. se selecciona Área;
2. se muestran sólo Empresas con vínculo activo en esa Área;
3. se selecciona la Empresa explotadora.

La asignación es opcional durante la transición de datos, para que la migración no invalide el Maestro ya existente. Antes de D5.5 deberán quedar configurados los activos que participen en inspecciones.

Listado

El Maestro incorpora filtros por:

• Área operativa;
• Empresa explotadora.

También muestra el contexto operativo actual de cada activo.

Permisos

• asset_relations.read: admin, director, supervisor, inspector y auditor;
• asset_relations.manage: admin y supervisor.

Auditoría e historial

Las altas y finalizaciones generan:

• ASSET_AREA_COMPANY_RELATION_CREATED;
• ASSET_AREA_COMPANY_RELATION_ENDED.

Los snapshots históricos de activos incorporan:

• rol operativo del tipo;
• Área operativa;
• Empresa explotadora.

La migración completa las versiones anteriores con valores neutros para evitar falsos cambios históricos.

Fuera de alcance de D5.3

No se implementa todavía:

• selección Área → Empresa en una planificación;
• generación automática de checklist;
• modelos de hallazgo por tipo/activo;
• gravedad 1–10;
• opción OTROS;
• cambios de APK.

Esos puntos pertenecen a D5.4, D5.5 y E1.