# Homium Audit Platform (audit-homium)

Plataforma web construida en **PHP 8.1 nativo** para la gestión y auditoría automatizada de sitios web mediante la herramienta `homium-audit`. Incorpora el diseño oficial del **Homium Design System** y está completamente optimizada para ejecutarse en **Ubuntu Server (GUI / Terminal)** con base de datos **MySQL** y procesamiento en segundo plano mediante **CronJob**.

---

## 🚀 Características del Sistema

* **Autenticación y Seguridad:** Sesiones blindadas, protección contra CSRF, contraseñas cifradas con algoritmo `BCRYPT` y logout seguro.
* **Vista 1 — Guardar Enlace (`?route=links/create`):**
  * Entrada individual de URLs con validación de sintaxis y protocolo (`http://` o `https://`).
  * Asignación por defecto del estado inicial **`sin_procesar`**.
  * Alertas visuales y confirmación inmediata.
* **Vista 2 — Dashboard General (`?route=dashboard`):**
  * Monitoreo en tiempo real de los estados: **`sin_procesar`**, **`pendiente`**, **`procesado`** y **`error`**.
  * Tarjetas métricas con contadores interactivos y auto-actualización en vivo cada 15 segundos sin recargar la página.
  * Filtros de estado por chips, buscador por URL en vivo y paginación.
  * Acciones de mantenimiento: re-encolar enlace a `sin_procesar` o eliminarlo de la base de datos.
* **Worker CLI para CronJob (`cron/worker.php`):**
  * Procesa lotes de **5 URLs** por ciclo.
  * Control de concurrencia con bloqueo exclusivo de archivo (*mutex lock* con `flock`) para evitar solapamientos.
  * Transición de estados atómica: `sin_procesar` $\rightarrow$ `pendiente` (mientras corre el proceso) $\rightarrow$ `procesado` o `error`.
  * Ejecución por terminal: `homium-audit '<URL>' --upload`.
* **Diseño Homium:** Estética *Dark Editorial*, paleta púrpura (`#290640`), acentos cian (`#00ffff`) y verde (`#5aeaa2`), y tipografía Rubik.

---

## 📋 Requisitos Previos en Ubuntu Server

* **Sistema Operativo:** Ubuntu Server 20.04 LTS o 22.04 LTS (con o sin entorno gráfico).
* **PHP:** Versión 8.1 o superior con extensiones CLI, MySQL, MBString, cURL.
* **Base de Datos:** MySQL Server 8.0+ o MariaDB 10.4+.
* **Servidor Web:** Apache 2 o Nginx.
* **Herramienta de Auditoría:** `homium-audit` instalada y accesible en el `PATH` del sistema.

---

## 🛠️ Guía Paso a Paso de Instalación en Ubuntu Server

### Paso 1: Instalar Paquetes del Sistema

Abre tu terminal en Ubuntu Server y ejecuta:

```bash
# Actualizar repositorios
sudo apt update && sudo apt upgrade -y

# Si tu Ubuntu no incluye PHP 8.1 por defecto, añade el repositorio oficial:
sudo apt install -y software-properties-common
sudo add-apt-repository ppa:ondrej/php -y
sudo apt update

# Instalar PHP 8.1, Apache y extensiones requeridas
sudo apt install -y apache2 php8.1 php8.1-cli php8.1-mysql php8.1-mbstring php8.1-curl php8.1-xml libapache2-mod-php8.1

# Instalar MySQL Server (si no lo tienes instalado aún)
sudo apt install -y mysql-server
```

Verifica la versión instalada:
```bash
php -v
# Debe mostrar PHP 8.1.x
```

---

### Paso 2: Configurar la Base de Datos MySQL

1. Inicia sesión en la consola de MySQL como administrador:
   ```bash
   sudo mysql -u root
   ```

