Saltar a contenido

ADS · S6 · Descubrimiento y modelado del dominio 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 6 (Descubrimiento y modelado del dominio), primera de la Unidad II. El orden es el de un proyecto nuevo: primero el negocio completo, después las entidades. Los datos que se citan salen de la copia de desarrollo (base de práctica de BD2, consultas del 10/11/2026), sin las cargas de prueba de BD2 S4 y S5.

1. Panorama holístico del negocio (sin entidades)

JD Refrigeración vende, instala y mantiene equipos de climatización, refrigeración y ventilación forzada, y vende el material y el servicio técnico que eso requiere. El recorrido de un cliente es este:

flowchart LR
    COT["Cotizar<br/>(proformas)"] --> VEN["Vender<br/>(ventas)"]
    VEN --> FAC["Facturar ante SUNAT<br/>(facturacion)"]
    VEN --> COB["Cobrar<br/>(cobranza)"]
    VEN --> INS["Instalar y atender<br/>(servicios)"]
    INS --> MAN["Mantener<br/>(postventa)"]
    MAN -.->|"nueva visita, nueva venta"| COT
    COM["Comprar<br/>(compras)"] --> INV["Tener stock<br/>(inventario)"]
    INV --> VEN
    CAT["Qué se vende y a cuánto<br/>(catalogo)"] -.-> COT
    CLI["A quién<br/>(clientes)"] -.-> COT
    PRV["A quién se compra<br/>(proveedores)"] -.-> COM
    SEG["Quién puede hacer qué<br/>(seguridad)"] -.-> VEN
    NOT["Avisar<br/>(notificaciones)"] -.-> FAC
Módulo candidato Qué hace, en una frase
proformas Le dice al cliente cuánto le costaría, antes de que decida
ventas Concreta lo que el cliente compró
facturacion Da validez tributaria a esa venta ante SUNAT
cobranza Cobra lo vendido a crédito y devuelve lo cobrado de más
servicios Instala y atiende en el local del cliente (órdenes de trabajo, técnicos, sedes)
postventa Programa y hace el mantenimiento preventivo de lo instalado
catalogo Define qué se vende y a qué precio
clientes Registra a quién se le vende, y dónde están sus locales
compras Consigue el material y los equipos, y paga a los proveedores
inventario Sostiene y corrige la disponibilidad física del material
proveedores Registra a quién se le compra
seguridad Quién entra y qué puede hacer cada uno
notificaciones Hace llegar correos y avisos

2. Subdominios

Módulo Subdominio Por qué
ventas Core Es donde se gana el dinero: precio con margen, descuento con tope, precio editado con motivo, detracción y retención
servicios y postventa Core Es lo que distingue a JD de una tienda: la instalación y el mantenimiento recurrente. 448 de los 483 mantenimientos salen de una venta, y un cliente con mantenimiento vuelve a comprar
proformas Supporting Necesaria y propia del negocio, pero simple: es una venta que todavía no ocurrió
facturacion Supporting Compleja (UBL 2.1, firma, plazos, reemplazos), pero no diferencia a JD: cualquier empresa peruana la necesita y se puede comprar a un OSE. Se construyó porque el envío directo no tiene costo mensual (ADR-S1-01)
cobranza Supporting Necesaria; sus reglas (saldo, abonos, devoluciones) son las de cualquier empresa
catalogo, clientes, proveedores, compras, inventario Supporting Necesarios y no diferenciadores
seguridad Generic Problema resuelto en la industria: se delegó a Keycloak (ADR-005) y el sistema solo guarda topes y permisos
notificaciones Generic Enviar un correo es un problema resuelto (SMTP)

3. Entidades y reglas de negocio, por módulo

Se modelan en profundidad en esta unidad: ventas, facturacion y cobranza. Son el proceso principal definido en S1, "venta con comprobante electrónico", y sus dos consecuencias directas: la validez tributaria y el dinero. Los otros módulos quedan como candidatos para después:

  • servicios y postventa: son Core, pero su regla depende de que la venta esté bien modelada primero. Son el candidato natural de S8.
  • catalogo y clientes: aparecen aquí solo como lo que la venta referencia.
  • los demás: no participan en el proceso principal.
