14.3 UML: elegir y auditar el diagrama que hace falta

Al terminar esta lección

• Elegir el tipo de diagrama según la pregunta que tiene que responder, y descartar el diagrama cuando la pregunta se responde mejor con prosa o una tabla.
• Auditar un diagrama de casos de uso, de clases, de secuencia, de estados o de despliegue contra su semántica, no contra su apariencia.
• Distinguir una dependencia de una asociación, una composición de una asociación, y un include de un extend.
• Detectar cuándo un mensaje o un estado descubre una regla que tiene que volver a la especificación.
• Explicar por qué un diagrama de capas o de C4 no es UML aunque se parezca a uno.

Antes de dibujar: la pregunta

Un diagrama responde una pregunta. Si no podés escribir la pregunta en una frase, no lo dibujes. "Mostrar la arquitectura" no es una pregunta. "¿Qué pasa en la base cuando dos pedidos compiten por la última unidad?" sí lo es, y tiene un diagrama de secuencia como respuesta natural.

Antes de elegir el tipo de diagrama, el árbol de decisión:

Practicá la elección. Cada frase de la lista tiene un diagrama natural, y una de ellas no necesita ninguno.

Un diagrama que no responde una pregunta concreta decora el documento. Compará los dos tipos de diagrama que más se usan por decoración:

Apéndice C · UML como herramienta, no como protagonista

C.1 Qué es obligatorio, cuándo aplica y qué es avanzado

No existe un diagrama UML obligatorio para todo proyecto. Lo que sí es obligatorio es resolver la frontera del sistema, el comportamiento, la arquitectura y el despliegue, al nivel de detalle que el riesgo exige. Un diagrama es una forma de resolver una de esas cuatro cosas, no un entregable en sí mismo.

Cuándo aplica cada uno:

• Casos de uso UML cuando la frontera, los actores o los objetivos son ambiguos. Si ya están claros en una lista, el diagrama repite la lista.
• Diagrama de despliegue cuando la topología, los nodos, los protocolos o los artefactos importan para una decisión, por ejemplo si el worker puede correr en el mismo proceso que la API.
• Diagrama de estados cuando el ciclo de vida gobierna qué operaciones están permitidas.

Avanzado, y solo si reduce una ambigüedad concreta: clases de diseño, secuencia de una interacción compleja, componentes. Un diagrama de clases de diseño con todos los métodos de cada clase casi nunca reduce ninguna ambigüedad: reproduce el código.

C.2 Casos de uso: frontera, actores y relaciones

Un caso de uso describe un objetivo de un actor frente al sistema. El diagrama muestra la frontera y las relaciones entre objetivos. No muestra el orden de los pasos; para eso está la especificación o la secuencia.

Auditoría:

• Un actor es un rol externo. "Vendedor" sí; "pantalla de pedido", "tabla de clientes" o "Juan, el vendedor de la zona norte" no.
• «include» va desde el caso base hacia el caso que siempre ocurre dentro de él. Es una dependencia discontinua.
• «extend» va desde el caso que agrega comportamiento opcional hacia el caso base, bajo una condición explícita. El caso base se completa sin él.
• La generalización usa flecha triangular hueca desde el especializado hacia el general.
• Las relaciones no expresan orden temporal. Si dibujás una flecha de "después de", estás escribiendo una secuencia en otro lugar.

Ejemplo con Nexo, con la forma del caso validado en la lección 5.3. Mermaid no tiene diagrama de casos de uso nativo, así que lo representamos con un flowchart. La semántica de las flechas es la del UML, no la del diagrama:

Lectura: CU-01 incluye evaluar crédito y reservar stock porque ocurren siempre que se registra un pedido. CU-02 extiende CU-01 porque solo ocurre cuando el pedido queda pendiente de autorización. CU-04 extiende CU-03 solo cuando hay un faltante físico. La autorización no es "un paso más" del registro; es una excepción con su propio actor.

Antipatrón típico: un «include» desde CU-02 hacia CU-01 porque "la autorización necesita el pedido". La dirección está invertida: CU-02 depende del pedido, pero es el pedido el que puede o no necesitarla. Corregirlo cambia el significado: el pedido confirmado sin autorización sigue siendo un caso completo.

