Ofertas¶

La distinción conceptual más importante del modelo:

Confundirlas haría imposible cambiar el precio de mañana sin reescribir el comprobante de ayer, que es justamente lo que el snapshot obligatorio evita.

También viven aquí plantilla_programacion y excepcion_calendario: ambas dependen de plantilla_oferta, así que documentarlas junto a Horarios formaría una dependencia circular entre módulos.

Requerimientos cubiertos¶

• RF-U-16
• RF-U-17
• RF-U-18
• RF-U-19
• RF-U-20
• RF-U-21
• RF-U-22
• RF-U-23
• RF-C-19
• RF-C-21
• RF-C-25
• RF-C-26
• RF-C-27
• RF-C-28
• RF-C-29
• RF-C-30
• RF-C-31
• RF-C-32
• RF-C-33
• RF-C-34
• RF-C-35
• RF-A-23
• RF-A-24
• RF-A-25
• RF-A-40
• RF-A-41

plantilla_oferta¶

Configuración reutilizable de una oferta. Máximo cinco activas por comercio.

• Régimen: Mutable rastreada
• Volumen estimado: 150-400 filas
• Origen:

  • RF-C-27
  • RF-C-28
  • RF-C-29
  • RF-C-30

Columnas¶

Llaves foráneas¶

Constraints¶

CONSTRAINT chk_plantillaoferta_nombre_longitud CHECK (length(nombre) >= 1)

CONSTRAINT chk_plantillaoferta_variante
CHECK (
  (tipo = 'pack_sorpresa' AND descripcion = '' AND foto_id IS NULL)
  OR
  (
    tipo = 'oferta_especifica'
    AND length(descripcion) BETWEEN 20 AND 200
    AND foto_id IS NOT NULL
  )
)

CONSTRAINT chk_plantillaoferta_precio CHECK (precio > 0)
CONSTRAINT chk_plantillaoferta_valor_referencia CHECK (valor_referencia > precio)
CONSTRAINT chk_plantillaoferta_cantidad_default CHECK (cantidad_default BETWEEN 1 AND 50)

chk_plantillaoferta_variante reúne en una sola restricción las reglas del pack sorpresa y de la oferta específica. Está expresada como disyunción de dos variantes completas, y no como una lista de CHECK condicionales, para que el mensaje de error identifique la variante violada en lugar de una regla suelta.

Unicidad¶

Índices¶

Es el índice de apoyo de trg_plantillaoferta_maximo_activas.

Triggers¶

chk_plantillaoferta_valor_referencia ya exige que el valor de referencia supere al precio, pero no cuánto. El descuento mínimo del treinta por ciento que fija RF-C-30 es configurable por RF-A-41, así que no cabe en un CHECK: lo lee trg_plantillaoferta_precio desde parametro_sistema, junto con el precio mínimo.

trg_plantillaoferta_items es el que traduce "una plantilla de este tipo no puede activarse con menos de tres elementos en su lista" (RF-C-28). Cuenta filas hijas, así que es trigger, y corre al activar y no al crear: una plantilla en construcción puede estar incompleta mientras is_active sea falso.

plantilla_oferta_item¶

Lista "puede contener" del pack sorpresa.

• Régimen: Mutable rastreada
• Origen:

  • RF-C-28

Columnas¶

Llaves foráneas¶

Constraints¶

CONSTRAINT chk_plantillaofertaitem_texto_longitud CHECK (length(texto) >= 1)

Unicidad¶

plantilla_programacion¶

Programación semanal de cada plantilla de oferta. Es lo que alimenta la generación automática de publicaciones diarias.

• Régimen: Mutable rastreada
• Volumen estimado: siete filas por plantilla
• Origen:

  • RF-C-19
  • RF-C-23

Columnas¶

ventana_id y cantidad_default son siempre obligatorias, incluso cuando is_active es falso: desactivar un día no borra su configuración, solo suspende la generación.

Llaves foráneas¶

Constraints¶

CONSTRAINT chk_plantillaprogramacion_diasemana CHECK (dia_semana BETWEEN 0 AND 6)

CONSTRAINT chk_plantillaprogramacion_cantidad_default
CHECK (cantidad_default BETWEEN 1 AND 50)

Unicidad¶

Índices¶

