Saltar a contenido

Documentación Técnica - DocuCenter

Índice de Documentación

Sistema de Consolidación Multi-Organización

  • Implementación de Columnas Source 🚀 IMPLEMENTADO - Guía de despliegue completa
  • Solución completa para colisión de PKs: 14 columnas source_* implementadas
  • Comandos Artisan: db:update-stub-source-column genérico
  • Job actualizado: Sincronización en 2 fases con mapeo de IDs
  • Scripts de despliegue: add-source-columns-consolidation.sh
  • UNIQUE constraints: add-unique-constraints-source-columns.sh
  • Guía paso a paso para producción
  • Validaciones post-despliegue y troubleshooting

  • Estado: ✅ Código completo y listo para deploy

  • Análisis Completo de Tablas Detail - Análisis crítico de colisión en tablas Detail con FKs ⭐ MÁS CRÍTICO - NUEVO

  • Revelación: Details TAMBIÉN tienen PKs auto-incrementales que colisionan
  • Problema doble: 8 tablas Detail + 7 tablas Header vulnerables
  • FK Constraints activos en fe_detail/fe_payment
  • FKs rotas: Details apuntan a headers inexistentes
  • Solución completa en 2 FASES obligatorias con mapeo de IDs
  • Código PHP: syncTableWithHeaderDetailRelation() con mapa de IDs
  • Estadísticas críticas: 0% Details protegidos, 100% vulnerables
  • Validaciones SQL post-sincronización

  • Estimado: 10-12 días de desarrollo + testing

  • Análisis de Colisión de PKs Auto-Incrementales - Análisis detallado del problema de colisión de llaves primarias en Headers ⭐ CRÍTICO

  • Identificación precisa del problema con ejemplos reales
  • Escenario de colisión: 2 organizaciones con ID=100
  • Estado actual: 1/7 tablas header implementadas (14%)
  • 6 tablas header vulnerables sin protección contra colisiones
  • Solución propuesta completa con código PHP y SQL
  • Manejo de relaciones Header-Detail con mapeo de FKs
  • Plan de implementación por fases (8-10 días)

  • Riesgos y métricas de éxito

  • Estado de la Documentación de Consolidación - Verificación completa del estado de la documentación vs código implementado ⭐ VERIFICADO

  • Resumen ejecutivo del sistema de consolidación
  • Verificación de implementación vs documentación (96% completo)
  • Identificación de componentes implementados y pendientes
  • Métricas de calidad de documentación

  • Próximos pasos y recomendaciones

  • Estrategia de Consolidación: Tablas Header-Detail - Análisis y estrategia para manejo de tablas con relaciones Header-Detail ⭐ COMPLETO

  • Identificación de 9 pares de tablas Header-Detail con auto-increment
  • Estrategia de mapeo de IDs (source_transaction_id, source_fe_id, etc.)
  • Plan de implementación detallado
  • Test cases específicos y riesgos documentados

  • Métricas de éxito y criterios de aceptación

  • Análisis de Replicación de Bases de Datos - Arquitectura y análisis completo del sistema de consolidación ⭐ COMPLETO

  • Problema a resolver: Limitación de Sage Connector (una BD, un ID_compania)
  • Arquitectura actual vs deseada (multi-organización → compañía consolidada)
  • Opciones de replicación comparadas (MySQL Binlog, Laravel Jobs, etc.)
  • Solución recomendada: Laravel Jobs Asíncronos con Redis
  • Plan de implementación por fases
  • Consideraciones de conflictos de IDs y sincronización bidireccional

Resolución de Problemas Arquitecturales

Livewire UI/UX Improvements

  • Preservación de Datos del Customer al Cambiar Tipo de Receptor - Preservación inteligente de datos en formulario ⭐ NUEVO
  • Problema: Cambiar tipo de receptor borraba completamente datos del customer
  • Solución: Preservación selectiva con limpieza solo de campos incompatibles
  • Auto-re-llenado automático según nuevo tipo de receptor
  • Mejora significativa en experiencia de usuario (80% menos re-trabajo)

