Sio-Back/README.md

SIO Backend - Sistema Integral de Operaciones

Drenax - API REST para Gestion de Servicios

---

Informacion General

Campo	Valor
Nombre	SIO Backend
Framework	Laravel 5.5
PHP	7.4
Base de Datos	MariaDB 11.8
Puerto Local	8000
URL Produccion	https://sio-api.consultoria-as.com

---

Arquitectura del Sistema

┌─────────────────────────────────────────────────────────┐
│                    FRONTEND                              │
│              Angular 8.3.29 + Material                   │
│                  Puerto: 4200                            │
└─────────────────────┬───────────────────────────────────┘
                      │ HTTPS (Cloudflare Tunnel)
                      ▼
┌─────────────────────────────────────────────────────────┐
│                    BACKEND (API)                         │
│               Laravel 5.5 (PHP 7.4)                      │
│                  Puerto: 8000                            │
└─────────────────────┬───────────────────────────────────┘
                      │
                      ▼
┌─────────────────────────────────────────────────────────┐
│                   DATABASE                               │
│                 MariaDB 11.8.3                           │
│                  Puerto: 3306                            │
└─────────────────────────────────────────────────────────┘

---

Estructura del Proyecto

sio-backend/
├── app/
│   ├── Http/
│   │   ├── Controllers/
│   │   │   ├── AtencionClientes/         # Controladores de servicios
│   │   │   │   ├── ServiciosController.php
│   │   │   │   └── EncuestasController.php
│   │   │   ├── Administrador/            # Controladores admin
│   │   │   │   ├── UsersController.php
│   │   │   │   ├── ClientesController.php
│   │   │   │   └── VehiculosController.php
│   │   │   ├── Operador/                 # Controladores operador
│   │   │   │   ├── ServiciosController.php
│   │   │   │   ├── JornadaController.php
│   │   │   │   └── CheckListController.php
│   │   │   ├── Reportes/                 # Controladores reportes
│   │   │   ├── SupervisorOperaciones/    # Controladores supervisor
│   │   │   └── Auth/                     # Autenticacion
│   │   ├── Middleware/
│   │   │   ├── SentinelACL.php           # Control de acceso por roles
│   │   │   └── RequestLogs.php           # Logs de peticiones
│   │   └── Requests/                     # Form Requests (validaciones)
│   ├── Models/                           # Modelos Eloquent
│   │   ├── User.php
│   │   ├── Cliente.php
│   │   ├── ServicioEnc.php
│   │   ├── ServicioDet.php
│   │   ├── ServicioProgreso.php
│   │   ├── ServicioEvidencia.php
│   │   ├── ServicioHistorial.php         # Historial de cambios
│   │   └── Vehiculo.php
│   ├── Observers/
│   │   └── ServicioDetObserver.php       # Observer para historial
│   ├── Mail/                             # Plantillas de correo
│   └── Providers/
├── config/
│   ├── app.php
│   ├── database.php
│   ├── jwt.php                           # Configuracion JWT
│   └── cors.php                          # Configuracion CORS
├── database/
│   ├── migrations/                       # Migraciones de BD
│   └── seeds/                            # Seeders de datos
├── routes/
│   ├── api.php                           # Rutas principales
│   ├── atencion-clientes-routes.php      # Rutas atencion clientes
│   ├── administrador-routes.php          # Rutas administrador
│   ├── operador-routes.php               # Rutas operador (movil)
│   ├── reportes-routes.php               # Rutas reportes
│   └── supervisor-operaciones-routes.php # Rutas supervisor
├── storage/
│   ├── app/public/                       # Archivos publicos (evidencias)
│   └── logs/laravel.log                  # Logs de la aplicacion
└── .env                                  # Variables de entorno

---

Base de Datos

Diagrama de Tablas Principales