2. Crea la base de datos, un usuario dedicado y asigna permisos:
   ```sql
   -- Crear base de datos con soporte UTF-8 completo
   CREATE DATABASE IF NOT EXISTS audit_homium 
   CHARACTER SET utf8mb4 
   COLLATE utf8mb4_unicode_ci;

   -- Crear usuario (sustituye 'tu_clave_segura' por la contraseña que desees)
   CREATE USER IF NOT EXISTS 'homium_user'@'localhost' IDENTIFIED BY 'tu_clave_segura';

   -- Otorgar todos los privilegios sobre la base de datos
   GRANT ALL PRIVILEGES ON audit_homium.* TO 'homium_user'@'localhost';
   FLUSH PRIVILEGES;

   EXIT;
   ```

3. Importa el esquema de tablas y los datos iniciales desde la raíz del proyecto:
   ```bash
   # Navega a donde tienes el proyecto (ejemplo: /var/www/audit-homium)
   cd /var/www/audit-homium

   # Importar tablas e índices
   mysql -u homium_user -p audit_homium < database/schema.sql

   # Importar usuario inicial y datos de prueba
   mysql -u homium_user -p audit_homium < database/seed.sql
   ```

---

### Paso 3: Ubicación y Permisos del Proyecto

Recomendamos alojar el proyecto en `/var/www/audit-homium`:

```bash
# Si aún no lo has movido al directorio web:
sudo cp -r /ruta/donde/tengas/audit-homium /var/www/audit-homium

# Asignar la propiedad al usuario del servidor web (www-data)
sudo chown -R www-data:www-data /var/www/audit-homium

# Permisos estándar de carpetas y archivos
sudo find /var/www/audit-homium -type d -exec chmod 755 {} \;
sudo find /var/www/audit-homium -type f -exec chmod 644 {} \;
```

---

### Paso 4: Configurar Variables de Entorno (`.env`)

Crea el archivo `.env` a partir de la plantilla:

```bash
cd /var/www/audit-homium
cp .env.example .env
nano .env
```

Configura tus datos de conexión a MySQL y el comando del worker:

```ini
APP_NAME="Homium Audit"
APP_ENV="production"
APP_DEBUG=false
APP_URL="http://localhost/audit-homium/public"

# Conexión MySQL configurada en el Paso 2
DB_HOST="127.0.0.1"
DB_PORT="3306"
DB_NAME="audit_homium"
DB_USER="homium_user"
DB_PASS="tu_clave_segura"
DB_CHARSET="utf8mb4"

# Comando de auditoría que ejecuta el terminal
# {url} será reemplazado de forma segura y sanitizada con escapeshellarg()
HOMIUM_AUDIT_CMD="homium-audit {url} --upload"

# Cantidad de URLs a procesar por cada ejecución del CronJob
WORKER_BATCH_SIZE=5
```

Guarda los cambios con `Ctrl + O`, presiona `Enter` y sal con `Ctrl + X`.

---

### Paso 5: Configurar el Servidor Web

#### Opción A: Servidor Web Apache (Recomendado)

1. Crea el archivo de configuración del VirtualHost:
   ```bash
   sudo nano /etc/apache2/sites-available/audit-homium.conf
   ```

2. Añade el siguiente bloque (reemplaza `audit.homium.local` o tu IP/dominio):
   ```apache
   <VirtualHost *:80>
       ServerName audit.homium.local
       ServerAdmin webmaster@localhost
       DocumentRoot /var/www/audit-homium/public

       <Directory /var/www/audit-homium/public>
           Options -Indexes +FollowSymLinks
           AllowOverride All
           Require all granted
       </Directory>

       ErrorLog ${APACHE_LOG_DIR}/audit-homium-error.log
       CustomLog ${APACHE_LOG_DIR}/audit-homium-access.log combined
   </VirtualHost>
   ```

3. Habilita el sitio, activa `mod_rewrite` y reinicia Apache:
   ```bash
   sudo a2ensite audit-homium.conf
   sudo a2enmod rewrite
   sudo systemctl restart apache2
   ```

---

#### Opción B: Servidor Web Nginx + PHP-FPM

Si prefieres Nginx, crea `/etc/nginx/sites-available/audit-homium`:
```nginx
server {
    listen 80;
    server_name audit.homium.local;
    root /var/www/audit-homium/public;
    index index.php index.html;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location ~ \.php$ {
        include snippets/fastcgi-php.conf;
        fastcgi_pass unix:/var/run/php/php8.1-fpm.sock;
        fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
        include fastcgi_params;
    }

    location ~ /\.ht {
        deny all;
    }
}
```
Habilítalo y recarga Nginx:
```bash
sudo ln -s /etc/nginx/sites-available/audit-homium /etc/nginx/sites-enabled/
sudo systemctl restart nginx
```

