¿Qué es SACS Arena?

SACS Arena es una API REST que ejecuta un flujo de búsqueda inteligente en 7 pasos contra un índice Azure Cognitive Search, usando OpenAI para clasificar la intención del usuario y devolver resultados contextuales para el Mundial 2026.

El flujo completo ocurre en el servidor — el frontend solo necesita enviar el query y reaccionar al decision que llega en la respuesta para saber qué mostrar. El campo decision puede ser CasoA (servicio dominante), CasoC (torneo dominante) o CasoD (ambiguo / navegar por filtros).

URL base

https://eventos.sacspro.com

Flujo de llamadas (máximo 3)

Configuración

Todas las variables se configuran en Azure App Service → Configuration → Application Settings. No incluir valores reales en appsettings.json del repositorio.

Variables requeridas

Azure Search

OpenAI

Sitios (mínimo un sitio)

Variables opcionales

Búsqueda — cantidad de resultados

Semantic (requiere Azure Search tier S1+)

Vector Search (Hybrid Search)

Scoring

Umbrales de decisión

Rate Limiting

Redis (caché distribuida)

Slack (notificaciones)

Monitoreo

Variables de override por sitio

Cada sitio puede sobreescribir los valores globales. Si una variable del sitio no se define → usa el valor global. Para agregar múltiples sitios incrementar el índice (0, 1, 2…).

# Sitio 0 (primer sitio)
Sites__0__SiteId                  = 61
Sites__0__Name                    = Posta MX
Sites__0__ApiKey                  = sf-postamx-xxxxxxxx
Sites__0__AllowedOrigins__0       = https://www.postamx.com
Sites__0__SemanticOnExploratory   = true
Sites__0__SemanticOnFinalSearch   = true
Sites__0__SemanticCallsLimit      = 80000
Sites__0__TimeZoneId             = Central Standard Time (Mexico)
Sites__0__GamificationEnabled    = true

# Sitio 1 (segundo sitio — con overrides)
Sites__1__SiteId                  = 42
Sites__1__Name                    = Otro Sitio
Sites__1__ApiKey                  = sf-otrop-xxxxxxxx
Sites__1__AllowedOrigins__0       = https://www.otrosite.com
Sites__1__OpenAIModel             = gpt-4o        # override del modelo global
Sites__1__FinalSearchTop          = 30            # override del top global
Sites__1__UseVectorSearch         = true          # hybrid search para este sitio

Notas de seguridad

$site = "nombrecliente"
$key  = [System.Guid]::NewGuid().ToString("N").Substring(0, 8)
Write-Host "sf-$site-$key"

Autenticación

Todos los endpoints de búsqueda requieren dos headers HTTP:

Códigos de error

Formato de error

{
  "error": "API Key requerida",
  "header": "X-Api-Key"
}

Flujo de búsqueda — 7 pasos

El flujo completo se ejecuta en SearchFlowOrchestrator.ExecuteAsync(). Cada paso alimenta al siguiente. El frontend recibe un único JSON con todos los bloques y solo necesita respetar los flags show de cada sección.

QueryUnderstandingService.AnalyzeAsync() envía el query a OpenAI y recibe:

Si la llamada a OpenAI falla, el orquestador hace fallback a LocalQueryClassifier.Classify() — un clasificador por reglas heurísticas que garantiza que siempre haya un intent mínimo para continuar el flujo.

El paso 1 y el paso 2 se ejecutan en paralelo para minimizar latencia.

AzureSearchService.ExecutePrimarySemanticAsync() ejecuta una búsqueda contra Azure Search con filtro base siteid eq {SiteId} (sin filtros de intent) usando el reranker semántico si está configurado.

Retorna:

• Documentos con rerankerScore (escala 0–4) y score léxico
• Facets de intentPrimary e intentService — distribución de intents en resultados
• Extracto de respuesta directa (captions) si el reranker semántico lo genera

Se obtienen los facets globales del sitio (distribución de documentos por intent en todo el índice) desde caché Redis. Se usan para construir las opciones de navegación en filter1.otherOptions — la sección "otras categorías" que aparece cuando el usuario navega sin un query específico.

Si Redis no está configurado, se calculan en memoria por cada request (mayor latencia). El TTL de caché de facets globales es de varios minutos para balancear frescura y rendimiento.

SemanticDecisionEngine.Decide() evalúa los resultados del paso 2 y la clasificación del paso 1 para producir un FlowState que determina qué bloque mostrar.

La dominancia se calcula como: count(docs con intent top) / total_docs_semánticos. Si el intent que detectó QU no aparece en los facets semánticos y confidence >= 0.70 → fuerza EmptyCascade.

Cuando el FlowState es EmptyCascade, el orquestador construye un resultado alternativo:

• Si QU detectó entidades (equipos, ciudades, personas) → busca por esas entidades directamente
• Si no hay entidades → presenta OtherOptions con los intents de mayor cobertura del sitio
• El bloque noContent en el response tiene show: true con mensaje y contenido relacionado

Se construyen chips de refinamiento a partir de los facets semánticos del paso 2: top 4 intents de torneo + top 2 intents de servicio. También se agregan sugerencias QA generadas por QU si no están ya repetidas en los facets.

Estos chips aparecen en el response como filterSuggestions.semantic[] y son opcionales para el frontend — funcionan como atajos para refinar el query activo.

Según el FlowState del paso 4, el orquestador llama al constructor correspondiente:

