76 lines
3.1 KiB
Markdown
76 lines
3.1 KiB
Markdown
# 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.
|