System Design
Glosario y lenguaje del dominio
Explica cómo construir un lenguaje compartido con definiciones operativas, contextos, ejemplos y owners para alinear negocio, APIs, datos y código.
- Última actualización
- Actualizada
- Nivel
- Fundamentos
System Design
Explica cómo construir un lenguaje compartido con definiciones operativas, contextos, ejemplos y owners para alinear negocio, APIs, datos y código.
El lenguaje del dominio no es un glosario de sinónimos. Es el contrato semántico que permite que negocio, diseño, datos, APIs y código hablen de la misma realidad sin traducirla de forma diferente en cada capa.
Un equipo puede implementar correctamente una definición equivocada. Palabras como pedido, venta, reserva, stock, cliente activo o cancelado suelen parecer obvias hasta que dos áreas las usan con significados distintos.
misma palabra + significados distintos
→ requisitos ambiguos
→ modelos contradictorios
→ reglas duplicadas
→ errores difíciles de detectarEl glosario hace explícito el significado operacional de los conceptos. El lenguaje ubicuo lleva ese significado a conversaciones, diagramas, nombres de eventos, APIs, base de datos y código.
Imagina que operaciones dice “stock disponible” refiriéndose a existencia física, mientras ventas descuenta reservas y soporte muestra una cifra en caché. Las tres pantallas pueden estar “bien programadas” y aun así producir decisiones incompatibles.
Sin lenguaje común aparecen problemas como:
venta y otra pedido como equivalentes.completed, pero negocio distingue pagado, preparado y entregado.customers, aunque también contiene prospectos y proveedores.realidad del negocio
→ conceptos
→ definiciones operativas
→ reglas y relaciones
→ nombres consistentes en artefactosUna definición operacional permite decidir casos reales. No basta con “un pedido es una solicitud del cliente”. Debe aclarar cuándo nace, qué contiene, quién puede modificarlo y cuándo deja de ser pedido pendiente.
El mismo concepto puede tener varias representaciones, pero estas no deberían cambiar su significado central.
Ejemplo:
Concepto: Pedido confirmado
UI: “Pedido aceptado”
Evento: OrderConfirmed
Estado almacenado: confirmedLa etiqueta puede adaptarse a la audiencia, pero la transición y sus garantías deben seguir siendo coherentes.
Extrae términos de entrevistas, documentos, hojas de cálculo, tickets y conversaciones. No inventes primero nombres técnicos.
Pregunta:
Debe indicar qué representa y, cuando corresponda, cómo se reconoce.
Stock físico
→ unidades registradas como presentes en una sucursal.
Stock reservado
→ unidades comprometidas con operaciones aún no finalizadas.
Stock vendible
→ cantidad que puede asignarse a nuevas ventas según reglas vigentes.Los contraejemplos revelan mejor los límites.
Pedido cancelado
Sí: operación anulada antes de entrega.
No: pedido entregado que posteriormente genera devolución.Cuando exista disputa, alguien debe tener autoridad para decidir el significado. Puede ser producto, operaciones, legal o un grupo interdisciplinario.
Actualiza requisitos, diagramas, contratos y nombres nuevos. No es útil mantener un glosario perfecto mientras el código usa otra terminología.
| Término | Definición operacional | No significa | Ejemplo | Owner |
|---|---|---|---|---|
| Stock vendible | Unidades que pueden comprometerse a una venta nueva | Existencia física total | 10 físicas − 2 reservadas = 8 | Inventario |
| Pedido confirmado | Pedido aceptado por la sucursal y con compromiso operativo | Pedido ya entregado | La sucursal acepta preparar 3 productos | Operaciones |
Domain-Driven Design propone usar un lenguaje compartido dentro de cada contexto. No es necesario adoptar todo DDD para aprovechar la idea.
La precisión importante es dentro de un contexto. Una palabra puede significar algo distinto en facturación y logística, siempre que la frontera sea explícita.
Facturación: cliente = entidad responsable de pago
Logística: cliente = destinatario de entregaForzar una definición global puede ser tan dañino como aceptar ambigüedad. Cuando los modelos difieren genuinamente, documenta contextos y traducciones.
Intención o solicitud que atraviesa un ciclo de aceptación.
Operación comercial reconocida según reglas del negocio; puede requerir confirmación o pago.
Proceso y resultado logístico de llevar bienes a un destino.
Estas entidades pueden relacionarse, pero no necesariamente son una sola:
pedido
→ puede rechazarse y nunca convertirse en venta
venta
→ puede existir con entrega pendiente
entrega
→ puede reintentarse sin duplicar la ventaModelarlas como un único estado enorme suele mezclar responsabilidades y producir transiciones imposibles.
El lenguaje debe distinguir:
pending.OrderConfirmed.ConfirmOrder.Nombrar un comando como evento puede hacer creer que algo ocurrió antes de validarlo.
order_id, order_number y referencia externa pueden representar cosas distintas:
El glosario evita usarlos indistintamente en soporte o integraciones.
El lenguaje cambia cuando el equipo aprende. Ese cambio debe gestionarse:
Renombrar customer a account puede ser cosmético o revelar una entidad distinta. No lo trates automáticamente como refactor superficial.
Separa contextos o crea nombres calificados: billing_account, delivery_recipient.
Una regla como “cliente activo” puede cambiar por fecha. Incluye vigencia y criterio.
Crea una capa de traducción; no dejes que el modelo externo invada todo el dominio.
Conserva precisión regulatoria y adapta presentación sin perder trazabilidad.
Evita seguir propagándolo solo porque existe en la base de datos.
“Una venta es una venta registrada”. No permite decidir nada. Corrige indicando condiciones y consecuencias.
Sucede cuando está aislado. Revisa nombres en talleres, PRs, contratos y modelos.
Una tabla heredada puede estar mal nombrada. El esquema existente es evidencia, no autoridad semántica.
Ignora contextos distintos. Define fronteras y traducciones.
admin técnico no describe necesariamente una responsabilidad de negocio.
Prueba cada definición con preguntas:
Un buen taller utiliza escenarios conflictivos, no solo aprobación verbal.
Es especialmente valioso cuando hay múltiples áreas, regulación, integraciones, vocabulario heredado o dominio complejo. En un sistema pequeño todavía conviene registrar los términos que afectan reglas y datos; no es necesario documentar palabras obvias.
pedido, venta y entrega no deberían asumirse equivalentes?Fundamentos de requisitos convierte este lenguaje compartido en necesidades y condiciones verificables.