EMTA - Manual Tecnico

Capas

1. Presentacion: SPA React con guards por perfil y etapas del flujo.
2. Aplicacion: controladores Laravel que concentran reglas de activacion, respuesta, control, cierre y auditoria.
3. Persistencia: MySQL con tablas maestras, configuracion, transaccionales y logs.
4. Integraciones: SMTP, WhatsApp/SMS via Brevo o webhook, almacenamiento documental y rutas publicas de branding.

Principios de diseño

• Aislamiento por tenant desde middleware y filtros automaticos.
• Seguridad por perfil, ruta, etapa y permisos puntuales de panel.
• Separacion entre configuracion estructural y tablas transaccionales de emergencia.
• Trazabilidad centralizada en audit_log_trs con exportacion amigable.
• Parametrizacion de acciones por riesgo, nivel y set de accion.

Controladores principales

• AuthController: login, codigo de activacion director, 2FA, reset y activacion de credenciales.
• ActivationController: preview, store, control panel, cambio de nivel, notificaciones, delegaciones, documentos y cierre.
• TenantDocumentController: carpetas, archivos, enlaces, descargas y relacion con riesgos.
• AuditController: consultas, filtros y dataset de responsabilidades.
• TenantUsersController y TenantPersonnelController: administracion de usuarios y personal.
• TenantBulkImportController: mapeo archivo-tabla y ejecucion de importacion inicial.
• TableCrudController: CRUD generico por tabla y soporte de mantenimiento.

Middleware y servicios

• Authenticate: autentica sesiones via Sanctum.
• ResolveTenant: resuelve tenant por contexto de usuario/cabecera.
• SetLocale: idioma por usuario o tenant.
• RestrictAuditor: reduce superficie de acceso para auditor y tenant_admin.
• AuditLogger: persistencia uniforme en audit_log_trs.
• TableSchemaService: metadata de tablas y etiquetas multilenguaje.
• TenantContext y LanguageService: contexto transversal de tenant e idioma.

Paginas de negocio

• Login, ResetPassword, ChangePassword.
• Pantalla1: activacion del plan.
• Pantalla2: respuesta operativa y acciones del usuario.
• Pantalla3: control central, delegaciones, riesgos y evidencias.
• Pantalla4: fin de emergencia y consolidado.
• Admin: tenant, usuarios, personal, documentos e importacion.
• Auditoria: exploracion y exportacion de eventos.

Guards y layout

• ProtectedRoute y PublicRoute separan acceso autenticado/no autenticado.
• AdminGate, DirectorGate, ResourceGate, AuditorGate aplican autorizacion por perfil.
• ControlGate valida acceso al panel via permiso puntual y activacion.
• DirectorFlowGate mantiene la secuencia funcional Pantalla1 - Pantalla4.
• MainLayout construye la navegacion superior, el menu contextual y la visibilidad por estado.

Perfiles soportados

• admin: administracion global del tenant.
• tenant_admin: mantenimiento operativo acotado.
• director: flujo completo de emergencia.
• recurso: confirmacion y ejecucion de acciones.
• recurso-visor: respuesta mas consulta del panel de control.
• auditor: trazabilidad y cumplimiento.

Controles de seguridad

• Autenticacion Bearer via Sanctum.
• 2FA configurable por tenant.
• Flujo de reseteo y activacion de credenciales.
• Permisos sobre panel por activacion y usuario.
• Restriccion de endpoints por middleware y guards de frontend.

Campos clave

• event_type, module, entity_type, entity_id.
• previous_value y new_value en JSON.
• plan_id, user_id, tenant_id.
• Timestamp alineado con timezone del tenant.

Eventos principales

• Plan: plan_activated, plan_status_changed, level_changed.
• Acciones: action_created, action_status_changed.
• Delegaciones: delegation_created, delegation_updated, delegation_auto, delegation_action.
• Documentos: document_uploaded, document_viewed, document_downloaded.

Dominio de emergencia