┌──────────────┐     ┌──────────────────┐     ┌──────────────┐
│    users     │     │  servicios_enc   │     │   clientes   │
├──────────────┤     ├──────────────────┤     ├──────────────┤
│ id           │◄────│ usuario_agenda_id│     │ id           │
│ email        │     │ cliente_id       │────►│ nombre       │
│ nombre       │     │ fecha_agenda     │     │ telefono     │
│ tipo_empleado│     │ sucursal_id      │     │ email        │
└──────────────┘     └────────┬─────────┘     └──────────────┘
                              │
                              │ 1:N
                              ▼
                     ┌──────────────────┐
                     │  servicios_det   │
                     ├──────────────────┤
                     │ id               │
                     │ servicio_enc_id  │
                     │ operador_id      │────► users
                     │ vehiculo_id      │────► cat_vehiculos
                     │ estatus_servicio │────► cat_estatus_servicios
                     │ fecha_solicitud  │
                     │ costo_servicio   │
                     └────────┬─────────┘
                              │
              ┌───────────────┼───────────────┐
              ▼               ▼               ▼
    ┌─────────────────┐ ┌───────────────┐ ┌────────────────────┐
    │servicios_progreso│ │servicios_     │ │servicios_historial │
    ├─────────────────┤ │evidencias     │ ├────────────────────┤
    │ fecha_ini       │ ├───────────────┤ │ campo              │
    │ fecha_fin       │ │ foto          │ │ valor_anterior     │
    │ firma           │ │ tipo          │ │ valor_nuevo        │
    │ litraje         │ └───────────────┘ │ usuario_id         │
    └─────────────────┘                   └────────────────────┘

Tablas del Sistema

Tabla	Registros	Descripcion
users	419	Usuarios del sistema
clientes	81,853	Clientes registrados
clientes_domicilios	83,637	Direcciones de clientes
servicios_enc	129,750	Encabezados de servicios
servicios_det	123,317	Detalle de servicios
servicios_progreso	114,219	Progreso de servicios
servicios_evidencias	180,861	Evidencias fotograficas
servicios_historial	-	Historial de cambios
cat_vehiculos	100	Catalogo de vehiculos
cat_servicios	64	Catalogo de servicios
cat_estatus_servicios	7	Estados de servicio
cat_formas_pagos	10	Formas de pago
cat_origenes	18	Origenes de servicio
roles	10	Roles de usuario
sucursales	4	Sucursales

Tipos de Empleados

ID	Tipo
1	Administrador
2	Operador
3	Auxiliar
5	Atencion a Clientes
6	Supervisor de Operaciones

Estatus de Servicios

ID	Nombre	Color
1	Realizado	#04B404 (Verde)
2	Reprogramado	#FF8000 (Naranja)
3	Cancelado	#B40404 (Rojo)
4	Pendiente	#FFFF00 (Amarillo)
5	Negativo	#FE2E2E (Rojo claro)
6	En Proceso	Azul
7	Sin Asignar	Gris

---

API Endpoints

Autenticacion

Metodo	Endpoint	Descripcion
POST	/api/login	Iniciar sesion
GET	/api/refresh	Refrescar token JWT
POST	/api/recoverpassword	Recuperar contrasena
POST	/api/updatepassword	Actualizar contrasena

Atencion a Clientes (/api/atencionclientes/)

Metodo	Endpoint	Descripcion
GET	/solicitud_servicios	Listar servicios
POST	/solicitud_servicios	Crear servicio
GET	/solicitud_servicios/{id}	Ver servicio
PUT	/solicitud_servicios/{id}	Actualizar servicio
POST	/solicitud_servicios/agenda	Obtener agenda por fecha
GET	/solicitud_servicios/cat_servicios	Catalogo de servicios
GET	/solicitud_servicios/estatus_servicios	Catalogo de estatus
GET	/solicitud_servicios/clientes	Listar clientes
GET	/solicitud_servicios/operadores	Listar operadores
GET	/solicitud_servicios/vehiculos	Listar vehiculos
GET	/solicitud_servicios/{id}/historial	Ver historial de cambios

Operador - App Movil (/api/operador/)