Customers Multi-Tenant Navigation

  • Resolución de Dependencia Circular en Customer Property - Corrección de inconsistencia lógica en inicialización de customer ⭐ NUEVO
  • Identificación y análisis de dependencia circular en getCustomerProperty()
  • Implementación de obtención directa desde relaciones de venta
  • Corrección de errores de layout y compilación
  • Testing y validación de arquitectura multi-tenant

PAC Integration Errors

  • Fix: Error "datosFacturaExportacion es requerido" - Corrección de nombre de campo para PAC Alanube ⭐ NUEVO
  • Error: PAC esperaba campo 'datosFacturaExportacion' pero recibía 'exportation'
  • Fix aplicado en AlanubeFormatterHelper para Panamá y República Dominicana
  • Facturas de exportación (tipo 03) ahora procesan correctamente

  • Scripts de testing y verificación incluidos

  • Fix: Requerimiento dPaisExt de TheFactoryHKA - Corrección para campo paisExtranjero requerido por PAC ⭐ NUEVO

  • Error: "El campo paisExtranjero es requerido" en operación interna a cliente extranjero
  • TheFactoryHKA requiere dPaisExt en gIdExt para todos los clientes extranjeros
  • Lógica automática para incluir dPaisExt según tipo de operación y nacionalidad

  • Testing completo con 5/5 casos de uso verificados

  • Fix: Error Validación paisExtranjero en Operación Interna - Corrección para clientes extranjeros en operación interna ⭐ IMPLEMENTADO

  • Resolución de conflicto de validación para operación interna (iDest=1) a cliente extranjero (iTipoRec=4)
  • Validación condicional de paisExtranjero basada en tipo de operación
  • Lógica automática de asignación de receptor_paisNacionalidad para operación interna

  • Cumplimiento de normativas DGI para facturas a clientes extranjeros en territorio panameño

  • Análisis Oficial Validaciones DGI - Análisis de ficha técnica DGI vs error 2152 ⭐ CRÍTICO

  • Error 2152 NO EXISTE en especificación oficial DGI (232 páginas)
  • Código fuera de rangos oficiales DGI (0800-1059)
  • Confirmado: Bug propietario de TheFactoryHKA

  • Nuestro sistema cumple 100% estándares DGI

  • Solución Definitiva PAC Error 2152 - Workaround implementado para bug en servicio externo TheFactoryHKA ⭐ IMPLEMENTADO

  • Problema confirmado en servicio externo: mapeo incorrecto de campos totales
  • Workaround implementado en HKAService líneas 276-295
  • Corrección automática para totalValorRecibido y totalTodosItems

  • Logging detallado de correcciones aplicadas

  • Corrección PAC Campos ISC Condicionales - Implementación de lógica condicional ISC según especificación oficial ⭐ IMPLEMENTADO

  • Corrección de "El campo valorISC es inválido" y "El campo totalISC no debe ser informado"
  • Lógica condicional para tasaISC, valorISC en items solo cuando tasa > 0
  • totalISC en totales solo cuando existe ISC real en items

  • Validación contra especificación oficial TheFactoryHKA

  • Investigación Transformación SOAP PAC 2152 - Investigación del punto exacto de transformación incorrecta ⭐ COMPLETADO

  • Identificación de cadena de transformación Create.php → HKAService → SOAP → XML
  • Logging detallado agregado antes del envío SOAP
  • Análisis de hipótesis: filterNullValues, servicio externo, array conversion

  • Evidencia de mapeo cruzado donde múltiples campos toman valor totalPrecioNeto

  • Resolución Error PAC 2152 - ITBMS Inválido - Corrección en progreso del error "Monto del ITBMS del ítem inválido" ⭐ ARCHIVADO

  • Análisis de inconsistencias en campos totales enviados al PAC
  • Corrección de campo dVTotItems (enviaba total general en lugar de suma de ítems)
  • Implementación de cálculo ITBMS con precisión DGI

  • Logging mejorado para debugging de valores enviados al PAC

  • Análisis Original ITBMS TheFactoryHKA - Documentación del análisis matemático inicial ⭐ COMPLETADO

  • Identificación de inconsistencia entre precio base (5.60), ITBMS (0.39) y total (5.99)
  • Métodos calculateCorrectITBMS() y validateITBMSCoherence() implementados

  • Testing con comando artisan test:itbms-calculation

  • Resolución: Error "Attempt to assign property cufe on array" - Corrección de error de asignación de propiedades en HKAService ⭐ COMPLETADO

  • Análisis de conversión incompleta de array a objeto con (object)$request
  • Implementación de conversión recursiva con json_decode(json_encode())
  • Corrección en HKAService::writeXMLLog() y simplificación en Create.php
  • Validación de transmisión exitosa al PAC

