ADS · S3 · SOLID, cohesión y acoplamiento del módulo ventas¶
SGE-JD · JD Refrigeración S.A.C. · Equipo CherryTree · Yoel Wagner Chambi Sirena · 10/11/2026
Trabajo autónomo de la sesión 3 (Diseño estructural y principios SOLID). Se evalúa el módulo ventas,
el del proceso principal (S1), que ya se abrió en C3 y C4
(S2). Todo lo que se afirma sale del código del 10/11/2026: tamaños con wc -l y usos con
grep.
El módulo tiene cuatro paquetes:
| Paquete | Clases | Líneas |
|---|---|---|
ventas.venta |
VentaController, VentaService, VentaRepository, Venta, VentaResponseDTO, ComprobantesDeVenta, 3 eventos |
1 172 |
ventas.detalleventa |
DetalleVenta |
126 |
ventas.reporte |
VentaReporteService |
132 |
ventas.tributos |
DeduccionTributariaService, TributosProperties |
86 |
1. Responsabilidad única (S)¶
| Clase | Líneas | Responsabilidad | ¿Cumple? |
|---|---|---|---|
VentaController |
140 | Traducir HTTP a llamadas al servicio: @Valid, sacar del JWT quién vende o anula |
Sí: ninguna regla de negocio; el usuario sale del token y nunca del cuerpo del request |
VentaService |
631 | Registrar y anular ventas… y también listar, paginar y ordenar, armar el reporte por moneda, y servir de fachada a Cobranza (5 métodos), Facturación (2) y Reportes (5) | No. Tiene al menos cuatro razones distintas para cambiar (sección 6) |
VentaRepository |
74 | Consultas de VENTAS y DETALLE_VENTA; bloquear() con bloqueo pesimista |
Sí: interfaz sin lógica |
Venta |
188 | Datos de la cabecera y su cálculo: subtotal, IGV, total, neto a cobrar | Sí: el cálculo es responsabilidad de quien tiene los datos (entidad rica, no anémica) |
DetalleVenta |
126 | Datos de la línea y su importe con descuento | Sí |
VentaResponseDTO |
86 | Forma de la venta en la API; desdeEntidad() la arma |
Sí: la conversión vive con el DTO, sin clase Mapper |
VentaReporteService |
132 | Excel de ventas e historial de un cliente | Sí, con matiz: comparte con VentaService la responsabilidad de "consultar ventas" |
DeduccionTributariaService |
65 | Decidir si una venta lleva detracción o retención y calcularla | Sí: una sola regla, una sola razón de cambio (la ley) |
TributosProperties |
21 | Porcentajes y umbrales de app.tributos |
Sí: solo configuración |
DeduccionTributariaService muestra lo que se busca. Cuando SUNAT cambie el umbral o el porcentaje, se toca
esa clase o sus propiedades, y nada más. Con VentaService no pasa lo mismo: un cambio en cómo se ordena una
lista, en lo que necesita Cobranza o en el formato del reporte cae siempre en el mismo archivo de 631 líneas.
2. Abierto/cerrado, Liskov e interfaces (O, L, I)¶
El módulo tiene una sola interfaz de servicio: ComprobantesDeVenta. Es la que está bien diseñada:
// ventas/venta/service/ComprobantesDeVenta.java: la DEFINE ventas
public interface ComprobantesDeVenta {
Optional<String> numeroComprobanteDeVenta(Long ventaId);
Optional<String> numeroNotaCreditoDeVenta(Long ventaId);
}
// facturacion/facturacion/service/FacturacionService.java: la IMPLEMENTA facturacion
public class FacturacionService implements ComprobantesDeVenta { … }
| Principio | ComprobantesDeVenta |
VentaService (sin interfaz) |
|---|---|---|
| O, abierto/cerrado | Abierta: un ComprobantesDeVentaSimulado para pruebas o un proveedor externo se suma sin tocar VentaReporteService |
Cerrada a extensión: no hay contrato que implementar. Además, registrarVentaDirecta tiene 5 sobrecargas (4, 6, 8, 9 y 10 parámetros). Cada dato nuevo (moneda, vendedor, rutina, fecha) agregó una sobrecarga, o sea, se modificó la clase para extenderla |
| L, Liskov | Cualquier implementación debe devolver Optional.empty() si la venta no tiene comprobante, nunca null ni una excepción; VentaReporteService depende de eso para imprimir "—" |
No aplica: hay una sola clase y no hay sustitución posible |
| I, segregación | 2 métodos, y su único cliente usa los 2 | 25 métodos públicos (19 operaciones distintas). El controlador usa 6 y ningún otro módulo más de 5 (tabla de abajo) |
Qué usa cada cliente de VentaService, contado con grep "ventaService\.<método>(" en todo src/main:
| Cliente | Módulo | Métodos que usa | de 25 |
|---|---|---|---|
VentaController |
ventas | listar, reportePagina, registrarVentaDirecta, convertirProformaEnVenta, anular, listarVentasConPagoAtrasado |
6 |
CobranzaService, DevolucionService |
cobranza | listarPendientesDeCobro, obtenerParaCobro, marcarComoPagada, volverAPendiente, obtenerPorIdPublico |
5 |
VentaReporteService |
ventas | buscar |
1 |
ReportesService, RentabilidadService |
reportes | registradasEntre, pendientesVencidasAl, listarPendientesDeCobro, lineasVendidas, lineasDeVentas |
5 |
FacturacionService |
facturacion | obtenerPorIdPublico, asignarComprobante |
2 |
OrdenTrabajoService |
servicios | registrarVentaDirecta, obtenerPorIdPublico |
2 |
VentasPostventaListener, EquipoInstaladoService |
postventa | obtenerPorIdPublico |
1 |
KardexService |
inventario | detallesDeProducto |
1 |
| (nadie) | — | listarTodas: código muerto |
0 |
Es una violación real de I. Postventa depende de una clase de 25 métodos para usar uno. Cualquier
cambio en la firma de anular obliga a recompilar Postventa, Inventario y Reportes, que no anulan nada.
3. Inversión de dependencias (D)¶
@Service
public class VentaService {
private final VentaRepository ventaRepository; // interfaz (Spring Data JPA)
private final ProformaService proformaService; // clase concreta (proformas)
private final ClienteService clienteService; // clase concreta (clientes)
private final ProductoService productoService; // clase concreta (catalogo)
private final TipoCambioService tipoCambioService; // clase concreta (config)
private final TopeDescuentoService topeDescuentoService; // clase concreta (seguridad)
private final DeduccionTributariaService deduccionTributariaService; // clase concreta (ventas.tributos)
private final ApplicationEventPublisher eventos; // interfaz (Spring)
private final AccesoUsuario acceso; // clase concreta (seguridad)
// todas llegan por el constructor; ninguna se crea con new
}
| Verificación | Resultado |
|---|---|
| ¿Inyección por constructor? | Sí, las 9 dependencias, todas final |
¿Algún new de un servicio o repositorio? |
No: grep " new [A-Z]*Service\| new [A-Z]*Repository" en ventas no encuentra nada |
| ¿Depende de abstracciones? | En parte. 2 de 9 son interfaces (VentaRepository, ApplicationEventPublisher); las otras 7 son clases concretas de otros módulos |
| ¿Hay inversión real en algún punto? | Sí, una: ComprobantesDeVenta. Ventas define lo que necesita y Facturación lo implementa, así que la dependencia de código va de facturacion hacia ventas, aunque en ejecución sea ventas la que consulta a facturación. Por eso ventas puede leer el número de comprobante sin conocer el módulo facturacion |
Que las 7 dependencias sean clases concretas no es todavía un problema práctico. Spring Modulith obliga a
que cada una sea la fachada pública de su módulo, nunca su repositorio, y cada una tiene una sola implementación.
Sería un problema si alguna necesitara una segunda versión, por ejemplo un TipoCambioService simulado para
pruebas sin internet. Hoy las pruebas simulan clases concretas con Mockito (@Mock VentaService, @Mock ClienteService), y las interfaces reales (OseClient, NotificadorCorreo) con @MockitoBean.
4. Cohesión y acoplamiento entre dos paquetes: venta y tributos, y venta y reporte¶
venta → tributos |
reporte → venta |
|
|---|---|---|
| Dependencia | VentaService llama a DeduccionTributariaService.aplicar(venta) |
VentaReporteService usa VentaService (consultas) y ComprobantesDeVenta |
| Dirección | Una sola: tributos no conoce a VentaService (solo recibe la entidad Venta) |
Una sola: venta no conoce el reporte… salvo VentaController, que inyecta los dos servicios |
| Cohesión interna | Alta: tributos hace una cosa (la deducción) con sus propiedades |
Media: el reporte arma Excel e historial; la paginación y el resumen por moneda, que también son reporte, quedaron en VentaService |
| Acoplamiento | Bajo: un método, aplicar(Venta) |
Medio: depende de la clase completa de 25 métodos, aunque usa 1 (buscar) |
| ¿Violación? | No | No es violación arquitectónica (mismo módulo; ModularityTests no lo controla), pero sí una tensión: el límite entre "operar ventas" y "consultar ventas" pasa por el medio de VentaService |
Dentro de un mismo módulo, que reporte use VentaService es una decisión interna y aceptable. La tensión
está en que VentaService.reportePagina() y VentaReporteService.exportarExcel() hacen el mismo tipo de
trabajo en dos paquetes distintos. Quien busque "cómo se arma el reporte de ventas" tiene que mirar los dos.
5. Modularidad y abstracción¶
Modularidad. ModularityTests (ApplicationModules.of(BomerpApplication.class).verify()) pasa en cada
mvn test. Ningún módulo usa VentaRepository y no hay ciclos. Se verifica de forma automática, no por
revisión.
Abstracción, DTO frente a entidad, en dos fronteras distintas:
| Frontera | Qué cruza | Evaluación |
|---|---|---|
| API REST → SPA | VentaResponseDTO |
Correcto. La SPA nunca recibe la entidad: ni costoUnitario (margen interno) ni las relaciones JPA salen sin decidirlo |
ventas → otros módulos |
La entidad Venta (obtenerPorIdPublico, obtenerParaCobro, buscar, registradasEntre…) y DetalleVenta (lineasVendidas) |
Fuga de abstracción. Hay 90 líneas de código (sin imports ni comentarios) que usan Venta o DetalleVenta en cobranza, facturacion y reportes. Un campo nuevo en la tabla o un cambio en una relación JPA se propaga a otros módulos. Y un módulo podría llamar a venta.setEstado(…) y saltarse anular(), con su stock y su motivo |
Spring Modulith permite esto, porque la entidad está en un paquete público del módulo. Pero es justo lo que la abstracción debería evitar.
6. Hallazgo real: VentaService es una "fachada de todo"¶
Qué se encontró. VentaService creó dos responsabilidades opuestas en la misma clase:
- Es el servicio de aplicación de la venta: registrar, convertir proforma, anular, con transacciones, bloqueos y eventos.
- Es la fachada pública del módulo para otros 6 módulos, que lo usan para leer ventas y a veces para
cambiarlas (
marcarComoPagada,asignarComprobante).
Cada vez que un módulo necesitó algo de ventas, se agregó un método aquí. El resultado son 631 líneas, 25
métodos públicos, 5 sobrecargas y un método que nadie usa (listarTodas).
Por qué importa (riesgo concreto). Las operaciones que cambian dinero y stock (anular,
marcarComoPagada) están en la misma clase pública que las consultas para reportes. Un desarrollador de
Reportes que abre VentaService para buscar registradasEntre tiene a mano volverAPendiente, que cambia el
estado de cobro de una venta.
Corrección propuesta. Es un refactor que todavía no se aplicó: se diseña aquí y se aplica en S10, con
GRASP. Se aplicaría el mismo patrón que ya funciona en ComprobantesDeVenta:
classDiagram
class VentasParaCobranza {
<<interface>>
+listarPendientesDeCobro(clienteId)
+obtenerParaCobro(ventaId)
+marcarComoPagada(ventaId)
+volverAPendiente(ventaId)
}
class VentasParaReportes {
<<interface>>
+registradasEntre(desde, hasta) List~VentaResumen~
+lineasVendidas(desde, hasta) List~LineaVendida~
}
class VentasConsulta {
<<interface>>
+obtener(ventaId) VentaResumen
}
class VentaService
VentasParaCobranza <|.. VentaService
VentasParaReportes <|.. VentaService
VentasConsulta <|.. VentaService
CobranzaService --> VentasParaCobranza
ReportesService --> VentasParaReportes
VentasPostventaListener --> VentasConsulta
| Paso | Efecto | Riesgo |
|---|---|---|
1. Interfaces por cliente (VentasParaCobranza, VentasParaReportes, VentasConsulta), implementadas por la misma VentaService |
I: cada módulo ve solo lo suyo; D: dependen de una interfaz | Bajo: no cambia ninguna lógica, solo el tipo que se inyecta |
2. Que las de lectura devuelvan records (VentaResumen, LineaVendida) y no la entidad |
Cierra la fuga de abstracción de la sección 5 | Medio: cobranza y reportes usan hoy campos de la entidad |
3. Reemplazar las 5 sobrecargas por un RegistroVentaCommand (record) |
O: un dato nuevo es un campo más, no otra sobrecarga | Bajo |
4. Borrar listarTodas |
Código muerto | Ninguno |
Las 215 pruebas existentes (VentaDirectaValidacionTest, VentaFechaPasadaIntegracionTest, PrecioEditadoIntegracionTest,
ModularityTests, la matriz de seguridad) son la red para hacerlo sin romper nada.
Por qué no es solo "una clase grande". Si fuera grande pero con una sola responsabilidad, sería aceptable. El problema es que mezcla quién la necesita: la SPA que vende, Cobranza que cobra y Reportes que lee. Esa mezcla es lo que S e I señalan, no el tamaño.
7. Integración con LP2 y BD2¶
| Criterio | Evidencia en LP2 | Relación con BD2 |
|---|---|---|
S en DeduccionTributariaService |
ventas.tributos (detracción y retención) |
— |
S/I en VentaService (hallazgo) |
631 líneas, 25 métodos, 6 módulos que lo usan además de ventas |
SP_REGISTRAR_VENTA (BD2 S1–S3) tiene una operación, con IN/OUT claros: la misma regla con una sola responsabilidad |
D con ComprobantesDeVenta |
Ventas define, Facturación implementa | — |
| Abstracción: la entidad cruza módulos | obtenerPorIdPublico devuelve Venta |
VENTA_AUDITORIA (BD2 S2) registra el cambio de estado aunque otro módulo modifique la entidad saltándose anular() |
| Modularidad | ModularityTests en verde |
Un solo esquema propietario (JDREFRIGERACION) |
8. Reflexión¶
¿Por qué el acoplamiento entre dos paquetes del mismo módulo no es automáticamente una violación, y qué lo diferencia del acoplamiento entre dos módulos distintos?
Dentro de un módulo, los paquetes los mantiene el mismo responsable y cambian por las mismas razones. Que
reporte use VentaService es como dos clases del mismo equipo que se conocen: si una cambia, quien la cambió
sabe arreglar la otra en el mismo commit. Entre módulos es distinto. cobranza es de Aron y ventas es mío, y
cada módulo debería poder cambiar por dentro sin avisar al otro. Por eso entre módulos solo se permite la
fachada pública, y ModularityTests lo verifica. El hallazgo de esta sesión está justo en ese borde.
VentaService es a la vez la clase interna de ventas y la fachada para otros 6 módulos, así que un cambio
interno se convierte en un cambio de contrato para todos. La diferencia no está en cuántas dependencias hay,
sino en si cruzan el límite de quién es responsable de qué.