Saltearse al contenido
Mi Plante · Entregable Afluence

16 - Estudio Profundo de Validación

Fecha: 2026-04-07
Alcance: Validacion profunda de docs/audit/01-15 contra el codigo real del repo
Metodo: lectura estatica de rutas, controladores, middleware, modelos, migraciones, servicios, jobs, listeners, config y frontend; contraste documento por documento; verificacion adicional de los puntos mas riesgosos detectados durante la auditoria

Resumen Ejecutivo

La documentacion de auditoria tiene una base buena, pero no puede tratarse como completamente confiable en su estado actual.

Mi veredicto despues de la validacion profunda es:

  • Los documentos son utiles para entender el sistema, pero varios mezclan arquitectura deseada con arquitectura realmente ejecutada.
  • El mayor desfase aparece en:
    • flujos de venta / pagaré / credito
    • auth / autorizacion / protecciones efectivas
    • contratos frontend-backend
    • matriz de variables de entorno
    • request lifecycle y manejo real de errores API
  • El repo contiene bugs reales de aplicacion y riesgos de seguridad que van mas alla de errores de documentacion.
  • El reporte 00-validation-report.md apunta en varias direcciones correctas, pero tambien contiene afirmaciones que necesitan matiz o correccion.

En corto:

  • 01, 04, 07, 10, 12, 13, 15: utiles y en varias partes acertados, pero con correcciones importantes
  • 02, 05, 06, 08, 09, 11, 14: utiles, pero con desalineaciones materiales frente al runtime real
  • 03: el mas incompleto respecto a cobertura y precision de configuracion

Hallazgos Confirmados de Alta Prioridad

Estos puntos quedaron sustentados directamente en el codigo y son mas importantes que cualquier correccion cosmética de docs.

Seguridad / control de acceso

  1. Bypass de checkout por POST directo

    • GET /checkout usa cliente_registro_completo y verificar_cliente_presenta_mora, pero POST /mis-compras y POST /mis-compras/procesar-carrito no.
    • Impacto: un usuario autenticado puede intentar comprar sin pasar por esos controles de negocio.
    • Evidencia: routes/web.php, app/Http/Controllers/Market/VentaController.php

  2. Endpoint publico de historial crediticio

    • GET /api/v1/datacredito/historial es publico.
    • Impacto: exposicion de una consulta sensible sin autenticacion.
    • Evidencia: routes/api.php, app/Http/Controllers/Api/DataCreditoController.php

  3. Registro aliado no atado realmente al link firmado

    • El GET /aliados/postulacion/{postulacion}/registro si es signed, pero el POST /aliados/postulacion/registro no lo es ni recibe {postulacion}.
    • Impacto: el flujo de invitacion firmada no queda realmente garantizado en el alta.
    • Evidencia: routes/ally/auth.php, app/Http/Controllers/AliadoAuth/RegisteredUserController.php

  4. CRUD publico de marcas

    • POST /marcas, PUT /marcas/{marca} y DELETE /marcas/{marca} estan expuestos sin auth.
    • Impacto: escritura publica sobre catalogo.
    • Evidencia: routes/web.php, app/Http/Controllers/Market/MarcaController.php

  5. Login aliado sin rate limiting

    • El login cliente si tiene limitacion de intentos; el login aliado no.
    • Evidencia: app/Http/Requests/Auth/LoginRequest.php, app/Http/Controllers/AliadoAuth/AuthenticatedSessionController.php

