# Auditoria De Acoplamiento Entre Capas Fecha: 2026-03-15 ## Alcance Se auditaron las capas y zonas principales del proyecto: - `app/Domain` - `app/Application` - `app/Infrastructure` - `app/Presentation` - `app/Http` - `app/Models` La medicion se hizo con analisis estatico de imports `use ...` sobre archivos PHP. Esta auditoria detecta acoplamiento estructural explicito; no cubre referencias totalmente calificadas dentro del cuerpo del codigo, resolucion dinamica por contenedor ni dependencias en views o configuracion. ## Regla De Evaluacion Se usaron dos niveles de severidad: - Violacion dura: Una capa interna depende de una capa externa o de una capa de entrega no permitida. - Acoplamiento framework: La capa usa directamente `Illuminate`, facades o utilidades de Laravel. Reglas aplicadas: - `Domain` no debe depender de `Application`, `Infrastructure`, `Presentation`, `Http`, `Models` ni `Illuminate`. - `Application` no debe depender de `Infrastructure`, `Presentation`, `Http` ni `Models`. - `Application` puede usar `Illuminate` solo como concesion tactica, pero se marca como deuda porque reduce portabilidad y testabilidad. - `Presentation` puede depender de `Application`; referencias directas a `Infrastructure` se marcan como warning. - `app/Http` se trato como una capa legacy fuera del esquema de Arquitectura Limpia. Su existencia no es una violacion por si sola, pero si es evidencia de bypass del borde de entrada. ## Resumen Ejecutivo Nivel de acoplamiento actual: medio-alto. Diagnostico corto: - `Domain` ya no tiene violaciones activas de capa en los contratos auditados. - `Application` es la capa mas erosionada. En varios puntos ya funciona como mezcla de caso de uso, servicio de infraestructura y adaptador Laravel. - `Presentation` esta bastante mejor contenida, pero convive con una capa `app/Http` legacy que bypassa el borde de entrada definido. - El mayor riesgo no esta en la cantidad total de archivos, sino en pocos hotspots con mucho peso transaccional. ## Metricas ### Inventario - `Domain`: 113 archivos - `Application`: 156 archivos - `Infrastructure`: 115 archivos - `Presentation`: 33 archivos - `Http`: 50 archivos - `Models`: 43 archivos ### Pureza Por Capa - `Domain`: 0 archivos con violaciones duras, 0 referencias prohibidas, pureza estimada `100.0%` - `Application`: 7 archivos con violaciones duras, 22 referencias prohibidas, pureza dura estimada `95.5%` - `Application`: 20 archivos con acoplamiento a `Illuminate`, 40 referencias framework - `Application`: 21 archivos totales afectados entre violaciones duras y framework, pureza estricta estimada `86.5%` - `Presentation`: 1 archivo con referencia directa a `Infrastructure`, pureza estimada `97.0%` - `Http` legacy: 100 referencias directas a `Application`, `Domain`, `Infrastructure`, `Models` o `Presentation` ### Observaciones Positivas - `Domain` no tiene imports directos a `Illuminate` - El daño arquitectonico esta concentrado, no repartido uniformemente - `Presentation` ya existe como capa separada y puede convertirse en el borde de entrada oficial ## Hallazgos ### 1. Resuelto: contratos de `Domain` ya no dependen de `Application` ni de `Infrastructure` Se corrigieron los 9 contratos auditados para que usen tipos del propio dominio o primitivas estables. Archivos saneados: - `app/Domain/Agents/Contracts/AgentRepository.php` - `app/Domain/Agents/Contracts/ProfileImageRepository.php` - `app/Domain/Clients/Contracts/ClientDocumentStorageRepository.php` - `app/Domain/Dashboard/Contracts/DashboardRepository.php` - `app/Domain/Developments/Contracts/DevelopmentRepository.php` - `app/Domain/Developments/Contracts/DevelopmentSettingsRepository.php` - `app/Domain/Home/Contracts/HomeRepository.php` - `app/Domain/Lote/Contracts/LoteRepository.php` - `app/Domain/User/Contracts/UserRepository.php` Resultado: - `Domain` queda con 0 violaciones activas en esta auditoria - Los contratos internos ya no miran hacia `Application` ni hacia modelos Eloquent - El siguiente trabajo debe concentrarse en `Application`, no en el nucleo ### 2. Alto: `Application` concentra logica de negocio mas detalles Eloquent/Laravel Esta es la principal fuente de acoplamiento del sistema. Los casos mas pesados usan directamente modelos Eloquent, facades, `DB`, `Storage`, `Number`, `Str`, validaciones y carga de relaciones. Hotspots principales por cantidad de referencias prohibidas: - `app/Application/Sales/Support/SalePaymentService.php` con 7 referencias - `app/Application/LandingPage/Support/LandingPageDataService.php` con 5 referencias - `app/Application/Contracts/Support/ContractTemplateService.php` con 3 referencias - `app/Application/Audit/Support/ModelAuditLogger.php` con 2 referencias - `app/Application/Developments/UseCases/GetDevelopmentFinancialDashboard.php` con 2 referencias - `app/Application/Sales/UseCases/ImportDevelopmentSales.php` con 2 referencias Patrones detectados: - Casos de uso leyendo y escribiendo `App\Infrastructure\Persistence\Eloquent\Models\...` - Servicios de aplicacion haciendo transacciones con `DB::transaction` - Servicios de aplicacion serializando metadata y manipulando storage - DTOs de aplicacion formateando moneda con `Illuminate\Support\Number` - Algunos casos puntuales ya se corrigieron moviendo consultas a contratos de dominio, como `GetDevelopmentBranches` Impacto: - `Application` deja de ser orquestacion y pasa a contener detalles de persistencia - El costo de pruebas unitarias sube porque la capa depende de Laravel/Eloquent - Cambiar infraestructura implica tocar la capa de aplicacion ### 3. Resuelto: `Application` ya no depende de `Presentation` Se elimino la inversion explicita que existia en: - `app/Application/Leads/UseCases/FindPotentialDuplicateLeads.php` Cambio aplicado: - el caso de uso ya no utiliza `App\Presentation\Http\Resources\LeadForSaleResource` - ahora arma sus candidatos duplicados a partir de `LeadData`, manteniendo el mismo contrato de salida para los consumidores actuales Resultado: - `Application` queda con `0` imports directos a `Presentation` - el caso de uso vuelve a ser reutilizable fuera del borde HTTP ### 4. Medio-Alto: coexistencia de dos bordes de entrada El proyecto mantiene simultaneamente: - `app/Presentation/Http/*` - `app/Http/*` Indicadores: - `app/Presentation/Http/Controllers`: 6 controladores - `app/Http/Controllers`: 33 controladores - `app/Http`: 100 referencias directas a capas internas o modelos Lectura arquitectonica: - `Presentation` existe, pero no es el borde dominante - `app/Http` sigue siendo el canal principal para muchos flujos legacy - Hay duplicidad conceptual de controladores, rutas, requests y resources Impacto: - La arquitectura real del sistema no tiene un solo entry point coherente - Las reglas de capa se vuelven dificiles de gobernar - La migracion hacia Arquitectura Limpia queda a medio camino ### 5. Medio: `Presentation` aun toca `Infrastructure` en puntos puntuales Caso detectado: - `app/Presentation/Http/Controllers/Web/DevelopmentController.php` Problema: - Usa `App\Infrastructure\Persistence\Eloquent\Models\Development` directamente para validaciones de existencia y resolucion de GeoJSON Impacto: - La capa de presentacion sigue absorbiendo detalles de persistencia en ciertos endpoints - La regla "Presentation -> Application" no esta completamente consolidada ### 6. Medio: `app/Http` legacy sigue operando directamente sobre modelos El caso mas claro es: - `app/Http/Controllers/RealEstate/SettingsController.php` Caracteristicas del acoplamiento: - CRUD directo sobre multiples modelos Eloquent - Validacion, autorizacion, persistencia y view orchestration en el mismo controlador - Alta superficie de cambio Esto no solo es deuda de capas; tambien es deuda de tamano y responsabilidad. ## Archivos Mas Criticos ### Nucleo - Sin violaciones activas en `Domain` dentro del alcance auditado ### Aplicacion - `app/Application/Sales/Support/SalePaymentService.php` - `app/Application/LandingPage/Support/LandingPageDataService.php` - `app/Application/Contracts/Support/ContractTemplateService.php` - `app/Application/Developments/UseCases/GetDevelopmentFinancialDashboard.php` - `app/Application/Sales/UseCases/ImportDevelopmentSales.php` ### Delivery / Legacy - `app/Presentation/Http/Controllers/Web/DevelopmentController.php` - `app/Http/Controllers/RealEstate/SettingsController.php` - `app/Http/Controllers/RealEstate/LeadController.php` - `app/Http/Controllers/API/V1/DevelopmentApiController.php` ## Evaluacion General ### Estado por capa - `Domain`: limpio respecto a dependencias de capa auditadas - `Application`: zona de mayor erosion; aqui esta la mayor parte del trabajo - `Infrastructure`: cumple el rol esperado, pero absorbe menos de lo que deberia porque `Application` le invadio responsabilidades - `Presentation`: encaminada, pero aun no domina el borde - `Http` legacy: principal bypass de la arquitectura objetivo ### Nivel estimado - Acoplamiento general: medio-alto - Riesgo de cambio transversal: alto - Riesgo de regresion al refactorizar: medio-alto - Facilidad actual para pruebas aisladas de negocio: media-baja ## Prioridad De Remediacion ### Fase 1: proteger el dominio Objetivo: - remover dependencias `Domain -> Application` - remover dependencias `Domain -> Infrastructure` Accion: - mover comandos, DTOs y filtros fuera de las interfaces del dominio - redefinir contratos del dominio usando VOs o primitivas del propio dominio ### Fase 2: adelgazar `Application` Objetivo: - sacar Eloquent y facades de servicios y casos de uso Accion: - introducir puertos de salida para storage, transacciones, metadata, pagos y lecturas complejas - mover formateo, lectura de modelos y `DB::transaction` hacia adaptadores de infraestructura Objetivos candidatos inmediatos: - `SalePaymentService` - `LandingPageDataService` - `ContractTemplateService` ### Fase 3: cortar la inversion `Application -> Presentation` Objetivo: - que los casos de uso devuelvan DTOs o arrays internos, nunca resources HTTP Accion: - extraer el mapeo de `LeadForSaleResource` fuera de `FindPotentialDuplicateLeads` ### Fase 4: consolidar el borde de entrada Objetivo: - definir si `Presentation` sera el borde oficial y migrar `app/Http` gradualmente Accion: - no abrir nuevos endpoints en `app/Http` salvo mantenimiento - migrar primero controladores grandes y con CRUD directo ## Criterios De Salida Recomendados Se puede considerar que la arquitectura empezo a estabilizarse cuando se cumplan estos umbrales: - `Domain`: 0 archivos con dependencias a capas externas - `Application`: 0 dependencias a `Presentation`, `Http`, `Models` - `Application`: dependencias a `Infrastructure` reducidas al minimo y encapsuladas tras contratos - `Presentation`: 0 acceso directo a modelos Eloquent - `app/Http`: congelado o en reduccion neta por migracion ## Conclusiones La base no esta rota, pero si esta mezclada. El nucleo ya quedo saneado en los contratos auditados y la existencia de `Presentation` muestra una direccion valida; sin embargo, hoy la capa de aplicacion concentra demasiados detalles de framework e infraestructura, y la capa `app/Http` legacy sigue compitiendo con el borde limpio. Si tuviera que resumir la deuda en una frase: el principal problema no es que falten capas, sino que las capas ya existentes no son todavia la frontera real del sistema.