Procesos de negocio como statecharts

En el frontend la máquina de estados se justifica por la interfaz: hay que decidir qué se pinta y qué botón se habilita. En el backend la justificación es más severa, porque lo que está en juego no es un botón mal habilitado sino un cobro duplicado, un envío a un pedido cancelado o una suscripción que factura después de haberse dado de baja. Y sin embargo el backend es donde el modelo suele faltar: el ciclo de vida de un pedido se codifica en una columna status de tipo texto, se protege con condicionales escritos por cinco personas distintas en cinco momentos distintos, y se documenta en un diagrama de Confluence que dejó de coincidir con el código el mismo trimestre en que se dibujó. La máquina existe —siempre existe—, pero existe como folclore. Este nivel entero consiste en sacarla del folclore y convertirla en artefacto: un valor que se puede leer, versionar, probar y consultar.

El ciclo de vida que nadie escribió

El punto de partida habitual no es un diseño sino un sedimento. Alguien creó la columna con dos valores, alguien añadió un tercero, alguien más metió una bandera porque el tercero no cubría un caso, y el conocimiento de qué transiciones son legales quedó repartido entre las funciones que las ejecutan.

async function marcarPagado(pedidoId: string) {
  const pedido = await repo.find(pedidoId)
  if (pedido.status === 'cancelado') throw new Error('no se puede pagar')
  if (pedido.reembolsado) throw new Error('ya reembolsado')
  await repo.update(pedidoId, { status: 'pagado', pagadoEn: new Date() })
  await cola.enviar('preparar-envio', { pedidoId })
}

Hay tres síntomas que delatan este sedimento y conviene aprender a verlos porque preceden siempre al incidente. El primero es el valor huérfano: un estado que ya nadie escribe pero que sigue apareciendo en filas antiguas y en algún condicional defensivo, porque nadie se atrevió a comprobar si quedaban casos vivos. El segundo es la bandera redundante: un booleano que codifica una fase del proceso en paralelo a la columna, con lo que existen combinaciones que el negocio nunca aprobó y que ninguna restricción impide. El tercero es el condicional asimétrico: dos funciones que escriben la misma columna comprueban cosas distintas antes de hacerlo, y el camino más laxo se convierte de facto en la regla del sistema, porque basta con recorrerlo una vez para dejar el proceso en un lugar del que ya no hay vuelta.

Esa función es correcta y aun así el sistema no lo es, porque la corrección es local. Nada garantiza que marcarPreparado repita las mismas comprobaciones, que el consumidor de la cola de reembolsos conozca la bandera, ni que la tarea nocturna que caduca pedidos abandonados respete las mismas reglas. El invariante del dominio —un pedido cancelado jamás avanza— no está escrito en ningún sitio: está replicado con distintos grados de fidelidad en cada punto de escritura, y basta con que un punto nuevo olvide una línea para que el invariante deje de existir sin que ninguna prueba falle.

Tres procesos, un mismo esqueleto

La observación que hace rentable este nivel es que los procesos de negocio se parecen mucho más entre sí de lo que sus nombres sugieren. Un pedido, una suscripción y una reclamación comparten una estructura de cuatro fases: una apertura reversible, una zona comprometida donde el dinero o la obligación ya se movieron, un conjunto de desenlaces terminales y una región de excepción que puede activarse casi en cualquier punto.

Ese esqueleto compartido tiene consecuencias prácticas. La primera es que el equipo puede razonar sobre procesos nuevos por analogía en vez de partir de cero. La segunda, más importante, es que las preguntas difíciles son las mismas en los tres casos: dónde está la frontera exacta a partir de la cual el proceso deja de ser reversible, qué pasa si el mundo exterior contradice al modelo, y qué desenlaces son de verdad terminales frente a los que solo lo parecían hasta que llegó el primer caso raro.

