Comercios¶

Ficha del comercio, expediente de afiliación, historial de estados, cola de cambios sensibles, pausas e indicadores de cumplimiento.

La fila de comercio se crea al enviar el formulario público, en estado pendiente_revision. Eso hace que la unicidad de RUC y la detección de duplicados operen desde el primer instante.

Requerimientos cubiertos¶

• RF-C-03
• RF-C-05
• RF-C-06
• RF-C-07
• RF-C-15
• RF-C-16
• RF-C-22
• RF-C-51
• RF-A-06
• RF-A-07
• RF-A-08
• RF-A-09
• RF-A-10
• RF-A-11
• RF-A-12
• RF-A-13
• RF-A-14
• RF-A-15
• RF-A-16
• RF-A-31
• RF-A-44

comercio¶

Ficha del comercio y su configuración de publicación.

• Régimen: Mutable rastreada
• Volumen estimado: 30-80 filas

Columnas¶

Llaves foráneas¶

Constraints¶

CONSTRAINT chk_comercio_descripcion_longitud CHECK (length(descripcion) <= 300)

CONSTRAINT chk_comercio_slug_format
CHECK (slug ~ '^[a-z0-9]+(-[a-z0-9]+)*$')

CONSTRAINT chk_comercio_regla_generacion
CHECK (num_nonnulls(hora_generacion_publicacion, horas_antes_generacion) = 1)

CONSTRAINT chk_comercio_horas_antes_reservable
CHECK (horas_antes_reservable BETWEEN 0 AND 48)

CONSTRAINT chk_comercio_calificacion_coherente
CHECK ((calificacion_promedio IS NULL) = (calificacion_conteo = 0))

Unicidad¶

Índices¶

No hay un índice dedicado sobre ultima_publicacion_at todavía: un barrido diario sobre el volumen de comercios afiliados no lo necesita a esta escala.

Triggers¶

trg_comercio_zona es la contraparte de gist_zona_poligono, que la ficha de Catálogos ya describe como el índice que "sostiene la derivación automática de comercio.zona_id". El trigger busca la zona activa cuyo polígono cubre ubicacion y la escribe; si no hay ninguna, deja la columna nula, que es su valor de ausencia honesto. Corre también en el UPDATE de la ubicación, que es lo que RF-A-13 llama "rederiva la zona" al aprobar un cambio de pin.

trg_comercio_horario_completo es un constraint trigger diferido, no un trigger corriente: en el momento del INSERT del comercio todavía no existe ninguna fila de horario, así que la comprobación tiene que ocurrir al COMMIT. Es el único de todo el modelo que necesita ese mecanismo, y lo necesita porque RF-C-17 define el horario de atención como una propiedad total del comercio (siete días, ni uno menos), no como una colección opcional. unq_comerciohorario_comercio_dia impide que sobren; solo este impide que falten.

Notas de diseño¶

calificacion_promedio admite nulo y calificacion_conteo no. Un comercio sin valoraciones no tiene promedio cero, no tiene promedio: la diferencia importa en el ranking, donde NULLS LAST deja abajo a los comercios nuevos en lugar de hundirlos como si tuvieran la peor nota. Las dos columnas las mantiene trg_valoracion_calificacion, no la capa de aplicación: chk_comercio_calificacion_coherente es la red de seguridad de D-17, no el mecanismo.

La detección de duplicados por proximidad no puede expresarse como EXCLUDE: la distancia geodésica combinada con similitud de texto no es un operador de solapamiento indexable en ese sentido. trg_comercio_duplicado combina ST_DWithin sobre gist_comercio_ubicacion con similarity() sobre gin_comercio_nombre, los dos índices que la tabla ya tiene, y escribe posible_duplicado/duplicado_de_comercio_id en la solicitud. Al vivir en un trigger en vez de una constraint, no es una garantía absoluta bajo concurrencia extrema (dos altas simultáneas a 30 m podrían pasar ambas), pero el efecto de un falso negativo es una revisión manual de más, no una inconsistencia de datos.

solicitud_afiliacion¶

Expediente de revisión. Relación 1:1 con comercio. Existe como tabla separada porque su ciclo de vida termina (aprobada o rechazada) mientras el comercio sigue vivo, y porque contiene datos del solicitante que no forman parte de la ficha pública.

• Régimen: Mutable protegida
• Origen:

  • RF-C-03
  • RF-C-04
  • RF-A-06 - RF-A-10

Columnas¶

solicitante_id no viene de una versión anterior de docs/: quien llena el formulario debe estar autenticado, para poder crear la membresía inicial de usuario_comercio cuando se aprueba la solicitud.

Constraints¶

CONSTRAINT chk_solicitudafiliacion_informacion_longitud
CHECK (length(informacion_requerida) <= 500)

