ADS · S9 · Diagramas dinámicos del módulo cobranza¶
SGE-JD · JD Refrigeración S.A.C. · Equipo CherryTree · Yoel Wagner Chambi Sirena · 10/11/2026
Trabajo autónomo de la sesión 9 (Diagramas dinámicos UML). Se usa el módulo diseñado en S8, y solo con las clases que existen en su diagrama. Las dos que faltaban se agregaron allá primero (hallazgo 1).
1. ¿Qué operación necesita un diagrama dinámico?¶
Las cuatro señales de la Tabla 2 de la guía, aplicadas a todas las operaciones del módulo:
| Operación | Bucle | Condiciones combinadas | Colaboración entre módulos | Transaccional | ¿Diagrama dinámico? |
|---|---|---|---|---|---|
porCobrar(clienteId) |
Sí (una fila por venta pendiente) | No | Sí (lee ventas) | No (solo lectura) | No: es una consulta; la ficha de S8 y el DTO CuentaPorCobrarResponse la describen completa |
historial(clienteId, ventaId) |
No | No | No | No | No: un filtro sobre el repositorio |
pagadoDeVenta(ventaId) |
No | No (un 404) | No | No | No: una suma y un error posible caben en una fila |
registrar(request, usuario) |
Sí (una vuelta por abono) | Sí (cliente, moneda, fecha, saldo, deducción, voucher) | Sí (clientes y ventas) | Sí (cobro y estado de las ventas, juntos) | Sí: las cuatro señales y 8 reglas que pueden rechazarla |
anular(id, motivo, usuario) |
Sí (una vuelta por abono) | Sí (ya anulado, motivo, venta anulada) | Sí (volverAPendiente) |
Sí | Sí, también las cuatro. Se elige registrar porque tiene más reglas que fallan (8 frente a 3); anular se cubre con el ciclo de vida (sección 4) |
registrarDevolucion(id, request) (otro agregado) |
No | Sí (estado, método) | No | Sí | No: sus dos condiciones están en la ficha de S8 |
2. Diagrama de secuencia: registrar un cobro¶
Las clases son las de S8: CobranzaController, CobranzaServiceImpl, ClienteService, CobroRepository,
VentasParaCobranza (que devuelve VentaParaCobro), CobroMapper y Cobro. Hay un fragmento alt por cada
regla que puede rechazar la operación (RN1 a RN6 de S8).
sequenceDiagram
autonumber
actor Lucy as Lucy (SPA)
participant CC as CobranzaController
participant CS as CobranzaServiceImpl
participant CL as ClienteService
participant CR as CobroRepository
participant VP as VentasParaCobranza
participant M as CobroMapper
participant C as Cobro
Lucy->>CC: POST /cobranza/cobros (CobroRequest)
alt forma inválida (@Valid: sin abonos, monto ≤ 0, sin método)
CC-->>Lucy: 400
end
CC->>CS: registrar(request, usuario del token)
CS->>CL: obtenerResumen(clienteId)
alt cliente no existe
CL-->>CS: RecursoNoEncontradoException
CS-->>CC: 404
end
alt RN5: fecha futura
CS-->>CC: 400
else RN6: detracción o retención sin N° de constancia
CS-->>CC: 400
else RN4: una venta repetida en el cobro
CS-->>CC: 400
end
CS->>CR: vigentesConReferencia(metodo, referencia)
alt RN3: el voucher ya se registró
CS-->>CC: 409 (indica el cobro anterior)
end
loop por cada ventaId, ordenados de menor a mayor
CS->>VP: bloquearParaCobro(ventaId)
VP-->>CS: VentaParaCobro (fila bloqueada hasta el fin de la transacción)
end
CS->>C: nuevo(cliente, fecha, moneda, método, referencia, usuario)
loop por cada abono
alt RN1: otro cliente u otra moneda que el cobro
CS-->>CC: 400
else RN5: fecha del cobro anterior a la venta
CS-->>CC: 400
end
CS->>CR: totalCobradoDeVenta(ventaId)
CR-->>CS: cobrado
alt RN2: monto > total − cobrado
CS-->>CC: 409 (saldo de la venta)
end
CS->>M: toAbono(abono, venta)
M-->>CS: Abono (con documentoVenta copiado)
CS->>C: agregarAbono(abono)
end
CS->>CR: save(cobro)
loop por cada venta cuyo saldo quedó en 0
CS->>VP: marcarPagada(ventaId)
end
CS->>M: toResponse(cobro)
CS-->>CC: CobroResponse
CC-->>Lucy: 201
¿Hace falta par? No. Dentro de un cobro no ocurre nada en paralelo: cada paso espera al anterior, y el
save y los marcarPagada están en la misma transacción. La concurrencia real está entre dos cobros
distintos. La resuelve el bloqueo ordenado de las ventas (RN8), y es un caso entre peticiones, no dentro de esta
secuencia. Eso sí, este diagrama dejó ver un hueco en esa concurrencia (hallazgo 2).
Orden de los mensajes. Todo lo que se puede rechazar sin tocar la base (forma, fecha, deducción, repetidas) va antes del primer bloqueo. Rechazar después de bloquear las ventas haría esperar a otro usuario por una petición que igual iba a fallar.
3. Diagrama de actividades, por carriles¶
Los rombos son los mismos alt de la secuencia.
flowchart TB
subgraph L1["Lucy (SPA)"]
A1([Elige cliente, ventas y montos]) --> A2[Envía el cobro]
Z1([Ve el recibo])
Z2([Ve el error y corrige])
end
subgraph L2["Backend · cobranza"]
B1{¿Forma válida?} -->|no| E400a[400]
B1 -->|sí| B2{¿Cliente existe?}
B2 -->|no| E404[404]
B2 -->|sí| B3{¿Fecha no futura,<br/>constancia si es deducción,<br/>sin ventas repetidas?}
B3 -->|no| E400b[400]
B3 -->|sí| B4{¿Voucher nuevo?}
B4 -->|no| E409a[409]
B4 -->|sí| B6[Crea el cobro]
B6 --> B7{¿Mismo cliente y moneda,<br/>fecha ≥ la de la venta?}
B7 -->|no| E400c[400]
B7 -->|sí| B8{¿Monto ≤ saldo?}
B8 -->|no| E409b[409]
B8 -->|sí| B9[Agrega el abono]
B9 --> B10{¿Quedan abonos?}
B10 -->|sí| B7
B10 -->|no| B11[Guarda el cobro]
end
subgraph L3["Módulo ventas"]
V1[Bloquea las ventas en orden de ID]
V2[Marca PAGADO las de saldo 0]
end
A2 --> B1
B4 -->|sí| V1 --> B6
B11 --> V2 --> Z1
E400a & E404 & E400b & E409a & E400c & E409b --> Z2
| Rombo | alt de la secuencia |
Regla |
|---|---|---|
| ¿Forma válida? | forma inválida | @Valid |
| ¿Cliente existe? | cliente no existe | 404 |
| ¿Fecha, constancia, repetidas? | RN5 / RN6 / RN4 | 400 |
| ¿Voucher nuevo? | RN3 | 409 |
| ¿Mismo cliente y moneda, fecha ≥ venta? | RN1 / RN5 | 400 |
| ¿Monto ≤ saldo? | RN2 | 409 |
4. ¿Necesita un diagrama de ciclo de vida?¶
Cobro: no. Tiene dos estados (VIGENTE y ANULADO) y una sola transición, que no se deshace. Su condición
(motivo de 5 caracteres o más, que la venta no esté anulada) ya está en la ficha de S8 y en CK_COBRO_ANULADO. Un
diagrama no diría nada que una fila de tabla no diga.
Venta.estadoPago: sí. Es el estado que cobranza cambia en otro módulo. Su continuidad depende de
operaciones que ocurren en momentos distintos (vender, cobrar, anular un cobro), y ninguna de ellas lo ve completo:
stateDiagram-v2
[*] --> PAGADO : venta al contado
[*] --> PENDIENTE : venta a crédito
PENDIENTE --> PAGADO : un cobro deja el saldo en 0 (registrar, RN7)
PAGADO --> PENDIENTE : se anula un cobro que la había pagado (anular, RN9)
PAGADO --> [*] : la venta se anula (queda la devolución en Cobranza)
PENDIENTE --> [*] : la venta se anula
Se quitó una transición: el enum y la CHECK de Oracle admiten un tercer estado, ATRASADO, pero ninguna
línea del backend lo asigna (grep ATRASADO en src/main: solo aparece la declaración del enum). El atraso se
calcula cada vez a partir de fechaLimitePago (diasAtraso en CuentaPorCobrarResponse). Dibujar
PENDIENTE → ATRASADO habría sido modelar una regla que no existe (hallazgo 3).
5. Interacción entre componentes (nivel C3)¶
Solo módulos completos, y solo los mensajes que cruzan un límite:
sequenceDiagram
participant SPA as SPA
participant COB as cobranza
participant CLI as clientes
participant VEN as ventas
SPA->>COB: POST /cobranza/cobros
COB->>CLI: obtenerResumen(clienteId)
loop por cada venta
COB->>VEN: bloquearParaCobro(ventaId)
VEN-->>COB: VentaParaCobro
end
loop por cada venta con saldo 0
COB->>VEN: marcarPagada(ventaId)
end
COB-->>SPA: 201 CobroResponse
Desaparecen CobroRepository, CobroMapper y Cobro: son internos de cobranza. Lo que queda es el contrato
entre módulos: dos operaciones de VentasParaCobranza y una de ClienteService. Si mañana ventas cambia por
dentro, este diagrama no cambia.
6. Diagrama de comunicación¶
La misma colaboración, con los mensajes numerados (los abonos se repiten por venta: 5.n, 6.n):
flowchart LR
Lucy((Lucy))
CC[CobranzaController]
CS[CobranzaServiceImpl]
CL[ClienteService]
CR[CobroRepository]
VP[VentasParaCobranza]
M[CobroMapper]
C[Cobro]
Lucy -- "1: registrar(CobroRequest)" --> CC
CC -- "2: registrar(request, usuario)" --> CS
CS -- "3: obtenerResumen(clienteId)" --> CL
CS -- "4: vigentesConReferencia(metodo, ref) · 7.n: totalCobradoDeVenta(ventaId) · 10: save(cobro)" --> CR
CS -- "5.n: bloquearParaCobro(ventaId) · 11.n: marcarPagada(ventaId)" --> VP
CS -- "6: nuevo(...) · 9.n: agregarAbono(abono)" --> C
CS -- "8.n: toAbono(abono, venta) · 12: toResponse(cobro)" --> M
7. Matriz de consistencia¶
Cada mensaje se cruza con la ficha de su clase en S8, más las operaciones que quedaron sin diagrama.
| # | Mensaje | Clase (S8) | ¿Está en su ficha? | Observación |
|---|---|---|---|---|
| 1 | registrar(CobroRequest) |
CobranzaController |
✓ | 201 y @Valid |
| 2 | registrar(request, usuario) |
CobranzaService |
✓ | El usuario sale del token, no del Request |
| 3 | obtenerResumen(clienteId) |
ClienteService |
✓ | |
| 4 | vigentesConReferencia(metodo, ref) |
CobroRepository |
✓ | Ver hallazgo 2: sin bloqueo |
| 5 | bloquearParaCobro(ventaId) → VentaParaCobro |
VentasParaCobranza |
✓ después de corregir S8 | VentaParaCobro no estaba en el diagrama de S8 (hallazgo 1) |
| 6 | nuevo(...) |
Cobro |
✓ | Constructor de fábrica |
| 7 | totalCobradoDeVenta(ventaId) |
CobroRepository |
✓ | Base del saldo (RN2) |
| 8 | toAbono(abono, venta) |
CobroMapper |
✓ | Copia documentoVenta |
| 9 | agregarAbono(abono) |
Cobro |
✓ | |
| 10 | save(cobro) |
CobroRepository |
✓ | Spring Data |
| 11 | marcarPagada(ventaId) |
VentasParaCobranza |
✓ | RN7, misma transacción |
| 12 | toResponse(cobro) |
CobroMapper |
✓ | |
| — | saldo(ventaId) |
VentasParaCobranza (tabla de refinamiento de S8) |
✗ inconsistencia | Estaba en la tabla y no en el diagrama. Resuelto: el saldo lo calcula cobranza (mensajes 5 y 7); se quitó de la tabla de S8 |
| — | porCobrar, historial, pagadoDeVenta |
CobranzaService |
✓ | Sin diagrama (sección 1): consultas |
| — | anular(id, motivo, usuario) |
CobranzaService |
✓ | Sin secuencia; su efecto en otro módulo está en el ciclo de vida (PAGADO → PENDIENTE) |
| — | volverAPendiente(ventaId) |
VentasParaCobranza |
✓ | Solo lo usa anular |
| — | registrarDevolucion |
DevolucionService |
✓ | Otro agregado; sin diagrama |
| — | EstadoPago.ATRASADO |
Venta (módulo ventas) |
✗ inconsistencia | Declarado y admitido por la CHECK, nunca asignado (hallazgo 3) |
8. Error o hallazgo¶
Hallazgo 1: la secuencia necesitaba una clase que el diagrama de S8 no tenía. Al dibujar el mensaje 5,
bloquearParaCobro tenía que devolver algo con el total, el cliente, la moneda y el estado de la venta. En S8 ese
tipo aparecía nombrado en la ficha del mapper (toAbono(AbonoRequest, VentaParaCobro)), pero no como clase en
el diagrama. Además, la tabla de refinamiento le atribuía a VentasParaCobranza una operación saldo que el
diagrama no tenía. Siguiendo la regla de la guía, no se inventó nada dentro de la secuencia: se volvió a S8, se
agregó el record VentaParaCobro y se corrigió la tabla. El saldo lo calcula cobranza, porque solo ella conoce los
abonos.
Hallazgo 2: el orden de los mensajes dejó ver una condición de carrera. El mensaje 4
(vigentesConReferencia) comprueba que el voucher no exista con una consulta, sin bloqueo, y el bloqueo
(mensaje 5) es sobre las ventas, no sobre el voucher. Si dos personas registran a la vez el mismo N° de
operación para ventas distintas, las dos consultas ven "no existe", ninguna espera a la otra, y entran dos cobros
con el mismo voucher. El código actual hace lo mismo (CobranzaService.registrar: primero la consulta y después el
bloqueo de las ventas). En la base no hay nada que lo impida: el índice de BD2 S5 sobre
UPPER(TRIM(referencia)) no es único. Corrección propuesta, con el mismo patrón que ya protege a los
comprobantes (UX_COMPROBANTE_VIGENTE_VENTA):
CREATE UNIQUE INDEX ux_cobro_voucher_vigente ON cobros (
CASE WHEN estado = 'VIGENTE' AND referencia IS NOT NULL THEN metodo_pago END,
CASE WHEN estado = 'VIGENTE' AND referencia IS NOT NULL THEN UPPER(TRIM(referencia)) END);
La consulta del mensaje 4 se queda, para dar un mensaje claro al usuario. El índice garantiza la regla aunque dos peticiones lleguen juntas. El diagrama de clases de S8 no podía mostrar esto, porque ahí la regla RN3 parecía completa.
Hallazgo 3: una transición sin regla real. El primer borrador del ciclo de vida de estadoPago tenía
PENDIENTE → ATRASADO "cuando vence la fecha límite". Al buscar quién hace esa transición, no la hace nadie:
ATRASADO solo existe en la declaración del enum y en la CHECK de VENTAS. El atraso se calcula al consultar.
Se quitó del diagrama. Queda como inconsistencia en la matriz: o se elimina el valor, o se le da una regla y una
tarea que lo asigne.
9. Reflexión¶
¿Qué decisión de orden o de continuidad de estado no se veía en el diagrama de clases y apareció recién en la secuencia o en el ciclo de vida? Relación con el caso del vehículo autónomo de Uber.
En el diagrama de clases de S8, la regla "el voucher no entra dos veces" parecía resuelta: una consulta en el
repositorio y un 409. Solo al poner los mensajes en orden se vio que esa comprobación ocurre antes del bloqueo y
sobre otra cosa (las ventas), y que dos peticiones simultáneas la pasan las dos. En el caso de Uber, el sistema
detectó el obstáculo varios segundos antes, pero cada vez que cambiaba de clasificación descartaba la historia de
lo que había visto, y la decisión de frenar llegó tarde. Cada componente estaba "bien" por separado: el problema
estaba en el orden y en la continuidad del estado entre un momento y el siguiente. Lo mismo pasa con estadoPago
de la venta: lo cambian tres operaciones en momentos distintos, y solo el diagrama de estados mostró que una de sus
transiciones, ATRASADO, no la ejecutaba nadie.