Flujo de ventas / credito / pagare

  1. ApiExceptionHandler no retorna su respuesta

    • Se invoca el handler custom pero no se hace return.
    • Impacto: la respuesta JSON estructurada pretendida no se usa.
    • Evidencia: bootstrap/app.php

  2. registrarEnCerticamara() siempre retorna false

    • Aunque cree el pagaré y actualice certicamara_uuid, el metodo retorna false.
    • Impacto: la rama que despacha credito inmediato al crear la venta nunca se comporta como parece indicar el codigo.
    • Evidencia: app/Services/VentaService.php

  3. Generacion duplicada de cuotas

    • VentaService genera cuotas al crear la compra y ProcesarPagareDigital vuelve a generarlas despues de la firma del pagaré.
    • Impacto: riesgo real de cuotas duplicadas.
    • Evidencia: app/Services/VentaService.php, app/Jobs/ProcesarPagareDigital.php

  4. Calculo de vencimientos usando created_at en modelos con creado_en

    • Venta y OrdenCompra heredan de Modelo, pero VentaService calcula cuotas contra created_at.
    • Impacto: las fechas se calculan desde now() en vez de desde la fecha real del registro.
    • Evidencia: app/Models/Modelo.php, app/Services/VentaService.php

  5. GenerarCreditoDeVenta marca la orden como PROCESADA por cada venta

    • No espera a que toda la orden quede consistente.
    • Impacto: una orden multi-venta puede quedar PROCESADA aunque otra venta falle o quede pendiente.
    • Evidencia: app/Jobs/GenerarCreditoDeVenta.php

  6. GenerarCreditoDeVenta no tiene failed() ni guardas de obsolescencia

    • Si falla por excepcion, la venta puede quedar PENDIENTE; tampoco valida que la venta siga en un estado procesable antes de aprobarla.
    • Evidencia: app/Jobs/GenerarCreditoDeVenta.php

  7. Descuento de cupo no atomico

    • Se usa $cliente->cupo_disponible - total y update(), no decrement().
    • Impacto: riesgo de lost update con jobs concurrentes del mismo cliente.
    • Evidencia: app/Jobs/GenerarCreditoDeVenta.php

  8. procesarCarrito() calcula mal el monto

    • Arma monto = precio * cantidad y luego VentaService::crearVenta() vuelve a multiplicar cantidad * monto.
    • Impacto: subtotal inflado para cantidades mayores a 1.
    • Evidencia: app/Http/Controllers/Market/VentaController.php, app/Services/VentaService.php

  9. procesarCarrito() fuerza numero_cuotas = 6

    • Se salta el request tipado del flujo principal y no respeta el rango por linea.
    • Evidencia: app/Http/Controllers/Market/VentaController.php

  10. Cache de DataCredito insuficiente

    • La cache del historial usa solo numero_documento + tipo, ignorando apellido.
    • Impacto: fuga/reuso incorrecto de respuesta cacheada.
    • Evidencia: app/Services/DataCreditoService.php

  11. DataCreditoService usa requestUUID fijo

    • Evidencia: app/Services/DataCreditoService.php

Contratos frontend-backend

  1. settings/Profile.vue no coincide con el backend

    • Frontend usa name; backend exige nombres y apellidos.
    • Evidencia: resources/js/pages/settings/Profile.vue, app/Http/Requests/Settings/ProfileUpdateRequest.php

  2. useWishlist() espera array plano, pero el backend devuelve paginador

    • Impacto: el preload del estado de wishlist queda roto o vacio.
    • Evidencia: resources/js/composables/useWishlist.ts, app/Http/Controllers/Market/ListaDeseoController.php

  3. UI aliado colorea estados que ya no son los reales

    • ally/ventas/Page.vue maneja cancelada, pero el backend usa rechazada y abandonada.
    • Evidencia: resources/js/pages/ally/ventas/Page.vue, app/Enum/Facturacion/EstadoVenta.php

Veredicto por Documento

01 - ER Diagram

Estado: mayormente correcto, con omisiones y varias simplificaciones peligrosas.

Correcto:

  • La columna central personas -> users -> clientes esta bien representada.
  • Las entidades de aliados, catalogo y facturacion principal existen y las relaciones base coinciden.
  • aprobar_cupo_eventos si usa UUID.
  • La nota sobre timestamps en español y soft delete en precios es correcta.

Corregir:

  • El documento mezcla relacion de esquema con relacion implementada en Eloquent.
  • orden_compras -> cuotas existe a nivel FK, pero no esta expuesto como relacion Eloquent real.
  • La cardinalidad de beneficiario esta sobreafirmada: el modelo es hasOne, pero el esquema no fuerza unicidad sobre compra_id.

