=====================================================
COMANDOS PARA RETIROS VENCIDOS - DESCUENTO DE STOCK
=====================================================

Fecha de creación: 17 de Enero 2026
Actualización: 17 de Enero 2026 - Agregado soporte para diferentes STATUS
Archivo: ImportRetiroProductosVencidos.php

=====================================================
DESCRIPCIÓN DEL COMANDO
=====================================================

Este comando procesa productos de retiros con diferentes status (NOTIFICADO,
PENDIENTE, SIN RETIRAR, etc.) que tengan más de 10 días hábiles vencidos
(excluyendo domingos) y descuenta las cantidades del stock en wp_postmeta
(_stock_retiro_tienda).

- Maneja KITS descomponiéndolos en productos simples
- Calcula productos simples que aparecen en kits
- Consolida cantidades por producto_id
- Protege contra stock negativo (mínimo 0)
- Actualiza wp_postmeta con meta_key '_stock_retiro_tienda'
- ✨ NUEVO: Permite especificar status personalizados

=====================================================
COMANDOS DISPONIBLES
=====================================================

1. ANÁLISIS PRODUCTOS NOTIFICADOS/PENDIENTES (DEFAULT):
   php artisan retiros:import-vencidos --dry-run

2. ANÁLISIS PRODUCTOS SIN RETIRAR:
   php artisan retiros:import-vencidos --dry-run --status="SIN RETIRAR"

3. ANÁLISIS MÚLTIPLES STATUS:
   php artisan retiros:import-vencidos --dry-run --status="NOTIFICADO,PENDIENTE,SIN RETIRAR"

4. EJECUCIÓN REAL - PRODUCTOS SIN RETIRAR:
   php artisan retiros:import-vencidos --update-stock --status="SIN RETIRAR"

5. EJECUCIÓN REAL - SOLO NOTIFICADOS:
   php artisan retiros:import-vencidos --update-stock --status="NOTIFICADO"

6. EXPORTAR CSV - PRODUCTOS SIN RETIRAR:
   php artisan retiros:import-vencidos --export-csv --status="SIN RETIRAR"

7. COMBINADO - ACTUALIZAR Y EXPORTAR SIN RETIRAR:
   php artisan retiros:import-vencidos --update-stock --export-csv --status="SIN RETIRAR"

8. VER AYUDA:
   php artisan retiros:import-vencidos --help

=====================================================
EJEMPLOS DE EJECUCIÓN POR CASO DE USO
=====================================================

CASO 1: PRODUCTOS NOTIFICADOS/PENDIENTES (Original)
Paso 1: php artisan retiros:import-vencidos --dry-run
Paso 2: php artisan retiros:import-vencidos --update-stock

CASO 2: PRODUCTOS SIN RETIRAR (Nuevo)
Paso 1: php artisan retiros:import-vencidos --dry-run --status="SIN RETIRAR"
Paso 2: php artisan retiros:import-vencidos --update-stock --status="SIN RETIRAR"

CASO 3: TODOS LOS STATUS PROBLEMÁTICOS
Paso 1: php artisan retiros:import-vencidos --dry-run --status="NOTIFICADO,PENDIENTE,SIN RETIRAR"
Paso 2: php artisan retiros:import-vencidos --update-stock --status="NOTIFICADO,PENDIENTE,SIN RETIRAR"
1. BÚSQUEDA DE RETIROS:
   - Status: NOTIFICADO o PENDIENTE
   - Fecha: > 10 días hábiles (sin domingos)
   - Tablas: fs_retiros + fs_retiro_productos

2. PROCESAMIENTO DE KITS:
   - Si producto es KIT: Descompone usando fs_productos_inteligentes
   - Si producto simple: Busca en qué kits aparece
   - Multiplica cantidades según composición

3. ACTUALIZACIÓN DE STOCK:
   - Tabla: wp_postmeta
   - Campo: meta_key = '_stock_retiro_tienda'
   - Operación: stock_actual - cantidad_a_descontar
   - Protección: max(0, resultado_final)

=====================================================
RESULTADOS ÚLTIMA EJECUCIÓN (17 ENE 2026)
=====================================================

- 59 retiros vencidos encontrados
- 68 productos originales procesados
- 85 productos únicos para actualizar stock
- 85 productos actualizados exitosamente
- 0 errores durante la actualización
- 1 producto nuevo creado (ID: 4770)

Productos destacados actualizados:
- Producto 7086: 3 → 0 (-9 unidades)
- Producto 5051: 1 → 0 (-3 unidades)
- Producto 8801: 1 → 0 (-1 unidad)

Total valor procesado: $482.133

=====================================================
ARCHIVOS RELACIONADOS
=====================================================

- Comando: app/Console/Commands/ImportRetiroProductosVencidos.php
- Modelos: fs_retiros, fs_retiro_productos, fs_productos_inteligentes
- BD: wp_postmeta (meta_key: '_stock_retiro_tienda')

=====================================================
NOTAS IMPORTANTES
=====================================================

⚠️ SIEMPRE ejecutar --dry-run primero para revisar los cambios
✅ El comando protege contra stock negativo automáticamente
📊 Usar --export-csv para guardar registro de los cambios
🔄 El comando puede ejecutarse múltiples veces de forma segura
📅 Los días hábiles NO incluyen domingos (sí incluyen sábados)

=====================================================
SOPORTE Y MANTENIMIENTO
=====================================================

- El comando incluye logging detallado
- Muestra resumen de actualización por status
- Maneja errores de forma segura
- Compatible con future ejecuciones

Para modificaciones futuras, revisar los métodos:
- procesarProductoParaDescuentoStock()
- consolidarProductosParaStock()
- actualizarStock()

=====================================================