# Microsoft Graph Sync Commands

## Descripción
Comandos de Artisan para gestionar la sincronización con Microsoft Graph, incluyendo carpetas de contactos y contactos de usuario.

## Comandos Disponibles

### 🚀 **Comando Principal: `msgraph:sync`**
```bash
# Sincronización completa: crear carpetas → sincronizar contactos
lando artisan msgraph:sync

# Con dry-run (simulación)
lando artisan msgraph:sync --dry-run
```

### 🗑️ **Comando de Eliminación: `msgraph:delete-folders`**
```bash
# Eliminar TODAS las carpetas de contactos (DESTRUCTIVO)
lando artisan msgraph:delete-folders --dry-run
lando artisan msgraph:delete-folders --force
```

### � **Comando de Diagnóstico: `msgraph:diagnose`**
```bash
# Analizar discrepancias en la sincronización
lando artisan msgraph:diagnose
lando artisan msgraph:diagnose --detailed
```

## Opciones de `msgraph:sync`

### ⚙️ **Opciones Principales**
- `--all` - Sincronización completa (comportamiento por defecto)
- `--dry-run` - Modo simulación, no hace cambios reales
- `--contact-folders` - Solo crear/actualizar carpetas de contactos
- `--contacts` - Solo sincronizar contactos

### 🧪 **Testing y Diagnóstico**
- `--test-connection` - Probar conexión y permisos de Microsoft Graph
- `--test-contact-folder[=nombre]` - Crear carpeta de prueba (por defecto: "Test-Folder")

### 🧹 **Limpieza**
- `--cleanup-database` - Limpiar todos los `ms_id` de la base de datos
- `--confirm-deletion` - Confirmación requerida para operaciones de eliminación
- `--delete-folders` - Eliminar TODAS las carpetas de contactos
- `--clear-contacts` - Limpiar contactos de carpetas existentes

### 📋 **Listado y Consulta**
- `--list-folders` - Listar todas las carpetas de contactos
- `--list-contacts=FOLDER` - Listar contactos de una carpeta específica
- `--list-all-contacts` - Listar todos los contactos de todas las carpetas
- `--sync-folder-ids` - Sincronizar IDs de carpetas existentes con la base de datos

## Ejemplos de Uso

### Sincronización Completa
```bash
# Sincronización real - crear carpetas de comités/grupos al nivel raíz
lando artisan msgraph:sync

# Simulación
lando artisan msgraph:sync --dry-run
```

### Solo Carpetas
```bash
# Crear solo carpetas de comités/grupos al nivel raíz
lando artisan msgraph:sync --contact-folders --dry-run
```

### Solo Contactos
```bash
# Sincronizar solo contactos en carpetas existentes
lando artisan msgraph:sync --contacts --dry-run
```

### Testing y Diagnóstico
```bash
# Probar conexión
lando artisan msgraph:sync --test-connection

# Crear carpeta de prueba
lando artisan msgraph:sync --test-contact-folder=TestFolder

# Diagnosticar problemas de sincronización
lando artisan msgraph:diagnose --detailed
```

### Operaciones Destructivas
```bash
# Eliminar TODAS las carpetas de contactos (simulación)
lando artisan msgraph:delete-folders --dry-run

# Eliminar TODAS las carpetas de contactos (real - CUIDADO!)
lando artisan msgraph:delete-folders --force

# Limpiar base de datos (simulación)
lando artisan msgraph:sync --cleanup-database --dry-run

# Limpiar base de datos (real)
lando artisan msgraph:sync --cleanup-database --confirm-deletion
```

### Consultar Datos Existentes
```bash
# Listar todas las carpetas de contactos
lando artisan msgraph:sync --list-folders

# Listar contactos de una carpeta específica
lando artisan msgraph:sync --list-contacts="Gas Committee (committee)"
lando artisan msgraph:sync --list-contacts="WG Implementation (workgroup)"

# Listar todos los contactos de todas las carpetas
lando artisan msgraph:sync --list-all-contacts

# Sincronizar IDs de carpetas existentes
lando artisan msgraph:sync --sync-folder-ids
```

## Estructura de Carpetas

### Nueva Estructura (Nivel Raíz)
Las carpetas se crean directamente al nivel raíz con el formato:
- **Comités**: `"Committee Name (committee)"`
- **Grupos de Trabajo**: `"WorkGroup Name (workgroup)"`

Ejemplos:
- `Gas Committee (committee)`
- `Electricity Committee (committee)`
- `WG Implementation (workgroup)`
- `TF Italy Gas (workgroup)`

## Proceso de Sincronización