Lo recorre la generación diaria de publicaciones.

Triggers¶

RF-C-19 lo enuncia palabra por palabra: "la ventana asignada debe pertenecer al mismo comercio y al mismo día de la semana". Son dos columnas de ventana_recogida y una de plantilla_oferta, tres tablas en juego, así que no hay CHECK ni llave foránea compuesta que lo exprese sin inventar índices redundantes en los dos padres.

Sin él, la generación diaria produce publicaciones cuya ventana pertenece a otro comercio o a otro día, y los cinco instantes que trg_publicacion_instantes deriva de esa ventana quedan resueltos contra horas que no corresponden a nada.

excepcion_calendario¶

Excepciones por fecha concreta, sin alterar la programación semanal.

• Régimen: Mutable rastreada
• Volumen estimado: decenas de filas por comercio y año
• Origen:

  • RF-C-21

Columnas¶

Llaves foráneas¶

Constraints¶

CONSTRAINT chk_excepcioncalendario_variante
CHECK (
  (tipo = 'cerrado' AND ventana_id IS NULL AND cantidad IS NULL)
  OR
  (tipo = 'modifica_ventana' AND ventana_id IS NOT NULL AND cantidad IS NULL)
  OR
  (tipo = 'modifica_cantidad' AND ventana_id IS NULL AND cantidad IS NOT NULL)
)

CONSTRAINT chk_excepcioncalendario_cantidad
CHECK (cantidad IS NULL OR cantidad BETWEEN 1 AND 50)

Unicidad¶

Puede haber más de una excepción para la misma fecha si son de tipo distinto (una modifica_ventana y otra modifica_cantidad el mismo día), pero no dos del mismo tipo.

Triggers¶

trg_excepcioncalendario_cierre es la mitad de RF-C-21 que la unicidad no alcanza: "un cierre excluye cualquier otra excepción del mismo día". unq_excepcioncalendario_plantilla_fecha_tipo admite hoy una cerrado y una modifica_cantidad sobre la misma fecha, que es una contradicción, porque un día cerrado no tiene cantidad que modificar. La regla mira filas hermanas, así que es trigger, y corre en las dos direcciones: rechaza un cerrado si ya hay otras excepciones ese día, y rechaza cualquier otra si ya hay un cerrado.

trg_excepcioncalendario_horizonte no puede ser CHECK porque compara contra hz_hoy(), que no es inmutable. El límite de noventa días es el que RF-C-21 fija de forma fija, no configurable, así que no es regla parametrizada.

publicacion¶

La instancia diaria. Es la tabla más leída del sistema.

• Régimen: Mutable protegida
• Volumen estimado: 100-300 filas diarias
• Origen:

  • RF-C-25
  • RF-C-35
  • RF-U-21
  • RF-U-22

Columnas¶

Columnas generadas¶

descuento_pct numeric(6,2)
GENERATED ALWAYS AS (100 * (1 - precio / valor_referencia)) STORED

cantidad_disponible smallint
GENERATED ALWAYS AS (cantidad_total - cantidad_reservada) VIRTUAL

descuento_pct es almacenada porque la moderación de contenido y la alerta de descuento excesivo la consultan por umbral. cantidad_disponible es virtual porque nunca se indexa: cualquier consulta que la necesite usa cantidad_reservada < cantidad_total directamente.

Llaves foráneas¶

Constraints¶

CONSTRAINT chk_publicacion_stock_coherente
CHECK (cantidad_reservada >= 0 AND cantidad_reservada <= cantidad_total)

CONSTRAINT chk_publicacion_entregado_coherente
CHECK (cantidad_entregada >= 0 AND cantidad_entregada <= cantidad_reservada)

CONSTRAINT chk_publicacion_orden_temporal
CHECK (
  reservable_desde_at <= reservas_cierran_at
  AND reservas_cierran_at <= ventana_inicio_at
  AND ventana_inicio_at <= ventana_fin_at
  AND ventana_fin_at <= validacion_hasta_at
)

CONSTRAINT chk_publicacion_publicada_con_aptitud
CHECK (publicada_at IS NULL OR aptitud_declarada_at IS NOT NULL)

