chore: import DH V2 D5.6.4 production baseline

2026-09-05 10:12:35 -03:00
commit 82213e72f5
757 changed files with 84218 additions and 0 deletions
@@ -0,0 +1,75 @@
+# 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.