### Lo que hace `msgraph:sync`:
1. **📁 Paso 1 - Carpetas**: Crea/actualiza carpetas de comités y grupos al nivel raíz
2. **🧹 Paso 2 - Limpieza DB**: Limpia ms_id de elementos no publicados/eliminados
3. **👥 Paso 3 - Contactos**: Sincroniza contactos basándose en la membresía actual

### Resultados mostrados:
- Carpetas eliminadas en paso 1
- Carpetas creadas en paso 2  
- Contactos creados en paso 3
- Errores en cada paso
- Resumen total

## Configuración Requerida

### Variables de Entorno (.env)
```env
MSGRAPH_SERVICE_USER_ID=usuario-servicio@tudominio.com
MSGRAPH_TENANT_ID=tu-tenant-id
MSGRAPH_CLIENT_ID=tu-client-id
MSGRAPH_CLIENT_SECRET=tu-client-secret
```

### Permisos en Azure
- `Contacts.ReadWrite` - Para crear/eliminar carpetas y contactos
- Acceso al usuario de servicio especificado

## Salida del Comando

### Ejemplo de Ejecución Exitosa
```
🚀 Starting Microsoft Graph Clean Slate synchronization...
⚠️  Running in DRY-RUN mode - no changes will be made
🔄 Running CLEAN SLATE synchronization (sync IDs → clear contacts → recreate contacts)...

📊 Clean Slate Synchronization Results:

🔄 Step 1 - Folder ID Synchronization:
+--------+-------+
| Metric | Count |
+--------+-------+
| Committees Synced | 3   |
| Workgroups Synced | 5   |
| Errors | 0     |
+--------+-------+

🧹 Step 2 - Contact Clearing:
+--------+-------+
| Metric | Count |
+--------+-------+
| Folders Cleared | 8   |
| Contacts Cleared | 142 |
| Errors | 0     |
+--------+-------+

📁 Step 3 - Contact Folders:
+--------+-------+
| Metric | Count |
+--------+-------+
| 📁 Created | 8   |
| 📝 Updated | 0   |
| ❌ Errors  | 0   |
+--------+-------+

📧 Step 3 - Contacts Recreation:
+--------+-------+
| Metric | Count |
+--------+-------+
| Created | 142 |
| Errors  | 0   |
+--------+-------+

📈 Clean Slate Summary:
+--------+-------+
| Metric | Total |
+--------+-------+
| Total Deleted (Step 1)    | 5   |
| Total Created (Steps 2+3) | 150 |
| Total Errors              | 0   |
+--------+-------+

✅ Clean Slate synchronization completed in 45.3 seconds
```

### Códigos de Salida
- `0` - Éxito
- `1` - Error durante la ejecución

## Logging

### Archivos de Log
- Los logs se escriben automáticamente a `storage/logs/laravel.log`
- Incluye timestamps, resultados detallados y stack traces de errores

### Ejemplo de Log Entry
```
[2025-06-18 10:30:45] local.INFO: Microsoft Graph Clean Slate sync completed via artisan command
{
    "execution_time": 45.3,
    "results": {
        "folder_sync": {"committees_synced": 3, "workgroups_synced": 5, "errors": 0},
        "contact_clearing": {"folders_cleared": 8, "contacts_cleared": 142, "errors": 0},
        "contact_folders": {"created": 0, "updated": 8, "errors": 0},
        "contacts": {"created": 142, "errors": 0}
    },
    "dry_run": true
}
```

## Troubleshooting

### Errores Comunes

#### "Service User ID not configured"
```bash
# Verificar configuración
lando artisan msgraph:sync --test-connection
```

#### Permisos insuficientes
```bash
# Probar conexión y permisos
lando artisan msgraph:sync --test-connection
```

#### Timeout en grandes volúmenes
- Usar `--dry-run` primero para estimar tiempo
- Ejecutar durante horas de menor uso
- Verificar que no hay restricciones de red

### Comandos de Diagnóstico
```bash
# Test completo de conectividad
lando artisan msgraph:sync --test-connection

# Probar creación de carpeta
lando artisan msgraph:sync --test-contact-folder --dry-run

# Ver qué se va a sincronizar
lando artisan msgraph:sync --dry-run
```

## Diferencias con Comando Anterior

### Opciones Removidas (ya no necesarias en Clean Slate)
- `--sync-folder-ids` - No necesario, siempre se recrean los IDs
- `--list-contacts` - No necesario, se recrean todos desde cero
- `--list-all-folders` - No necesario, se recrean todas desde cero
- `--delete-all-folders` - Integrado en Clean Slate
- `--delete-folders` - No necesario, se eliminan todas
- `--cleanup-orphaned` - No necesario, se limpia todo

### Nuevas Características
- Proceso en 3 pasos claramente definido
- Resultados detallados por paso
- Enfoque más simple y robusto
- Menos opciones confusas

---

*Última actualización: 18 de junio de 2025*