dh-inspeccion-v2/docs/PHASE_D5_5.md

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.