Metodo	Endpoint	Descripcion
GET	/checklist	Obtener checklist del vehiculo
GET	/checklist/vehiculos	Obtener vehiculos disponibles
POST	/checklist	Enviar checklist completado
POST	/iniciarjornada	Iniciar jornada laboral
POST	/finalizarjornada/{id}	Finalizar jornada
GET	/solicitud_servicios	Obtener servicios asignados
GET	/solicitud_servicios/{id}	Detalle de servicio
POST	/solicitud_servicios/iniciar	Iniciar servicio
POST	/solicitud_servicios/finalizar-new	Finalizar servicio
POST	/solicitud_servicios/verificar/servicios	Verificar servicios
GET	/servicios/diasiguiente	Servicios del dia siguiente
POST	/vehiculos_incidencias	Reportar incidencia vehiculo

Supervisor de Operaciones (/api/supervisoroperaciones/)

Metodo	Endpoint	Descripcion
GET	/asesores	Listar operadores
GET	/asesores/{id}/servicios	Servicios de un operador
POST	/iniciarjornada	Iniciar jornada supervisor
POST	/finalizarjornada/{id}	Finalizar jornada

Administrador (/api/administrador/)

• Gestion de usuarios
• Gestion de catalogos (clientes, vehiculos, servicios)
• Configuraciones del sistema

Reportes (/api/reportes/)

• Reportes de servicios por periodo
• Productividad por operador
• Encuestas de satisfaccion
• Capacidad aprovechada

---

Instalacion

Requisitos

• PHP 7.4
• Composer
• MariaDB 10+ / MySQL 5.7+
• Extensiones PHP: mbstring, xml, curl, mysql, gd, bcmath, zip

Pasos de Instalacion

# Clonar repositorio
git clone https://git.consultoria-as.com/consultoria-as/Sio-Back.git
cd Sio-Back

# Instalar dependencias
composer install --no-dev --optimize-autoloader

# Copiar archivo de configuracion
cp .env.example .env

# Generar clave de aplicacion
php artisan key:generate

# Configurar permisos
chmod -R 775 storage bootstrap/cache
chown -R www-data:www-data storage bootstrap/cache

# Ejecutar migraciones
php artisan migrate

# (Opcional) Ejecutar seeders
php artisan db:seed

Configuracion del Archivo .env

APP_NAME=SIO
APP_ENV=production
APP_DEBUG=false
APP_URL=https://sio-api.consultoria-as.com

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=sio_database
DB_USERNAME=sio_user
DB_PASSWORD=tu_password

MAIL_DRIVER=smtp
MAIL_HOST=smtp.gmail.com
MAIL_PORT=587
MAIL_USERNAME=correo@gmail.com
MAIL_PASSWORD=app_password
MAIL_ENCRYPTION=tls

AMBIENTE=PROD

Ejecutar en Desarrollo

php artisan serve --host=0.0.0.0 --port=8000

Ejecutar en Produccion

Se recomienda usar Nginx o Apache. Ejemplo de configuracion Nginx:

server {
    listen 80;
    server_name sio-api.consultoria-as.com;
    root /var/www/sio-backend/public;

    index index.php;

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

    location ~ \.php$ {
        fastcgi_pass unix:/var/run/php/php7.4-fpm.sock;
        fastcgi_index index.php;
        fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
        include fastcgi_params;
    }
}

---

Funcionalidades Especiales

Historial de Cambios (Observer)

El sistema registra automaticamente todos los cambios realizados a los servicios mediante un Observer de Eloquent.

Modelo: app/Models/ServicioHistorial.php Observer: app/Observers/ServicioDetObserver.php

Campos rastreados:

• estatus_servicio_id
• operador_id
• vehiculo_id
• auxiliar_1, auxiliar_2, auxiliar_3
• costo_servicio
• fecha_solicitud
• duracion
• comentarios
• comentarios_cancelacion

Estructura de la tabla:

