Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/obando1998/Proyecto_UCP/llms.txt

Use this file to discover all available pages before exploring further.

Overview

The DevolutionSync dashboard provides comprehensive analytics for product returns, displaying real-time statistics filtered by date with breakdowns by status, return type, and quantities. All users can access the dashboard with role-appropriate data visibility.

Total Returns

Complete count by date

Status Breakdown

Pending, approved, rejected

Motivo Analysis

Returns, shortages, overages

Quantities

Units and kilograms tracked

Dashboard Access

All authenticated users can access the dashboard:
controllers/HomeController.php
public function __construct() {
    // Iniciamos sesión si no está iniciada
    if (session_status() === PHP_SESSION_NONE) session_start();
    
    // Verificamos autenticación
    if (!isset($_SESSION['logged_in'])) {
        header('Location: index.php?url=auth/index');
        exit;
    }
    
    // Usamos DevolucionModel que ya tiene la lógica de estadísticas centralizada
    $this->model = new DevolucionModel();
}
Unlike other features, the dashboard is accessible to all user roles (Admin, Auxiliary, and Consultation).

Date Filtering

Filter Implementation

The dashboard supports date-based filtering:
controllers/HomeController.php
public function index() {
    // Capturar fecha del filtro o usar la actual
    $fechaFiltro = $_GET['fecha'] ?? date('Y-m-d');
    
    // 1. Obtener estadísticas del día seleccionado
    $statsHoy = $this->model->obtenerEstadisticas($fechaFiltro);
    
    // 2. Obtener estadísticas históricas (sin pasar fecha)
    $statsGeneral = $this->model->obtenerEstadisticas();
    
    // 3. Obtener fechas disponibles para el select
    $fechas = $this->model->obtenerFechas();

    $titulo = "Dashboard General - DevolutionSync";
    require_once 'Views/home/dashboard.php';
}

Date Selector Interface

The view provides a dropdown to select dates:
views/home/dashboard.php
<form method="GET" action="index.php" class="date-selector">
    <input type="hidden" name="url" value="home/index">
    <label for="fecha">Seleccionar Fecha:</label>
    <select name="fecha" id="fecha" onchange="this.form.submit()">
        <?php foreach ($fechas as $f): ?>
            <option value="<?php echo $f; ?>" <?php echo ($fechaFiltro == $f) ? 'selected' : ''; ?>>
                <?php echo date('d/m/Y', strtotime($f)); ?>
            </option>
        <?php endforeach; ?>
    </select>
    <button type="submit">Actualizar</button>
</form>

Statistics Query

Core Statistics Method

The obtenerEstadisticas() method generates comprehensive analytics:
models/DevolucionModel.php
public function obtenerEstadisticas($fecha = null) {
    $where = $fecha ? "WHERE DATE(fecha_creacion) = :fecha" : "";
    
    // Usamos COALESCE para que devuelva 0 en vez de NULL si no hay datos
    $sql = "SELECT 
                COUNT(*) as total,
                COALESCE(SUM(cantidad_kg), 0) as total_kg,
                COALESCE(SUM(cantidad_und), 0) as total_und,
                
                -- Conteo por Estados
                COUNT(CASE WHEN estado = 'Pendiente' THEN 1 END) as pendientes,
                COUNT(CASE WHEN estado = 'Aprobado' THEN 1 END) as aprobados,
                COUNT(CASE WHEN estado = 'Rechazado' THEN 1 END) as rechazados,
                
                -- Conteo por Motivos
                COUNT(CASE WHEN motivo = 'Devolucion' THEN 1 END) as motivo_dev,
                COUNT(CASE WHEN motivo = 'Faltante' THEN 1 END) as motivo_fal,
                COUNT(CASE WHEN motivo = 'Sobrante' THEN 1 END) as motivo_sob
            FROM devoluciones 
            $where";

    $stmt = $this->db->prepare($sql);
    if ($fecha) $stmt->bindValue(':fecha', $fecha);
    $stmt->execute();
    return $stmt->fetch(PDO::FETCH_ASSOC);
}
When $fecha is provided, the query includes WHERE DATE(fecha_creacion) = :fecha to return statistics for a specific day.

Available Dates Query

models/DevolucionModel.php
public function obtenerFechas() {
    $stmt = $this->db->query("SELECT DISTINCT DATE(fecha_creacion) as fecha FROM devoluciones ORDER BY fecha DESC");
    return $stmt->fetchAll(PDO::FETCH_COLUMN);
}

Dashboard Metrics

Primary Indicators

The dashboard displays six primary metrics:
1

Total Returns

Complete count of all returns for the selected date.
$statsHoy['total_dev'] ?? 0
2

Return Type: Devolucion

Count of returns with motivo = ‘Devolucion’.
$statsHoy['motivo_dev'] ?? 0
3

Return Type: Faltante

Count of returns with motivo = ‘Faltante’.
$statsHoy['motivo_fal'] ?? 0
4

Return Type: Sobrante

Count of returns with motivo = ‘Sobrante’.
$statsHoy['motivo_sob'] ?? 0
5

Total Kilograms

Sum of all cantidad_kg values.
number_format($statsHoy['total_kg'] ?? 0, 2)
6

Total Units

Sum of all cantidad_und values.
number_format($statsHoy['total_und'] ?? 0, 0)

Status Breakdown

