maom/ProyectoGestionDocumentos
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
ProyectoGestionDocumentos/README.md

7.1 KiB
Raw Blame History

Proyecto: Sistema de Gestión de Oficios

Descripción

Aplicación web para la gestión de oficios y trámites internos: registro, derivación, seguimiento, historial, etiquetas, alertas y reportes.

Stack tecnológico

  • Backend: PHP (tipos estrictos, PDO) — recomendable PHP 7.4+ (8.x recomendado)
  • Base de datos: MySQL / MariaDB
  • Frontend: HTML, CSS y JavaScript (archivos en assets/)
  • Persistencia: subidas en uploads/ (archivos adjuntos)
  • Cron jobs: cron/enviar_alertas.php para alertas y notificaciones

Modelos de datos (resumen)

Nota: las definiciones abajo se infieren de los modelos models/Oficio.php y models/Usuario.php.

  • Oficio (tabla oficios / vista v_oficios_completo)

    • id (int)
    • numero_oficio (string) — formato: PREFIJO-AÑO-SECUENCIA (ej. REC-2026-0001)
    • tipo (string) — recibido/enviado
    • remitente (string)
    • destinatario (string)
    • asunto (string)
    • descripcion (text, nullable)
    • fecha_recepcion (date/datetime)
    • fecha_vencimiento (date/datetime, nullable)
    • prioridad (enum/string)
    • estado (enum/string) — ej. recibido, en_proceso, respondido, archivado
    • responsable_id (int, nullable) — FK a usuarios.id
    • derivado_a_id (int, nullable)
    • comentario_derivacion (text, nullable)
    • creado_por (int)
    • es_confidencial (boolean)
    • deleted_at (nullable timestamp) — eliminación lógica
    • created_at / updated_at (timestamps)

    Relaciones y tablas auxiliares:

    • oficio_etiquetas (oficio_id, etiqueta_id)
    • etiquetas (id, nombre)
    • comentarios (oficio_id, usuario_id, comentario, es_privado, created_at)
    • historial_cambios (tabla, registro_id, accion, usuario_id, ip_address, detalle, created_at)

  • Usuario (tabla usuarios)

    • id (int)
    • rol_id (int) — FK a roles.id
    • nombre (string)
    • apellido (string)
    • email (string)
    • username (string)
    • password_hash (string)
    • cargo (string, nullable)
    • area (string, nullable)
    • supervisor_id (int, nullable)
    • activo (boolean)
    • deleted_at (nullable timestamp)
    • ultimo_login (datetime, nullable)
    • token_recuperacion, token_expira (para recuperación de contraseña)

    Tablas relacionadas:

    • roles (id, nombre, permisos)

Ejemplo de contrato de datos (JSON)

  • Oficio (respuesta API / formato de formulario):

    { "numero_oficio": "REC-2026-0001", "tipo": "recibido", "remitente": "Oficina X", "destinatario": "Dirección Y", "asunto": "Solicitud de información", "descripcion": "Detalle...", "fecha_recepcion": "2026-06-01", "fecha_vencimiento": "2026-06-10", "prioridad": "alta", "estado": "recibido", "responsable_id": 3, "etiquetas": [1,2], "es_confidencial": 0 }

  • Usuario (creación mínima):

    { "rol_id": 2, "nombre": "Ana", "apellido": "Pérez", "email": "ana@example.com", "username": "aperez", "password": "(texto plano; se guardará hash)" }

Requisitos previos

  • Servidor con PHP 7.4+ instalado (extensión PDO y pdo_mysql habilitadas).
  • MySQL o MariaDB.
  • Servidor web: Apache/Nginx o entorno WAMP/XAMPP/Laragon en Windows.
  • Carpeta uploads/ con permisos de escritura por el usuario del servidor web.
  • Habilitar cron (Linux) o tarea programada (Windows Task Scheduler) para las alertas.