stateDiagram-v2
[*] --> pendiente
pendiente --> pagado: PAGO_CONFIRMADO
pendiente --> cancelado: CANCELAR
pendiente --> caducado: vence el plazo
pagado --> preparando: RESERVA_OK
pagado --> reembolsando: CANCELAR
preparando --> enviado: TRANSPORTISTA_RECOGE
enviado --> entregado: PRUEBA_DE_ENTREGA
enviado --> incidencia: FALLO_DE_REPARTO
incidencia --> enviado: REINTENTO
incidencia --> devuelto: DEVOLUCION_A_ORIGEN
reembolsando --> cancelado: ABONO_OK
entregado --> [*]
cancelado --> [*]

Lo que el modelo obliga a decidir

Escribir la máquina no añade reglas: revela las que faltaban. Cada arista que no se sabe dónde poner corresponde a una pregunta de negocio que el sistema anterior respondía por omisión, y por tanto de forma distinta según qué camino recorriera el usuario.

import { setup, assign } from 'xstate'

type Pedido = { id: string; total: number; motivo: string | null }

export const pedido = setup({
  types: {
    context: {} as Pedido,
    events: {} as
      | { type: 'PAGO_CONFIRMADO'; referencia: string }
      | { type: 'CANCELAR'; motivo: string; actor: 'cliente' | 'operador' }
      | { type: 'PRUEBA_DE_ENTREGA' },
  },
  guards: {
    cancelacionPermitida: ({ event }) => event.type === 'CANCELAR' && event.motivo.length > 0,
  },
}).createMachine({
  id: 'pedido',
  initial: 'pendiente',
  context: ({ input }: { input: Pedido }) => input,
  states: {
    pendiente: {
      on: {
        PAGO_CONFIRMADO: 'pagado',
        CANCELAR: { target: 'cancelado', guard: 'cancelacionPermitida' },
      },
      after: { PLAZO_DE_PAGO: 'caducado' },
    },
    pagado: { on: { CANCELAR: { target: 'reembolsando', guard: 'cancelacionPermitida' } } },
    reembolsando: { on: { ABONO_OK: 'cancelado' } },
    caducado: { type: 'final' },
    cancelado: { type: 'final' },
  },
})

Obsérvese que el mismo evento CANCELAR conduce a destinos distintos según el estado de origen: en pendiente termina el proceso de inmediato, en pagado abre una compensación. Esa diferencia existía antes en el negocio, pero el código la expresaba como una condición dentro de una única función de cancelación, mezclada con la validación del motivo y con el registro de auditoría. Al llevarla al grafo se convierte en topología, que es la forma de conocimiento más barata de leer y la más difícil de contradecir por accidente.

Dónde encaja la máquina en el servicio

Queda una decisión de encaje que suele resolverse mal: qué hacer cuando un evento es ilegal en la posición actual. La respuesta por defecto —lanzar una excepción— es aceptable en un endpoint sincrónico, donde el usuario merece un mensaje inmediato, y desastrosa en un consumidor de cola, donde una excepción reencola el mensaje y produce un bucle infinito de reintentos sobre algo que jamás será legal. La disciplina consiste en distinguir tres desenlaces distintos: el evento que no corresponde ahora pero podría corresponder más tarde, y por tanto conviene aplazar; el evento que ya se aplicó y llega repetido, que se descarta en silencio; y el evento que nunca fue legal en este proceso, que debe registrarse como anomalía y detenerse. Una máquina de estados hace triviales las tres respuestas porque sabe con precisión si el evento tiene transición, si la tenía en un estado anterior o si no aparece en el modelo.

La máquina no sustituye a la capa de aplicación ni al repositorio: se coloca entre ambos como árbitro puro. El controlador traduce la petición HTTP en un evento del dominio, la máquina decide si ese evento es legal en la posición actual y qué efectos ordena, y la capa de infraestructura ejecuta esos efectos y persiste el resultado. La regla que mantiene sano el diseño es que la máquina no llame a nadie: describe qué debe ocurrir y devuelve esa descripción, mientras que quien la hospeda decide cómo y cuándo cumplirla. Con esa separación, el mismo modelo sirve al endpoint sincrónico, al consumidor de cola y a la tarea programada, sin que ninguno de los tres necesite conocer las reglas del otro.