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.

​
Prerequisites

Before you begin, ensure you have the following installed:
  • Docker (20.10 or higher)
  • Docker Compose (1.29 or higher)
  • A MySQL database server accessible from your Docker container
This quick start guide uses Docker Compose for the fastest setup experience. For production deployment, see the Installation Guide.

​
Setup Steps

1

Clone the Repository

Clone the DevolutionSync repository to your local machine:
git clone https://github.com/your-org/devolutionsync.git
cd devolutionsync
2

Configure Database Connection

Update the database credentials in Config/Conexion.php:
Config/Conexion.php
<?php
class Conexion {
    public static function Conectar() {
        $host = '192.200.100.40';      // Your MySQL host
        $db   = 'devolutionsync';       // Database name
        $user = 'SANMARINO';            // Database user
        $pass = 'sanmarino2021*';       // Database password
        $charset = 'utf8';

        $dsn = "mysql:host=$host;dbname=$db;charset=$charset";

        $opciones = [
            PDO::ATTR_ERRMODE            => PDO::ERRMODE_EXCEPTION,
            PDO::ATTR_DEFAULT_FETCH_MODE => PDO::FETCH_ASSOC,
            PDO::ATTR_EMULATE_PREPARES   => false,
        ];

        try {
            $pdo = new PDO($dsn, $user, $pass, $opciones);
            return $pdo;
        } catch (PDOException $e) {
            die("Error de conexión (PDO): " . $e->getMessage());
        }
    }
}
In production, use environment variables or a .env file instead of hardcoded credentials.
3

Initialize the Database

Import the database schema and default users:
mysql -h 192.200.100.40 -u SANMARINO -p devolutionsync < Script_BD/Script_DB.sql
This creates the following tables:
  • devoluciones - Product return records
  • notificaciones - User notifications
  • login_attempts - Security tracking
  • usuarios - User accounts
  • producto - Product catalog
And inserts three default users:
UsernamePasswordRoleGrado
ANALISTA1088350785Admin1
AUXILIAR895623Auxiliary2
CONSULTA895623Consultation3
4

Launch with Docker Compose

Start the application using Docker Compose:
docker-compose up -d
The Docker-compose.yml configuration:
Docker-compose.yml
services:
  web:
    build:
      context: .
      dockerfile: Dockerfile
    container_name: Proyecto_UCP
    ports:
      - "8097:80"                   
    volumes:
      - ./:/var/www/html
    networks:
      - red_local

volumes:
  db_data:

networks:
  red_local:
The application builds from this Dockerfile:
Dockerfile
# Usa la imagen oficial de PHP con Apache
FROM php:8.2-apache

# Habilita extensiones necesarias
RUN docker-php-ext-install pdo pdo_mysql mysqli

# Copia todos los archivos del proyecto al contenedor
COPY . /var/www/html/

# Ajusta permisos
RUN chown -R www-data:www-data /var/www/html \
    && chmod -R 755 /var/www/html

# Expone el puerto del servidor Apache
EXPOSE 80
5

Access the Application

Open your browser and navigate to:
http://localhost:8097
You should see the DevolutionSync login page.

​
First Login

Log in with administrator credentials to access the full dashboard:
  • Username: ANALISTA
  • Password: 1088350785
  • Redirects to: Dashboard with analytics and pending approvals
The authentication flow in AuthController.php:
Controllers/AuthController.php
public function login() {
    header('Content-Type: application/json');
    
    if ($_SERVER['REQUEST_METHOD'] === 'POST') {
        $username = trim($_POST['username'] ?? '');
        $password = $_POST['password'] ?? '';

        $user = $this->model->buscarUsuario($username);

        if ($user && $password === $user['PAS']) {
            $_SESSION['user'] = $user['USR'];
            $_SESSION['nombre'] = $user['NOMBRE'];
            $_SESSION['grado'] = $user['GRADO'];
            $_SESSION['logged_in'] = true;
            $_SESSION['last_activity'] = time();
            
            session_regenerate_id(true);

            echo json_encode([
                'success' => true,
                'redirect' => $this->getRedirectUrl($user['GRADO'])
            ]);
        } else {
            echo json_encode(['success' => false, 'message' => 'Credenciales incorrectas']);
        }
    }
}

private function getRedirectUrl($grado) {
    switch ($grado) {
        case 1: 
            return 'index.php?url=home/index';  // Admin dashboard
        case 2: 
            return 'index.php?url=devolucion/crear';  // Auxiliary form
        case 3: 
            return 'index.php?url=consulta/index';  // Read-only view
        default: 
            return 'index.php?url=auth/index';
    }
}
After logging in as ANALISTA, you’ll see the main dashboard with real-time statistics:

​
Dashboard Features

The HomeController.php loads analytics from the DevolucionModel:
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';
}

​
Statistics Query

The statistics are generated by a comprehensive SQL query:
Models/DevolucionModel.php
public function obtenerEstadisticas($fecha = null) {
    $where = $fecha ? "WHERE DATE(fecha_creacion) = :fecha" : "";
    
    $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);
}

​
Test the Workflow

1

Create a Return Request

  1. Log out and log back in as AUXILIAR
  2. Fill out the return registration form with:
    • Customer NIT and details
    • Product code from catalog
    • Deviation type (return/shortage/surplus)
    • Quantities and evidence photo
  3. Submit the form
2

Review as Admin

  1. Log out and log back in as ANALISTA
  2. Navigate to the admin panel
  3. Review the pending request
  4. Approve or reject with authorization code
3

Check Notifications

  1. Log back in as AUXILIAR
  2. View the notification of the admin’s decision
  3. Review the authorization code and observations

​
Verify Installation

Check that all services are running: 
# Check container status
docker ps

# View application logs
docker logs Proyecto_UCP

# Test database connection
docker exec -it Proyecto_UCP php -r "require 'Config/Conexion.php'; Conexion::Conectar(); echo 'Connected!\n';"

​
Common Issues

Edit Docker-compose.yml and change the port mapping:
ports:
  - "8098:80"  # Use a different port
Then restart: docker-compose down && docker-compose up -d
Verify the database is accessible from the Docker container:
docker exec -it Proyecto_UCP ping 192.200.100.40
docker exec -it Proyecto_UCP mysql -h 192.200.100.40 -u SANMARINO -p
If the database is on the same host, use host.docker.internal instead of an IP address.
Check PHP session configuration:
docker exec -it Proyecto_UCP php -i | grep session
Ensure session.save_path is writable by the www-data user.
Verify the uploads directory has correct permissions:
docker exec -it Proyecto_UCP ls -la uploads/
docker exec -it Proyecto_UCP chown -R www-data:www-data uploads/
docker exec -it Proyecto_UCP chmod -R 755 uploads/

​
Next Steps

Installation Guide

Set up DevolutionSync for production deployment

API Reference

Explore the MVC controllers and models
For security best practices and production hardening, refer to the Installation Guide.

Build docs developers (and LLMs) love

Get started for freeTalk to us