Saltar a contenido

Admin · Chat, flujos y recomendador

Esta área de la API admin agrupa tres responsabilidades relacionadas con el chat conversacional: el historial de conversaciones (consulta, exportación, cambio de estado y borrado de conversaciones y sus logs de depuración), la gestión de flujos de decisión (conversation-trees) que alimentan el motor híbrido, y la introspección de las acciones, checks e intents que el editor de flujos ofrece como paleta. Sirve para que el operador del restaurante monitorice lo que la IA conversa con los clientes y para que diseñe y publique el árbol de decisión que gobierna el motor híbrido.

Todos los endpoints requieren autenticación de administrador (JWT) y aplican multitenancy por restaurant_id: cada petición pasa por el puerto compartido IRestaurantAccessChecker, que verifica el acceso del admin al restaurante y traduce los fallos a 404 (no existe) o 403 (sin acceso). Un SUPER_ADMIN ve todos los restaurantes; el resto de roles quedan acotados a los restaurantes a los que tienen acceso. Nunca se confía en el restaurant_id del body: siempre se valida contra la auth o el path/query verificado.

Patrones a tener en cuenta:

  • Paginación en el listado de conversaciones con page + per_page (shape canónico PaginatedResponse).
  • Versionado de flujos: un árbol está en estado draft, active o archived; solo se edita un draft (PUT devuelve 409 en otro estado), se valida contra los registros reales del intérprete y se activa archivando la versión anterior (rollback posible). El árbol es datos (JSON en conversation_trees), no código.
  • Simulación: POST /{tree_id}/simulate hace un dry-run de una frase contra el árbol y devuelve la ruta de nodos recorrida, sin efectos secundarios.
  • Exportación de conversaciones en JSON o CSV, incluyendo el contenido de thinking oculto al cliente.

Tiempo real

Estos endpoints son de gestión sobre datos ya persistidos; el flujo conversacional en vivo (frames content, : thinking, done, recommendation) viaja por SSE en las rutas de chat del cliente, no aquí. Ver Eventos SSE.

Para entender qué decide cada pieza del chat, consulta la arquitectura del chat híbrido y del recomendador. Visión general de la API en Referencia de la API.

Generado automáticamente

Las tablas y fichas de endpoints de esta página se generan desde el contrato OpenAPI. No las edites a mano; edita la intro en documentation/reference/api/_intros/admin-chat-flujos.md y regenera con python scripts/gen_openapi_reference.py.

Resumen de endpoints

Método Ruta Resumen Auth
GET /api/v1/admin/audit-logs List Audit Logs Bearer (admin)
GET /api/v1/admin/audit-logs/export Export Audit Logs Bearer (admin)
GET /api/v1/admin/audit-logs/export/csv Export Audit Logs Csv Bearer (admin)
GET /api/v1/admin/audit-logs/{log_id} Get Audit Log Bearer (admin)
GET /api/v1/admin/reviews/restaurant/{restaurant_id} List Reviews Bearer (admin)

Detalle

GET /api/v1/admin/audit-logs

List Audit Logs

List audit logs with pagination and filters.

  • Auth: Bearer (admin)
  • Parámetros: action (query, opcional), action_type (query, opcional), cursor (query, opcional), date_from (query, opcional), date_to (query, opcional), page (query, opcional), per_page (query, opcional), resource_type (query, opcional), restaurant_id (query, opcional), search (query, opcional), sort_by (query, opcional), sort_order (query, opcional), status (query, opcional), target_type (query, opcional), user_id (query, opcional)
  • Respuestas: 200 AuditLogListResponse, 422 HTTPValidationError

GET /api/v1/admin/audit-logs/export

Export Audit Logs

Export audit logs in CSV or JSON format (super admin only).

  • Auth: Bearer (admin)
  • Parámetros: action (query, opcional), action_type (query, opcional), date_from (query, opcional), date_to (query, opcional), format (query, opcional), resource_type (query, opcional), status (query, opcional), target_type (query, opcional), user_id (query, opcional)
  • Respuestas: 200, 422 HTTPValidationError

GET /api/v1/admin/audit-logs/export/csv

Export Audit Logs Csv

Export audit logs as CSV (super admin only).

  • Auth: Bearer (admin)
  • Parámetros: action (query, opcional), action_type (query, opcional), date_from (query, opcional), date_to (query, opcional), resource_type (query, opcional), status (query, opcional), target_type (query, opcional), user_id (query, opcional)
  • Respuestas: 200, 422 HTTPValidationError

GET /api/v1/admin/audit-logs/{log_id}

Get Audit Log

Get audit log detail.

  • Auth: Bearer (admin)
  • Parámetros: log_id (path, requerido)
  • Respuestas: 200 AuditLogResponse, 422 HTTPValidationError

GET /api/v1/admin/reviews/restaurant/{restaurant_id}

List Reviews

List a restaurant's reviews. Requires verified access to the restaurant.

  • Auth: Bearer (admin)
  • Parámetros: restaurant_id (path, requerido), page (query, opcional), size (query, opcional)
  • Respuestas: 200 ReviewListResponse, 422 HTTPValidationError