Primera version estable de microservicios

docs/AUTOMATIC_SERVICES_FLOW.md

@@ -0,0 +1,203 @@
+# Flujo Automático de Servicios de Pedimentos
+
+## Descripción General
+
+Después de completar exitosamente el procesamiento de un **pedimento completo**, el sistema ahora ejecuta automáticamente los siguientes servicios en segundo plano:
+
+1. **Partidas** (si el pedimento tiene partidas)
+2. **Remesas** (si el pedimento tiene remesas)
+3. **Acuses** (si existen documentos digitalizados)
+
+## Flujo de Ejecución
+
+### 1. Ejecución del Pedimento Completo
+```
+POST /services/pedimento_completo
+```
+
+El endpoint procesa el pedimento completo y al finalizar exitosamente:
+- ✅ Crea servicios adicionales automáticamente
+- ✅ Programa la ejecución automática de servicios de seguimiento
+- ✅ Retorna respuesta inmediata al cliente
+
+### 2. Ejecución Automática en Segundo Plano
+
+El sistema ejecuta automáticamente los siguientes servicios:
+
+#### Partidas
+- **Condición**: `numero_partidas > 0`
+- **Servicio**: `POST /services/partidas`
+- **Tipo**: 4
+
+#### Remesas  
+- **Condición**: `remesas = 1` en el XML del pedimento
+- **Servicio**: `POST /services/remesas`
+- **Tipo**: 5
+
+#### Acuses
+- **Condición**: Siempre se ejecuta (procesará solo si hay documentos digitalizados)
+- **Servicio**: `POST /services/acuse`
+- **Tipo**: 6
+
+## Características del Sistema Automático
+
+### ⏱️ Timing y Secuencia
+- **Espera inicial**: 5 segundos después de completar el pedimento completo
+- **Verificación de servicios**: Espera hasta 30 segundos a que se creen los servicios
+- **Intervalo entre servicios**: 3 segundos entre cada ejecución
+- **Ejecución secuencial**: Los servicios se ejecutan uno tras otro, no en paralelo
+
+### 🔄 Sistema de Reintentos
+- **Reintentos automáticos**: Hasta 2 reintentos por servicio
+- **Backoff exponencial**: Tiempo de espera incrementa exponencialmente (2, 4, 8... segundos, máximo 30)
+- **Tolerancia a fallos**: Si un servicio falla, continúa con los siguientes
+
+### 📊 Logging y Monitoreo
+- **Logging detallado**: Cada paso del proceso se registra con emojis para fácil identificación
+- **Resumen de ejecución**: Al final se muestra un resumen con éxitos/fallos
+- **Callback de finalización**: Notificación cuando termine todo el proceso
+
+## Respuesta del Endpoint
+
+El endpoint `/services/pedimento_completo` ahora retorna información adicional:
+
+```json
+{
+  "success": true,
+  "message": "Pedimento completo procesado exitosamente. Servicios automáticos programados.",
+  "data": {
+    "organizacion": "uuid-organizacion",
+    "servicio": 123,
+    "estado": 3,
+    "pedimento_id": "uuid-pedimento",
+    "documento": { ... },
+    "xml_content": { ... },
+    "edocuments": [ ... ],
+    "servicios_adicionales": {
+      "servicio_partidas": 124,
+      "servicio_acuse": 125,
+      "servicio_estado_pedimento": 126,
+      "servicio_edocument": 127,
+      "servicio_remesas": 128  // Solo si aplica
+    },
+    "servicios_automaticos": {
+      "programados": true,
+      "remesas_programadas": true,
+      "partidas_programadas": true,
+      "acuses_programados": true,
+      "mensaje": "Los servicios de partidas, remesas y acuses se ejecutarán automáticamente en segundo plano"
+    }
+  }
+}
+```
+
+## Consulta de Estado
+
+Para verificar el progreso de los servicios automáticos:
+
+```
+GET /services/status/{pedimento_id}?organizacion={organizacion_id}
+```
+
+### Respuesta de Estado
+```json
+{
+  "success": true,
+  "pedimento_id": "uuid-pedimento",
+  "organizacion": "uuid-organizacion",
+  "summary": {
+    "total_services": 6,
+    "completed_services": 4,
+    "in_progress_services": 1,
+    "error_services": 1,
+    "completion_percentage": 66.7
+  },
+  "services": {
+    "pedimento_completo": {
+      "exists": true,
+      "service_id": 123,
+      "estado": 3,
+      "estado_nombre": "FINALIZADO"
+    },
+    "partidas": {
+      "exists": true,
+      "service_id": 124,
+      "estado": 3,
+      "estado_nombre": "FINALIZADO"
+    },
+    "remesas": {
+      "exists": true,
+      "service_id": 128,
+      "estado": 2,
+      "estado_nombre": "EN_PROCESO"
+    },
+    "acuse": {
+      "exists": true,
+      "service_id": 125,
+      "estado": 4,
+      "estado_nombre": "ERROR"
+    }
+  }
+}
+```
+
+## Estados de Servicio
+
+| Estado | Código | Descripción |
+|--------|--------|-------------|
+| CREADO | 1 | Servicio creado, esperando ejecución |
+| EN_PROCESO | 2 | Servicio ejecutándose actualmente |
+| FINALIZADO | 3 | Servicio completado exitosamente |
+| ERROR | 4 | Servicio falló después de reintentos |
+
+## Logs de Ejemplo
+
+```
+2024-07-10 12:00:15 INFO - Pedimento completo procesado exitosamente - Servicio: 123
+2024-07-10 12:00:16 INFO - Programando servicios automáticos - Remesas: True, Partidas: True
+2024-07-10 12:00:16 INFO - Servicios automáticos programados exitosamente para pedimento uuid-pedimento
+2024-07-10 12:00:21 INFO - Esperando a que se completen las creaciones de servicios...
+2024-07-10 12:00:26 INFO - 🔄 Iniciando procesamiento de partidas...
+2024-07-10 12:00:26 INFO - Servicio tipo 4 encontrado para pedimento uuid-pedimento
+2024-07-10 12:00:45 INFO - ✅ Servicio partidas completado exitosamente
+2024-07-10 12:00:48 INFO - 🔄 Iniciando procesamiento de remesas...
+2024-07-10 12:01:05 INFO - ✅ Servicio remesas completado exitosamente
+2024-07-10 12:01:08 INFO - 🔄 Iniciando procesamiento de acuse...
+2024-07-10 12:01:25 INFO - ✅ Servicio acuse completado exitosamente
+2024-07-10 12:01:25 INFO - 🎉 Ejecución automática completada exitosamente - 3/3 (100%)
+2024-07-10 12:01:25 INFO - Servicios automáticos completados para pedimento uuid-pedimento: 3/3 exitosos
+```
+
+## Beneficios
+
+### ✨ Para el Usuario
+- **Respuesta inmediata**: No espera a que se completen todos los servicios
+- **Procesamiento automático**: No necesita ejecutar manualmente cada servicio
+- **Tolerancia a fallos**: Los errores en servicios individuales no afectan el flujo completo
+
+### 🔧 Para el Sistema
+- **Desacoplamiento**: El pedimento completo no depende de los servicios secundarios
+- **Escalabilidad**: Procesamiento en segundo plano no bloquea recursos
+- **Monitoreo**: Logging detallado para debugging y análisis
+
+### 📈 Para el Negocio
+- **Eficiencia**: Automatización reduce tiempo de procesamiento manual
+- **Confiabilidad**: Sistema de reintentos asegura máxima tasa de éxito
+- **Visibilidad**: Estado en tiempo real de todos los servicios
+
+## Consideraciones Técnicas
+
+### Memoria y Recursos
+- Las tareas en segundo plano se ejecutan en el mismo proceso
+- Uso mínimo de memoria adicional
+- Timeout automático para evitar tareas colgadas
+
+### Manejo de Errores
+- Errores en servicios automáticos no afectan la respuesta del pedimento completo
+- Logs detallados para debugging
+- Reintentos automáticos con backoff exponencial
+
+### Concurrencia
+- Ejecución secuencial evita sobrecarga del sistema VUCEM
+- Intervalos de espera configurables
+- Control de recursos mediante timeouts