Falta:

  • postulacion_aliados_lineas
  • descontable_descuento
  • matiz sobre relaciones que existen en DB pero no en modelo

02 - Route Inventory

Estado: util pero incompleto e insuficiente como documento operativo.

Correcto:

  • La separacion general por archivos de rutas y dominios esta bien.
  • La nota de /simulador-cuotas con withoutMiddleware('auth') es correcta.
  • La mayoria del inventario ally/auth/api coincide.

Corregir:

  • Falta GET /health.
  • Rutas de lineas de escritura existen en el router pero no son funcionales porque el controlador no implementa esos metodos.
  • carrito y lista-deseos estan listadas como publicas, pero operativamente fallan para invitados.

Falta:

  • resaltar la gravedad de las rutas publicas de escritura sobre marcas
  • distinguir entre “route registrada” y “route funcional”

03 - Env Config Matrix

Estado: el documento mas flojo en cobertura y precision.

Correcto:

  • El mismatch de TransUnion esta bien detectado.
  • Los duplicados de .env.example estan bien detectados.
  • La mayoria de mappings basicos de config/app.php, auth.php, database.php, queue.php, mail.php, filesystems.php y services.php son utiles.

Corregir:

  • DB_DATABASE y DB_URL estan documentados demasiado pegados a SQLite.
  • BROADCAST_CONNECTION no tiene respaldo real en este repo.
  • La nota de locales esta incompleta.
  • Se mezclan variables reales omitidas con otras que no tienen evidencia suficiente en el repo.

Falta:

  • varias variables de cache.php
  • variables de queue.php, logging.php, database.php, filesystems.php
  • bloque de config/log-viewer.php

04 - Notification Catalog

Estado: bastante bueno.

Correcto:

  • Las 7 notificaciones custom existen.
  • Todas son mail.
  • Ninguna esta realmente queueada.
  • El flujo de postulaciones hacia notificaciones esta bien trazado.
  • VerifyEmail built-in y TicketSoporte existen.

Corregir:

  • InformarDePostulacionAprobada no es simplemente “duplicado”; su intencion funcional no coincide exactamente con lo que hoy hacen las otras notificaciones.

Falta:

  • detallar mejor los disparadores reales de VerifyEmail
  • resaltar el riesgo operativo del fan-out sincrono a administradores

05 - Queue Catalog

Estado: bueno como mapa base, pero insuficiente para explicar el comportamiento real.

Correcto:

  • Inventario de jobs
  • scheduler cada 15 minutos
  • cadena ValidarPagareDigital -> ProcesarPagareDigital -> GenerarCreditoDeVenta
  • ausencia de failed() en GenerarCreditoDeVenta

Corregir:

  • ProcesarPagareDigital no valida de verdad consistencia de cuotas en multi-venta; solo loguea warning.
  • faltan riesgos de idempotencia y replay de webhook
  • el flujo de batch de carga masiva necesita mas cautela documental

Falta:

  • duplicidad de cuotas
  • carrera potencial en procesamiento masivo
  • aclarar que varios fallos “de negocio” y fallos “por excepcion” no se comportan igual

06 - Architecture Diagram

Estado: bueno para orientarse, pero materialmente desfasado en la parte de billing y request flow.

Correcto:

  • estructura de directorios
  • conteos generales de servicios/DTOs/modelos/jobs/listeners
  • stack frontend base
  • shared props y cache global
  • soporte SSR

Corregir:

  • la parte de middleware mezcla web y api como si compartieran el mismo pipeline
  • el flujo de compra documentado no coincide con el runtime real
  • la arquitectura de ventas esta descrita como event-driven de facturacion, pero el camino vivo es job/webhook-driven
  • se sobredimensiona el rol de Spatie Permission en autorizacion efectiva

Falta:

  • EMCALI y Core Credito dentro del bloque de integraciones
  • logging frontend/backend a BD
  • protagonismo real del webhook de Certicamara

07 - Auth / Authorization Map

Estado: bastante bueno en guards y middleware, pero incompleto en bypasses y garantias reales.

