# Documentación del Proyecto: Plataforma de Auditoría Homium (audit-homium)

> **Versión:** 1.0.0-draft  
> **Estado:** Fase de especificación y arquitectura aprobada  
> **Plataforma destino:** Ubuntu Server (GUI) · PHP 8.1 · MySQL · CronJob  
> **Línea de diseño:** Homium Design System (Dark Editorial)

---

## 1. Visión General del Proyecto

El sistema **audit-homium** es una solución integral compuesta por:
1. **Aplicación Web (PHP 8.1 MVC ligero):** Permite el acceso autenticado de usuarios, el registro de URLs para auditoría y la visualización de un dashboard centralizado de estados en tiempo real.
2. **Motor Worker CLI (CronJob):** Proceso desatendido que extrae periódicamente lotes de enlaces pendientes en la base de datos MySQL y dispara en terminal la herramienta nativa `homium-audit [URL] --upload`, actualizando los estados correspondientes.

---

## 2. Decisiones de Negocio y Flujo Aprobadas

Basado en la definición de requerimientos:

| Parámetro | Especificación Aprobada |
| :--- | :--- |
| **Comando Terminal** | `homium-audit '<URL>' --upload` ejecutado desde el entorno Ubuntu Server. |
| **Almacenamiento de Salida** | No se requiere guardar el output de terminal en BD; solo la transición de estados y marcas temporales. |
| **Ciclo de Estados** | `sin_procesar` $\rightarrow$ `pendiente` (mientras el worker ejecuta el comando) $\rightarrow$ `procesado` (al finalizar con éxito) o `error` (si falla la ejecución). |
| **Ingreso de Enlaces** | Uno a uno mediante formulario web validado con sanitización estricta. |
| **Alcance de Datos** | Enlaces compartidos globalmente: todos los usuarios autenticados colaboran en la misma cola. |
| **Tamaño de Lote (Worker)** | 5 URLs por ciclo de ejecución del CronJob. |
| **Concurrencia** | Bloqueo por archivo (*file locking* con `flock`) en el worker para prevenir ejecuciones simultáneas solapadas. |

---

## 3. Arquitectura del Sistema

### 3.1 Diagrama de Componentes

```
[ Usuario Web ] 
       │
       ▼
┌──────────────────────────────────────────────────────────┐
│  Interfaz Web Homium (PHP 8.1 + CSS Design System)      │
│  ├── Login / Autenticación de Sesión                    │
│  ├── Vista 1: Registro de Enlace (Estado: sin_procesar) │
│  └── Vista 2: Dashboard de Monitoreo y Métricas         │
└────────────────────────────┬─────────────────────────────┘
                             │
                             ▼
┌──────────────────────────────────────────────────────────┐
│                 Base de Datos MySQL                      │
│  ├── usuarios (id, email, password_hash, rol, ...)       │
│  └── enlaces (id, url, estado, creado_en, procesado_en)  │
└────────────────────────────▲─────────────────────────────┘
                             │
 ┌───────────────────────────┴─────────────────────────────┐
 │       Worker CLI (PHP 8.1 - cron/worker.php)            │
 │  ├── Ejecutado cada N minutos vía Ubuntu Crontab        │
 │  ├── Bloqueo Mutex anti-solapamiento (flock)            │
 │  ├── Selecciona 5 enlaces 'sin_procesar'                │
 │  ├── Transición atómica a 'pendiente'                   │
 │  ├── Ejecuta: homium-audit '<url>' --upload             │
 │  └── Transición final a 'procesado' o 'error'           │
 └─────────────────────────────────────────────────────────┘
```

---

## 4. Modelo de Datos (MySQL)

### Tabla `usuarios`
Gestiona el acceso seguro a la plataforma.

```sql
CREATE TABLE IF NOT EXISTS usuarios (
    id INT AUTO_INCREMENT PRIMARY KEY,
    nombre VARCHAR(100) NOT NULL,
    email VARCHAR(150) NOT NULL UNIQUE,
    password_hash VARCHAR(255) NOT NULL,
    creado_en TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    actualizado_en TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_general_ci;
```

### Tabla `auditorias`
Almacena las URLs y su ciclo de auditoría.

```sql
CREATE TABLE IF NOT EXISTS auditorias (
    id INT AUTO_INCREMENT PRIMARY KEY,
    url TEXT NOT NULL,
    estado ENUM('sin_procesar', 'pendiente', 'procesado', 'error') NOT NULL DEFAULT 'sin_procesar',
    intentos INT DEFAULT 0,
    creado_en TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    actualizado_en TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    procesado_en DATETIME NULL,
    INDEX idx_estado (estado),
    INDEX idx_creado (creado_en)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_general_ci;
```

