# Fase D5.3.24 · Historial de contexto operativo

## Objetivo

Preservar de forma explícita la evolución de la ubicación jerárquica y del contexto operativo de cada elemento del Inventario: padre físico, Área y Operadora.

## Regla funcional

Un cambio actual de jerarquía, Área u Operadora nunca elimina la relación anterior. La relación vigente se cierra con una fecha de fin y se agrega una nueva relación con fecha de inicio, motivo, usuario, request y versión del Inventario.

Los cambios ordinarios de nombre, código, atributos o descripción siguen usando la edición normal. Los registros consolidados no pueden cambiar `parentId`, `operationalAreaId` ni `operatorCompanyId` por el endpoint general: deben usar el cambio de contexto auditado. La única excepción es una alta de campo todavía DRAFT y pendiente de revisión, porque en ese momento oficina está corrigiendo el registro provisional antes de validarlo.

## Persistencia

Nueva tabla `asset_context_history` con un único registro activo por elemento. Guarda:

- `parent_id`
- `operational_area_id`
- `operator_company_id`
- `valid_from`
- `valid_until`
- `change_reason`
- `end_reason`
- `asset_version_number`
- `source`
- `request_id`
- usuario creador/finalizador

No existe eliminación de historial para el rol de aplicación.

## Reconstrucción de antecedentes

La migración analiza `asset_versions` y detecta sólo los puntos donde cambió alguno de estos tres valores. Esos puntos se convierten en intervalos históricos. Así se aprovecha el versionado ya existente y no se presupone que la relación actual existió desde el alta del elemento.

Para activos sin versiones recuperables se crea una línea base a partir del contexto vigente.

## Cambio de contexto

Nuevo endpoint:

`POST /api/v3/assets/:id/context`

Requiere `assets.manage_context` y un motivo obligatorio. Puede indicar una fecha efectiva pasada siempre que sea posterior al inicio del contexto vigente y no esté en el futuro.

La operación es transaccional:

1. valida padre y reglas de jerarquía;
2. valida Área–Operadora;
3. cierra el contexto anterior;
4. actualiza el contexto actual de `assets`;
5. captura una nueva `asset_version` tipo `CONTEXT_CHANGED`;
6. inserta el nuevo intervalo;
7. registra auditoría `ASSET_CONTEXT_CHANGED`.

## Consulta histórica

Nuevo endpoint:

`GET /api/v3/assets/:id/context-history`

El panel de Inventarios muestra contexto vigente e intervalos anteriores con motivo y vigencia.

`AssetTemporalService` también consulta `asset_context_history`, por lo que al pedir un activo a una fecha determinada reemplaza padre, Área y Operadora por los que estaban vigentes en ese instante.

## Permisos iniciales

`assets.manage_context` queda asignado por defecto a `admin` y `supervisor`. El Inspector conserva las altas de campo y las correcciones provisionales, pero no puede transferir un Inventario consolidado.

## Reglas preservadas

- Una visita = una Acta.
- Actas cerradas no se modifican.
- Hallazgos originales no se reescriben.
- Una conciliación de alta de campo no sustituye referencias históricas.
- SMTP puede continuar sin configurar.