CONSTRAINT chk_solicitudafiliacion_resuelta_coherente
CHECK ((resuelta_at IS NULL) = (resuelta_by IS NULL))

CONSTRAINT chk_solicitudafiliacion_duplicado_coherente
CHECK (duplicado_de_comercio_id IS NULL OR posible_duplicado)

CONSTRAINT chk_solicitudafiliacion_horario_propuesto_tipo
CHECK (jsonb_typeof(horario_propuesto) = 'array')

CONSTRAINT chk_solicitudafiliacion_vence
CHECK (vence_at > created_at)

CONSTRAINT chk_solicitudafiliacion_reaplicar
CHECK (
  puede_reaplicar_desde IS NULL
  OR (resuelta_at IS NOT NULL AND puede_reaplicar_desde > resuelta_at)
)

CONSTRAINT chk_solicitudafiliacion_duplicado_distinto
CHECK (duplicado_de_comercio_id IS NULL OR duplicado_de_comercio_id <> comercio_id)

La tercera parece obvia y no lo es: trg_comercio_duplicado busca candidatos por proximidad y similitud de nombre, y el comercio de la propia solicitud es el candidato perfecto para sí mismo. Sin la restricción, un error en la consulta del trigger produciría un expediente que se señala a sí mismo como duplicado, que es indistinguible de un duplicado real en la bandeja de RF-A-06.

Unicidad¶

Índices¶

Es el índice de apoyo del proceso que vence las solicitudes a los 15 días.

No hay un índice dedicado para la bandeja ordenada por antigüedad todavía; con el volumen de un piloto, created_at (ya indexada por la columna estándar) alcanza.

Triggers¶

trg_solicitudafiliacion_horario_especificacion valida la forma completa de horario_propuesto: exige exactamente 7 elementos, cada uno con dia_semana numérico entre 0 y 6 sin repetir, cerrado booleano, y hora_apertura/hora_cierre como texto presentes si y solo si el día no está cerrado. Es el mismo problema que resuelven trg_parametrosistema_especificacion y trg_media_variantes_especificacion en Catálogos: un jsonb de forma libre necesita su propia barrera porque ningún CHECK declarativo puede validar la estructura completa de un arreglo.

trg_solicitudafiliacion_verificacion es la traducción de la palabra "obligatoria" de RF-C-04. Lee el estado destino y, si tiene apply-equivalente (es decir, si es el estado aprobado del catálogo), rechaza cuando telefono_verificado_at o email_verificado_at siguen nulos. Sin él, un expediente se puede aprobar con datos de contacto que nadie comprobó, y el correo con el enlace de creación de contraseña de RF-C-07 sale hacia una dirección no verificada.

trg_solicitudafiliacion_reapertura cubre el caso raro pero real de RF-C-07: reaplicar reabre el expediente anterior, porque la relación con comercio es 1:1 y unq_comercio_ruccedula impide crear otro comercio con el mismo RUC. Reabrir es limpiar resuelta_at, y eso solo puede pasar cuando ya se cumplieron los quince días que la propia fila anotó en puede_reaplicar_desde.

Notas de diseño¶

horario_propuesto se guarda como evidencia de lo que el solicitante declaró, y no se normaliza en comercio_horario hasta la aprobación: si un comercio alega que se le aprobó con otro horario, la solicitud es la que responde.

solicitud_cambio_comercio¶

Cambios sensibles que no se aplican de inmediato: el valor anterior sigue publicado hasta que administración apruebe.

• Régimen: Mutable protegida
• Origen:

  • RF-C-16
  • RF-A-13

Columnas¶

Constraints¶

CONSTRAINT chk_solicitudcambiocomercio_distancia_coherente
CHECK ((campo = 'ubicacion') = (distancia_m IS NOT NULL))

CONSTRAINT chk_solicitudcambiocomercio_distancia_umbral
CHECK (distancia_m IS NULL OR distancia_m > 100)

CONSTRAINT chk_solicitudcambiocomercio_resuelta_coherente
CHECK ((resuelta_at IS NULL) = (resuelta_by IS NULL))

CONSTRAINT chk_solicitudcambiocomercio_valor_distinto
CHECK (valor_propuesto <> valor_anterior)

Unicidad¶

Triggers¶

trg_solicitudcambiocomercio_snapshot pertenece a la familia de derivación de snapshot: sobrescribe la columna en vez de comparar contra ella. RF-A-13 pide mostrar "el valor anterior y el propuesto lado a lado", y un valor anterior que el llamador declara no prueba nada sobre lo que la ficha pública decía cuando se propuso el cambio.

trg_solicitudcambiocomercio_aplica es la traducción directa de lo que estado_solicitud_cambio.apply significa: el catálogo declara qué estados aplican el cambio, y el trigger lo ejecuta en la misma transacción que marca la solicitud como resuelta. Escribe en comercio la columna que nombra campo, y para ubicacion deserializa el WKT del valor_propuesto, lo que dispara a su vez trg_comercio_zona y rederiva la zona sin ninguna coordinación adicional.

