dh-inspeccion-v2/docs/PHASE_D5_3_25.md

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.