wsconcilia-laravel/README.md

🚀 WSCONCILIA API Laravel

📖 Descripción

Este proyecto migra completamente la funcionalidad de los archivos PHP originales (ObtenCiudades.php y ObtenEmpresas.php) a una API Laravel moderna, estructurada y escalable. La migración mantiene la compatibilidad con los procedimientos almacenados existentes mientras añade las ventajas del framework Laravel.

🎯 Objetivos de la Migración

• ✅ Modernización: De archivos PHP individuales a framework Laravel estructurado
• ✅ Escalabilidad: Arquitectura preparada para crecimiento futuro
• ✅ Mantenibilidad: Código organizado siguiendo patrones MVC
• ✅ Compatibilidad: Mantiene procedimientos almacenados existentes
• ✅ Documentación: API autodocumentada y endpoints claros

🔧 Especificaciones Técnicas

Framework y Versiones

• Laravel: 12.x
• PHP: >= 8.1
• Base de datos: SQL Server
• Driver: sqlsrv (Microsoft SQL Server)

Configuración de Base de Datos Original

// Migrado desde config.php
$serverName = "10.201.84.3"; // SQL Server
$connectionOptions = [
    "Database" => "personal",
    "Uid" => "sysdev", 
    "PWD" => "tRGtXNNW1DaT",
    "CharacterSet" => "UTF-8"
];

Configuración Laravel (.env)

# Aplicación
APP_NAME=WSCONCILIA-API
APP_ENV=local
APP_DEBUG=true
APP_LOCALE=es
APP_FALLBACK_LOCALE=es

# Base de Datos SQL Server
DB_CONNECTION=sqlsrv
DB_HOST=10.201.84.3
DB_PORT=1433
DB_DATABASE=personal
DB_USERNAME=sysdev
DB_PASSWORD=tRGtXNNW1DaT

📋 Requisitos del Sistema

Software Requerido

• PHP >= 8.1 con extensiones:
  • pdo_sqlsrv (SQL Server)
  • sqlsrv (Microsoft SQL Server)
  • mbstring
  • xml
  • json
• Composer (gestor de dependencias PHP)
• SQL Server (accesible desde 10.201.84.3)

Dependencias Laravel

{
    "require": {
        "laravel/framework": "^12.0",
        "doctrine/dbal": "^4.3"
    }
}

🚀 Instalación y Configuración

1. Preparación del Entorno

# Clonar o navegar al proyecto
cd /home/xesar/Documents/WSCONCILIA-Laravel

# Verificar archivos principales
ls -la app/Http/Controllers/Api/
ls -la app/Models/

2. Instalación de Dependencias

# Instalar dependencias de Composer
composer install

# Verificar instalación de doctrine/dbal (para SQL Server)
composer show doctrine/dbal

3. Configuración de Variables de Entorno

# El archivo .env ya está configurado con:
cat .env | grep -E "DB_|APP_NAME"

4. Verificación de Configuración

# Verificar configuración (sin conectar a BD)
php artisan config:show database.connections.sqlsrv

🗂 Arquitectura del Proyecto

Estructura de Directorios

WSCONCILIA-Laravel/
├── 📁 app/
│   ├── 📁 Http/
│   │   ├── 📁 Controllers/
│   │   │   └── 📁 Api/
│   │   │       ├── 📄 CiudadesController.php
│   │   │       └── 📄 EmpresasController.php
│   │   └── 📁 Middleware/
│   │       └── 📄 CorsMiddleware.php
│   └── 📁 Models/
│       ├── 📄 Ciudad.php
│       └── 📄 Empresa.php
├── 📁 config/
│   └── 📄 wsconcilia.php (configuración personalizada)
├── 📁 routes/
│   └── 📄 api.php (rutas de la API)
├── 📄 .env (configuración de entorno)
├── 📄 README.md (esta documentación)
└── 📄 test-api.sh (script de pruebas)

Componentes Principales

<EFBFBD><EFBFBD> Controladores API

CiudadesController.php

// Migrado desde ObtenCiudades.php
- obtenerCiudades() → EXEC sapObtenListadoCiudadesxNombre
- obtenerCiudadesAlternativo() → Query Builder alternativo

EmpresasController.php

// Migrado desde ObtenEmpresas.php  
- obtenerEmpresas() → EXEC sapObtenEmpresas
- obtenerEmpresasAlternativo() → Query Builder alternativo
- obtenerEmpresaPorId(int $id) → Funcionalidad adicional

🗄 Modelos Eloquent

Ciudad.php

// Modelo para tabla ciudades
- $fillable: ['nombre', 'codigo', 'estado_id', 'activo']
- scopeActivas(): Solo ciudades activas