---

## 5. Diseño e Identidad Visual (Homium Design System)

La interfaz se construye bajo las pautas oficiales del **Homium Design System**:

* **Estética:** *Dark editorial*, sobria, tecnológica y de alto impacto visual.
* **Paleta de Colores (Regla 60 / 20 / 20):**
  * **60% Superficie principal:** Púrpura profundo Homium (`#290640`), fondo elevado para tarjetas (`#380a55`), fondo hundido (`#1d042d`).
  * **20% Acento principal y botones:** Cyan brillante (`#00ffff`), foco y enlaces (`#5cffff`).
  * **20% Acentos secundarios y éxito:** Verde Homium (`#5aeaa2`).
* **Tipografía:** Rubik (pesos 300 Light para titulares editoriales con palabras destacadas en cursiva cian, 400 para texto general y 600/700 para datos).
* **Vistas Implementadas:**
  1. **Vista de Acceso (Login):** Pantalla limpia con logotipo oficial Homium, protección contra fuerza bruta y diseño centrado en tarjeta de vidrio/elevada.
  2. **Vista 1 (Registrar Enlace):** Formulario intuitivo con validación de URL, botón de envío con microanimación y confirmación inmediata.
  3. **Vista 2 (Dashboard General):** 
     * Tarjetas de métricas: Total Enlaces, Sin Procesar, En Proceso (Pendiente), Procesados y Errores.
     * Tabla interactiva con badges semánticos, filtros por estado, ordenación y buscador.

---

## 6. Estructura de Archivos del Proyecto

```text
audit-homium/
├── config/
│   ├── database.php        # Conexión PDO con variables de entorno
│   └── app.php             # Configuración general y comando homium-audit
├── cron/
│   └── worker.php          # Script CLI ejecutado por crontab (lotes de 5)
├── database/
│   ├── schema.sql          # Creación de tablas e índices
│   └── seed.sql            # Usuario inicial de prueba
├── public/
│   ├── assets/
│   │   ├── css/
│   │   │   └── homium-theme.css # Tokens, estilos y layout de Homium
│   │   ├── fonts/          # Tipografía Rubik
│   │   ├── img/            # Logotipos y bolt SVG de Homium
│   │   └── js/
│   │       └── app.js      # Interacciones, alertas y refresco
│   └── index.php           # Front-Controller y enrutador web
├── src/
│   ├── Controllers/
│   │   ├── AuthController.php
│   │   ├── LinkController.php
│   │   └── DashboardController.php
│   ├── Models/
│   │   ├── User.php
│   │   └── Link.php
│   └── Utils/
│       ├── Auth.php
│       └── Database.php
├── views/
│   ├── layouts/
│   │   ├── header.php
│   │   └── footer.php
│   ├── auth/
│   │   └── login.php
│   ├── links/
│   │   └── create.php      # Vista 1: Guardar enlace
│   └── dashboard/
│       └── index.php       # Vista 2: Dashboard general
├── .env.example            # Plantilla de variables de entorno
├── DOCUMENTACION.md        # Esta documentación
└── README.md
```

---

## 7. Despliegue en Ubuntu Server (GUI)

### 7.1 Requisitos del Servidor
* Ubuntu Server (20.04 LTS o 22.04 LTS) con interfaz GUI o CLI.
* PHP 8.1 CLI y FPM/Apache (`php8.1`, `php8.1-cli`, `php8.1-mysql`, `php8.1-mbstring`, `php8.1-curl`).
* Servidor MySQL 8.0 o MariaDB.
* Servidor Web Apache 2 o Nginx.
* Herramienta `homium-audit` instalada y accesible en el `PATH` del sistema (o ruta absoluta configurada en `.env`).

### 7.2 Configuración del CronJob
Para ejecutar el procesador cada minuto (o la frecuencia deseada) procesando 5 URLs por ciclo:

```bash
# Editar el crontab del usuario del sistema (ej. www-data o usuario estándar)
crontab -e

# Añadir la siguiente línea:
* * * * * /usr/bin/php /var/www/audit-homium/cron/worker.php >> /var/log/audit-worker.log 2>&1
```

---

## 8. Estado Actual y Próximos Pasos

* [x] Análisis del requerimiento funcional y levantamiento de dudas.
* [x] Inspección y homologación con `Homium Design System`.
* [x] Definición de modelo de datos MySQL y flujo de estados.
* [x] Creación del documento de arquitectura y contexto del proyecto (`DOCUMENTACION.md`).
* [ ] **Siguiente paso:** Creación de la estructura física del proyecto, base de datos SQL, vistas web (login, registro de enlaces, dashboard) y el script `cron/worker.php`.