Manual del Programador

Se describen controladores, servicios y modelos del sistema

Modelos

Modelos

Modelos de Datos (Eloquent)

 

Este documento condensa los conocimientos y entidades de la capa de datos (app/Models) del sistema GDU, describiendo la responsabilidad primordial de cada Modelo y sus relaciones principales.

🏢 Arquitectura Institucional y Acceso

  1. Dependencia
    • Entidad que representa a las áreas operativas, oficinas o secretarías de la Institución.
    • Se relaciona fuertemente con los Expedientes actuando como creador y como poseedor (holder). Puede agrupar a múltiples usuarios y participar de los "pases paralelos" mediante tablas pivote.
  2. User
    • Representa al usuario físico/agente que opera el sistema. Utiliza características de Spatie/Permissions (Roles), autenticación de Jetstream, y se encuentra asignado en "caliente" a una dependencia (dependenciaActiva) en la que opera temporalmente.

📁 Núcleo Documental (Expedientes)

  1. Expediente
    • Es el corazón y objeto transaccional principal del sistema. Funciona como un agrupador legal de los sucesos.
    • Tiene dos relaciones temporarles críticas: dependencia_id (la originaria que lo creó) y holder_id (El tenedor actual en el flujo lógico, quien lo tiene en "posesión").
  2. TipoExpediente
    • Modelo de configuración y lectura. Define de forma maestra la taxonomía (Ej: Acción de Pago, Licitación, Expediente Estándar), sus colores de interfaz, e íconos.
  3. ExpedienteManifest
    • Entidad puramente técnica. Modela la cadena de bloques (Blockchain interno) del expediente. Guarda instantáneas versionadas (version, manifest_hash, prev_manifest_hash, state_hash) garantizando integridad legal de manera inmutable tras cada movimiento.
  4. DependenciaExpediente
    • Modelo que actúa netamente como Clase Pivote (Pivot) con atributos adicionales (activo, expira) para sostener de forma estructurada el compartir simultáneos paralelo los expedientes.

📑 Solicitudes 

  1. Solicitud
    • Predecesora del Expediente. Es el formulario interactivo provisto en la mesa de entrada o self-service. Contiene los datos crudos provistos por el "Causante". Una vez aprobada se convierte en Expediente Oficial mediante la rutina de caratular.

📑Comunicaciones

  1. Ccoo
    • Modela una "Comunicación Oficial". Es una entidad de envío de oficios, resoluciones o mensajes entre una dependencia_origen y una dependencia_destino.

📎 Archivos y Adjuntos (Ecosistema Múltiple)

El sistema segrega fuertemente los subidos acorde al ámbito donde se agregaron:

  1. Archivoe
    • Archivos y fojas PDF vinculadas directamente a un Expediente Oficializado. Está versionado (hash), auditado, y permite adjuntar firmas.
  2. Archivot
    • Archivos transitorios vinculados inicialmente a una Solicitud que aún no es Expediente.
  3. ArchivoCcoo
    • Disposición de almacenamiento enfocada a las Comunicaciones Oficiales (Ccoo).
  4. Firma
    • Entidad complementaria al Archivoe. Captura los metadatos específicos leídos en un PDF (Nombre del certificado, fecha de validación legal del PKI, validez criptográfica) en un registro verificable.
  5. (Nota: File es una clase obsoleta o fallida marcada en el código para deprendimiento futuro)

📡 Herramientas de Sistema

  1. Log
    • Modela la traza silenciosa de auditoría interna. Almacena la Acción, qué Usuario/Dependencia interactuó, sobre qué entidad (Solicitud/Expediente) y anexa factores forenses básicos de HTTP (IP, User Agent).
  2. Email
    • Réplica de correos institucionales inyectados. Guarda destinatario, remitente y el cuerpo limpio que luego se utiliza interactivamente con el controlador de Inteligencia Artificial de las bandejas integradas.

Controladores

Controladores

