Estados¶

Ningún estado del sistema se almacena como cadena de texto. Cada entidad con ciclo de vida referencia por llave foránea una tabla de catálogo propia, que puede ampliarse con filas nuevas sin migrar el esquema.

Esta página define el patrón, el reparto de responsabilidades entre el catálogo y las marcas temporales de la entidad, y el catálogo completo de los catorce dominios de estado del modelo.

Requerimientos cubiertos¶

• RF-U-35
• RF-C-06
• RF-A-32
• RF-A-37
• RF-A-45
• RF-A-46
• RF-A-63

Taxonomía de enumeraciones¶

No toda enumeración cerrada es un estado. Convertirlas todas en tablas prometería una extensibilidad que no existe, y dejarlas todas como texto perdería la que sí existe. El modelo distingue tres clases y aplica un mecanismo distinto a cada una.

La prueba para separar estado de discriminador: si agregar un valor nuevo obliga a agregar columnas que solo aplican a ese valor, es un discriminador. Modelarlo como tabla no lo haría extensible, solo escondería que no lo es.

Reparto de responsabilidades¶

El catálogo de estado y la entidad gobernada cubren necesidades distintas y no compiten.

Las cuatro reglas que impone la última fila (estado activo, estado terminal, transición declarada y coherencia con las marcas) son una familia completa de triggers, definida en Triggers. Aquí se describe el contrato que esa familia lee; allá, cómo lo impone.

La entidad gobernada lleva marcas temporales que registran sus transiciones (confirmada_at, cancelada_at, resuelta_at, revisada_at) y que existen de todos modos por obligación de auditoría. Esas marcas son las que sostienen los índices parciales, porque el predicado de un índice solo admite expresiones inmutables sobre columnas de la propia fila.

CREATE UNIQUE INDEX unq_reserva_usuario_comercio_activa
ON reserva (perfil_id, comercio_id)
WHERE finalizada_at IS NULL;

estado_<entidad>¶

Forma base que comparten los catorce catálogos de estado del modelo, heredada de la clase base compartida por todo el modelo, no declarada fila por fila en cada módulo.

• Régimen: Mutable rastreada
• Volumen estimado: 3-8 filas por dominio
• Origen:

  • RF-A-37
  • RF-A-46

Columnas¶

Además de las columnas estándar (id, created_at, updated_at) y de is_active (régimen mutable rastreada):

A estos campos comunes cada dominio agrega sus atributos semánticos: los booleanos que el motor consulta en lugar de comparar contra codigo. Se componen a partir de seis mixins compartidos (allow_edit, allow_login, allow_reserva, public, require_admin, require_motivo) más, en algunos dominios, columnas propias sin equivalente en otro catálogo. El contrato completo, dominio por dominio, está más abajo.

Los prefijos no son decorativos y fijan la dirección en que se lee el atributo. Confundirlas invierte la mitad del catálogo, así que se declaran una sola vez aquí:

require_admin es, por tanto, "alcanzar este estado exige que actúe un administrador", y por eso es falso en todo estado initial: a un estado inicial no llega nadie, se nace en él.

La excepción son los dos require_* que describen una espera y no una condición de entrada: estado_moderacion.require_revision y estado_incidente.require_comercio marcan que una fila en ese estado sigue pendiente de alguien. Se leen como allow_*, no como require_admin, y por eso require_revision puede ser cierto en un estado initial.

Llaves foráneas¶

La forma base no declara ninguna. Un catálogo de estado es hoja del grafo: nadie lo referencia desde dentro del módulo y él no referencia a nadie.

Constraints¶

CONSTRAINT chk_<tabla>_codigo_format
CHECK (codigo ~ '^[a-z][a-z0-9_]*$')

CONSTRAINT chk_<tabla>_initial_isactive
CHECK (NOT initial OR is_active)

CONSTRAINT chk_<tabla>_initial_terminal
CHECK (NOT (initial AND terminal))

Unicidad¶

Triggers¶

Los tres primeros son compartidos por toda tabla del modelo (ver Columnas estándar) y no llevan el nombre de la tabla en el nombre del trigger; el cuarto es específico de estado_<entidad>.

Triggers de la entidad gobernada¶

No viven en el catálogo sino en cada tabla que lo referencia, y son los que convierten los atributos semánticos de arriba en garantías. Los cuatro se instancian igual en las catorce tablas con estado_id; el detalle de la plantilla está en Triggers. Ninguno está implementado todavía.

trg_<tabla>_transicion_valida solo se instala en las tres tablas con catálogo de transiciones. En las once restantes, trg_<tabla>_estado_coherente carga con toda la regla: no hay par que validar, pero sí un contrato que cumplir entre el estado y las marcas.

Índices¶

Los dos índices únicos cubren el resto de accesos. Con menos de diez filas por tabla, cualquier índice adicional sería más caro de mantener que el recorrido secuencial que evita.

Régimen de auditoría¶

Mutable rastreada

