# Guía de Deployment - Masser Drummond

Este documento describe cómo desplegar cambios en los ambientes de producción del proyecto Laravel.

## 🏗️ Arquitectura de Ambientes

El proyecto cuenta con 4 ambientes:

### 1. Desarrollo
- **Ubicación**: Servidor de desarrollo
- **Rama Git**: `dev`
- **Propósito**: Pruebas y desarrollo de nuevas funcionalidades
- **Base de datos**: Base de datos de desarrollo

### 2. QA (Quality Assurance)
- **Ubicación**: Servidor de QA
- **Rama Git**: `release/x.x.x` (versiones de release)
- **Propósito**: Última revisión y validación antes de subir a producción
- **Base de datos**: Base de datos de QA

### 3. Producción Local (PRINCIPAL - Maestro) ⭐
- **Ubicación**: Computador local en las instalaciones del cliente
- **Rama Git**: `master`
- **Rol**: **AMBIENTE DE PRODUCCIÓN PRINCIPAL**
- **Base de datos**: Base de datos local (MySQL/MariaDB)
- **Descripción**: Este es el ambiente de producción REAL que usa el cliente diariamente. Corre en local porque a veces no tienen conexión a internet y no puede afectar la operación. Es la fuente de verdad del sistema.
- **Usuarios**: Cliente y usuarios finales

### 4. Producción Web (Respaldo - Esclavo)
- **Ubicación**: Servidor AWS
- **Rama Git**: `master` (misma que Prod Local)
- **Rol**: Ambiente esclavo/respaldo en la nube
- **Base de datos**: Base de datos en AWS (RDS o similar)
- **Descripción**: Réplica de Prod Local para tener la información en la nube. Recibe todos los datos que se generan en Prod Local.
- **Propósito**: Respaldo, acceso remoto cuando sea necesario, y disponibilidad en la nube

---

## 🔄 Flujo de Desarrollo y Deployment

```
Desarrollo (dev) 
    ↓
QA (release/x.x.x)
    ↓
Prod Local (master) ⭐ PRINCIPAL
    ↓
Prod Web (master) - Sincronización automática/manual
```

**⚠️ IMPORTANTE**: 
- **Prod Local** es la producción REAL - lo que usa el cliente
- **Prod Web** es solo un espejo/respaldo de Prod Local
- Todos los cambios deben validarse en QA antes de ir a producción

---

## 📦 Requisitos

* PHP >= 7.3
* Composer
* MySQL/MariaDB
* Node.js & NPM
* Servidor web (Nginx/Apache)
* Git

---

## 🚀 PROCESO DE DEPLOYMENT - PRODUCCIÓN LOCAL (PRINCIPAL)

### ✅ CHECKLIST COMPLETO (Seguir en orden)

**⚠️ CRÍTICO**: Este es el ambiente de PRODUCCIÓN PRINCIPAL que usa el cliente. Seguir este proceso con mucho cuidado.

Usa esta lista cada vez que vayas a bajar cambios a producción local:

#### 1️⃣ Preparación

```bash
# Ir al directorio del proyecto
cd /var/www/masser-drummond

# Hacer backup de la base de datos (IMPORTANTE)
# Manualmente:
mysqldump -u usuario -p nombre_db > backup_$(date +%Y%m%d_%H%M%S).sql
```

#### 2️⃣ Bajar Cambios del Repositorio

```bash
# Ver rama actual
git branch

# Asegurarse de estar en la rama correcta (generalmente master o main)
git checkout master

# Guardar cambios locales si los hay (opcional)
git stash

# Bajar últimos cambios
git pull origin master

# Si hiciste stash, recuperar cambios
# git stash pop
```

#### 3️⃣ Actualizar Dependencias

```bash
# Actualizar dependencias de PHP
composer install --no-dev --optimize-autoloader

# Actualizar dependencias de Node
npm install

# Compilar assets
# npm run production
```

#### 4️⃣ Ejecutar Migraciones

```bash
# Ver migraciones pendientes
php artisan migrate:status

# Ejecutar TODAS las migraciones pendientes
# php artisan migrate --force

# O ejecutar migraciones ESPECÍFICAS (recomendado para control)
# php artisan migrate --path=/database/migrations/2024_12_15_create_nueva_tabla.php --force
```

