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**
```php
// 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)**
```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**
```json
{
    "require": {
        "laravel/framework": "^12.0",
        "doctrine/dbal": "^4.3"
    }
}
```

## 🚀 Instalación y Configuración

### **1. Preparación del Entorno**
```bash
# 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**
```bash
# 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**
```bash
# El archivo .env ya está configurado con:
cat .env | grep -E "DB_|APP_NAME"
```

### **4. Verificación de Configuración**
```bash
# 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**

#### **<2A><> Controladores API**

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

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

#### **🗄 Modelos Eloquent**

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

**Empresa.php**
```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):
```json
{
    "tipo": 0,
    "mensaje": "OK", 
    "data": [
        {
            "id": 1,
            "nombre": "Ciudad Ejemplo",
            "codigo": "CE001"
        }
    ]
}
```

**Respuesta de Error**:
```json
{
    "tipo": 1,
    "mensaje": "Descripción del error específico",
    "data": []
}
```

## 🔄 Mapeo de Migración

### **Archivo → Controlador**

#### **ObtenCiudades.php → CiudadesController.php**
```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**
```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:**
   ```php
   // Original: die(json_encode(["error" => sqlsrv_errors()]));
   // Nuevo: try-catch con respuestas HTTP apropiadas
   ```

2. **Alternativas con Query Builder:**
   ```php
   // Nuevo método alternativo sin procedimientos almacenados
   DB::table('ciudades')->select('*')->orderBy('nombre')->get();
   ```

3. **Middleware CORS:**
   ```php
   // Configurado para acceso desde frontend
   'Access-Control-Allow-Origin' => '*'
   ```

## 🧪 Testing y Pruebas

### **<2A><> Verificación Sin Conexión a BD**
```bash
# Verificar estructura del proyecto
php artisan route:list --path=api

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

### **🚀 Iniciar Servidor de Desarrollo**
```bash
# Iniciar servidor Laravel (puerto 8000)
php artisan serve

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

### **📋 Script de Pruebas Automatizado**
```bash
# 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**
```bash
# 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**
```php
// 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**
```php
// config/wsconcilia.php  
'database' => [
    'stored_procedures' => [
        'ciudades' => 'sapObtenListadoCiudadesxNombre',
        'empresas' => 'sapObtenEmpresas',
    ],
]
```

### **📝 Logging y Monitoreo**
```php
// 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:**
- [x] Migración completa de controladores
- [x] Configuración de rutas API versionadas
- [x] Modelos Eloquent preparados
- [x] Middleware CORS configurado
- [x] Manejo de errores estructurado
- [x] Documentación completa
- [x] Scripts de prueba automatizados
- [x] 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**
```bash
# 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**
```bash
# 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:**
```bash
# Instalar extensión SQL Server para PHP
sudo apt-get install php8.1-sqlsrv php8.1-pdo-sqlsrv
```

**2. Error de permisos:**
```bash
# Dar permisos a directorios de Laravel
chmod -R 755 storage bootstrap/cache
```

**3. Error de conexión a BD:**
```bash
# Verificar configuración sin conectar
php artisan tinker
>>> config('database.connections.sqlsrv')
```

**4. Error de CORS:**
```bash
# 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:**
- [x] ✅ Proyecto Laravel creado y configurado
- [x] ✅ Controladores migrados con lógica original
- [x] ✅ Rutas API estructuradas y versionadas  
- [x] ✅ Modelos Eloquent preparados
- [x] ✅ Configuración SQL Server lista
- [x] ✅ Middleware CORS configurado
- [x] ✅ Documentación completa generada
- [x] ✅ 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