codigo es de solo lectura: cambiarlo rompería todo el trigger que lo menciona y toda referencia en esta documentación. Las etiquetas, descripciones y atributos semánticos sí son editables. Un DELETE no borra la fila: la reescribe en is_active = false, porque un estado referenciado por una sola fila histórica es parte del historial. Cada UPDATE queda además en la tabla de eventos gemela, por el mismo régimen que cualquier catálogo administrable.

transicion_<entidad>¶

Tres entidades llevan su máquina de estados como datos, en una tabla transicion_<entidad> que enumera los pares admitidos: comercio, reserva y publicacion.

• Régimen: Mutable rastreada
• Volumen estimado: 5-15 filas por dominio

Columnas¶

Además de las columnas estándar y de is_active:

Llaves foráneas¶

Constraints¶

CONSTRAINT chk_<tabla>_noreflex
CHECK (from_estado_id <> to_estado_id)

CONSTRAINT chk_<tabla>_actor
CHECK (actor IN ('admin', 'comercio', 'sistema', 'user'))

CONSTRAINT chk_<tabla>_descripcion_motivo_mutex
CHECK (NOT require_descripcion OR require_motivo)

Unicidad¶

No declara ninguna más allá de la llave primaria. Dos filas con el mismo par (from_estado_id, to_estado_id) y distinto actor son legítimas: el mismo tránsito puede estar permitido para un actor y no para otro, con exigencias de motivo distintas.

Cómo se consume¶

La validación del par la impone trg_<tabla>_transicion_valida, un trigger BEFORE UPDATE OF estado_id en la entidad gobernada. Antes de escribir, consulta transicion_<entidad> por (from_estado_id, to_estado_id, actor) y rechaza si no existe una fila activa, o si la transición encontrada exige motivo o descripción y la fila no los trae.

El actor de la petición llega por SET LOCAL hz.actor, que la capa de API fija al abrir la transacción. Cuando nadie lo fija (una migración de datos, una corrección desde psql) el trigger sigue exigiendo que el par exista, pero no que exista para un actor concreto: la integridad del ciclo de vida no depende de que el llamador se identifique, y la autorización por rol no es asunto de la base. El contrato completo está en Triggers.

¿Por qué solo tres entidades?¶

reserva, publicacion y comercio tienen máquinas de estados con ramas, actores distintos y consecuencias irreversibles: una transición ilegal de reserva produce entregas duplicadas o stock fantasma. El resto de los dominios tiene ciclos lineales sin ramificación, donde el orden está implícito y una tabla de transiciones sería mecanismo sin regla que imponer. Esos once ciclos no quedan sin validar: trg_<tabla>_estado_terminal impide revivir una fila cerrada y trg_<tabla>_estado_coherente exige que las marcas temporales respalden el estado declarado, que es toda la regla que un ciclo lineal necesita.

Catálogo de los 14 dominios¶

Cada bloque lista sus filas semilla, sus atributos semánticos y la marca temporal de la entidad gobernada que identifica el subconjunto vivo para los índices parciales. Salvo donde se indica lo contrario, el código exacto de cada fila, su etiqueta y su descripción quedan a criterio de quien siembra el catálogo: lo único que las notas de dominio fijan es qué fila es initial y cuáles son terminal.

Las tablas de esta sección son el contenido real de hz_estados/seeders.py, y los bloques citados como Marca en <tabla> son la especificación que lee trg_<tabla>_estado_coherente: cada uno declara qué marca temporal tiene que respaldar qué atributo semántico. Ahí donde el bloque dice "equivale a", el trigger impone una equivalencia estricta en las dos direcciones.

estado_usuario¶

allow_login distingue solo a anonimizado de los otros tres: los tres admiten sesión, y es allow_reserva el que separa activo de pendiente_verificacion/suspendido. Es la corrección que RF-U-02 pide ("una cuenta sin ningún canal verificado puede iniciar sesión y explorar, pero no puede reservar") y que RF-A-20 pide del otro lado ("el usuario conserva el acceso a la aplicación y ve el motivo y la fecha de reactivación al intentar reservar").

No hay un estado de "eliminación pendiente" en este catálogo. La solicitud de eliminación de RF-U-12 y RF-A-62 no está modelada todavía: hoy la ejecución solo se refleja como el paso a anonimizado, y el expediente intermedio que esos requerimientos describen queda pendiente.

estado_comercio¶

Cuatro estados, no siete: la revisión de la solicitud de afiliación (en_revision, aprobada, rechazada) vive en estado_solicitud_afiliacion, y una pausa temporal declarada por el comercio vive en pausa_comercio; este catálogo solo gobierna la cuenta del comercio en sí.

estado_solicitud_afiliacion¶

allow_edit en en_revision es lo que habilita la edición del formulario que pide RF-A-10 mientras el expediente sigue abierto, y se apaga en los dos estados terminales.

Marca en solicitud_afiliacion

• resuelta_at IS NULL delimita el expediente abierto

estado_solicitud_cambio¶