The dashboard shows return distribution by approval status:
views/home/dashboard.php
<div class="general-stats">
    <h3>Estado de Devoluciones - <?php echo date('d/m/Y', strtotime($fechaFiltro)); ?></h3>
    <div class="stats-grid">
        <div class="stat-item">
            <div class="stat-value"><?php echo $statsHoy['pendientes'] ?? 0; ?></div>
            <div class="stat-label">Pendientes</div>
        </div>
        <div class="stat-item">
            <div class="stat-value"><?php echo $statsHoy['aprobadas'] ?? 0; ?></div>
            <div class="stat-label">Aprobadas</div>
        </div>
        <div class="stat-item">
            <div class="stat-value"><?php echo $statsHoy['rechazadas'] ?? 0; ?></div>
            <div class="stat-label">Rechazadas</div>
        </div>
        <div class="stat-item">
            <div class="stat-value">
                <?php 
                $totalRevisadas = ($statsHoy['aprobadas'] ?? 0) + ($statsHoy['rechazadas'] ?? 0);
                $totalDev = $statsHoy['total_dev'] ?? 0;
                $porcentaje = $totalDev > 0 ? round(($totalRevisadas / $totalDev) * 100, 1) : 0;
                echo $porcentaje . '%';
                ?>
            </div>
            <div class="stat-label">Revisadas</div>
        </div>
    </div>
</div>
The “Revisadas” percentage is calculated as (aprobadas + rechazadas) / total * 100, showing the review completion rate.

Historical Overview

The dashboard includes aggregate statistics across all dates:
views/home/dashboard.php
<div class="general-stats">
    <h3>Resumen General (Todas las Fechas)</h3>
    <div class="stats-grid">
        <div class="stat-item">
            <div class="stat-value"><?php echo $statsGeneral['total_dev'] ?? 0; ?></div>
            <div class="stat-label">Total Devoluciones</div>
        </div>
        <div class="stat-item">
            <div class="stat-value"><?php echo $statsGeneral['aprobadas'] ?? 0; ?></div>
            <div class="stat-label">Total Aprobadas</div>
        </div>
        <div class="stat-item">
            <div class="stat-value"><?php echo $statsGeneral['rechazadas'] ?? 0; ?></div>
            <div class="stat-label">Total Rechazadas</div>
        </div>
        <div class="stat-item">
            <div class="stat-value"><?php echo number_format($statsGeneral['total_kg'] ?? 0, 2); ?></div>
            <div class="stat-label">Total KG General</div>
        </div>
        <div class="stat-item">
            <div class="stat-value"><?php echo number_format($statsGeneral['total_und'] ?? 0, 0); ?></div>
            <div class="stat-label">Total UND General</div>
        </div>
        <div class="stat-item">
            <div class="stat-value"><?php echo count($fechas); ?></div>
            <div class="stat-label">Días con Actividad</div>
        </div>
    </div>
</div>

Real-Time Updates

The dashboard displays real-time data with visual indicators:
views/home/dashboard.php
<div class="current-date">
    <strong>Mostrando datos para:</strong> 
    <?php 
    if ($fechaFiltro == date('Y-m-d')) {
        echo "<strong>HOY - " . date('d/m/Y') . "</strong>";
    } else {
        echo date('d/m/Y', strtotime($fechaFiltro));
    }
    ?>
</div>
views/home/dashboard.php
<?php if ($fechaFiltro == date('Y-m-d')): ?>
    <div class="indicator-trend trend-positive">En tiempo real</div>
<?php else: ?>
    <div class="indicator-trend trend-neutral">Datos históricos</div>
<?php endif; ?>

Data Aggregation

SQL Aggregation Techniques

The statistics query uses advanced SQL features:
COALESCE(SUM(cantidad_kg), 0) as total_kg
Returns 0 instead of NULL when no records exist, preventing PHP errors.
COUNT(CASE WHEN estado = 'Pendiente' THEN 1 END) as pendientes
Counts only records matching the condition in a single query pass.
WHERE DATE(fecha_creacion) = :fecha
Extracts the date portion of the timestamp for accurate day-based filtering.

Performance Optimization

Single Query Design

All statistics are retrieved in one SQL query using conditional aggregation, minimizing database round trips.

Indexed Dates

The fecha_creacion column should have an index for fast date-based filtering:
CREATE INDEX idx_fecha ON devoluciones(fecha_creacion);

Date Caching

Available dates are queried separately and cached in the view, avoiding repeated queries.

NULL Coalescing

Using COALESCE in SQL prevents NULL propagation and simplifies PHP logic.

Indicator Grid

The dashboard uses a responsive grid layout:
views/home/dashboard.php
<div class="indicators-grid">
    <div class="indicator-card border-blue">
        <div class="date-badge">FECHA SELECCIONADA</div>
        <div class="indicator-icon">📦</div>
        <div class="indicator-value"><?php echo $statsHoy['total_dev'] ?? 0; ?></div>
        <div class="indicator-label">Total Devoluciones</div>
        <?php if ($fechaFiltro == date('Y-m-d')): ?>
            <div class="indicator-trend trend-positive">En tiempo real</div>
        <?php else: ?>
            <div class="indicator-trend trend-neutral">Datos históricos</div>
        <?php endif; ?>
    </div>
    <!-- Additional cards... -->
</div>

Analytics Use Cases

Track today’s returns in real-time to identify unusual patterns or spikes requiring immediate attention.

Next Steps

Authentication

Learn about role-based access control

Return Management

Understand the return registration process

Approval Workflow

Review the admin approval system

Build docs developers (and LLMs) love