**⚠️ Migraciones Específicas a Ejecutar:**
```bash
# Actualizar esta lista cuando haya nuevas migraciones importantes
# Ejemplo:
# php artisan migrate --path=/database/migrations/2024_12_15_add_column_to_users.php --force
# php artisan migrate --path=/database/migrations/2024_12_15_create_samples_table.php --force

# AGREGAR AQUÍ LAS MIGRACIONES NUEVAS QUE SE DEBEN EJECUTAR:
# -----------------------------------------------------------
php artisan migrate --path=/database/migrations/2025_12_11_000000_add_new_fields_to_samples_table.php --force
php artisan migrate --path=/database/migrations/2025_12_11_000001_update_view_samples_history_add_new_fields.php --force
php artisan migrate --path=/database/migrations/2025_12_12_110129_add_equipment_location_to_equipments_table.php --force
php artisan migrate --path=/database/migrations/2025_12_19_100000_create_test_import_system_tables.php --force
php artisan migrate --path=/database/migrations/2025_12_21_234548_add_data_field_to_parameter_values_table.php --force
php artisan migrate --path=/database/migrations/2025_12_23_000000_add_is_additional_field_to_test_import_template_fields.php --force
php artisan migrate --path=/database/migrations/2025_12_26_000000_create_laboratory_equipment_details_table.php --force
php artisan migrate --path=/database/migrations/2025_12_19_000000_add_lubricant_refill_fields_to_samples_table.php --force
php artisan migrate --path=/database/migrations/2025_12_19_000001_update_view_samples_history_add_refill_fields.php --force
php artisan migrate --path=/database/migrations/2025_12_11_013402_create_comments_table.php --force
php artisan migrate --path=/database/migrations/2026_01_08_000000_add_serial_component_to_component_equipments_table.php --force
php artisan migrate --path=/database/migrations/2025_12_29_102643_add_default_comments_to_samples_table.php --force
php artisan migrate --path=/database/migrations/2025_12_30_000202_add_serial_component_to_equipments_table.php --force
php artisan migrate --path=/database/migrations/2026_01_08_144911_create_notifications_table.php --force
php artisan migrate --path=/database/migrations/2026_01_14_115501_add_deleted_at_to_samples_table.php --force
php artisan migrate --path=/database/migrations/2026_01_13_034617_add_report_fields_to_users_table.php --force
php artisan migrate --path=/database/migrations/2026_01_19_000001_update_view_samples_history_add_refill_fields.php --force

php artisan migrate --path=/database/migrations/2026_01_15_000001_create_component_location_audit_table.php --force
php artisan migrate --path=/database/migrations/2026_01_16_000001_create_component_equipment_audit_table.php --force
php artisan migrate --path=/database/migrations/2026_02_03_111435_add_goal_data_to_users_table.php --force

php artisan migrate --path=/database/migrations/2026_01_31_000001_create_equipment_account_audit_table.php --force

php artisan migrate --path=/database/migrations/2026_04_09_000001_create_consequences_table.php --force
php artisan migrate --path=/database/migrations/2026_04_10_000001_create_causes_table.php --force
php artisan migrate --path=/database/migrations/2026_02_02_182358_create_configure_reports_table.php --force

php artisan migrate --path=/database/migrations/2026_05_25_000001_add_refrigerant_results_lookup_indexes.php --force

php artisan migrate --path=/database/migrations/2026_05_27_000001_add_system_type_id_to_causes_table.php --force

php artisan migrate --path=/database/migrations/2026_05_28_000001_create_tv_display_settings_table.php --force
php artisan migrate --path=database/migrations/2026_05_28_000002_register_alarm_comments_module.php --force

php artisan migrate --path=database/migrations/2026_06_02_000001_create_trend_detection_settings_table.php --force
php artisan migrate --path=database/migrations/2026_06_02_000002_extend_notifications_for_trend_grouping.php --force
php artisan migrate --path=database/migrations/2026_06_02_000003_register_trend_detection_settings_module.php --force

php artisan migrate --path=database/migrations/2026_06_25_000001_add_cause_to_causes_table.php --force
php artisan migrate --path=database/migrations/2026_06_25_000002_add_multi_select_columns_to_causes_table.php --force

```

