# 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`:

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

Sobre esa jerarquía se agrega el contexto operativo:

```text
Á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.