Análisis y Mapeos de Integración

Zoho Books Integration

  • Zoho Purchase Order Mapping Analysis - Análisis completo del mapeo de órdenes de compra desde Zoho Books hacia modelos DocuCenter ⭐ NUEVO
  • Estructura de datos del webhook de Zoho
  • Mapeo hacia PurchaseHeaderImp y PurchaseDetailImp
  • Clases de transformación e importación

  • Scripts de testing y validación

  • Segunda Verificación Custom Fields de Zoho desde API - Implementación de consulta a API de Zoho para obtener cf_sagevendorid y cf_sagecustomerid ⭐ ACTUALIZADO

  • Doble verificación para vendors (cf_sagevendorid) y customers (cf_sagecustomerid)
  • Helper centralizado ZohoCustomFieldsHelper para ambos tipos de campos
  • Consulta directa a contacts API cuando custom_field_hash no incluye campos personalizados
  • Manejo robusto de errores con fallbacks y logging detallado

Sistema de Control de Acceso Organizacional

  1. Control de Acceso para Configuraciones
  2. Sistema de Control de Acceso Organizacional - Arquitectura completa del sistema
  3. Guía de Implementación - Guía práctica paso a paso

  4. Resumen de Implementación - Resumen ejecutivo y estado final

  5. Sistema de Gestión de Planes

  6. Plan Management Complete Guide - Guía completa del sistema de gestión de planes
  7. Routes-as-Permissions Architecture - Arquitectura de rutas como permisos

Integraciones PAC

  1. Eliminación del Campo Virtual pac_type

  2. Resumen de Eliminación pac_type - Eliminación sistemática del campo virtual pac_type

  3. API CheckRUC

  4. Campo Type (Tipo de Contribuyente) - Detección automática de tipo de contribuyente

  5. Digifact Panamá

  6. Guía de Implementación Digifact PAC - Análisis completo y guía de implementación para PAC Digifact ⭐ NUEVO

    • Análisis exhaustivo de API REST v1.0.4
    • Arquitectura de autenticación con JWT (30 días vigencia)
    • Endpoints de certificación y consulta
    • Plan de implementación por fases
    • Integración con arquitectura multi-tenant DocuCenter
    • Scripts de testing y validación

  7. Alanube República Dominicana

  8. Mejoras DOM Consumer Invoice - Enhancements para el consumer DOM

  9. Testing System Summary - Framework de testing para Alanube DOM

  10. Alanube Panamá

  11. Integración Completa Alanube Panamá - Implementación completa del servicio
  12. Guía de Uso del Servicio - Manual de uso del AlanubeService
  13. Guía de Notas de Crédito - Manual completo para notas de crédito

  14. Corrección Mapeo Datos Exportación - Fix para errores PAC en documentos de exportación ⭐ NUEVO

  15. QuickBooks Online

  16. Job Creación de Bills - Sincronización de compras hacia QuickBooks como Bills
  17. Payment Lookup Integration - Funcionalidad de búsqueda de pagos existentes para prevenir duplicados
  18. Payment Methods Integration - Sistema de determinación de métodos de pago basado en balance de QB
  19. Mejoras Manejo de Errores registerPaymentsQB - Sistema robusto de captura y manejo de errores ⭐ NUEVO
  20. Corrección Asignación País Clientes Extranjeros - Fix para preservar país original de clientes extranjeros ⭐ NUEVO
  21. Detección de Clientes Extranjeros - Sistema completo de detección y manejo de clientes extranjeros en QuickBooks ⭐ NUEVO
  22. Solución Rate Limiting HTTP 429 - Manejo robusto de rate limiting para APIs QuickBooks ⭐ NUEVO

  23. Sistema Inteligente de Prevención de Duplicación - Detección avanzada con algoritmo de similitud de nombres ⭐ NUEVO

  24. Sistemas de Validación

  25. Validation System Overview - Sistema de validaciones completo
  26. Alanube Validation - Validaciones específicas para Alanube
  27. Customer APIs Validation - Validación de integridad para APIs customer
  28. Customer APIs Validation Summary - Resumen de implementación