CONSTRAINT chk_publicacion_variante
CHECK (
  (tipo = 'pack_sorpresa' AND descripcion = '' AND foto_id IS NULL)
  OR
  (
    tipo = 'oferta_especifica'
    AND length(descripcion) BETWEEN 20 AND 200
    AND foto_id IS NOT NULL
  )
)

CONSTRAINT chk_publicacion_precio_positivo CHECK (precio > 0)
CONSTRAINT chk_publicacion_valor_referencia_mayor CHECK (valor_referencia > precio)
CONSTRAINT chk_publicacion_cantidad_total CHECK (cantidad_total BETWEEN 0 AND 50)
CONSTRAINT chk_publicacion_origen CHECK (origen IN ('automatica', 'manual', 'duplicada'))

CONSTRAINT chk_publicacion_origen_autor
CHECK ((origen = 'automatica') = (creada_by IS NULL))

CONSTRAINT chk_publicacion_origen_duplicada
CHECK ((origen = 'duplicada') = (duplicada_de_id IS NOT NULL))

CONSTRAINT chk_publicacion_orden_marcas
CHECK (
  (agotado_at IS NULL OR (publicada_at IS NOT NULL AND agotado_at >= publicada_at))
  AND (cerrada_at IS NULL OR (publicada_at IS NOT NULL AND cerrada_at >= publicada_at))
)

chk_publicacion_origen_autor traduce la única diferencia real entre los tres orígenes: RF-C-23 genera desde un proceso, que no tiene usuario, y RF-C-24 y RF-C-34 los crea una persona. Hoy creada_by admite nulo sin condición, de modo que una publicación manual puede quedar sin autor y la bitácora de RF-C-14 no tiene a quién nombrar.

chk_publicacion_stock_coherente es una de las invariantes críticas del sistema. Combinada con que trg_reserva_ajustar_stock mueve cantidad_reservada dentro de la misma transacción que crea la reserva, convierte la sobreventa en un error de transacción sin SELECT ... FOR UPDATE explícito y sin ventana de carrera entre la lectura y la escritura.

chk_publicacion_variante/_precio_positivo/_valor_referencia_mayor se repiten aquí, ya declaradas también en plantilla_oferta, porque una publicación manual (plantilla_oferta_id IS NULL) puede traer estos valores propios sin haber pasado nunca por una plantilla, y el ReadOnly de abajo solo impide modificarlos después de creados, no valida su forma al insertar.

Unicidad¶

NULLS NOT DISTINCT es lo que hace idempotente a generar_publicaciones_del_dia incluso cuando plantilla_oferta_id es nulo (publicación manual): sin él, dos publicaciones manuales del mismo comercio, fecha y ventana no colisionarían. Es también lo que cumple el "no puede existir más de una publicación de la misma plantilla para la misma fecha y ventana" de RF-C-24 sin ninguna comprobación previa.

Triggers¶

trg_readonly_snapshot cubre comercio_id, plantilla_oferta_id, ventana_id, fecha_operativa, origen, tipo, nombre, descripcion, categoria_comida_id, foto_id, precio, valor_referencia y los cinco instantes. Los campos mutables son estado_id, cantidad_total, cantidad_reservada, cantidad_entregada, publicada_at, agotado_at, cerrada_at y aptitud_declarada_at/_by.

cantidad_total queda deliberadamente fuera de esa lista: dejarla de solo lectura habría hecho imposibles tres requerimientos a la vez — RF-C-31 ("el sistema impide reducir la cantidad total por debajo de las unidades ya reservadas", que presupone que se puede reducir), RF-C-32 ("el comercio puede aumentar o reducir la cantidad durante la ventana") y RF-C-33 (marcar como agotado "iguala la cantidad total a las unidades ya reservadas"). Lo que la protege no es ReadOnly: chk_publicacion_stock_coherente ya impide bajarla por debajo de cantidad_reservada, que es exactamente el límite de RF-C-31, y trg_publicacion_agotado se encarga del efecto en el estado.

trg_publicacion_instantes¶

La pieza que hace honesto el snapshot temporal. Los cinco instantes son hoy datos de entrada: chk_publicacion_orden_temporal comprueba que estén ordenados entre sí, no que correspondan a la ventana que la fila referencia. El trigger los deriva y sobrescribe lo que haya mandado el llamador:

Es también la única instancia de la familia de derivación que consume parámetros, y donde D-16 se paga: la tolerancia y el corte se leen una vez, en la escritura, y quedan congelados en la fila. Un cambio posterior del parámetro no mueve las publicaciones ya creadas, que es lo que las notas de diseño de abajo describen como "el contrato con quien ya reservó".

trg_publicacion_agotado¶

RF-C-32 describe una transición que el sistema hace solo: "si la disponibilidad llega a cero, la publicación pasa a agotada; si vuelve a ser positiva, regresa a publicada". Los dos pares están declarados en transicion_publicacion con actor sistema, así que el trigger no inventa nada: calcula cantidad_total - cantidad_reservada y mueve estado_id, y trg_publicacion_transicion_valida lo valida como a cualquier otro cambio.

Corre BEFORE y en la misma sentencia que mueve el contador, que es lo que permite cumplir el "treinta segundos o menos" de RF-C-32 sin ningún proceso que barra publicaciones buscando ceros.

trg_publicacion_alerta_moderacion¶

RF-A-25 enumera cinco disparadores y cuatro de ellos dependen solo de esta fila y de parametro_sistema: descuento sobre precio.descuento_revision_pct, precio bajo precio.minimo, oferta específica sin foto y cantidad mayor a treinta. El quinto, la primera publicación de un comercio recién aprobado, se resuelve contando las publicaciones anteriores del comercio.

Es AFTER INSERT OR UPDATE e inserta en alerta con ON CONFLICT ON CONSTRAINT unq_alerta_abierta DO NOTHING, que es lo que traduce el "no se acumulan alertas idénticas sin atender sobre la misma publicación" del requerimiento a control de flujo en vez de a un error.

Índices¶

Notas de diseño¶

Los cinco instantes se resuelven al crear la publicación y no se recalculan: si el comercio edita la ventana de recogida mañana, las publicaciones de hoy conservan los suyos, son el contrato con quien ya reservó.

comercio_id está denormalizado desde la plantilla aunque sea derivable. La consulta del directorio filtra y agrupa por comercio en cada carga, y trg_readonly_snapshot garantiza que la copia no pueda contradecir al original.

publicacion_item¶

Copia congelada de plantilla_oferta_item al publicar. Copia y no referencia porque el comprobante que el usuario consulta meses después debe mostrar lo que decía la oferta ese día.

• Régimen: append-only
• Origen:

  • RF-C-28

Columnas¶

Constraints¶

CONSTRAINT chk_publicacionitem_texto_longitud CHECK (length(texto) >= 1)

Unicidad¶

Ninguna, además de la llave primaria, y por la misma razón que plantilla_oferta_item: una unq_publicacionitem_publicacion limitaría a un ítem por publicación y haría imposible copiar la lista de tres a ocho elementos que la plantilla declara. La ficha anterior la documentaba; no existe en el código y no debe crearse.

orden importa aquí más que en la plantilla: el comprobante que el usuario consulta meses después debe mostrar la lista en el mismo orden en que la vio al reservar.

despublicacion¶

Retiro administrativo de una publicación. Relación 1:1.

• Régimen: append-only
• Volumen estimado: unidades por semana
• Origen:

  • RF-A-24

Columnas¶

Constraints¶

CONSTRAINT chk_despublicacion_resolucion
CHECK (resolucion_reservas IN ('mantener', 'cancelar'))

CONSTRAINT chk_despublicacion_reservas_afectadas CHECK (reservas_afectadas >= 0)

Unicidad¶

Es la unicidad que cumple el "una publicación no puede despublicarse dos veces" de RF-A-24, sin ninguna comprobación previa.

Triggers¶

trg_despublicacion_reservas es lo que la ficha de columnas ya prometía al describir reservas_afectadas como "contadas por un trigger". Como toda la familia de derivación, sobrescribe en vez de comparar: el número tiene que ser el que la base contó en el instante de la despublicación, no el que declaró quien la ejecutó, porque es la evidencia de cuánta gente quedó afectada por una decisión administrativa.

trg_despublicacion_estado cierra el bucle: insertar la fila de despublicación es despublicar. Dejar el cambio de estado en manos del llamador permitiría una despublicación registrada que nunca retiró la oferta del mapa, que es lo contrario de lo que RF-A-24 llama "de forma inmediata".