Módulo Entidad Identificador Regla de negocio Dónde se cumple hoy
ventas Venta id Total = suma de líneas + 18 % IGV. Una venta anulada es definitiva y se anula con motivo y quién. Solo con permiso se registra con fecha de hasta 30 días atrás Venta.calcularTotal(); VentaService.anular(); trigger TRG_VENTA_ESTADO_BU (BD2 S2)
ventas DetalleVenta id Cantidad mayor que 0. El descuento no supera el tope del rol. El precio editado solo sube y lleva motivo. El material necesita stock suficiente VentaService, PrecioDeLinea; CK_DETALLE_VENTA_* (BD2 S1)
facturacion Comprobante serie + numero (y id) Una venta tiene un solo comprobante vigente. Se envía a SUNAT dentro de los 3 días. Aceptado, su ambiente ya no cambia. Rechazado con CDR, se reemplaza por otro, no se corrige UX_COMPROBANTE_VIGENTE_VENTA, TRG_COMPROBANTE_AMBIENTE, Comprobante.fueraDePlazo()
facturacion NotaCredito serie + numero Anular una venta con comprobante aceptado exige su nota de crédito VentasFacturacionListener.alAnularVenta
cobranza Cobro id El mismo voucher (método + N° de operación) no entra dos veces. Se anula con motivo, no se borra CobroRepository.vigentesConReferencia (índice de BD2 S5); CK_COBRO_ANULADO
cobranza DetalleCobro id El abono a una venta no supera su saldo; cuando el saldo llega a 0, la venta pasa a PAGADO CobranzaService y VentaService.marcarComoPagada
catalogo Producto id Precio = costo × (1 + margen); solo el material controla stock (ADR-006); stock nunca negativo Producto.calcularPrecioVenta(), controlaStock(); CK_PRODUCTO_STOCK
clientes Cliente id (y RUC o DNI) RUC de 11 y DNI de 8, sin duplicados; si es agente de retención, sus ventas grandes llevan retención ClienteService; DeduccionTributariaService

4. Casos de uso relevantes

No son operaciones CRUD: cada uno cruza reglas y a veces módulos.

Módulo Caso de uso Valor para el negocio
ventas Convertir una proforma aceptada en venta La cotización se cumple con los precios y descuentos que se negociaron, no con los de hoy (118 de 228 proformas se convirtieron)
ventas Registrar una venta directa Venta con stock, tope de descuento, IGV, detracción o retención, comprobante y mantenimientos en una sola operación
ventas Anular una venta Devuelve el stock, emite la nota de crédito, cancela los mantenimientos pendientes y, si ya se cobró, deja la devolución pendiente
facturacion Emitir un comprobante de reemplazo Un comprobante rechazado por SUNAT no se corrige: se emite otro para la misma venta y el rechazado queda en el historial
cobranza Registrar un cobro repartido Una transferencia del cliente puede pagar varias facturas, y una factura puede pagarse en varias cuotas (82 de 99 ventas cobradas tienen más de un cobro)
postventa Programar la rutina de mantenimiento al vender un equipo Las visitas preventivas quedan agendadas desde la venta

5. Objetos de valor

Objeto de valor Reemplaza a Por qué es objeto de valor ¿Existe hoy?
Dinero (monto + moneda + tipo de cambio) BigDecimal sueltos más Venta.moneda y Venta.tipoCambio en campos separados Dos montos se comparan por contenido. Sumar soles con dólares es un error que hoy solo evita la disciplina del programador, y la conversión con el tipo de cambio hoy se llama desde cuatro lugares (VentaService, ProformaService, CompraService y la entidad Venta) No: es el candidato principal
RutinaMantenimiento (frecuencia, visitas, primera visita) Tres parámetros sueltos No tiene identidad y calcula fechaVisita(i). Define sus límites (MAX_FRECUENCIA_MESES = 12, MAX_VISITAS = 24), pero no los valida él mismo: lo hace quien lo usa. Un objeto de valor completo se validaría en su constructor Sí: record RutinaMantenimiento
PrecioDeLinea (precio, precio de catálogo, quién lo editó, motivo) Cuatro campos que tienen que ir juntos La regla "el precio editado solo sube y lleva motivo" vive en PrecioDeLinea.resolver() Sí: record PrecioDeLinea
RangoFecha (desde, hasta) desde/hasta repetidos en buscar, lineasVendidas y registradasEntre Valida desde ≤ hasta en un solo lugar. Es justo el filtro que BD2 S4 tuvo que reescribir No

Un matiz: EnvioSunat está marcado @Embeddable, como un objeto de valor, pero no lo es. Se modifica en el tiempo (registrarIntento) y su historia importa. Es el estado de una entidad (Comprobante) guardado en su misma tabla. Que algo sea @Embeddable dice dónde se guarda, no qué es en el dominio.

6. Prueba de tres partes

La prueba hace tres preguntas: (1) ¿ciclo de vida? ¿B puede existir sin A?; (2) ¿cardinalidad? ¿B pertenece a un solo A?; (3) ¿invariante compartido? ¿Tienen que cambiar juntos, atómicamente? Solo si las tres dicen "sí", B se compone dentro de A.