CREATE TABLE servicios_historial (
    id INT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
    servicio_det_id INT UNSIGNED NOT NULL,
    usuario_id INT UNSIGNED NOT NULL,
    campo VARCHAR(100) NOT NULL,
    valor_anterior TEXT,
    valor_nuevo TEXT,
    accion ENUM('crear', 'actualizar', 'eliminar') DEFAULT 'actualizar',
    ip_address VARCHAR(45),
    created_at TIMESTAMP,
    updated_at TIMESTAMP
);

Validacion de Disponibilidad

Antes de asignar operador/vehiculo, el sistema valida:

• Que no esten asignados a otro servicio en el mismo horario
• Disponibilidad de auxiliares
• Conflictos de tiempo

Encuestas de Satisfaccion

• Encuesta Domestico: 12 preguntas
• Encuesta Empresarial: 13 preguntas

---

Middlewares

SentinelACL

Control de acceso basado en roles usando Cartalyst Sentinel.

// Rutas protegidas por rol
Route::middleware(['jwt', 'acl:administrador'])->group(function () {
    // Solo administradores
});

RequestLogs

Registra todas las peticiones HTTP para auditoria.

---

Comandos Artisan Utiles

# Limpiar cache
php artisan cache:clear
php artisan config:clear
php artisan route:clear
php artisan view:clear

# Optimizar para produccion
php artisan config:cache
php artisan route:cache

# Migraciones
php artisan migrate                  # Ejecutar migraciones
php artisan migrate:rollback         # Revertir ultima migracion
php artisan migrate:fresh --seed     # Recrear BD con seeders

# Generar documentacion de rutas
php artisan route:list

# Logs
tail -f storage/logs/laravel.log

---

Backup y Restauracion

Crear Backup

mysqldump -u sio_user -p sio_database > backup_$(date +%Y%m%d_%H%M%S).sql

Restaurar Backup

mysql -u sio_user -p sio_database < backup_XXXXXXXX.sql

---

Seguridad

Autenticacion JWT

El sistema usa JSON Web Tokens para autenticacion stateless.

Header requerido:

Authorization: Bearer {token}

CORS

Configurado en config/cors.php para permitir peticiones del frontend.

Validaciones

Todas las peticiones son validadas mediante Form Requests en app/Http/Requests/.

---

Troubleshooting

Error 500 - Internal Server Error

# Verificar permisos
chmod -R 775 storage bootstrap/cache

# Verificar logs
tail -f storage/logs/laravel.log

# Limpiar cache
php artisan cache:clear
php artisan config:clear

Error 422 - Unprocessable Entity

• Verificar datos enviados en la peticion
• Revisar validaciones en el Form Request correspondiente

Error de conexion a BD

• Verificar credenciales en .env
• Confirmar que MariaDB este ejecutandose
• Verificar permisos del usuario de BD

CORS bloqueado

• Verificar configuracion en config/cors.php
• Agregar dominio del frontend a la lista de origenes permitidos

---

Tecnologias Utilizadas

• Laravel 5.5 - Framework PHP
• PHP 7.4 - Lenguaje de programacion
• MariaDB - Base de datos
• Cartalyst Sentinel - Autenticacion y roles
• JWT - Tokens de autenticacion
• Eloquent ORM - Mapeo objeto-relacional
• DOMPDF - Generacion de PDFs
• Maatwebsite Excel - Exportacion a Excel

---

Estructura de Respuestas API

Respuesta Exitosa

{
    "success": true,
    "data": { ... },
    "message": "Operacion exitosa"
}

Respuesta de Error

{
    "success": false,
    "error": "Mensaje de error",
    "code": 400
}

Respuesta Paginada

{
    "success": true,
    "data": [ ... ],
    "meta": {
        "current_page": 1,
        "last_page": 10,
        "per_page": 15,
        "total": 150
    }
}

---

Contacto

Campo	Valor
Sistema	SIO (Sistema Integral de Operaciones)
Empresa	Drenax
Dominio	consultoria-as.com

---

Version: 1.0 Ultima actualizacion: 2026-01-17