• activacion_del_plan_trs
• activacion_nivel_hist_trs
• asignacion_en_funciones_trs
• ejecucion_accion_trs
• notas_operativas_trs

Dominio de comunicaciones

• notificacion_envio_trs
• notificacion_confirmacion_trs
• control_panel_access_trs
• audit_log_trs

Dominio organizacional

• persona_mst
• persona_rol_cfg
• persona_rol_grupo_cfg
• rol_cat
• grupo_operativo_cfg

Dominio de configuracion y soporte

• riesgo_cat, nivel_alerta_cat, tipo_emergencia_cat
• accion_set_cfg, accion_set_detalle_cfg, riesgo_nivel_accion_set_cfg
• tenant_documents, tenant_document_links, tenant_document_riesgo_trs
• bulk_import_file_map_cfg

Autenticacion

POST /api/v1/auth/login
POST /api/v1/auth/activation-code/validate
POST /api/v1/auth/activation-code/activate
POST /api/v1/auth/password/forgot
POST /api/v1/auth/password/reset
POST /api/v1/auth/2fa/verify
POST /api/v1/auth/2fa/resend

Activacion y operacion

POST /api/v1/activacion
GET  /api/v1/activacion/preview
GET  /api/v1/activacion/{activationId}/control
GET  /api/v1/activacion/{activationId}/control/access
POST /api/v1/activacion/{activationId}/control/access
PUT  /api/v1/activacion/{activationId}/nivel
POST /api/v1/activacion/{activationId}/finalizar
GET  /api/v1/acciones/mias
POST /api/v1/acciones/confirmar

Documentos y auditoria

POST /api/v1/activacion/{activationId}/documentos
POST /api/v1/activacion/{activationId}/documentos/visto
GET  /api/v1/tenant/documents/folders
POST /api/v1/tenant/documents/folders
GET  /api/v1/tenant/documents/{documentId}/download
GET  /api/v1/audit
GET  /api/v1/audit/filters
GET  /api/v1/audit/responsibilities

Administracion e importacion

GET  /api/v1/tenant/settings
PUT  /api/v1/tenant/settings
GET  /api/v1/tenant/users
GET  /api/v1/tenant/personnel
GET  /api/v1/tenant/import/mappings
POST /api/v1/tenant/import/mappings/sync
POST /api/v1/tenant/import/mappings/upsert
POST /api/v1/tenant/import/run

Objetivo tecnico

• Eliminar cargas manuales tabla por tabla.
• Detectar el tipo real del archivo y no solo su extension.
• Permitir limpieza previa o adicion de registros.
• Registrar auditoria del proceso y resultado por archivo.

Componentes implementados

• bulk_import_file_map_cfg
• TenantBulkImportController
• Pestana Importacion masiva en Admin
• Script de hosting 2026-05-04_bulk_import_file_map_cfg_hosting.sql

Ambientes

• Local: Laravel + Vite con VITE_API_URL.
• Produccion: frontend compilado y backend con caches de framework.
• Hosting: scripts SQL versionados en emta-backend/SQL.

Artefactos de operacion

• Rutas web/API y comandos artisan agendados.
• Logs de Laravel y auditoria en BD.
• Repositorio documental por tenant y branding publico.

Pruebas minimas obligatorias

• Autenticacion por perfil y guards de ruta.
• Activacion con preview y generacion de acciones.
• Respuesta operativa y confirmaciones.
• Delegaciones manuales y automaticas.
• Cierre de emergencia y consolidado final.
• Visualizacion/descarga de documentos con auditoria.
• Importacion masiva con y sin limpieza previa.

Pruebas de regresion recomendadas

• i18n de mensajes y notificaciones.
• Acceso al panel sin caducidad durante emergencia activa.
• Visibilidad del boton Delegar cuando la titularidad fue delegada en transaccionales.
• Exportacion amigable de auditoria.
• Filtros de grupos operativos activos e EV dependientes.