#### 5️⃣ Ejecutar Seeders

```bash
# Ver lista de seeders disponibles (revisar en database/seeds/)
ls -la database/seeds/

# IMPORTANTE: Si los seeders no se detectan, ejecutar primero estos comandos
composer dump-autoload
php artisan optimize:clear

# Ejecutar seeders ESPECÍFICOS
# php artisan db:seed --class=RolesSeeder
# php artisan db:seed --class=PermitsSeeder
# php artisan db:seed --class=UsersSeeder

# AGREGAR AQUÍ LOS SEEDERS QUE SE DEBEN EJECUTAR:
# ------------------------------------------------
php artisan db:seed --class=ActionsSeeder
php artisan db:seed --class=EquipmentLocationSeeder
php artisan db:seed --class=TestTemplatesModuleSeeder
php artisan db:seed --class=MigrateLaboratoryEquipmentDetailsSeeder
php artisan db:seed --class=RefrigerantsModuleSeeder
php artisan db:seed --class=UpdateProductTypeReferencesSeeder
php artisan db:seed --class=UpdateViscosityTestValuesSeeder
php artisan db:seed --class=RefrigerantTestValuesSeeder
```

**⚠️ NOTAS IMPORTANTES**: 
- Nunca ejecutar `php artisan db:seed` sin --class a menos que sepas que todos los seeders son seguros para producción
- Si al ejecutar un seeder obtienes error "Class not found" o "Target class does not exist", ejecuta:
  ```bash
  composer dump-autoload
  php artisan optimize:clear
  ```
  Y luego intenta ejecutar el seeder nuevamente

#### 6️⃣ Limpiar y Optimizar Caché

```bash
# Limpiar cachés
php artisan config:clear
php artisan cache:clear
php artisan route:clear
php artisan view:clear

# Regenerar cachés optimizados
php artisan config:cache
php artisan route:cache
php artisan view:cache

# Limpiar y regenerar autoload de Composer
composer dump-autoload -o
```

#### 7️⃣ Verificar Permisos

```bash
# Asegurar permisos correctos en storage y bootstrap/cache
sudo chown -R www-data:www-data storage bootstrap/cache
sudo chmod -R 775 storage bootstrap/cache
```

#### 8️⃣ Reiniciar Servicios

```bash
# Reiniciar PHP-FPM (ajustar versión según tu instalación)
sudo systemctl restart php7.4-fpm
# O
# sudo systemctl restart php8.0-fpm

# Reiniciar servidor web
sudo systemctl restart nginx
# O
# sudo systemctl restart apache2

# Si usas supervisor para queues
# sudo supervisorctl restart all
```

#### 9️⃣ Verificación

```bash
# Ver logs en tiempo real
tail -f storage/logs/laravel.log

# Verificar estado de la aplicación
# php artisan about

# Probar conexión a base de datos
php artisan tinker
>>> DB::connection()->getPdo();
>>> exit
```

---

## 🌐 PROCESO DE DEPLOYMENT - PRODUCCIÓN WEB (AWS - Esclavo)

### ✅ CHECKLIST PARA PROD WEB

**⚠️ IMPORTANTE**: Este ambiente es un ESCLAVO/RESPALDO de Prod Local. Solo se actualiza después de que los cambios estén funcionando correctamente en Prod Local.

#### 1️⃣ Conectarse al Servidor AWS

```bash
# SSH al servidor AWS (ajustar según tu configuración)
ssh -i /path/to/key.pem ubuntu@tu-servidor-aws.com
# O
ssh usuario@ip-del-servidor

# Ir al directorio del proyecto
cd /path/to/project
```

#### 2️⃣ Seguir Mismos Pasos que Prod Local

Repetir pasos del 1 al 9 de "PROCESO DE DEPLOYMENT - PRODUCCIÓN LOCAL (PRINCIPAL)"

