ADS · S14 · Decisiones arquitectónicas y trazabilidad¶
SGE-JD · JD Refrigeración S.A.C. · Equipo CherryTree · Yoel Wagner Chambi Sirena · 10/11/2026
Trabajo autónomo de la sesión 14, sobre el dossier de S13.
Ya existía un primer documento de S14, S14_ADS_decisiones_trazabilidad.md del 07/11/2026, con el ADR-006 (solo los materiales controlan stock) y la primera tabla de atributos. Se escribió antes de la auditoría de S13, así que este documento: - formaliza las dos decisiones que la auditoría dejó pendientes (ADR-007 y ADR-008); - actualiza los atributos con la evidencia de ADS S4 a S13 y BD2 S8 a S14; - traza dos requerimientos más; - corrige la matriz.
Lo del 07/11 que sigue vigente se referencia, no se copia.
Registro de decisiones del proyecto:
| ADR | Decisión | Estado |
|---|---|---|
| ADR-001 a ADR-005 | Arquitectura del backend, Spring Modulith, versión de Spring Boot, JWT y Keycloak | Del curso LP2 |
| ADR-S1-01, ADR-S4-01 | Envío directo a SUNAT; una sola instancia | ADS S1 y S4 |
| ADR-006 | Solo los materiales controlan stock, con una regla en el dominio | Aceptada e implementada (07/11) |
| ADR-007 | El abono lo crea Cobro.abonar() |
Implementada el 11/11/2026 (sección 1, al final) |
| ADR-008 | VentaAnuladaEvent lleva los datos que sus oyentes necesitan |
Implementada el 11/11/2026, con 8 campos (sección 2, al final) |
1. ADR-007 · El abono lo crea Cobro, con abonar(venta, monto)¶
Estado: aceptada el 10/11/2026 e implementada el 11/11/2026. Origen: hallazgo H3 de S13.
Contexto¶
Cuatro fuentes responden distinto a "¿quién crea el abono de un cobro?". Cada una tenía sentido sola, y nadie registró que la siguiente contradecía a la anterior:
| Fuente | Quién crea el abono | Cómo se llama |
|---|---|---|
| S7 (clases) | Lo crea otro; Cobro.agregarDetalle(d) lo recibe |
DetalleCobro, montoTotal |
| S8 (capas) | El mapper: toAbono(AbonoRequest, VentaParaCobro) → Abono; Cobro.agregarAbono(Abono) lo recibe |
Abono, importe |
| S10 (GRASP) | Cobro: abonar(VentaParaCobro, monto) lo crea y suma el total (Creator + Information Expert) |
DetalleCobro, montoTotal |
| Código (hoy) | El servicio: cobro.agregarDetalle(new DetalleCobro(venta, monto)) y, después del bucle, cobro.setMontoTotal(total) (CobranzaService.java:167 y :171) |
DetalleCobro, montoTotal |
Consecuencia práctica:
- Si alguien implementa S8 al pie de la letra, Cobro sigue anémico y su total se puede fijar con un setter que no cuadre con sus abonos.
- Si implementa S10, el toAbono de S8 sobra.
- Los dos diseños están aprobados en el dossier.
Decisión¶
Cobrocrea sus abonos:public Abono abonar(VentaParaCobro venta, BigDecimal monto)valida que el monto sea positivo y que la moneda coincida, crea el abono conventaId,documentoVentayfechaVenta, lo agrega y suma el total.- El total no tiene setter: solo cambia dentro de
abonar(). Así se cumple el invariante "total = Σ abonos" de S7, que hoy depende de que el servicio haga la suma bien. - El mapper solo traduce:
AbonoRequest→(ventaId, monto).toAbonodesaparece de S8. - Un solo nombre,
Abono, el término del negocio ("el abono a una venta", glosario de S6), en el diseño y en el código. La tabla sigue siendoDETALLE_COBRO, y el cambio de nombre es solo de la clase (@Table(name = "detalle_cobro")). - El saldo sigue en el servicio: necesita lo ya cobrado de otras transacciones (
CobroRepository.totalCobradoDeVenta), y eso no está dentro del agregado.
Alternativas consideradas¶
| Alternativa | Por qué no |
|---|---|
| Que el mapper cree el abono (S8) | El mapper es de la capa web. Las reglas del abono (positivo, misma moneda) quedarían repartidas entre el mapper y el servicio, y la entidad no podría proteger su total |
| Dejarlo en el servicio (lo actual) | Funciona y está probado (CobranzaServiceTest, 9 pruebas), pero el total depende de un setMontoTotal externo, y cualquier otro camino que cree cobros (una importación, una devolución) tendría que repetir la suma |
Una fábrica aparte (AbonoFactory) |
Indirección sin beneficio: el único que contiene y registra abonos es Cobro |
Consecuencias¶
- El invariante del total queda en un solo lugar, y se prueba con una prueba unitaria de
Cobrosin base de datos. CobranzaService.registrarse acorta: valida contra el saldo y llama aabonar.- S8 (mapper y nombre), S9 (secuencia:
agregarAbono→abonar) y S7 (DetalleCobro→Abono) se actualizan en el dossier al implementar. No se reescriben hoy. - Riesgo:
Abonotiene hoy una relación@ManyToOnecon la entidadVenta(brecha B1 de S8). El ADR-007 no la resuelve:abonarrecibeVentaParaCobroy guarda elventaId, lo que exige hacer B1 primero o al mismo tiempo.
Verificación contra el código, cuando se implemente:
grep -rn "new DetalleCobro\|new Abono\|setMontoTotal" src/main/java
Debe aparecer solo dentro de Cobro.java. Hoy aparece en CobranzaService.java:167 y :171. CobranzaServiceTest debe seguir 9/9.
2. ADR-008 · VentaAnuladaEvent lleva los datos que sus oyentes necesitan¶
Estado: aceptada el 10/11/2026 e implementada el 11/11/2026, con una corrección (abajo). Origen: hallazgos H1 y H5 de S13 y el rediseño de S11.
Contexto¶
- Hoy el evento es
VentaAnuladaEvent(Long ventaId)y tiene tres oyentes (S13, H1). - Como solo trae el ID,
DevolucionService.alAnularVenta(línea 48) llama de vuelta aventaService.obtenerPorIdPublicopara leer cliente, moneda y fecha de anulación. - S11 diseñó un evento más rico
(ventaId, clienteId, moneda, fechaAnulacion, documento), pero S13 encontró que omite el motivo. El consumidor que el mismo S11 anuncia (resumen semanal de anulaciones "por motivo") tendría que volver a llamar a ventas. - Además, la RTM decía que el stock se devolvía "por el evento", y no es así (sección 5). Hay que dejar escrito qué viaja por el evento y qué no.
Decisión¶
- El evento queda así:
VentaAnuladaEvent(Long ventaId, Long clienteId, Moneda moneda, LocalDate fechaAnulacion,
String documento, String motivo)
Cada campo sale de un atributo real (S13, sección 4). documento se obtiene del puerto ComprobantesDeVenta y puede ser null si la venta nunca tuvo comprobante.
2. Los oyentes no llaman de vuelta a ventas para leer la venta anulada. Lo que es propio de su módulo, como lo pagado en cobranza o el comprobante en facturación, lo leen de su propio módulo.
3. El stock NO viaja por el evento: se devuelve con la fachada ProductoService.sumarStock, síncrona y dentro de la misma transacción, como hoy. Un oyente puede fallar o, en el futuro, ser asíncrono. El stock tiene que quedar devuelto sí o sí, junto con la anulación.
Alternativas consideradas¶
| Alternativa | Por qué no |
|---|---|
Solo ventaId (lo actual) |
Cada oyente nuevo agrega una llamada de vuelta y una dependencia de lectura hacia ventas. El día que los oyentes sean asíncronos (S11), leerían la venta en un momento distinto al de la anulación |
Mandar la entidad Venta |
Es la fuga de abstracción de S3: el oyente podría modificarla, y cualquier campo nuevo de la tabla viaja a otros módulos |
| Copia completa de la venta, con líneas | Ningún oyente usa las líneas. El stock, que sí las necesita, va por la fachada (punto 3) |
Devolver el stock con un oyente en catalogo |
Haría la devolución tan frágil como el oyente más débil. Hoy la anulación y el stock son todo o nada (FlujoCompletoEndToEndTest: 10 → 7 → 10) |
Consecuencias¶
DevolucionServicedeja de depender deVentaServicepara la anulación. Le quedacobranzaService.pagadoDe, que es suyo.- El resumen semanal por motivo es posible sin tocar
ventas. - El evento pasa a ser un contrato: quitarle un campo rompe a los oyentes. Se documenta en el
recordy se cubre con una prueba de cada oyente que use solo los datos del evento.
Verificación contra el código, cuando se implemente:
grep -n "obtenerPorIdPublico" src/main/java/com/bomerp/cobranza/devolucion/service/DevolucionService.java
Hoy la encuentra en la línea 48; después no debe encontrar nada. VentaAnuladaEvent.java debe tener los seis campos. FlujoCompletoEndToEndTest debe seguir en verde (stock, visitas, devolución, 409).
2b. Implementación de los dos ADR (11/11/2026)¶
ADR-007, cómo quedó:
- Verificación del ADR: grep "new Abono|new DetalleCobro|setMontoTotal" solo encuentra new Abono dentro de Cobro.java.
- La clase: DetalleCobro se llama ahora Abono. La tabla sigue siendo DETALLE_COBRO, así que no hubo migración.
- El cobro: Cobro.abonar(venta, monto) valida que el monto sea positivo y que la moneda coincida, crea el abono y suma montoTotal, que ya no tiene setter.
- El abono: no tiene constructor público, para que solo lo cree su cobro.
- Diferencia con el diseño: abonar recibe la entidad Venta, no el VentaParaCobro de S8. Ese record y quitar la entidad del abono (brecha B1) siguen pendientes, y van juntos.
- Sigue en el servicio: Cobro.anular() (brecha B4).
ADR-008, la corrección que apareció al implementarlo. Los 6 campos del diseño no alcanzaban:
- La devolución de una venta al contado no tiene abonos en cobranza; lo pagado es el total de la venta, si estaba pagada.
- Con solo 6 campos, DevolucionService habría tenido que seguir consultando la venta.
- Por eso el evento quedó con 8 campos: (ventaId, clienteId, moneda, fechaAnulacion, documento, motivo, total, pagada). Los dos nuevos salen de datos reales de la venta (calcularTotal() y estadoPago), como exige la regla de S13.
Cómo quedó:
- Sin llamada de vuelta: DevolucionService ya no depende de VentaService. Arma la venta y el cliente como referencias JPA, sin consultarlos, con el id que trae el evento.
- Número de comprobante: lo pone VentaService con el puerto ComprobantesDeVenta, resuelto al anular para no crear un ciclo entre beans.
- Stock: sigue devolviéndose por fachada antes del evento, como fija el punto 3.
Pruebas:
- Todas las del backend contra la copia de desarrollo: 228/0 como el dueño y 228/0 como JD_APP.
- FlujoCompletoEndToEndTest cubre la anulación con stock, visitas, devolución y el 409 de una segunda anulación.
3. Atributos de calidad: decisión inicial frente a evidencia real¶
La tabla del 07/11 tenía cinco atributos. Aquí se completa con lo medido después, en los dos cursos. "Antes" es lo que se declaró en S1 (RNF).
| Atributo | Decisión inicial (S1) | Evidencia real | ¿Se cumple? |
|---|---|---|---|
| Seguridad (RNF-05) | JWT y autorización por rol | 07/11: Keycloak con PKCE, 14 de 14 casos en 05_matriz.ps1. Nuevo: • BD2 S8: el backend corrió 217 ejecuciones de prueba como JD_APP, un usuario sin privilegios directos (solo roles derivados del código), con el mismo resultado que como dueño del esquema; las 2 fallas se deben al trigger de BD2 S2 y no a permisos. • BD2 S9: la auditoría unificada registró el DELETE denegado (código 2004) y la clave incorrecta (1017) |
Sí. Falta aplicar JD_APP en desarrollo y producción |
| Mantenibilidad / modularidad (RNF-01) | Monolito modular, un módulo por paquete | ModularityTests en verde; 15 paquetes, 13 de negocio (S13, H2); 201 métodos de prueba (199 @Test + 2 parametrizados). Pero: • VentaService tiene 631 líneas y 25 métodos usados por 6 módulos (ADS S3). • CobranzaService inyecta FacturacionService en lugar del puerto ComprobantesDeVenta (ADS S10). • S13 encontró 5 inconsistencias entre documentos |
Parcial: los límites entre módulos se cumplen y se verifican; dentro de ventas y cobranza hay deuda registrada (ADR-007 y ADR-008) |
| Rendimiento (RNF-02) | Endpoints bajo 1000 ms | 07/11: pantallas principales de 27 a 642 ms; listas completas /ventas 1079 ms y /proformas 1426 ms. Nuevo, en base: • BD2 S10: índice de fecha usado (costo 251 → 175) y compuesto (cliente_id, fecha_venta). • BD2 S14: el reporte de rentabilidad (5 tablas, 27 200 ventas) tarda 110 ms en frío y 31 ms en caliente, con 100 % de aciertos en caché |
Parcial: la base responde; las dos listas completas no se volvieron a medir y siguen pendientes |
| Fiabilidad / integridad transaccional (RF-11, RF-17) | Stock atómico | 07/11: todo o nada (10 → 7 → 10). Nuevo: • BD2 S14: bloqueo real cobranza contra anulación. Con un UPDATE simple, la anulación esperó ~42 s y se aplicó sin mezclarse con el cobro revertido. Con la espera del backend (WAIT 10), se rindió a los 10,03 s (ORA-00054), que el manejador convierte en 409. • ADS S4: con dos instancias, las tareas programadas duplicaron el 50 % del trabajo, y por eso ADR-S4-01 fija una instancia |
Sí, con una instancia |
| Recuperabilidad (RNF-08, nuevo en esta tabla) | Respaldo diario con Data Pump | BD2 S13, en la base de práctica: ARCHIVELOG, RMAN nivel 0 (28 s) y nivel 1 (12 s), PITR al segundo anterior a un UPDATE sin WHERE con RTO de 33 s y sin perder el cambio legítimo. Pero: la imagen 23-slim de desarrollo y producción no trae RMAN, el respaldo automático no está programado y la copia fuera de la PC espera la carpeta de JD |
Parcial: probado en práctica, no en producción |
| Interoperabilidad (RNF-03, RF-10) | API REST JSON | 07/11: SUNAT beta aceptó facturas, boletas y notas de crédito con CDR. ADS S11: capa anticorrupción real (OseClient), Circuit Breaker diseñado |
Sí (producción espera el certificado) |
4. Requerimientos trazados de punta a punta¶
Los cinco eslabones (requerimiento → arquitectura → base de datos → backend → prueba) están en la RTM, sección 3, para cuatro requerimientos:
| Requerimiento | Trazado | Eslabones pendientes, registrados |
|---|---|---|
| RF-11 · Descuento de stock atómico | 07/11 (corregido el 10/11, sección 5) | Ninguno |
| RF-14 · Rutina de mantenimiento | 07/11 | Ninguno |
| RF-17 · Anular venta | 10/11 | Trigger y auditoría de BD2 S2 solo en práctica; 2 pruebas por adaptar al trigger (BD2 S8); ADR-008 |
| RF-20 · Cobranza con abonos | 10/11 | Índice UX_COBRO_VOUCHER_VIGENTE (ADS S9); prueba de Cobro.abonar() (ADR-007); prueba del voucher simultáneo |
RF-17 y RF-20 se eligieron porque son los que tocan los dos ADR nuevos: cada ADR queda conectado con un requerimiento y una prueba.
5. Error o hallazgo: la matriz decía que el stock volvía por el evento¶
Es una inconsistencia distinta de las de S13, entre la matriz y el código:
| Fuente | Qué decía |
|---|---|
| RTM, RF-17 (arquitectura) | "ventas → catalogo, postventa, facturacion, cobranza por VentaAnuladaEvent" |
| RTM, traza de RF-11 (backend) | "al anular, VentaAnuladaEvent lo devuelve" |
| Código | VentaService.anular llama a productoService.sumarStock(devueltas) en la línea 518, dentro de la transacción y antes de publicar el evento (línea 525). grep sumarStock solo lo encuentra ahí y en CompraService. Ningún oyente de catalogo escucha VentaAnuladaEvent |
- El código está bien y la matriz estaba mal. Si alguien "arreglaba" el código para que coincidiera con la matriz, moviendo la devolución a un oyente en
catalogo, el stock pasaba a depender de que ese oyente no fallara. Y si el oyente se volvía asíncrono (S11), la devolución quedaba fuera de la transacción de la anulación. - Corrección (10/11/2026): la RTM ya dice "fachada, misma transacción", con la nota corregido. Para que no vuelva a pasar, el punto 3 del ADR-008 lo deja como decisión explícita.
6. Matriz de trazabilidad final¶
RTM.md, actualizada al 10/11/2026: RF-01 a RF-35 y RNF-01 a RNF-09, con la columna de requerimiento y, para cada uno, arquitectura, base de datos, API, pantalla, prueba y estado.
Cambios de esta sesión: - RF-17 y la traza de RF-11, corregidas (sección 5). - RF-17 y RF-20, trazados de punta a punta. - ADR-007 y ADR-008 en los pendientes registrados.
7. Reflexión¶
- La decisión que nunca registré fue la de la sección 5: devolver el stock por fachada y en la misma transacción, no por evento. Estaba bien en el código, pero el único documento que la mencionaba decía lo contrario.
- El Ariane 5 explotó en 1996 por reusar el software de referencia inercial del Ariane 4 sin revisarlo. Una conversión de 64 a 16 bits era segura en el contexto del Ariane 4, cuya velocidad horizontal nunca la desbordaba. Esa suposición no estaba escrita junto a la decisión, y el Ariane 5, más rápido, la rompió a los ~37 s del despegue.
- Aquí el contexto que hace válida la decisión es que la anulación sea una sola transacción síncrona. S11 ya propone oyentes asíncronos. Si ese cambio llegaba sin el ADR-008, alguien podía mover el stock al evento siguiendo la matriz, y la anulación habría seguido "funcionando" en las pruebas mientras perdía stock en producción.
- Un ADR no solo dice qué se decidió: dice bajo qué supuesto sigue siendo correcto.