## 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.