Correcto:

  • guards web y app
  • aliases en bootstrap/app.php
  • middleware global del grupo web
  • Spatie Permission instalado pero no cableado en runtime
  • login cliente con rate limit y filtro guard='web'
  • login aliado con filtro guard='app', activo y empresa activa

Corregir:

  • la aprobacion de cupo no exige realmente una secuencia dura de fases
  • el flujo firmado del registro aliado esta sobreafirmado
  • falta distinguir proteccion de GET versus POST

Falta:

  • bypass de checkout por POST directo
  • riesgo del endpoint DataCredito publico
  • no obligatoriedad real de OTP verificado antes del cuestionario

08 - Sale Lifecycle State Machine

Estado: buen esqueleto, pero desalineado con los edge cases reales.

Correcto:

  • enums de estado
  • transiciones principales pendiente -> aprobada, pendiente -> rechazada/abandonada, aprobada -> entregada
  • timeout de 60 minutos
  • estados sin trigger explicito (LEGALIZADA, COMPLETADA, DEVUELTA)

Corregir:

  • subestima la generacion duplicada de cuotas
  • usa parcialmente evidencia incorrecta del importador CSV
  • simplifica mal la semantica de algunos estados de orden
  • la narrativa de PlanCredito necesita mas fuerza: hoy es una pieza no operativa

Falta:

  • cuotas maestras de orden
  • desfase entre estados viejos/nuevos de orden/pedido
  • falta de idempotencia del webhook

09 - Event & Job Dependency Graph

Estado: bastante acertado en eventos muertos y listeners sincronicos.

Correcto:

  • eventos de postulacion
  • ValidationLog
  • listeners sincronicos
  • dead code de VentaCompletada y VentaCancelada
  • bug de VentaCanceladaListener

Corregir:

  • necesita explicitar mejor que el billing vivo ya no depende de esos eventos de facturacion

Falta:

  • riesgo de persistir payloads sensibles en aprobar_cupo_eventos
  • impacto operativo de que ValidationLog este en la ruta critica

10 - External Integrations Map

Estado: bueno en inventario, corto en riesgo.

Correcto:

  • TransUnion
  • Experian CrossCore
  • DataCredito
  • Certicamara
  • Core Credito
  • EMCALI
  • headers, timeouts y auth principales

Corregir:

  • Slack no debe presentarse como integracion activa
  • el endpoint DataCredito publico requiere tratamiento de riesgo, no solo descripcion
  • el webhook de Certicamara esta subdocumentado en seguridad

Falta:

  • uso real o no uso de verificarPagare()
  • enforcement comentado de score minimo del cuestionario
  • requestUUID fijo

11 - Data Flow Diagram

Estado: util para nivel macro, pero con varios contratos errados.

Correcto:

  • patrones generales Inertia vs axios
  • papel central de HandleInertiaRequests
  • capa de servicios, cache, cola y APIs externas

Corregir:

  • checkout/purchase flow no coincide del todo con el request real
  • user_stats no es verdaderamente “por usuario” como el nombre sugiere
  • varios contratos frontend-backend estan simplificados o mal shapeados

Falta:

  • bug real del wishlist paginado
  • diferencia entre props compartidas y props de controlador en varias paginas

12 - Credit Approval Workflow Diagram

Estado: uno de los mejores documentos, pero no debe leerse como garantia exacta de enforcement.

Correcto:

  • fases, servicios e integraciones principales
  • eventos ValidationLog
  • caches intermedias
  • daily limit basado en LEGAL_CHECK / START

Corregir:

  • el backend no obliga realmente que el cuestionario ocurra solo despues de OTP verificado
  • aprobar cupo no exige “todas las fases”, sino >= 5 process types exitosos del mes
  • varias degradaciones de error estan sobreexplicadas respecto a lo que el codigo garantiza

Falta:

  • explicitar que el enforcement real es mas debil que el diagrama ideal

13 - Frontend Page Map

Estado: bueno para inventario, flojo en contratos.

Correcto:

  • layouts principales
  • gran parte del inventario de paginas
  • patrones de comunicacion frontend

