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,66 @@
+# Fase D5.5 · Planificación web y checklist
+
+## Objetivo
+
+Consolidar la preparación de una visita desde oficina antes de su inicio en campo. La planificación queda anclada a un Área y a una Organización operadora vigente, incorpora antecedentes y próximos controles automáticamente, permite sumar registros preventivos y exige que toda exclusión quede justificada y trazable.
+
+## Contexto operativo explícito
+
+Cada visita nueva puede guardar `operational_area_id` y `operator_company_id`. La API valida que ambos pertenezcan a tipos con roles `AREA` y `COMPANY` y que exista una relación `OPERATOR` vigente entre ellos. El `scope_asset_id` conserva compatibilidad y, para la planificación D5.5, referencia el Área seleccionada.
+
+La web resuelve primero el Área y luego ofrece únicamente las Organizaciones operadoras vigentes de ese Área.
+
+## Checklist automático
+
+Cada generación se conserva como una fotografía append-only en `inspection_visit_checklist_items`. La generación vigente clasifica los hallazgos del contexto en:
+
+- `COMPANY_OVERDUE`: respuesta de empresa vencida.
+- `VERIFICATION_OVERDUE`: control de campo vencido.
+- `UPCOMING_CONTROL`: control previsto dentro de los próximos 30 días desde la fecha planificada.
+- `ANTECEDENT`: antecedente histórico sin acción automática inmediata.
+
+Los registros con vencimientos o controles accionables se incorporan automáticamente a la visita. Regenerar no borra generaciones anteriores.
+
+Si cambia Área, Operadora o fecha de inicio, el checklist vigente queda marcado como no válido hasta que oficina lo regenere y revise. La confirmación a `PLANNED` no regenera silenciosamente: exige una generación vigente.
+
+## Registros preventivos y exclusiones
+
+Oficina puede agregar registros del Inventario que pertenezcan al mismo Área y Operadora aunque no tengan un pendiente previo. Esos registros quedan identificados con origen `PREVENTIVE`.
+
+Los orígenes disponibles son:
+
+- `LEGACY`
+- `AUTOMATIC`
+- `PREVENTIVE`
+- `VERIFICATION`
+
+Retirar un registro de la visita requiere una exclusión específica con motivo de al menos 10 caracteres. La proyección vigente se guarda en `inspection_visit_assets`, mientras la historia se agrega a `inspection_visit_asset_events`. Una reincorporación no elimina la exclusión anterior. Un registro excluido tampoco puede reincorporarse por la operación genérica de alta preventiva.
+
+## Visitas de verificación
+
+Las visitas creadas desde Hallazgos continúan siendo visitas normales, ahora con Área y Operadora explícitas y registros con origen `VERIFICATION`. La planificación debe completar equipo y checklist antes de confirmarse.
+
+## Inicio exclusivo desde APK
+
+La web crea, configura y confirma la planificación. No expone una acción de inicio. El endpoint de inicio mantiene `assertMobileInspector`, que exige transporte bearer y rol inspector, por lo que el inicio y la ejecución de campo permanecen reservados a la APK.
+
+## Trazabilidad
+
+D5.5 agrega auditoría de:
+
+- generación de checklist;
+- exclusión de un registro;
+- reincorporación de un registro.
+
+Las tablas históricas nuevas sólo conceden `SELECT` e `INSERT` al rol de aplicación y revocan `UPDATE` y `DELETE`.
+
+## Compatibilidad preservada
+
+D5.5 no modifica las reglas consolidadas:
+
+- una visita genera una sola Acta;
+- el Acta cerrada no se reescribe;
+- los hallazgos y respuestas históricas permanecen protegidos;
+- las verificaciones sucesivas siguen siendo append-only;
+- el catálogo contextual D5.4.1 continúa validando aplicabilidad y gravedad;
+- SMTP puede seguir pendiente sin bloquear esta fase.