---

## ⏰ Configuración del CronJob en Ubuntu

El script `cron/worker.php` es el encargado de consultar la base de datos, tomar las URLs en `sin_procesar`, pasarlas a `pendiente`, ejecutar el comando `homium-audit '<url>' --upload` y actualizarlas a `procesado` (o `error`).

### Estructura de un CronJob en Linux

Crontab utiliza una sintaxis de 5 posiciones de tiempo:

```text
┌───────────── Minuto (0 - 59)
│ ┌─────────── Hora (0 - 23)
│ │ ┌───────── Día del mes (1 - 31)
│ │ │ ┌─────── Mes (1 - 12)
│ │ │ │ ┌───── Día de la semana (0 - 7) (0 y 7 = domingo)
│ │ │ │ │
* * * * * <comando a ejecutar>
```

---

### ¿Cómo configurarlo para que se ejecute cada 10 minutos?

Para que se ejecute **cada 10 minutos** se utiliza la expresión `*/10 * * * *`:

1. Abre el editor de Crontab para el usuario del servidor web (`www-data`) o tu usuario con permisos:
   ```bash
   sudo crontab -u www-data -e
   ```
   *(Si es la primera vez que lo abres, elige la opción `1` para el editor `nano`).*

2. Pega la siguiente línea al final del archivo:
   ```cron
   # Ejecutar worker de auditoría cada 10 minutos registrando salida en el log
   */10 * * * * /usr/bin/php /var/www/audit-homium/cron/worker.php >> /var/log/audit-worker.log 2>&1
   ```

3. Crea el archivo de log y otorga permisos de escritura para que el cron pueda escribir en él:
   ```bash
   sudo touch /var/log/audit-worker.log
   sudo chown www-data:www-data /var/log/audit-worker.log
   sudo chmod 664 /var/log/audit-worker.log
   ```

4. Guarda el archivo con `Ctrl + O`, presiona `Enter` y sal con `Ctrl + X`.

---

### ⏱️ Tabla de Ejemplos de Frecuencias Comunes

| Frecuencia Deseada | Expresión Cron | Ejemplo de Línea Completa |
| :--- | :--- | :--- |
| **Cada 10 minutos** *(tu caso)* | `*/10 * * * *` | `*/10 * * * * /usr/bin/php /var/www/audit-homium/cron/worker.php >> /var/log/audit-worker.log 2>&1` |
| **Cada 5 minutos** | `*/5 * * * *` | `*/5 * * * * /usr/bin/php /var/www/audit-homium/cron/worker.php >> /var/log/audit-worker.log 2>&1` |
| **Cada 15 minutos** | `*/15 * * * *` | `*/15 * * * * /usr/bin/php /var/www/audit-homium/cron/worker.php >> /var/log/audit-worker.log 2>&1` |
| **Cada 30 minutos** | `*/30 * * * *` | `*/30 * * * * /usr/bin/php /var/www/audit-homium/cron/worker.php >> /var/log/audit-worker.log 2>&1` |
| **Cada 1 minuto** | `* * * * *` | `* * * * * /usr/bin/php /var/www/audit-homium/cron/worker.php >> /var/log/audit-worker.log 2>&1` |
| **Cada 1 hora (en punto)** | `0 * * * *` | `0 * * * * /usr/bin/php /var/www/audit-homium/cron/worker.php >> /var/log/audit-worker.log 2>&1` |
| **Cada 2 horas** | `0 */2 * * *` | `0 */2 * * * /usr/bin/php /var/www/audit-homium/cron/worker.php >> /var/log/audit-worker.log 2>&1` |
| **De Lunes a Viernes cada 10 min** | `*/10 * * * 1-5`| `*/10 * * * 1-5 /usr/bin/php /var/www/audit-homium/cron/worker.php >> /var/log/audit-worker.log 2>&1` |

---

### 🔍 Pruebas y Monitoreo del CronJob