C.3 Clases de dominio: composición, asociación y dependencia

El modelo conceptual muestra las entidades del negocio y las relaciones que importan para una regla. No es el modelo de la base de datos. Evitá IDs técnicos, columnas y timestamps de auditoría, salvo que el negocio los nombre como concepto.

Auditoría:

• Las multiplicidades se escriben en ambos extremos cuando aportan una regla. Copiar la cardinalidad de una clave foránea sin semántica produce 1..* donde el negocio admite cero.
• La composición (rombo relleno) solo corresponde cuando el ciclo de vida del todo gobierna la parte: una línea de pedido no existe sin pedido.
• La navegabilidad (la punta de flecha) se agrega solo cuando el acceso en una dirección es relevante para una regla.
• Una dependencia (flecha punteada) no sustituye una asociación persistente. Si una reserva referencia un depósito y se guarda en la base, es una asociación.

Modelo de dominio de Nexo, con las entidades de la figura 7 del manual:

Lectura: la composición entre Pedido y LineaPedido está justificada porque una línea no tiene sentido sin su pedido. Producto no es compuesto por la línea: el catálogo existe antes y sigue existiendo después. Eso es una asociación.

Caso frecuente: el alumno ve que una línea tiene un producto y dibuja un rombo relleno de Producto a LineaPedido, porque "el producto contiene la línea". La prueba es preguntar qué pasa cuando se borra el pedido. Si el producto sigue existiendo, no hay composición.

C.4 Secuencia: el orden de los mensajes

Un diagrama de secuencia responde a una pregunta sobre el orden. Participantes en horizontal, tiempo de arriba hacia abajo, mensajes con dirección y nombre. Las activaciones solo se agregan cuando clarifican quién ejecuta qué.

Auditoría:

• Cada mensaje tiene dirección y nombre. Los retornos se dibujan con flecha punteada solo cuando aportan información.
• Los fragmentos alt, opt y loop tienen condiciones explícitas. Un alt sin condición es una suposición.
• Un mensaje que descubre una regla nueva ("el precio se recalcula después de la reserva") vuelve a la especificación antes de cambiar el diagrama.

CU-01 con la secuencia del orden validado: precio, crédito y reserva dentro de la misma transacción. Las dos ramas de la decisión de crédito son las que más se omiten:

Lectura: la rama de conflicto no crea un segundo pedido. El diagrama permite verificar el test T08 antes de escribirlo: con el mismo requestId y otro contenido, la única salida es el conflicto y ningún efecto nuevo. Si en la rama de crédito rechazado no aparece el ROLLBACK, el diagrama está mal, no el sistema.

C.5 Estados: ciclo de vida de un pedido

Un diagrama de estados responde qué operaciones están permitidas en cada condición. Los estados representan condiciones relevantes del negocio, no pantallas. Las transiciones usan evento, guard y acción cuando corresponde.

Auditoría:

• Nodo inicial negro. Nodo final cuando el ciclo realmente termina.
• Un estado llamado "PantallaConfirmacion" o "FormularioDeCarga" describe una interfaz. El estado es "pendiente de autorización", que puede durar un día y sobrevivir a cualquier pantalla.
• Revisá alcanzabilidad: todo estado tiene que poder alcanzarse, y ninguna transición puede llevar a un estado que la especificación prohíbe.
• Cada transición que depende de una regla dice cuál.

Reconstrucción del ciclo del pedido para el slice. Los estados son los de la figura 9 del manual; las transiciones son una reconstrucción a partir de los eventos del canon (autorizar, reservar, preparar, facturar):

Lectura: no hay transición desde PENDIENTE_AUTORIZACION hacia DESPACHADO. Esa ausencia es la regla. La expiración automática de la reserva blanda no aparece porque su TTL todavía es BLOCKED (RN-07): dibujarla sería inventar la política.

C.6 Despliegue: nodos, artefactos y comunicación