apply es el flag que el trigger consulta para decidir si escribe el valor_propuesto en comercio al resolver: es la traducción directa de "aprobar aplica el cambio, rechazar no".

Marca en solicitud_cambio_comercio

• resuelta_at IS NULL

estado_publicacion¶

mutate_stock marca en qué estados trg_reserva_ajustar_stock puede mover cantidad_reservada; está apagado en programada porque ese estado no admite reservas y por tanto no hay stock que mover, y deja de aplicar en cuanto la publicación cierra por cualquier vía, para que un ajuste tardío no reviva una fila ya cerrada. agotada sigue siendo public porque el cliente debe verla como "sin stock", no como inexistente.

Marcas en publicacion

• publicada_at IS NOT NULL AND cerrada_at IS NULL delimita la publicación viva

estado_reserva¶

alta es un estado de tránsito casi instantáneo: existe para que la fila nazca antes de contar el stock, y por eso es el único estado no terminal con consume_stock apagado; el trigger la mueve a retenida en la misma transacción, y es ese paso el que reserva la unidad. consume_stock es el atributo del que depende la aritmética de inventario: verdadero en expirada y en retirada porque la unidad se consumió o se perdió y en ningún caso volvió a estar disponible, y falso en las tres cancelaciones, que sí devuelven inventario. Quien lo lee es trg_reserva_ajustar_stock, que compara el atributo del estado viejo contra el del nuevo y escribe el delta en publicacion.cantidad_reservada. finalizada coincide con terminal en todas las filas de este dominio; se expone como atributo propio para que una consulta pueda filtrar por él sin depender de la columna base.

Marcas en reserva

• finalizada_at IS NULL (columna generada, COALESCE de retirada_at/cancelada_at/expirada_at) equivale a que el estado actual no tenga finalizada
• retencion_expira_at sostiene el barrido de retenida vencidas
• validacion_hasta_at sostiene el barrido de activa vencidas

resultado_validacion¶

No es un estado de ciclo de vida sino el desenlace inmutable de un intento de canje en mostrador. Comparte la forma base porque cada caso necesita un mensaje propio para el operador, y ese mensaje es contenido editable, no un valor fijo en código.

Las siete filas están activas simultáneamente, no hay transición entre ellas. initial se fija en exito únicamente porque la columna lo exige por esquema, no porque tenga significado de ciclo de vida.

estado_invitacion¶

Marca en invitacion

• consumida_at IS NULL equivale a canjeable

estado_moderacion¶

Es el único dominio compartido por dos entidades con arranques distintos, y el initial del catálogo solo sirve a una de ellas: una respuesta_valoracion de comercio nace pendiente porque la moderación previa es obligatoria, mientras que una valoracion de usuario nace publicada y se modera después. El trigger de valoracion fija su estado inicial explícitamente en vez de apoyarse en initial, y unq_<tabla>_initial no se interpone porque la marca sigue estando en una sola fila.

Marca en ambas tablas

• oculta_at IS NULL equivale a public

estado_incidente¶

require_comercio está apagado en las cuatro filas: el descargo del comercio que pide RF-A-34 es opcional y sus rondas viven en incidencia_descargo, no en un estado propio. Queda declarado para cuando el flujo exija una espera formal al comercio antes de resolver.

Marca en incidencia

• resuelta_at IS NULL delimita la incidencia abierta; combinada con ultimo_movimiento_at sostiene la alerta de 48 h sin movimiento

estado_alerta¶

Marca en alerta

• revisada_at IS NULL sostiene el índice único que impide acumular alertas idénticas sin atender

estado_notificacion¶

pendiente es el atributo que delimita la cola de envío, y sigue encendido en enviada: el mensaje salió pero todavía espera acuse del proveedor, así que sigue siendo trabajo abierto para el monitor de salud de RF-A-61. happy_path se reserva para el desenlace bueno de verdad, que es entregada.

descartada no marca fallo: RF-A-61 dice que "un mensaje no enviado por preferencia del usuario no cuenta como fallo del proveedor", que es exactamente lo que ese estado registra. Si marcara fallo, el conteo de fallos de 24 h se inflaría con supresiones legítimas.

Marcas en notificacion

• enviada_at IS NULL AND descartada_at IS NULL es la cola de envío (idx_notificacion_cola)
• fallida_at IS NOT NULL sostiene el conteo de fallos de 24 h

estado_campana¶

Confirmar una campaña siempre exige un segundo administrador distinto de quien la creó, ver Notificaciones.

No hay un estado previsualizada separado: previsualizar no muta el estado de la campaña, solo fija destinatarios_estimados: es un prerrequisito de datos para confirmar_campana, no un tránsito.

estado_plantilla_mensaje¶

Marcas en plantilla_mensaje

• vigente_desde IS NOT NULL AND vigente_hasta IS NULL equivale a vigente y sostiene la unicidad "una sola plantilla vigente por código y canal" (impuesta en trigger, no en constraint, ver Catálogos)