ADS · S1 · Visión arquitectónica inicial de SGE-JD¶
SGE-JD · JD Refrigeración S.A.C. · Equipo CherryTree · Yoel Wagner Chambi Sirena · 10/11/2026
Trabajo autónomo de la sesión 1 (Fundamentos de arquitectura de software). Es la primera visión del sistema completo, no solo del backend. Cada decisión tiene su justificación y la evidencia que la comprueba.
Contenido:
- Dominio y proceso principal.
- Stakeholders.
- Atributos de calidad priorizados.
- Estilo arquitectónico inicial.
- Diagrama arquitectónico inicial.
- Decisiones arquitectónicas iniciales.
- Matriz de integración ADS-BD2-LP2.
- Hallazgo.
- Reflexión.
1. Dominio y proceso principal¶
| Elemento | SGE-JD |
|---|---|
| Dominio del proyecto | Gestión comercial y técnica de una empresa de climatización, refrigeración y ventilación forzada (JD Refrigeración S.A.C., Lima): catálogo, proformas, ventas, facturación electrónica, cobranza, compras e inventario, y servicio técnico postventa |
| Proceso principal | Venta con comprobante electrónico: proforma → venta (contado o crédito) → factura o boleta aceptada por SUNAT → cobro → mantenimiento preventivo del equipo instalado |
| Entidad transaccional principal | Venta–DetalleVenta (tablas VENTAS y DETALLE_VENTA); de ella dependen Comprobante, Cobro–DetalleCobro y Mantenimiento |
| Usuarios principales | Lisandro, gerente y dueño (rol ADMIN), y Lucy, asistente administrativa (rol ASISTENTE, con permisos que Lisandro le delega) |
| Sistemas externos reales | SUNAT (envío del comprobante y CDR), apis.net.pe (RUC, DNI y el tipo de cambio que publica SUNAT), servidor SMTP (comprobantes y proformas por correo) y Keycloak (identidad) |
Diferencia con BomERP: en BomERP el proceso es "venta con control de stock". En JD el stock es solo una parte, porque la mayoría de lo que se vende no tiene stock (ver el hallazgo, sección 8). Lo que no puede fallar es el comprobante ante SUNAT: una venta sin comprobante válido es un problema tributario.
2. Stakeholders¶
| Stakeholder | Interés | Atributo de calidad asociado |
|---|---|---|
| Lisandro (gerente, ADMIN) | Ver ventas, márgenes y cobranza reales; decidir quién puede hacer qué (descuentos, precios, fechas pasadas) | Seguridad (autorización) · Auditabilidad |
| Lucy (asistente, ASISTENTE) | Registrar proformas, ventas y cobros rápido, sin errores ni pasos de más | Usabilidad · Integridad |
| Clientes de JD | Recibir su factura o boleta válida, con el monto correcto y a tiempo | Integridad · Confiabilidad de integraciones |
| SUNAT (regulador) | Comprobantes con formato UBL 2.1 firmado, enviados en plazo (3 días) y sin duplicados | Interoperabilidad · Integridad |
| Contador externo | Totales, IGV, detracciones y anulaciones que cuadren con los comprobantes | Integridad · Auditabilidad |
| DBA (BD2) | Esquema Oracle con reglas protegidas en la base, permisos mínimos, respaldos y auditoría | Seguridad · Recuperabilidad |
| Equipo de desarrollo (LP2) | Módulos con límites claros para trabajar en paralelo (3 integrantes, 13 módulos) | Mantenibilidad |
El que más condiciona las decisiones es SUNAT. Fija el formato, la firma, el plazo y la inmutabilidad del comprobante. Ningún otro stakeholder puede negociar esas reglas.
3. Atributos de calidad priorizados¶
| # | Atributo | Por qué importa en JD | Cómo se verifica (evidencia en el proyecto) |
|---|---|---|---|
| 1 | Integridad | Total, IGV y stock no pueden quedar inconsistentes, y un comprobante aceptado no puede cambiar | Transacción única en VentaService con bloqueo del producto (descontarStock); trigger TRG_COMPROBANTE_AMBIENTE (ORA-20031); BD2 S1: FN_TOTAL_VENTA reproduce los 237 totales de Java y las CHECK nuevas (CK_PRODUCTO_STOCK…) |
| 2 | Seguridad | Los costos, márgenes y anulaciones son información del dueño; Lucy no debe superar sus topes | Keycloak con JWT RS256, roles ADMIN/ASISTENTE y 11 permisos delegables (PERM_*); matriz de seguridad 14/14 |
| 3 | Auditabilidad | Quién anuló, quién editó un precio y por qué; qué se envió a SUNAT y con qué resultado | HISTORIAL_CAMBIOS, VENTAS.ANULADO_POR/MOTIVO_ANULACION, DETALLE_VENTA.MOTIVO_PRECIO, ENVIOS_SUNAT, INTENTOS_CORREO |
| 4 | Confiabilidad de las integraciones | SUNAT y el correo pueden fallar; la venta no debe perderse ni duplicarse | Reintentos del envío a SUNAT y del correo; estado INCIERTO sin reenvío automático; prueba de integración real del 08/11/2026 |
| 5 | Mantenibilidad | Tres desarrolladores en 13 módulos durante 16 semanas | Spring Modulith: ModularityTests falla si un módulo usa el repositorio de otro o forma ciclos |
La prioridad sigue al costo de equivocarse. Un error de integridad se convierte en una multa o en dinero mal cobrado. Uno de rendimiento (RNF-02, 185 ms medidos) solo hace esperar a Lucy, y por eso queda fuera de los cinco primeros.
4. Estilo arquitectónico inicial¶
| Opción | ¿Aplica a SGE-JD? | Justificación |
|---|---|---|
| Monolito modular | Sí | Un solo ejecutable para una empresa con 2 usuarios y una PC; los módulos por dominio dan los límites que un equipo de 3 necesita, verificados con Spring Modulith |
| Arquitectura en capas | Sí, dentro de cada módulo | Controller → Service → Repository → Entity, con DTO en el borde |
| Hexagonal (puertos y adaptadores) | Solo en las integraciones | SUNAT, RUC/DNI, correo y WhatsApp están detrás de interfaces (OseClient, ConsultaRucClient, NotificadorCorreo) con implementación real y simulada; el resto del dominio no lo necesita |
| Microservicios | No | Dos usuarios y una sola base no justifican red, despliegue y consistencia distribuida; los eventos internos dejan la puerta abierta |
| Clean Architecture | Parcialmente | Se respeta la regla de dependencia (el dominio no conoce a Spring MVC), sin la estructura formal completa |
5. Diagrama arquitectónico inicial¶
flowchart TB
L[Lisandro · ADMIN]
U[Lucy · ASISTENTE]
SPA[SPA Angular · bomerp-frontend]
KC[Keycloak · identidad y roles]
API[Backend Spring Boot · monolito modular de 13 módulos]
DB[(Oracle · esquema JDREFRIGERACION)]
SUNAT[SUNAT · comprobantes electrónicos]
RUC[apis.net.pe · RUC, DNI y tipo de cambio]
SMTP[Servidor SMTP · correo]
L --> SPA
U --> SPA
SPA -- inicio de sesión --> KC
SPA -- REST JSON + JWT --> API
API -- valida el JWT --> KC
API -- JPA + reglas en PL/SQL y CHECK --> DB
API -- SOAP, XML UBL 2.1 firmado --> SUNAT
API -- REST --> RUC
API -- PDF + XML --> SMTP
Es intencionalmente simple. Las vistas C4 completas (contexto, contenedores, componentes y código) son el trabajo de S2. Este diagrama fija que hay una SPA, un backend único, una base Oracle y cuatro sistemas externos, uno de ellos regulador.
6. Decisiones arquitectónicas iniciales¶
| Código | Decisión | Alternativas consideradas | Justificación | Consecuencia |
|---|---|---|---|---|
| ADR-001 | Un solo proyecto Spring Boot con módulos por paquete (monolito modular) | Microservicios; proyecto Maven multimódulo | Un despliegue en una PC; equipo de 3; el curso pide capas, no distribución | Un único .jar; los límites no los da Maven, hay que verificarlos (ADR-002) |
| ADR-002 | Límites verificados con Spring Modulith: los módulos se hablan por fachadas y eventos | Solo convención documentada | Una regla documentada se rompe en silencio; un test que falla, no | ModularityTests en cada mvn test; Ventas avisa a Postventa por VentaRegistradaEvent |
| ADR-005 | Identidad en Keycloak (no JWT propio) | JWT propio con tabla USUARIOS |
Contraseñas, bloqueo por intentos y política fuera de la aplicación | La tabla USUARIOS se retiró (07/11/2026); depende de un contenedor más |
| ADR-S1-01 | Envío directo a SUNAT (SEE - Del Contribuyente), sin OSE ni intermediario | OSE de pago; proveedor tipo Gosocket | Sin costo mensual para JD; control del XML y del CDR | El sistema firma y guarda el XML; SUNAT_AMBIENTE obligatorio y solo direcciones oficiales |
| ADR-S1-02 | Reglas críticas también en Oracle (CHECK y PL/SQL), no solo en Java | Solo validaciones del backend | Cualquier cliente SQL o script puede saltarse Java (hallazgo de BD2 S1) | Las reglas viven en dos lugares y hay que mantenerlas iguales; FN_TOTAL_VENTA lo comprueba contra los totales de Java |
ADR-001, 002 y 005 vienen del curso (BomERP) y el equipo los adoptó y verificó. ADR-S1-01 y ADR-S1-02 son propios de JD. El ADR completo de una decisión propia está en S14_ADS_decisiones_trazabilidad.md (ADR-006).
7. Matriz de integración ADS-BD2-LP2¶
| Decisión ADS | Evidencia en BD2 | Evidencia en LP2 |
|---|---|---|
| Integridad de la venta | SP_REGISTRAR_VENTA, FN_TOTAL_VENTA y CHECK de stock, cantidad y descuento (BD2 S1) |
VentaService.registrarVentaDirecta, transacción y bloqueo del producto |
| Inmutabilidad del comprobante | Trigger TRG_COMPROBANTE_AMBIENTE (ORA-20031) |
EnvioSunatService fija el ambiente una sola vez |
| Auditabilidad | Tabla de auditoría con trigger (se construye en BD2 S2) | HISTORIAL_CAMBIOS, anulación con motivo |
| Seguridad de mínimo privilegio | JD_APP: solo CREATE SESSION y EXECUTE (BD2 S1; se completa en S8) |
Keycloak, roles y PERM_* |
| Mantenibilidad | Un esquema propietario (JDREFRIGERACION) por sistema |
ModularityTests en verde |
8. Hallazgo: la decisión "obvia" de copiar el dominio de BomERP¶
Qué parecía obvio. Tomar el proceso de BomERP, "venta de productos con control de stock", y poner el stock como la regla central del sistema.
Qué mostraron los datos. En la copia de la base del 10/11/2026, solo 16 de los 39 productos
controlan stock: los de MATERIAL_SERVICIO. Los otros 23 no lo controlan: servicios, equipos de
climatización, refrigeración y ventilación que se venden por pedido. En cambio, las 237 ventas tienen
comprobante, y cada uno pasa por SUNAT.
| Consulta (BD2, base de práctica) | Resultado |
|---|---|
| Productos por sector | MATERIAL_SERVICIO 16 (con 864 unidades); CLIMATIZACION 8; SERVICIO 7; REFRIGERACION 4; VENTILACION_FORZADA 4 |
| Ventas con comprobante | 237 de 237 |
Riesgo técnico detectado. Con el stock como centro, la arquitectura habría tratado a SUNAT como un "servicio de notificación" opcional, como en BomERP. Pero si SUNAT no responde, la venta queda sin validez tributaria. El riesgo real es la integración, no el inventario.
Ajuste. El proceso principal se definió como venta con comprobante electrónico (sección 1). SUNAT pasó a
ser el stakeholder que más condiciona (sección 2). La confiabilidad de las integraciones entró como atributo 4.
La regla de stock quedó acotada al material (ADR-006, Producto.controlaStock()).
Qué aprendí. El dominio no se copia de un ejemplo: se mide. Una consulta sobre los datos reales cambió la prioridad de dos atributos de calidad.
9. Reflexión¶
¿Por qué una arquitectura debe justificar decisiones y no solo mostrar componentes?
Un diagrama de componentes dice qué existe, pero no por qué ni qué pasa si se cambia. Dos sistemas pueden tener el mismo dibujo, una SPA, un backend y una base, y necesitar arquitecturas opuestas. En SGE-JD, ese dibujo no muestra que SUNAT obliga a no modificar un comprobante aceptado. Tampoco que el stock solo importa para el material. Una decisión justificada, con sus alternativas y su consecuencia, permite que quien llegue después sepa qué puede tocar y qué no. Y una decisión con evidencia, como un test o una consulta, se puede comprobar. Sin la justificación, la arquitectura es una opinión que se pierde en el primer cambio.