**⚠️ CRÍTICO**: 
- **SOLO DESPLEGAR** después de que todo esté funcionando en Prod Local
- Asegurarse de hacer backup de la BD antes de cualquier cambio
- Verificar que las variables de entorno (.env) sean correctas para AWS:
  - DB_HOST (probablemente RDS endpoint)
  - APP_URL (dominio web)
  - Credenciales de S3 u otros servicios de AWS si aplica
- Los datos se sincronizan desde Prod Local → Prod Web (no al revés)

---

## 📋 COMANDOS ADICIONALES ÚTILES

### Queue/Jobs

```bash
# Si usas colas, reiniciar workers
php artisan queue:restart

# Ver trabajos fallidos
php artisan queue:failed

# Reintentar trabajos fallidos
php artisan queue:retry all
```

### Mantenimiento

```bash
# Poner aplicación en modo mantenimiento
php artisan down --message="Actualizando sistema" --retry=60

# Quitar modo mantenimiento
php artisan up
```

### Testing (antes de deployment)

```bash
# Ejecutar tests
php artisan test
# O
./vendor/bin/phpunit
```

### Logs

```bash
# Ver últimos errores
tail -100 storage/logs/laravel.log

# Buscar errores específicos
grep "ERROR" storage/logs/laravel.log

# Limpiar logs antiguos (con cuidado)
# echo "" > storage/logs/laravel.log
```

---

## ⚙️ Variables de Entorno Críticas

Verificar que estas variables estén correctamente configuradas en `.env`:

```env
# APP_ENV=production
# APP_DEBUG=false
# APP_URL=https://tu-dominio.com

# DB_CONNECTION=mysql
# DB_HOST=127.0.0.1
# DB_PORT=3306
# DB_DATABASE=nombre_base_datos
# DB_USERNAME=usuario
# DB_PASSWORD=contraseña_segura
```

---

## 🧯 Troubleshooting

### Error: "Class not found"
```bash
composer dump-autoload -o
php artisan config:clear
```

### Error: "Permission denied"
```bash
sudo chown -R www-data:www-data storage bootstrap/cache
sudo chmod -R 775 storage bootstrap/cache
```

### Error: "SQLSTATE connection refused"
```bash
# Verificar que MySQL esté corriendo
sudo systemctl status mysql

# Verificar credenciales en .env
cat .env | grep DB_
```

### La aplicación muestra errores 500
```bash
# Activar modo debug temporalmente para ver el error
# En .env cambiar APP_DEBUG=true (NO dejar en producción)
# Ver logs
tail -f storage/logs/laravel.log
```

### Assets no se actualizan
```bash
npm run production
php artisan view:clear
# Limpiar caché del navegador (Ctrl+Shift+R)
```

---

## 📄 Notas Importantes

### ⚠️ Recordatorios Críticos

* **SIEMPRE** hacer backup de la base de datos antes de ejecutar migraciones
* **NUNCA** ejecutar `php artisan migrate:fresh` o `migrate:refresh` en producción
* **Prod Local es PRODUCCIÓN PRINCIPAL** - el cliente trabaja ahí diariamente
* **Flujo obligatorio**: Desarrollo → QA → Prod Local → Prod Web
* **NO SALTAR** el ambiente de QA - es la última validación antes de producción
* **Prod Web** se actualiza DESPUÉS de Prod Local, no antes
* **MANTENER** este documento actualizado con nuevas migraciones y seeders específicos
* **DOCUMENTAR** cada deployment en la sección de registro
* **VERIFICAR** que todo funcione correctamente después de cada deployment
* **Comunicar** al cliente antes de hacer deployments en Prod Local (horarios de baja actividad)

### 🔄 Sincronización Prod Local ↔ Prod Web

* Los datos se replican desde Prod Local (maestro) → Prod Web (esclavo)
* Verificar que el proceso de sincronización de datos esté funcionando
* Si hay scripts de sincronización, ejecutarlos después del deployment en Prod Local

---

## 🔗 Enlaces Útiles

* Documentación Laravel: https://laravel.com/docs
* Logs del servidor: `storage/logs/laravel.log`
* Logs de base de datos: `storage/logs/query.log` (si está habilitado)