• BuildDirectAnswerResult() → CasoC con directAnswer.show: true
• BuildResultsResult() → CasoA o CasoC con results.items poblados
• BuildFilter1Result() → CasoD con filter1.show: true y opciones de intent
• BuildEmptyCascadeResultAsync() → CasoD con noContent.show: true + OtherOptions

Todos los constructores populan siempre filterSuggestions, availableCities y debug independientemente del caso.

Tabla de decisiones completa

POST /api/search

Ejecuta el flujo completo de búsqueda (7 pasos). Primera llamada del flujo — siempre con userSelection: null. Retorna SearchResponse con todos los bloques según la decisión del motor.

const res = await fetch('https://eventos.sacspro.com/api/search', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Api-Key':  'sf-postamx-a3b5c7d9',
    'X-Site-Id':  '61'
  },
  body: JSON.stringify({
    siteId:        61,
    query:         "resultado mexico uruguay",
    activeCity:    null,    // ciudad activa del filtro (opcional)
    userSelection: null
  })
})
const data = await res.json()

Lógica del frontend — response inicial

// Respuesta directa extractiva (responde la pregunta directamente)
if (data.directAnswer?.show) {
  renderDirectAnswer(data.directAnswer)
}

// Navegación por intents (Filter1)
if (data.filter1.show) {
  renderFilter1(data.filter1)
}

// Resultados principales
if (data.results.show) {
  renderResults(data.results)
}

// Sin resultados — mostrar mensaje + OtherOptions
if (data.noContent.show) {
  renderNoContent(data.noContent)
}

// Chips de refinamiento (siempre presentes)
renderFilterSuggestions(data.filterSuggestions)

// Flujo terminado si no hay más filtros pendientes
const flowDone = !data.filter1.show && !data.suggestFilter2.show

POST /api/search/refine

Llamar cuando el usuario selecciona una opción del Filter1 (intent). Requiere userSelection no nulo. Devuelve resultados filtrados por ese intent y, si hay entidades disponibles, muestra suggestFilter2.

const opcion = data.filter1.relatedOptions[0]

const body = {
  siteId: 61,
  query:  "resultado mexico uruguay",
  activeCity: null,
  userSelection: {
    selectedIntent:         opcion.intent,   // "Resultados y marcadores"
    isServiceIntent:        opcion.isService, // false
    userExplicitlySelected: true,
    selectedTeam:           null,
    selectedPlace:          null,
    selectedPerson:         null
  }
}

Response tras elegir Filter1

POST /api/search/filter2

Filtro directo por intent + entidad (equipo, ciudad o persona) sin re-ejecutar Query Understanding. Más eficiente que /refine cuando ya se conoce el intent y la entidad exacta. Siempre retorna resultados finales (filter1.show y suggestFilter2.show = false).

{
  "siteId":     61,
  "intent":     "Resultados y marcadores",
  "isService":  false,
  "activeCity": null,
  "entityTeam": "México",
  "entityPlace":null,
  "entityPerson":null
}

GET /api/cities

Retorna la lista de ciudades disponibles para filtrar en este sitio. Llamar al inicializar el widget para poblar el selector de ciudad. No requiere parámetros — usa el X-Site-Id del header.

[
  {
    "label":          "Ciudad de México",
    "canonicalValue": "Ciudad de México"   // usar este valor en activeCity
  },
  {
    "label":          "Monterrey",
    "canonicalValue": "Monterrey"
  }
]

GET /api/suggestions

Retorna sugerencias de autocompletado para el campo de búsqueda. Incluye sugerencias textuales, facets recientes y distribución de intents para mostrar al usuario antes de escribir.

GET /api/today-news

Retorna las últimas 6 noticias del día del sitio, ordenadas por fecha de creación. Usado para poblar la pantalla de bienvenida del widget antes de que el usuario escriba.

GET /api/tag-cloud

Retorna una nube de tags con la distribución de documentos por intent del sitio. Usado para mostrar categorías al usuario en la pantalla inicial del widget.

GET /api/site-config

Retorna la configuración pública del sitio: template de bienvenida, flags habilitados (gamificación, newsletter, fixtures), ciudades disponibles. Llamar al inicializar el widget.

{
  "siteId":             61,
  "welcomeTemplate":   "template1",
  "gamificationEnabled":true,
  "newsletterEnabled":  true,
  "showFixtures":       true,
  "enableFeedback":     false,
  "availableCities": [
    { "label": "Ciudad de México", "canonicalValue": "Ciudad de México" }
  ]
}

POST /api/subscribe

Suscribe un email al newsletter del sitio. Solo activo si NewsletterEnabled: true.

Response: { "ok": true, "alreadySubscribed": false }

POST /api/feedback

Registra feedback del usuario sobre los resultados de búsqueda. Solo activo si EnableFeedback: true en la configuración del sitio.

POST /api/telemetry/*

Endpoints de tracking para análisis de comportamiento. El widget los llama automáticamente — no requieren integración manual adicional por parte del cliente.

/click — registra cuando el usuario hace clic en un resultado.
/zero-click — registra cuando la búsqueda no produjo ningún clic.

Modelo: SearchRequest

Campos de UserSelection

Modelo: SearchResponse

DirectAnswerDto

Filter1Block

Filter1Option

SuggestFilter2Dto

FilterSuggestionsDto

NoContentDto

ResultsBlock

Modelo: DocumentDto

Cada elemento en results.items, directAnswer.others y noContent.relatedContent:

Modelo: Filter2Request

Request para POST /api/search/filter2:

Endpoints de Dashboard

Solo requieren el header X-Api-Key. No requieren X-Site-Id.