================================================================================
                    DOCUMENTACIÓN: SISTEMA DE ENVÍO DE CORREOS A GMAIL
                              Hogar de los Abuelos - Sistema Web
================================================================================

📧 RESUMEN GENERAL
==================
El sistema utiliza un mecanismo personalizado para enviar notificaciones por correo 
electrónico a Gmail cuando se registra la ubicación de un adulto mayor. El sistema 
está configurado para enviar correos automáticos con información de geolocalización.

📁 ARCHIVOS PRINCIPALES
=======================

1. 📄 ubicacion_abuelos/email_config.php
   - Configuración principal del sistema de correos
   - Define credenciales de Gmail
   - Contiene la función enviarCorreoUbicacion()
   - Genera el contenido HTML del correo

2. 📄 ubicacion_abuelos/PHPMailer.php
   - Implementación personalizada de envío SMTP
   - Maneja la conexión con Gmail usando fsockopen
   - Implementa protocolo SMTP con TLS/SSL

3. 📄 ubicacion_abuelos/ubicar_abuelos.php
   - Página que recibe el QR escaneado
   - Registra la ubicación del adulto mayor
   - Ejecuta el envío del correo automáticamente

4. 📄 ubicacion_abuelos/registro_ubicacion.php
   - Procesa el registro de ubicación
   - También ejecuta envío de correo

⚙️ CONFIGURACIÓN ACTUAL
========================

🔐 Credenciales Gmail:
- Servidor SMTP: smtp.gmail.com
- Puerto: 587 (STARTTLS)
- Usuario: phpasa4@gmail.com
- Contraseña de aplicación: mhle vupb vndn phmr
- Nombre remitente: "Hogar de los Abuelos"

📧 Destinatario fijo:
- Correo destino: adultomayor@sibate-cundinamarca.gov.co

🔄 FLUJO DE FUNCIONAMIENTO
==========================

1. 📱 ESCANEO QR
   - Usuario escanea código QR del adulto mayor
   - Se abre ubicar_abuelos.php con parámetro ?cedula=XXXXXX

2. 🌍 CAPTURA UBICACIÓN
   - JavaScript obtiene geolocalización del navegador
   - Se capturan coordenadas GPS (latitud, longitud)

3. 💾 REGISTRO EN BASE DE DATOS
   - Se guarda la ubicación en tabla 'ubicaciones'
   - Se registra fecha, hora, coordenadas y datos del adulto mayor

4. 📧 ENVÍO AUTOMÁTICO DE CORREO
   - Se ejecuta enviarCorreoUbicacion()
   - Se genera correo HTML con información completa
   - Se envía a adultomayor@sibate-cundinamarca.gov.co

📋 CONTENIDO DEL CORREO
=======================

🎨 Formato HTML:
- Diseño profesional con colores institucionales
- Header con logo y título
- Información del adulto mayor
- Coordenadas GPS exactas
- Enlace directo a Google Maps
- Fecha y hora del registro

📍 Información incluida:
- Nombre completo del adulto mayor
- Fecha y hora exacta del registro
- Coordenadas GPS (latitud y longitud)
- Enlace directo a Google Maps
- Diseño responsive para móviles

🔧 IMPLEMENTACIÓN TÉCNICA
=========================

📡 Protocolo SMTP:
1. Conexión a smtp.gmail.com:587
2. Comando EHLO para identificación
3. STARTTLS para encriptación
4. Autenticación con credenciales
5. Envío del mensaje RFC 2822
6. Cierre de conexión

🔒 Seguridad:
- Uso de contraseña de aplicación de Gmail
- Conexión TLS/SSL obligatoria
- Validación de formato de email
- Codificación UTF-8 para caracteres especiales

⚡ Características técnicas:
- Timeout de 30 segundos para conexión
- Manejo de errores con logs
- Soporte para HTML y texto plano
- Codificación base64 para autenticación

🛠️ CONFIGURACIÓN GMAIL
=======================

Para que funcione correctamente, la cuenta Gmail debe tener:

1. ✅ Verificación en 2 pasos activada
2. ✅ Contraseña de aplicación generada
3. ✅ Acceso de aplicaciones menos seguras (si es necesario)

📝 Pasos para generar contraseña de aplicación:
1. Ir a Configuración de Google Account
2. Seguridad → Verificación en 2 pasos
3. Contraseñas de aplicaciones
4. Generar nueva contraseña para "Correo"
5. Usar la contraseña de 16 caracteres generada

🔍 DEBUGGING Y LOGS
===================

📊 Logs del sistema:
- Los errores se registran con error_log()
- Se pueden revisar en logs del servidor web
- Códigos de respuesta SMTP se validan

🐛 Problemas comunes:
- Error 535: Credenciales incorrectas
- Error 550: Destinatario rechazado
- Timeout: Problemas de conectividad
- TLS Error: Problemas de certificados

📈 MONITOREO
============

✅ Indicadores de éxito:
- Correo aparece en bandeja de entrada
- No hay errores en logs del servidor
- Función retorna true

❌ Indicadores de fallo:
- Función retorna false
- Errores en error_log
- Correo no llega al destinatario

🔄 MANTENIMIENTO
================

🔧 Tareas regulares:
- Verificar validez de contraseña de aplicación
- Monitorear logs de errores
- Comprobar entrega de correos
- Actualizar credenciales si es necesario

⚠️ Consideraciones importantes:
- Gmail tiene límites de envío diario
- Las contraseñas de aplicación pueden expirar
- Cambios en políticas de Gmail pueden afectar funcionamiento

📞 CONTACTO TÉCNICO
===================

Para soporte técnico del sistema de correos:
- Revisar logs en: /var/log/apache2/error.log (Linux) o Event Viewer (Windows)
- Verificar conectividad SMTP: telnet smtp.gmail.com 587
- Probar credenciales manualmente

================================================================================
                              FIN DE DOCUMENTACIÓN
                    Última actualización: Octubre 2025
================================================================================