docs/REFACTORING_SUMMARY.md

@@ -0,0 +1,148 @@
+## Resumen de Refactorización - Endpoints de Pedimentos
+
+### Endpoints Refactorizados (marcados como #Testeado)
+
+Los siguientes endpoints han sido completamente refactorizados aplicando buenas prácticas:
+
+#### 1. `/services/pedimento_completo` ⚡ **CON EJECUCIÓN AUTOMÁTICA**
+- **Mejoras implementadas:**
+  - Validación robusta de datos de entrada
+  - Manejo de errores específico por operación
+  - Logging detallado con contexto de operación
+  - Actualización de estados de servicio más robusta
+  - Procesamiento mejorado de documentos digitalizados
+  - Creación automática de servicios adicionales con validación
+  - Respuestas estandarizadas con información detallada
+  - Manejo de warnings para errores no críticos
+  - **🆕 EJECUCIÓN AUTOMÁTICA**: Dispara automáticamente partidas, remesas y acuses en segundo plano
+  - **🆕 SISTEMA DE REINTENTOS**: Reintentos automáticos con backoff exponencial
+  - **🆕 TOLERANCIA A FALLOS**: Continúa procesamiento aunque fallen servicios individuales
+
+#### 2. `/services/partidas`
+- **Mejoras implementadas:**
+  - Procesamiento individual de cada partida con manejo de errores
+  - Validación de número de partidas antes del procesamiento
+  - Continuidad del proceso aunque fallen partidas individuales
+  - Reporte detallado de partidas exitosas vs fallidas
+  - Logging específico para cada partida procesada
+
+#### 3. `/services/remesas`
+- **Mejoras implementadas:**
+  - Simplificación del flujo de procesamiento
+  - Validación mejorada de credenciales y contribuyente
+  - Manejo de errores más específico
+  - Respuesta estandarizada con información del documento generado
+
+#### 4. `/services/acuse`
+- **Mejoras implementadas:**
+  - Procesamiento individual de cada documento digitalizado
+  - Validación de documentos antes del procesamiento SOAP
+  - Manejo robusto de documentos sin número de e-document
+  - Continuidad del proceso aunque fallen documentos individuales
+  - Extracción y guardado de PDFs con validación de contenido
+  - Reporte detallado de documentos exitosos vs fallidos
+
+### Funciones Auxiliares Agregadas
+
+#### 1. `_validate_request_data()`
+- Validación centralizada de datos de entrada
+- Logging detallado de validaciones
+- Mensajes de error específicos
+
+#### 2. `_get_pedimento_service()`
+- Obtención robusta de servicios con manejo de errores
+- Validación de existencia de servicios
+- Logging específico por tipo de operación
+
+#### 3. `_get_vucem_credentials()`
+- Obtención segura de credenciales VUCEM
+- Validación de existencia de credenciales
+- Manejo de errores específico para credenciales
+
+#### 4. `_update_service_status()` (mejorada)
+- Actualización robusta de estados con nombres descriptivos
+- Retorno de éxito/fallo para validación
+- Logging detallado del proceso de actualización
+- Manejo de errores mejorado
+
+#### 5. `_create_response()`
+- Generación de respuestas estandarizadas
+- Estructura consistente en todas las respuestas
+- Información detallada del servicio y estado
+
+#### 6. `_log_operation_summary()`
+- Logging de resumen para cada operación
+- Información consolidada de éxito/fallo
+- Contexto adicional opcional
+
+#### 7. `_validate_soap_controller()`
+- Validación de disponibilidad del controlador SOAP
+- Prevención de errores por controlador no disponible
+
+### Buenas Prácticas Implementadas
+
+#### 1. **Manejo de Errores**
+- Try-catch específicos por tipo de operación
+- Propagación controlada de HTTPExceptions
+- Logging detallado de errores con traceback
+- Actualización automática de estados en caso de error
+- Diferenciación entre errores críticos y warnings
+
+#### 2. **Logging Consistente**
+- Logging estructurado con contexto de operación
+- Niveles apropiados (INFO, WARNING, ERROR)
+- Información de progreso durante procesamiento
+- Resúmenes de operación al final
+
+#### 3. **Validación Robusta**
+- Validación temprana de datos de entrada
+- Verificación de existencia de recursos
+- Validación de estados antes de continuar
+- Manejo de casos edge (documentos sin número, etc.)
+
+#### 4. **Respuestas Estandarizadas**
+- Estructura consistente en todas las respuestas
+- Información detallada de éxito/fallo
+- Warnings para errores no críticos
+- Metadata útil (contadores, IDs, etc.)
+
+#### 5. **Manejo de Estados**
+- Transiciones de estado explícitas y validadas
+- Rollback automático en caso de error
+- Logging de cambios de estado
+- Validación de actualizaciones exitosas
+
+#### 6. **Documentación Mejorada**
+- Docstrings detallados para cada endpoint
+- Descripción de flujo de procesamiento
+- Especificación de parámetros y respuestas
+- Documentación de excepciones posibles
+
+#### 7. **Typing y Tipado**
+- Uso de Optional y typing hints
+- Especificación de tipos de retorno
+- Mejor IntelliSense y detección de errores
+
+### Beneficios Obtenidos
+
+1. **Mantenibilidad**: Código más limpio y organizado
+2. **Debugging**: Logging detallado facilita la identificación de problemas
+3. **Robustez**: Mejor manejo de casos edge y errores
+4. **Consistencia**: Estructura uniforme en todos los endpoints
+5. **Monitoreo**: Información detallada para monitoring y alertas
+6. **Escalabilidad**: Funciones auxiliares reutilizables
+7. **Testing**: Estructura más amigable para pruebas unitarias
+
+### Archivos Modificados
+
+- `/api/api_v1/endpoints/pedimentos.py` - Refactorización completa
+- Imports mejorados con tipado
+
+### Próximos Pasos Recomendados
+
+1. **Testing**: Implementar pruebas unitarias para las nuevas funciones
+2. **Monitoring**: Agregar métricas de performance y contadores
+3. **Configuración**: Externalizar timeouts y límites a configuración
+4. **Cache**: Implementar cache para credenciales VUCEM
+5. **Rate Limiting**: Agregar límites de velocidad para peticiones SOAP
+6. **Retry Logic**: Implementar reintentos automáticos para peticiones fallidas

docs/routing_options.md

@@ -0,0 +1,4 @@
+# Alternativa: Si quieres cambiar el prefijo, puedes usar:
+# application.include_router(api_router, prefix="")  # Sin prefijo
+# o
+# application.include_router(api_router)  # También sin prefijo