Empresa.php

// Modelo para tabla empresas
- $fillable: ['nombre', 'rfc', 'direccion', 'telefono', 'email', 'activo']
- scopeActivas(): Solo empresas activas

🌐 Endpoints de la API

📍 Rutas Principales

Método	Endpoint	Descripción	Origen
GET	/api/health	Estado de salud del API	Nuevo
GET	/api/info	Información y documentación del API	Nuevo

📍 Rutas de Ciudades (v1)

Método	Endpoint	Descripción	Origen
GET	/api/v1/ciudades	Obtener ciudades (SP)	ObtenCiudades.php
GET	/api/v1/ciudades-alt	Obtener ciudades (Query Builder)	Nuevo

📍 Rutas de Empresas (v1)

Método	Endpoint	Descripción	Origen
GET	/api/v1/empresas	Obtener empresas (SP)	ObtenEmpresas.php
GET	/api/v1/empresas-alt	Obtener empresas (Query Builder)	Nuevo
GET	/api/v1/empresas/{id}	Obtener empresa por ID	Nuevo

📊 Formato de Respuesta

Respuesta Exitosa (mantiene formato original):

{
    "tipo": 0,
    "mensaje": "OK", 
    "data": [
        {
            "id": 1,
            "nombre": "Ciudad Ejemplo",
            "codigo": "CE001"
        }
    ]
}

Respuesta de Error:

{
    "tipo": 1,
    "mensaje": "Descripción del error específico",
    "data": []
}

🔄 Mapeo de Migración

Archivo → Controlador

ObtenCiudades.php → CiudadesController.php

// ORIGINAL (ObtenCiudades.php)
$sql = "{CALL sapObtenListadoCiudadesxNombre}";
$stmt = sqlsrv_query($conn, $sql);
while ($row = sqlsrv_fetch_array($stmt, SQLSRV_FETCH_ASSOC)) {
    $data[] = $row;
}

// MIGRADO (CiudadesController.php)
public function obtenerCiudades(): JsonResponse {
    $ciudades = DB::select('EXEC sapObtenListadoCiudadesxNombre');
    return response()->json([
        "tipo" => 0,
        "mensaje" => "OK",
        "data" => $ciudades
    ]);
}

ObtenEmpresas.php → EmpresasController.php

// ORIGINAL (ObtenEmpresas.php)
$sql = "{CALL sapObtenEmpresas}";
$stmt = sqlsrv_query($conn, $sql);
while ($row = sqlsrv_fetch_array($stmt, SQLSRV_FETCH_ASSOC)) {
    $data[] = $row;
}

// MIGRADO (EmpresasController.php)
public function obtenerEmpresas(): JsonResponse {
    $empresas = DB::select('EXEC sapObtenEmpresas');
    return response()->json([
        "tipo" => 0,
        "mensaje" => "OK", 
        "data" => $empresas
    ]);
}

Mejoras Implementadas

1. Manejo de Errores Mejorado:

   // Original: die(json_encode(["error" => sqlsrv_errors()]));
   // Nuevo: try-catch con respuestas HTTP apropiadas
   

2. Alternativas con Query Builder:

   // Nuevo método alternativo sin procedimientos almacenados
   DB::table('ciudades')->select('*')->orderBy('nombre')->get();
   

3. Middleware CORS:

   // Configurado para acceso desde frontend
   'Access-Control-Allow-Origin' => '*'
   

🧪 Testing y Pruebas

<EFBFBD><EFBFBD> Verificación Sin Conexión a BD

# Verificar estructura del proyecto
php artisan route:list --path=api

# Comprobar configuración
php artisan config:show database.connections.sqlsrv

🚀 Iniciar Servidor de Desarrollo

# Iniciar servidor Laravel (puerto 8000)
php artisan serve

# Verificar que el servidor esté funcionando
curl http://localhost:8000/api/health

📋 Script de Pruebas Automatizado

# Ejecutar script de pruebas completo
./test-api.sh

# Contenido del script:
# - Prueba /api/health
# - Prueba /api/info  
# - Prueba /api/v1/ciudades
# - Prueba /api/v1/empresas

🔧 Pruebas Manuales con cURL

# Estado de salud
curl -X GET http://localhost:8000/api/health

# Información del API
curl -X GET http://localhost:8000/api/info

# Ciudades (cuando tengas conexión DB)
curl -X GET http://localhost:8000/api/v1/ciudades

# Empresas (cuando tengas conexión DB)
curl -X GET http://localhost:8000/api/v1/empresas

# Empresa específica
curl -X GET http://localhost:8000/api/v1/empresas/1

