ProyectoGestionDocumentos

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)

Acceder a la URL del sistema y autenticarse (login.php).
Desde el panel/dashboard ver KPIs y oficios próximos a vencer.
Crear un nuevo oficio (oficios/crear.php) o generar número automático con la función del modelo.
Derivar oficios a responsables, añadir comentarios y etiquetas.
Revisar historial y auditoría por oficio.
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

Clonar o copiar el repositorio en el servidor web.
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"

Copiar y editar el archivo de configuración (si existe) config/config.php y actualizar credenciales de DB, base_url, ajustes de correo.
Asegurar que uploads/ es escribible por el servidor web y que logs/ existe para auditoría.
(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"

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.