Relación Ciclo de vida Cardinalidad Invariante compartido Resultado
Venta – DetalleVenta (mismo módulo) Una línea no existe sin su venta Pertenece a una sola El total cuadra con las líneas, atómicamente Compone
Venta – Comprobante (ventas / facturacion) El comprobante no existe sin venta… …pero una venta puede tener varios a lo largo del tiempo (el rechazado y su reemplazo) Se crean en la misma transacción, pero después cada uno cambia solo: SUNAT acepta el comprobante sin tocar la venta, y anular la venta no modifica el comprobante, emite una nota No compone, se referencia. Es su propio agregado en facturacion
Venta – Cobro (ventas / cobranza) El cobro existe aunque se anule una de las ventas que pagó Muchos a muchos: un cobro puede repartirse entre varias ventas (DetalleCobro) y una venta se paga con varios cobros (82 de 99) "Un abono no supera el saldo" se valida contra la venta, pero el cobro se registra y se anula solo No compone, se referencia. Cobranza es módulo propio
DetalleVenta – Producto (ventas / catalogo) El producto existe sin esa línea Un producto aparece en muchas líneas El stock sí cambia en la misma transacción, pero por la fachada descontarStock, con bloqueo; no forma parte del agregado No compone, se referencia
Venta – Mantenimiento (ventas / postventa) El mantenimiento sigue aunque la venta se anule (se cancela, no se borra) Una venta genera varios (448 de 483 vienen de una venta) No: se programan por evento y se atienden meses después No compone, se referencia por evento

7. Lenguaje ubicuo y agregado

Término de JD Significado compartido En el código
Proforma Cotización con precios y descuentos que se respetan si el cliente acepta Proforma, convertirProformaEnVenta
Venta directa Venta sin proforma previa registrarVentaDirecta
Anular Dejar sin efecto una venta sin borrarla; es definitivo VentaService.anular, EstadoVenta.ANULADA
Comprobante Factura (a RUC) o boleta (a DNI) electrónica Comprobante, series F001 y B001
Por emitir Venta guardada que todavía no tiene comprobante porque falta un dato de JD ventasPorEmitir, EstadoSunatVentaDTO.porEmitir
Comprobante de reemplazo El que se emite cuando SUNAT rechazó el anterior; el rechazado no se corrige Comprobante.reemplazaA
CDR Constancia de recepción de SUNAT: dice si aceptó o rechazó EnvioSunat
Nota de crédito El comprobante que anula a otro ya aceptado NotaCredito
Detracción / retención Parte del total que el cliente no le paga a JD, sino a SUNAT o a su cuenta TipoDeduccion, DeduccionTributariaService
Tope de descuento Máximo que puede dar cada rol; lo fija Lisandro TopesDescuento
Precio editado Precio de línea mayor al de catálogo, con motivo PrecioDeLinea
Abono / cobro Dinero recibido que se reparte entre ventas Cobro, DetalleCobro
Material de servicio El único tipo de producto que controla stock Sector.MATERIAL_SERVICIO, controlaStock()
Rutina de mantenimiento Frecuencia y número de visitas que se programan al vender un equipo RutinaMantenimiento

Agregado del proceso transaccional: Venta (raíz) con DetalleVenta.

flowchart TB
    subgraph AGG["Agregado Venta (raíz)"]
        V["Venta<br/>total = Σ líneas + IGV · anulada es definitiva"]
        D["DetalleVenta<br/>cantidad > 0 · descuento ≤ tope · precio editado solo sube"]
        V -->|"contiene y protege"| D
    end
    COMP["Comprobante<br/>(agregado de facturacion)"] -.->|"referencia por venta"| V
    COB["Cobro → DetalleCobro<br/>(agregado de cobranza)"] -.->|"referencia por venta"| V
    MAN["Mantenimiento<br/>(postventa)"] -.->|"referencia por venta"| V
    PROD["Producto<br/>(catalogo)"] -.->|"referenciado por la línea"| D
    EXT["Cualquier otro módulo"] -->|"solo a través de VentaService"| V
    EXT -.->|"prohibido: modificar una línea directo"| D

8. Esquema inicial del modelo de dominio

Sin atributos ni operaciones todavía; eso es S7.

