# Fase D5.3.25 · Historial de verificaciones de hallazgos

## Objetivo

Convertir el seguimiento de verificaciones en una historia explícita de eventos. `nextControlOn` continúa siendo la proyección vigente usada por colas y planificación, pero deja de ser la única evidencia de lo ocurrido.

## Regla funcional

Cada hallazgo conserva todas las decisiones de control y todas las verificaciones sucesivas. Una nueva fecha nunca elimina la anterior y un resultado de campo ya registrado no puede sustituirse.

La secuencia puede contener tantas iteraciones como sean necesarias:

1. fecha de verificación definida por oficina;
2. visita de verificación planificada;
3. resultado de campo;
4. nueva fecha si el hallazgo continúa abierto;
5. nueva visita;
6. nuevo resultado;
7. cierre administrativo cuando corresponda.

## Ledger append-only

Nueva tabla `inspection_finding_verification_events`.

Registra eventos:

- `CONTROL_DATE_DEFINED`
- `CONTROL_DATE_CHANGED`
- `CONTROL_DATE_CLEARED`
- `VISIT_PLANNED`
- `RESULT_RECORDED`

Cada evento conserva fecha de ocurrencia, fecha anterior, fecha nueva, visita vinculada, resultado, observaciones, usuario y evidencia relacionada.

El rol de aplicación sólo tiene `SELECT` e `INSERT`. No puede actualizar ni borrar eventos.

## Antecedentes

La migración reconstruye eventos existentes desde:

- `inspection_finding_versions`, para cambios de `nextControlOn` realizados por oficina;
- `inspection_finding_verification_visits`, para visitas y resultados ya registrados.

No se inventan eventos que no puedan deducirse de los antecedentes persistidos.

## Resultado de campo inmutable

Una fila `inspection_finding_verification_visits` representa un intento concreto dentro de una visita concreta. D5.3.25 impide registrar dos veces el resultado del mismo intento.

La protección existe en dos niveles:

- servicio: devuelve `VERIFICATION_RESULT_IMMUTABLE` si ya existe resultado;
- base de datos: un trigger impide modificar los campos del resultado una vez que `result_recorded_at` quedó definido.

Una verificación posterior se realiza en una nueva visita y genera nuevos eventos, sin tocar la anterior.

## Proyección vigente

`inspection_findings.next_control_on` se conserva para búsquedas, dashboard y planificación. Cada cambio de ese campo se acompaña de un evento histórico dentro de la misma transacción.

Cuando un resultado:

- es `RESOLVED`, la proyección se limpia y el historial conserva el control realizado;
- es `NOT_RESOLVED`, la proyección se limpia y oficina debe definir el siguiente control;
- es `REQUIRES_NEW_DATE`, la nueva fecha se convierte en la proyección vigente y también queda registrada en el ledger.

## Consulta y web

`GET /api/v3/inspection-findings/:id/verification-history`

La ficha de Hallazgos incorpora “Historial completo de verificaciones” con:

- cambios de fecha;
- visitas planificadas;
- resultados sucesivos;
- observaciones;
- usuario;
- enlace a cada visita;
- cantidad de evidencias vinculadas.

## Reglas preservadas

- Una visita = una Acta.
- Actas cerradas no se modifican.
- El hallazgo original no se reescribe.
- La primera respuesta de empresa continúa inmutable.
- Las presentaciones posteriores siguen siendo append-only.
- El cierre del hallazgo continúa siendo una decisión administrativa.
- SMTP puede continuar pendiente sin bloquear esta fase.