Controladores (app/Http/Controllers)


  1. ArchivoController: Verifica permisos locales y devuelve archivos privados incrustados de forma segura dentro del sistema (view()) o fuerza su descarga directa (download()).
  2. CcooController: Administra el ciclo de vida de creación de las "Comunicaciones Oficiales" (CCOO), y se apoya en el asistente de IA para pre-rellenar los contenidos institucionales.
  3. EmailController: Lista la bandeja de entrada de correos sincronizados. Al visualizar un email (show()) también gatilla el servicio de OpenAI para tener un borrador de respuesta listo para usar.
  4. ExpedienteController: Es el corazón del ruteo. Gestiona el registro y visualización de expedientes. Interactúa con el blockchain de archivos mostrándo si el documento es válido y permite búsquedas múltiples por año y clave.
  5. LogController: Actúa como auditor. Recibe y registra todos los eventos sensibles del usuario guardando su IP, User-Agent corporativo y la dependencia activa generando un hash único por la actividad sobre Expedientes o Solicitudes.
  6. NotificationController: Permite al usuario ver, listar y marcar como leídas las notificaciones propias (markAsRead(), markAllAsRead()).
  7. SolicitudController: El origen del trámite web (CRUD de solicitudes). Una vez que una solicitud pasa todos los requerimientos (aprobar()), este controlador usa la función caratular() para transformarla en un "Expediente formal" dentro del sistema.

Servicios

Servicios

🛠️ Servicios (app/Services)


  1. ExpedienteService: Gestiona el flujo del movimiento de los Expedientes entre las distintas Dependencias. Resuelve lógicas para pases en paralelo y comprueba que dependencias tienen permisos para adjuntar archivos a un expediente específico.


     Funciones Activas  (Core del Servicio)

      • obtenerDependenciasEnPaseParaleloActivo(int $expedienteId) Funcionalidad: Es una consulta de bajo nivel (DB::table) a la tabla pivote dependencia_expediente que relaciona un expediente con varias oficinas simultáneamente. Qué hace: Retorna en forma de un simple array los IDs numéricos de todas las dependencias con las cuales un expediente comparte el estado de "pase paralelo" en estado "activo".

      • sePuedeTransferir(int $expedienteId, int $dependenciaActualId) Funcionalidad: Evalúa lógicamente si el usuario puede "Transferir/Enviar" un expediente. Regla de negocio actual: Busca en la BD si el expediente pertenece a esa dependencia actual (holder_id === $dependenciaActualId) y además comprueba que NO tenga pases paralelos distribuidos (!$relacionesActivas). Por lo tanto, un expediente en medio de un "pase en paralelo" activo hacia varias oficinas no se puede transferir de raíz al próximo paso hasta que se cierre el paralelo.

      • dependenciaPuedeAgregarArchivos(int $expedienteId, int $dependenciaId) Funcionalidad: Decide si una dependencia en concreto tiene permitido el alta de nuevos documentos. Regla de negocio actual: Si la dependencia está involucrada dentro del listado de "Pases en paralelo activo", entonces le permite añadir archivos (return true;). Si no está en paralelo, evalúa si es el simple poseedor primario del expediente (holder_id). Dato interesante del código: Antes había un bloque de validación más rígido que impedía subir archivos, pero fue comentado asumiendo el nuevo permiso de que "AHORA PERMITIMOS QUE SE AGREGUE DOCUMENTACION AUNQUE ESTE EN PARALELO".

      • yoTengoExpediente(int $expedienteId, int $dependenciaId) Funcionalidad: Simple comprobación binaria para uso rápido en vistas (if/else). Qué hace: Solo evalúa si la dependencia X pedida coincide con el poseedor primario (holder_id) cargado en el Objeto Expediente.

      • yoTengoExpedienteEnParalelo(int $expedienteId, int $dependenciaId) Funcionalidad: Complementa la función de arriba. Qué hace: Llama al método obtenerDependenciasEnPaseParaleloActivo() y revisa con un simple in_array si la dependencia X está contenida en ese listado de oficinas involucradas en un pase conjunto.


  2. FirmaDigitalService: Responsable de integrar funciones a nivel de sistema operativo para validar firmas digitales en los PDF (usando comandos como pdfsig y bases NSS) y aplica una "firma por sistema" a los documentos.
  3. ManifiestoExpedienteService: Maneja la integridad de la documentación aplicando un modelo estilo "blockchain". Sella expedientes (sellar()) adjuntando manifiestos con hash canonicos estado por estado para garantizar que los documentos no hayan sido adulterados leyendo el historial (verificarCadena()).
  4. OpenAIService: Centraliza la conexión y peticiones a la API de ChatGPT para sugerir o generar de forma automática respuestas (generateReply()) a correos y comunicaciones simulando asistentes virtuales.