Uso del sistema (flujo general)

  1. Acceder a la URL del sistema y autenticarse (login.php).
  2. Desde el panel/dashboard ver KPIs y oficios próximos a vencer.
  3. Crear un nuevo oficio (oficios/crear.php) o generar número automático con la función del modelo.
  4. Derivar oficios a responsables, añadir comentarios y etiquetas.
  5. Revisar historial y auditoría por oficio.
  6. Recuperar contraseña mediante recuperar_password.php.

Módulos del sistema

  • Autenticación y autorización (controllers/AuthController.php, login.php, logout.php)
  • Gestión de oficios (controllers/OficioController.php, vistas en views/oficios/)
  • Usuarios y roles (controllers/UsuarioController.php, models/Usuario.php, vistas en views/usuarios/)
  • Reportes (controllers/ReporteController.php, views/reportes/)
  • Alertas/cron (cron/enviar_alertas.php)
  • Exportes y descargas (exports/)
  • Borrado lógico / papelera (views/oficios/papelera.php)
  • Plantilla/layout compartido (views/layout/)

Seguridad

  • Contraseñas: se almacenan con password_hash (Bcrypt) según models/Usuario.php.
  • Eliminación lógica: uso de deleted_at para evitar borrados accidentales.
  • Historial de cambios: auditoría en historial_cambios para operaciones críticas.
  • Recomendaciones adicionales:
    • Implementar CSRF tokens en formularios.
    • Escapar/validar salida para evitar XSS (especialmente descripcion y comentarios).
    • Forzar HTTPS en producción y HSTS.
    • Limitar tamaño/tipo de archivos subidos y almacenar fuera del webroot o en almacenamiento S3 con enlaces firmados.
    • Hardenear sesiones (cookie secure, SameSite, regenerar id de sesión en login).
    • Logging y alertas sobre intentos fallidos de login.

Instalación y configuración

  1. Clonar o copiar el repositorio en el servidor web.
  2. Crear una base de datos y ejecutar el SQL primario:
# En PowerShell (ejemplo con mysql CLI)
mysql -u root -p nombre_base_de_datos < "e:\PROYECTOS\ProyectoGestion\database\gestion_documentos.sql"

  1. Copiar y editar el archivo de configuración (si existe) config/config.php y actualizar credenciales de DB, base_url, ajustes de correo.

  2. Asegurar que uploads/ es escribible por el servidor web y que logs/ existe para auditoría.

  3. (Opcional) Configurar una tarea programada para alertas:

# Ejecutar script de alerta desde PHP en Windows Task Scheduler o desde Linux cron
php "e:\PROYECTOS\ProyectoGestion\cron\enviar_alertas.php"
  1. Acceder a la aplicación y crear el primer usuario administrador (o importar desde SQL si existe dump).

Posibles mejoras

  • Añadir un sistema de migraciones (Phinx, Doctrine Migrations o laravel-migrations) para versiones de esquema.
  • Preparar Dockerfile y docker-compose para entornos reproductibles.
  • Añadir tests automatizados (PHPUnit) y linters (PHPStan/Psalm, PHPCS).
  • Implementar API RESTful con autenticación basada en tokens (JWT) para integraciones.
  • Mejorar seguridad: CSRF, CSP, pruebas de penetración, 2FA.
  • Soporte para almacenamiento de archivos en la nube (S3) y vistas previas seguras.
  • Sistema de auditoría más detallado y panel de administración de roles y permisos (RBAC fino).

Estado y cobertura de requisitos

  • título: Hecho
  • descripción: Hecho
  • stack tecnológico: Hecho
  • modelos de datos: Hecho (resumen basado en models/)
  • requisitos previos: Hecho
  • uso del sistema: Hecho
  • módulos del sistema: Hecho
  • seguridad: Hecho (incluye recomendaciones)
  • instalación y configuración: Hecho (pasos e import SQL)
  • posibles mejoras: Hecho

Contacto y notas

Si necesitas que adapte el README a un formato distinto (más corto, versión en inglés, o agregar diagramas ER y ejemplos de requests), dímelo y lo preparo.