⚙ Configuración Avanzada

🔐 Configuración de Seguridad

// config/wsconcilia.php
'cors' => [
    'allowed_origins' => ['*'], // Cambiar en producción
    'allowed_methods' => ['GET', 'POST', 'PUT', 'DELETE', 'OPTIONS'],
    'allowed_headers' => ['Content-Type', 'Authorization', 'X-Requested-With'],
]

📊 Configuración de Base de Datos

// config/wsconcilia.php  
'database' => [
    'stored_procedures' => [
        'ciudades' => 'sapObtenListadoCiudadesxNombre',
        'empresas' => 'sapObtenEmpresas',
    ],
]

📝 Logging y Monitoreo

// Los logs se guardan automáticamente en:
// storage/logs/laravel.log

// Para ver logs en tiempo real:
tail -f storage/logs/laravel.log

🚦 Estados del Proyecto

✅ Completado y Funcional:

• Migración completa de controladores
• Configuración de rutas API versionadas
• Modelos Eloquent preparados
• Middleware CORS configurado
• Manejo de errores estructurado
• Documentación completa
• Scripts de prueba automatizados
• Configuración SQL Server lista

⏳ Pendiente (Requiere Conexión a BD):

• Testing de procedimientos almacenados reales
• Validación de estructura de tablas existentes
• Optimización de consultas según datos reales
• Configuración de cache para consultas frecuentes

🔮 Mejoras Futuras Sugeridas:

• Autenticación API (Sanctum/Passport)
• Rate limiting para endpoints
• Paginación para grandes conjuntos de datos
• Validación de requests con Form Requests
• Tests unitarios automatizados (PHPUnit)

🛠 Comandos Útiles

🔄 Artisan Commands

# Ver todas las rutas
php artisan route:list

# Limpiar cache de configuración
php artisan config:clear

# Ver configuración actual
php artisan config:show

# Generar clave de aplicación
php artisan key:generate

# Información del entorno
php artisan about

📦 Composer Commands

# Actualizar dependencias
composer update

# Ver paquetes instalados
composer show

# Autoload classes
composer dump-autoload

🔧 Solución de Problemas

❌ Problemas Comunes y Soluciones

1. Error de extensión sqlsrv:

# Instalar extensión SQL Server para PHP
sudo apt-get install php8.1-sqlsrv php8.1-pdo-sqlsrv

2. Error de permisos:

# Dar permisos a directorios de Laravel
chmod -R 755 storage bootstrap/cache

3. Error de conexión a BD:

# Verificar configuración sin conectar
php artisan tinker
>>> config('database.connections.sqlsrv')

4. Error de CORS:

# Verificar middleware CORS
php artisan route:list --middleware=cors

📞 Información de Contacto y Soporte

📊 Configuración Original Migrada:

Servidor: 10.201.84.3 (SQL Server)
Base de datos: personal  
Usuario: sysdev
Puerto: 1433 (estándar SQL Server)

🔗 URLs del API en Desarrollo:

Base URL: http://localhost:8000/api
Health Check: http://localhost:8000/api/health
Documentación: http://localhost:8000/api/info

📚 Referencias y Documentación

• Laravel Documentation: https://laravel.com/docs
• SQL Server PHP Drivers: https://docs.microsoft.com/en-us/sql/connect/php/
• Laravel API Resources: https://laravel.com/docs/eloquent-resources
• Doctrine DBAL: https://www.doctrine-project.org/projects/dbal.html

---

📋 Checklist de Implementación

Para el Desarrollador:

• ✅ Proyecto Laravel creado y configurado
• ✅ Controladores migrados con lógica original
• ✅ Rutas API estructuradas y versionadas
• ✅ Modelos Eloquent preparados
• ✅ Configuración SQL Server lista
• ✅ Middleware CORS configurado
• ✅ Documentación completa generada
• ✅ Scripts de prueba creados

Para Testing (Cuando tengas conexión):

• ⏳ Probar conexión a SQL Server
• ⏳ Verificar procedimientos almacenados
• ⏳ Testear endpoints con datos reales
• ⏳ Validar respuestas JSON
• ⏳ Comprobar manejo de errores

Para Producción:

• 🔮 Configurar variables de entorno de producción
• 🔮 Implementar autenticación API
• 🔮 Configurar CORS específicos
• 🔮 Optimizar consultas de base de datos
• 🔮 Implementar logging avanzado

---

🎯 Proyecto migrado exitosamente de PHP vanilla a Laravel API 📅 Fecha de migración: 12 de septiembre de 2025 🔧 Estado: Listo para testing con conexión a base de datos