Corregir:

  • props de varias paginas no coinciden con lo que realmente entrega backend
  • settings/Profile.vue rompe el contrato actual
  • ally/ventas/Page.vue maneja mal estados actuales

Falta:

  • bug de wishlist
  • distincion precisa entre shared props y props del controlador

14 - Request Lifecycle Flowchart

Estado: didactico, pero mezcla comportamiento pretendido con comportamiento real.

Correcto:

  • entrada por public/index.php
  • pipeline general web
  • SSR/CSR a gran nivel
  • deteccion del bug de ApiExceptionHandler

Corregir:

  • el diagrama mezcla web y api como si compartieran middleware global
  • algunos bloques reflejan comportamiento “intencionado”, no necesariamente el runtime real
  • el mapeo de errores HTTP custom necesita mas cuidado

Falta:

  • resaltar que varias respuestas API custom hoy no salen por el bug del missing return

15 - Glossary

Estado: muy util, con pocas correcciones de concepto.

Correcto:

  • terminologia de negocio
  • estados principales
  • servicios e integraciones
  • buena parte de la nomenclatura financiera y de aprobacion de cupo

Corregir:

  • PlanCredito debe quedar explicitamente marcado como no operativo
  • algunas descripciones de estados/trigger son mas suposicion de negocio que evidencia de codigo
  • la referencia a cancelada en facturacion no coincide con enums vivos

Correcciones Mas Importantes para la Documentacion

Si hubiera que priorizar correcciones documentales antes de una presentacion o entrega, haria esto:

  1. Reescribir 06, 08, 11 y 14

    • Son los documentos donde mas se mezcla flujo ideal con flujo real.

  2. Corregir 03 con cobertura real de config

    • Hoy la matriz transmite mas confianza de la que merece.

  3. Actualizar 07 y 12 con las garantias reales

    • Importante para no vender un modelo de seguridad o de workflow mas fuerte de lo que el backend aplica.

  4. Ajustar 13 con contratos reales de props y endpoints

    • Sobre todo por bugs ya visibles entre frontend y backend.

  5. Mantener 01, 04, 10, 15 como base, pero con addendum

    • No necesitan una reescritura total; si necesitan precision.

Recomendacion Final

La conclusion tecnica no es que la auditoria original este mal hecha, sino que el sistema tiene suficientes desajustes entre documentacion, intencion arquitectonica y comportamiento real como para exigir una segunda pasada de consolidacion.

Mi recomendacion es:

  • usar estos documentos como base exploratoria
  • no usarlos aun como fuente final de verdad
  • consolidar una version corregida enfocada en:
    • seguridad efectiva
    • flujo real de ventas/pagaré/credito
    • contratos frontend-backend
    • configuracion e infraestructura real

Archivos Clave Revalidados Directamente

  • bootstrap/app.php
  • routes/web.php
  • routes/ally/auth.php
  • routes/api.php
  • app/Http/Middleware/HandleInertiaRequests.php
  • app/Http/Controllers/Market/VentaController.php
  • app/Http/Controllers/Market/ListaDeseoController.php
  • app/Http/Controllers/Api/DataCreditoController.php
  • app/Http/Controllers/AliadoAuth/RegisteredUserController.php
  • app/Services/AprobarCupoService.php
  • app/Services/IdentityValidationService.php
  • app/Services/DataCreditoService.php
  • app/Services/VentaService.php
  • app/Jobs/GenerarCreditoDeVenta.php
  • app/Jobs/ProcesarPagareDigital.php
  • resources/js/pages/settings/Profile.vue
  • resources/js/composables/useWishlist.ts
  • resources/js/pages/ally/ventas/Page.vue

Estado del Estudio

Este documento no reemplaza automaticamente cada uno de los docs 01-15; los valida, corrige y prioriza.
En esta pasada ya se incorporaron correcciones prioritarias dentro de 01-15, principalmente como bloques de Validated Corrections en cada archivo.
El siguiente paso natural seria producir una version v2 mas profunda de los documentos mas desalineados, empezando por 06, 08, 11, 12, 13 y 14.