185 lines
7.1 KiB
Markdown
185 lines
7.1 KiB
Markdown
## 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:
|
|
|
|
```powershell
|
|
# En PowerShell (ejemplo con mysql CLI)
|
|
mysql -u root -p nombre_base_de_datos < "e:\PROYECTOS\ProyectoGestion\database\gestion_documentos.sql"
|
|
```
|
|
|
|
3. Copiar y editar el archivo de configuración (si existe) `config/config.php` y actualizar credenciales de DB, base_url, ajustes de correo.
|
|
|
|
4. Asegurar que `uploads/` es escribible por el servidor web y que `logs/` existe para auditoría.
|
|
|
|
5. (Opcional) Configurar una tarea programada para alertas:
|
|
|
|
```powershell
|
|
# Ejecutar script de alerta desde PHP en Windows Task Scheduler o desde Linux cron
|
|
php "e:\PROYECTOS\ProyectoGestion\cron\enviar_alertas.php"
|
|
```
|
|
|
|
6. 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.
|