dh-inspeccion-v2/docs/PHASE_D5_3_24.md

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.