Notas de diseño¶

chk_solicitudcambiocomercio_distancia_umbral codifica que mover el pin menos de 100 m se aplica directo y por tanto no genera fila aquí: la capa de API resuelve ese atajo antes de escribir, y la constraint cierra la vía por la que un INSERT podría dejar una fila con un umbral que no corresponde. Es deliberado que el atajo no sea un trigger: aplicar el cambio directo o encolarlo son dos operaciones distintas, y elegir entre ellas es una decisión del llamador, no un invariante de la fila.

comercio_foto¶

Adjunto fotográfico del comercio.

• Régimen: Mutable rastreada
• Origen:

  • RF-C-15

Columnas¶

comercio_id con llave foránea CASCADE (una foto no significa nada fuera de su comercio y nadie más la referencia), media_id con RESTRICT, y orden (smallint, 0 por defecto): la secuencia que el comercio eligió para su galería, no el orden de inserción.

Unicidad¶

Triggers¶

Notas de diseño¶

La galería de RF-C-15 admite hasta cinco fotos por comercio. Ese tope no es una unicidad ni un CHECK: cuenta filas hermanas, así que es trigger. La ficha anterior documentaba una unq_comerciofoto_comercio que habría limitado a una foto por comercio; no existe en el código y no debe crearse, porque contradice el requerimiento.

pausa_comercio¶

Pausa temporal declarada por el propio comercio.

• Régimen: Mutable protegida
• Origen:

  • RF-C-22

Columnas¶

Constraints¶

CONSTRAINT chk_pausacomercio_fin_coherente
CHECK ((tipo_duracion = 'indefinida') = (fin_at IS NULL))

CONSTRAINT chk_pausacomercio_fin_posterior
CHECK (fin_at IS NULL OR fin_at > inicio_at)

Unicidad¶

Triggers¶

trg_pausacomercio_reservas_vivas hace las dos cosas a la vez, y por eso es un solo trigger: cuenta las reservas del comercio con finalizada_at IS NULL, escribe el número en reservas_pendientes_al_pausar y rechaza si es mayor que cero. RF-C-22 dice que el sistema "muestra el contador de reservas vivas y exige resolverlas antes de permitir la pausa", así que el contador siempre queda en cero en las filas que llegan a existir; su valor está en que el número lo escribió la base y no el llamador, de modo que la columna no puede mentir sobre por qué se admitió la pausa.

chk_pausacomercio_fin_coherente solo exige fin_at IS NULL para tipo_duracion = 'indefinida'; tanto hasta_fecha como hoy exigen un fin_at resuelto. Para hasta_fecha lo trae el llamador; para hoy, trg_pausacomercio_fin lo deriva al cierre del día operativo en America/Managua, que es la duración "hoy" que pide RF-C-22.

comercio_indicador¶

Instantánea diaria de las tasas de cumplimiento por ventana móvil.

• Régimen: append-only
• Origen:

  • RF-C-51
  • RF-A-44
  • RF-A-53

Columnas¶

Constraints¶

CONSTRAINT chk_comercioindicador_ventanadias CHECK (ventana_dias IN (14, 30))

CONSTRAINT chk_comercioindicador_base_coherente
CHECK ((reservas_base = 0) = (tasa_entrega IS NULL))

CONSTRAINT chk_comercioindicador_tasas_juntas
CHECK (
  num_nonnulls(tasa_entrega, tasa_cancelacion, tasa_expiracion, incidencias_por_100)
  IN (0, 4)
)

CONSTRAINT chk_comercioindicador_tasa_entrega_rango
CHECK (tasa_entrega IS NULL OR tasa_entrega BETWEEN 0 AND 100)

CONSTRAINT chk_comercioindicador_tasa_cancelacion_rango
CHECK (tasa_cancelacion IS NULL OR tasa_cancelacion BETWEEN 0 AND 100)

CONSTRAINT chk_comercioindicador_tasa_expiracion_rango
CHECK (tasa_expiracion IS NULL OR tasa_expiracion BETWEEN 0 AND 100)

CONSTRAINT chk_comercioindicador_reservas_base CHECK (reservas_base >= 0)

incidencias_por_100 queda fuera de chk_comercioindicador_tasas_rango: no está acotada a 100 como las otras tres, así que se agrupa con ellas solo en la constraint "juntas o ninguna".

Unicidad¶

Notas de diseño¶

Las tasas admiten nulo y el CHECK obliga a que las cuatro lo sean a la vez: un comercio sin reservas en la ventana no tiene tasa de entrega del 0 %, no tiene tasa. Escribir cero lo haría aparecer en la alerta de cumplimiento como el peor comercio de la plataforma por el mérito de no haber vendido nada.