DGI Compliance & Formularios Condicionales

  1. Implementación 98% DGI Compliance
  2. Formularios Condicionales JSch09 - Sistema completo de campos condicionales para 9 tipos de documento
  3. Validaciones Críticas DGI - Validaciones automáticas obligatorias según ficha técnica
  4. Campos Adicionales Completos - 45+ campos adicionales para 98% compliance
  5. Fix clearTransactionTypeSale - Solución a método faltante en componente Livewire ⭐ NUEVO

Optimizaciones de Infraestructura

Laravel Framework & Job Management

  • Error Laravel Builder::query() Correction - Corrección de patrones Eloquent Builder en SQL Server jobs ⭐ IMPLEMENTADO
  • Error: "Call to undefined method Illuminate\Database\Eloquent\Builder::query()"
  • Corrección de Builder::query() por Model::newQuery() en STCostOfGoodsOfCategoryJob
  • Patrones correctos para SQL Server data processing jobs
  • Validación de sintaxis y funcionalidad completa

Servidor de Producción

  • Configuración Memoria Swap Debian 11 - Configuración completa de memoria swap para servidor de producción ⭐ NUEVO
  • Configuración de swap para resolver "MySQL server has gone away" errors
  • Optimización MySQL para ambiente de producción Debian 11 (bullseye)
  • Scripts de monitoreo de memoria y sistema
  • Guía específica para deployment sin Docker

Optimizaciones

  1. Sistema de Búsqueda
  2. Optimización Customer Search - Mejoras al search de customers

  3. Implementación Search Components - Componentes de búsqueda

  4. Sistema de Estado de Transacciones

  5. Enhanced Transaction Status System - Sistema mejorado de seguimiento de estado para transacciones FE

Testing

  1. Framework de Testing
  2. Test QuickBooks Error Handling - Testing de manejo de errores registerPaymentsQB ⭐ NUEVO
  3. Testing Infrastructure - Infraestructura de testing para DocuCenter

Troubleshooting y Soluciones

  1. Errores de OrganizationService
  2. Solución: Error getOrganizationActive() - Fix completo para métodos inexistentes
docs/technical/
├── index.md                                               # Este archivo
├── organization-access-control-system.md                 # Sistema de control de acceso
├── implementation-guide-organization-access.md           # Guía de implementación
├── organization-access-implementation-summary.md         # Resumen de implementación
├── alanube-dom-consumer-invoice-improvements.md
├── TESTING_SYSTEM_SUMMARY.md
├── alanube-panama-complete-integration.md               # Implementación del servicio
├── alanube-panama-service-usage.md                     # Manual de uso del servicio
├── alanube-panama-credit-notes-guide.md                # Guía de notas de crédito
├── validation-system-overview.md
├── alanube-validation.md
├── customer-search-optimization.md
├── search-components-implementation.md
└── testing-infrastructure.md

Scripts de Automatización

scripts/
├── implement-organization-access.sh                     # Script de implementación automatizada
├── diagnose-kart-invoice.sh
├── docs-cleanup.sh
├── simulate-kart-test.sh
└── ...

Componentes Enhanced

app/Http/Livewire/Setting/Enhanced/
├── InvuposEnhanced.php                                  # Ejemplo completo con control de acceso
├── ImportEnhanced.php                                   # Importación con múltiples tipos
└── ...

Convenciones

  • Toda la documentación técnica se mantiene en español
  • Los archivos siguen el formato feature-description.md
  • Se incluyen ejemplos de código y casos de uso
  • Se documentan tanto implementación como testing