#### 1. Probar el Worker manualmente en la terminal
Antes de esperar que el cron se dispare, puedes probarlo directamente:
```bash
sudo -u www-data php /var/www/audit-homium/cron/worker.php
```

Verás una salida formateada como esta:
```text
===============================================================
[2026-09-07 15:00:01] Iniciando ciclo de worker Homium Audit
Lote máximo: 5 | Plantilla: homium-audit {url} --upload
===============================================================
[2026-09-07 15:00:01] Se reclamaron 3 enlace(s) para procesar.
---------------------------------------------------------------
[2026-09-07 15:00:01] [ID: 1] Iniciando auditoría para: https://homium.lat
[2026-09-07 15:00:01] [ID: 1] Ejecutando: homium-audit 'https://homium.lat' --upload
[2026-09-07 15:00:05] [ID: 1] OK -> Finalizado en 4.2s. Estado actualizado a 'procesado'.
===============================================================
[2026-09-07 15:00:05] Resumen del lote: 3 procesados exitosamente, 0 con error.
===============================================================
```

#### 2. Monitorear los logs en tiempo real
Para observar en vivo las ejecuciones automáticas del cron:
```bash
tail -f /var/log/audit-worker.log
```

#### 3. Verificar que el servicio de cron esté activo
```bash
sudo systemctl status cron
```
Si estuviera detenido, inícialo con:
```bash
sudo systemctl enable --now cron
```

---

## 🔐 Credenciales de Acceso Iniciales

| Campo | Valor por Defecto |
| :--- | :--- |
| **Ruta Web** | `http://tu-servidor/?route=login` (o `http://localhost/audit-homium/public/?route=login`) |
| **Usuario / Correo** | `admin@homium.lat` |
| **Contraseña** | `admin1234` |

---

## 🧭 Flujo de Trabajo en las Vistas

1. **Acceder:** Ingresa con las credenciales al sistema.
2. **Vista 1 — Guardar Enlace (`?route=links/create`):**
   * Pega la URL del sitio web a auditar.
   * El sistema la valida y la guarda con el estado `sin_procesar`.
3. **Vista 2 — Dashboard General (`?route=dashboard`):**
   * Observa la URL en la tarjeta **Sin Procesar**.
   * Cuando el cronjob se ejecuta (por ejemplo cada 10 minutos), verás que pasa a **En Proceso (`pendiente`)**.
   * Al completarse la ejecución del comando `homium-audit`, cambiará automáticamente a **Procesados (`procesado`)**.
   * Si alguna URL falla, se marca como `error` y se detalla el código de retorno. Dispones de un botón para volver a encolarla a `sin_procesar` con un solo clic.

---

## 📁 Estructura del Directorio

```text
audit-homium/
├── config/
│   └── config.php          # Carga variables de .env y configuraciones
├── cron/
│   └── worker.php          # Script CLI ejecutado por el CronJob cada 10 min
├── database/
│   ├── schema.sql          # Creación de tablas MySQL (usuarios y enlaces)
│   └── seed.sql            # Usuario administrador y enlaces de prueba
├── public/                 # DocumentRoot público
│   ├── assets/
│   │   ├── css/            # Estilos Homium Theme y componentes App
│   │   ├── fonts/          # Tipografías oficiales Rubik
│   │   ├── img/            # Logotipos SVG oficiales Homium
│   │   └── js/             # Script de refresco automático de métricas
│   └── index.php           # Punto de entrada Front-Controller
├── src/
│   ├── Controllers/        # AuthController, LinkController, DashboardController
│   ├── Models/             # User.php, Link.php (lógica de estados y cola)
│   ├── Utils/              # Auth, Database (PDO), Router
│   └── bootstrap.php       # Autoloader PSR-4 y arranque de la aplicación
├── views/
│   ├── auth/               # Vista de login
│   ├── dashboard/          # Vista 2: Dashboard con estados y métricas
│   ├── layouts/            # Encabezado con navbar Homium y pie de página
│   └── links/              # Vista 1: Formulario para guardar enlace
├── .env.example            # Plantilla de configuración
├── DOCUMENTACION.md        # Documentación de arquitectura técnica
└── README.md               # Este manual completo
```