flowchart LR
    subgraph MVEN["ventas: agregado"]
        VEN[Venta] --- DET[DetalleVenta]
    end
    subgraph MFAC["facturacion"]
        COMP[Comprobante] --- NC[NotaCredito]
    end
    subgraph MCOB["cobranza"]
        COB[Cobro] --- DC[DetalleCobro]
    end
    subgraph MCAT["catalogo"]
        PROD[Producto]
    end
    subgraph MCLI["clientes"]
        CLI[Cliente]
    end
    PROD -.->|"referenciado por"| DET
    CLI -.->|"referenciado por"| VEN
    VEN -.->|"referenciada por"| COMP
    VEN -.->|"referenciada por"| DC

Son los mismos módulos que la vista C3 de S2. No son contenedores: siguen dentro de un solo backend (ADR-S4-01).

9. Integración con BD2 y LP2

Decisión de dominio Evidencia en BD2 Evidencia en LP2
Agregado Venta–DetalleVenta FK DETALLE_VENTA.VENTA_ID (sin índice hasta BD2 S5); SP_REGISTRAR_VENTA en una transacción (S1) @Transactional en VentaService; Venta.detalles con cascada
Una venta anulada es definitiva TRG_VENTA_ESTADO_BU (S2) VentaService.anular (409 si ya está anulada)
Un comprobante vigente por venta UX_COMPROBANTE_VIGENTE_VENTA, que evitó 2 621 duplicados en la prueba de ADS S4 FacturacionService.emitirAlRegistrar
Stock nunca negativo CK_PRODUCTO_STOCK (S1) ProductoService.descontarStock con bloqueo
Voucher único IX_COBROS_REFERENCIA_NORM (S5) CobroRepository.vigentesConReferencia
Objeto de valor Dinero NUMBER(12,2) y MONEDA con CHECK No existe todavía: BigDecimal y Moneda sueltos

10. Error o hallazgo

Hallazgo 1: un módulo Core apareció tarde. La primera tabla de módulos del proyecto tenía 12 módulos. El de servicios técnicos (órdenes de trabajo, sedes, equipos instalados, contratos) se agregó recién el 28/10/2026, como módulo 13. Todavía figura en el README con "Responsable: Por asignar". Pasó porque el equipo empezó por las entidades (Producto, Venta, Cliente, heredadas de BomERP) y no por el recorrido del cliente. En el recorrido (sección 1), "instalar y atender" está entre vender y mantener, y es imposible saltárselo. Ese módulo trajo consigo reglas que tocaron módulos ya cerrados: detracción y retención en Ventas y en Cobranza, y ventas que facturan órdenes de trabajo (13 de 58). Con el panorama primero, habría estado en el diseño desde el inicio.

Hallazgo 2: la conclusión de BomERP sobre los pagos no vale para JD. En la guía, Pago se compone dentro de Venta: no existe sin ella, pertenece a una sola y cambia con ella. En JD falla la cardinalidad. Un cobro se puede repartir entre varias ventas (DetalleCobro), y 82 de 99 ventas cobradas se pagaron en varios cobros. Si se compusiera dentro de Venta, el caso real "el cliente paga tres facturas con una transferencia" sería imposible de registrar. Por eso Cobranza es un módulo propio. Un matiz: en los datos de prueba ningún cobro reparte entre varias ventas (0 de 222). La regla sale del requisito (RF de cobranza), no de los datos, y conviene que el próximo juego de datos lo incluya.

Hallazgo 3: los límites del agregado son solo una convención en el código. DetalleCobro, Comprobante y EquipoInstalado referencian a la venta con @ManyToOne Venta, es decir, con la entidad completa, no con su identificador. El modelo de dominio dice "se referencia", pero el código permite que Cobranza tenga la venta cargada y llame venta.setEstado(…) sin pasar por la raíz. Es la misma fuga de abstracción que encontró S3. En DDD, entre agregados se referencia por identidad (ventaId). Queda para S8, el diseño por capas.

11. Reflexión

¿Por qué empezar por el panorama holístico, en vez de por las entidades, reduce el riesgo de descubrir tarde un módulo completo?

Porque las entidades se descubren desde lo que ya se conoce, y lo que no se conoce no tiene entidad todavía. El equipo empezó por Producto, Venta y Cliente, porque eran las de BomERP, y desde ahí no había forma de "ver" las órdenes de trabajo: no salen de ninguna tabla existente. El panorama, en cambio, recorre lo que hace el negocio de punta a punta, y en JD nadie puede contar cómo funciona sin decir "y después vamos a instalarlo al local del cliente". Recorrer el negocio obliga a nombrar cada paso, aunque todavía no se sepa qué datos tiene. En SGE-JD, saltarse ese paso costó agregar un módulo Core a mitad del proyecto, con cambios en ventas y cobranza que ya estaban cerrados.