System Design
Requisitos funcionales
Explica cómo especificar comportamientos mediante actores, entradas, estados, reglas, errores, postcondiciones, concurrencia e idempotencia.
- Última actualización
- Actualizada
- Nivel
- Fundamentos
System Design
Explica cómo especificar comportamientos mediante actores, entradas, estados, reglas, errores, postcondiciones, concurrencia e idempotencia.
Un requisito funcional no describe una pantalla ni una tarea de desarrollo. Describe un comportamiento observable que el sistema debe ejecutar para producir un resultado útil, incluyendo condiciones, decisiones, errores y efectos persistentes.
Los requisitos funcionales responden qué debe hacer el sistema cuando un actor, evento o proceso inicia una operación.
disparador
→ validar contexto y permisos
→ aplicar reglas
→ cambiar o consultar estado
→ producir resultado observable
→ registrar efectos necesariosUn requisito es completo cuando permite diseñar el flujo y decidir si una implementación cumple, sin imponer prematuramente una tecnología.
“Gestionar pedidos” parece una funcionalidad, pero oculta múltiples comportamientos:
Si se deja como frase amplia, cada rol interpreta un alcance distinto y los errores aparecen al integrar estados, permisos y datos.
entrada + estado actual + reglas
→ comportamiento
→ salida + nuevo estado + efectosEjemplo:
Confirmar pedido
Entrada: pedido pendiente y usuario autorizado
Estado actual: stock vendible suficiente
Reglas: no exceder stock, precio vigente capturado
Salida: pedido confirmado
Efectos: reserva creada y evento registradoIndica quién o qué inicia la operación: persona, sistema externo, job o evento. El actor no siempre es humano.
Condiciones que deben existir antes de ejecutar. No deben confundirse con validaciones internas que el sistema realiza durante el flujo.
Datos necesarios, formato, identidad y contexto. Incluye qué datos son opcionales y qué fuente es autoritativa.
Secuencia normal de decisiones y cambios. Debe mantenerse en nivel de comportamiento, no en detalles de frameworks.
Qué ocurre cuando falta un dato, una regla no se cumple, una dependencia falla o la operación se repite.
Estado garantizado después de éxito o fallo. Una operación atómica puede garantizar que no quedan cambios parciales.
Eventos, notificaciones, auditoría o integración. Debe aclararse si forman parte del commit o se procesan después.
RF-XX: Nombre
Objetivo relacionado:
Actor o disparador:
Descripción:
Precondiciones:
Entradas:
Flujo principal:
Alternativas y errores:
Reglas aplicables:
Postcondiciones:
Efectos observables:
Criterios de aceptación:
Dependencias:
Preguntas abiertas:No todos los campos necesitan texto extenso. La plantilla sirve para detectar vacíos, no para producir burocracia.
RF-ORD-12: Cancelar pedido pendiente
Actor: cliente o agente autorizado.
Precondición: el pedido existe y está en estado pending o confirmed.
Entrada: ID del pedido y motivo.
Flujo:
1. El sistema verifica identidad y permiso.
2. Valida que el estado permita cancelación.
3. Cambia el estado a cancelled.
4. Libera reservas activas.
5. Registra actor, fecha y motivo.
Resultado: el pedido queda cancelado una sola vez.La operación no es simplemente actualizar una columna. Coordina estado, inventario y auditoría. “Una sola vez” implica idempotencia: repetir la solicitud no debe liberar dos veces la misma reserva.
RF-SALE-04: Confirmar venta
Entradas:
- sucursal
- productos y cantidades
- medio de pago
- idempotency key
Reglas:
- cada cantidad debe ser positiva
- el producto debe estar habilitado en la sucursal
- no se permite exceder stock vendible
- el total se calcula con precios capturados por la operación
Resultado exitoso:
- venta confirmada
- movimientos de inventario registrados
- total y líneas persistidos
- respuesta con ID y comprobante
Resultado rechazado:
- ningún cambio parcial
- causa identificable por producto o reglaEn producción, el diseño debe decidir concurrencia, transacción, timeout e integración con pagos. El requisito expresa las garantías; la arquitectura decide cómo implementarlas.
La operación cumple todas las condiciones.
La entrada es válida, pero una regla produce otro resultado esperado: stock insuficiente, pedido ya cancelado o cliente no elegible.
Falla una dependencia, base de datos o red. Puede requerir reintento, estado pendiente o compensación.
Separarlos mejora mensajes, métricas y pruebas. Un rechazo de negocio no debería registrarse como error de infraestructura.
Muchos requisitos dependen del ciclo de vida:
pending → confirmed → preparing → dispatched → delivered
└──────────────→ cancelledUn requisito debe indicar desde qué estados puede ejecutarse y qué transición produce. De lo contrario, surgen operaciones imposibles como cancelar un pedido entregado sin modelar devolución.
Una validación secuencial puede fallar cuando dos operaciones compiten:
A lee stock = 5
B lee stock = 5
A vende 4
B vende 4
→ stock lógico = -3El requisito debe decir “no permitir stock negativo bajo solicitudes concurrentes”. No necesita ordenar usar locks concretos, pero sí expresar la garantía que se verificará.
Operaciones iniciadas por red pueden repetirse porque el cliente no recibió la respuesta.
request
→ servidor confirma
→ respuesta se pierde
→ cliente reintentaPara pagos, pedidos o webhooks, define si la misma intención debe devolver el resultado previo en vez de duplicar efectos.
Si el requisito necesita una pasarela, inventario externo o correo, define:
No conviertas “enviar correo” en requisito crítico de la misma transacción si el resultado principal puede completarse sin él.
“Actor: administrador” suele ser insuficiente. Explica la capacidad y el alcance:
Un store manager puede cancelar pedidos de su sucursal antes de despacho.Esto conecta el comportamiento con reglas y datos, no con un nombre genérico de rol.
Decide si se rechaza o representa una operación válida.
Distingue no encontrado de no autorizado cuando la seguridad lo exige.
Define unicidad e idempotencia.
Aclara atomicidad o estado pendiente.
Webhooks y eventos pueden llegar duplicados o retrasados.
Un comportamiento correcto fila por fila puede ser inviable en batch; define límites o procesamiento asíncrono.
Decide qué partes pueden revertirse y cuáles requieren compensación.
“Mostrar botón Guardar” no explica comportamiento. El botón es una representación posible.
Produce diseños que solo funcionan en demos.
“Crear endpoint Express” acopla el requisito a una solución.
Una operación enorme dificulta priorización y pruebas. Separa cuando cada resultado puede variar.
Mantén una fuente y relación para evitar contradicción.
Puede dejar cambios parciales o incertidumbre.
Pueden coexistir. Evita copiar el mismo párrafo en tres lugares; enlaza y usa cada artefacto para su pregunta.
Conviene para operaciones críticas, reglas complejas, integraciones, concurrencia o múltiples equipos. Para CRUD sencillo, una historia con criterios y modelo de datos puede ser suficiente.
Requisitos no funcionales define las cualidades y límites bajo los cuales estos comportamientos deben seguir siendo útiles.