Un diagrama de despliegue responde qué corre dónde y cómo se comunican las partes. Los nodos y entornos se distinguen de los artefactos desplegados en ellos. Las líneas son caminos de comunicación con su protocolo.

Auditoría:

• No mezcles un componente lógico con un servidor físico por comodidad. El worker es un proceso; puede correr en un nodo, pero no es el nodo.
• Cada línea tiene protocolo o tipo de comunicación. Una línea sin etiqueta no dice nada que no diga la presencia de la conexión.
• Si el dibujo muestra capas, contexto o componentes sin nodos ni protocolos, es otro tipo de diagrama. Etiquetalo como tal.

Topología del primer release de Nexo. Mermaid no tiene diagrama de despliegue UML; esta es una representación con flowchart, y las líneas llevan los protocolos del canon:

Lectura: la base es compartida entre la API y el worker, y es el único lugar donde se compromete una reserva. El proveedor fiscal se alcanza solo desde el worker, nunca desde la transacción del pedido. Esa es la decisión que el diagrama hace visible.

Antipatrón: poner el outbox "en el servidor de aplicación" como si fuera un nodo más. El outbox es una tabla en la misma base; el proceso que lo drena es el worker. Dibujarlo como nodo oculta que la consistencia depende de la base.

C.7 Antipatrones

• Síntoma: el diagrama tiene veinte cajas y ninguna pregunta. Causa: se dibujó para "documentar". Corrección: escribir la pregunta primero y borrar todo lo que no ayude a responderla.
• Síntoma: el actor es "la pantalla de pedidos". Causa: se modeló la interfaz en lugar del rol. Corrección: el actor es quien persigue el objetivo ("Vendedor"); la pantalla es un detalle de implementación.
• Síntoma: todas las entidades están unidas con composición. Causa: se confunde "tiene" con "no existe sin". Corrección: aplicar la prueba del borrado: si el todo se borra y la parte sigue teniendo sentido, es asociación.
• Síntoma: la secuencia tiene un mensaje "validar regla" sin dirección ni condición. Causa: se usó el diagrama para esconder una decisión. Corrección: llevar la regla a la especificación, con su ID, y referenciarla en el mensaje.
• Síntoma: el diagrama de estados tiene un estado "Pantalla de confirmación". Causa: se modelaron las pantallas en lugar de las condiciones del negocio. Corrección: reemplazarlo por la condición real, por ejemplo CONFIRMADO, y dejar la pantalla fuera.

Diagrama con defectos. Es el modelo de dominio de un alumno. Hay cinco líneas que no deberían estar así:

Errores frecuentes

• Síntoma: el documento tiene un diagrama de clases de diseño con todos los métodos. Causa: se confundió el modelo con el código. Corrección: mantener solo las entidades y relaciones que una regla necesita.
• Síntoma: el caso de uso "Autorizar crédito" aparece como base de "Registrar pedido" con un include. Causa: se invirtió la dirección de la dependencia. Corrección: revisar la dirección con la prueba de la lección, o con C.2.
• Síntoma: el diagrama de despliegue tiene un nodo "Outbox". Causa: se dibujó un componente lógico como si fuera un servidor. Corrección: el outbox es tabla; el worker es el nodo o proceso.
• Síntoma: un diagrama de estados sin transiciones desde un estado terminal. Causa: se dibujó la transición ideal, no la prohibida. Corrección: listar explícitamente qué no puede pasar, y verificarlo con una prueba de transición ilegal (T11).

Repasá las distinciones que más confunden:

Para llevarte

• Escribí la pregunta antes que el diagrama. Si no hay pregunta, no hay diagrama.
• Un actor es un rol externo, no una pantalla ni una tabla.
• Composición solo cuando el ciclo de vida del todo gobierna la parte.
• Los estados son condiciones del negocio, no pantallas. Las transiciones prohibidas valen tanto como las permitidas.
• Cada línea de un despliegue tiene un protocolo. Si no lo tiene, no es un diagrama de despliegue.
• Un mensaje que descubre una regla nueva vuelve a la especificación antes de cambiar el diagrama.