Skip to content

Feedback (widget para beta testers) ​

Este módulo recibe el feedback que los usuarios envían desde el widget flotante que aparece en toda la aplicación (spec completa: ). Es un recurso global de la plataforma — no está asociado ni filtrado por empresa/tenant — y está pensado para la fase de beta: cualquier persona que use la plataforma, esté o no autenticada, puede dejar una puntuación de 1 a 5 estrellas y un comentario opcional.

Este módulo se desarrolló en varias tareas, todas completas:

  • FEEDBACK-001 — creó la entidad FeedbackEntity y el módulo vacío.
  • FEEDBACK-002 — endpoint público de envío POST /feedback.
  • FEEDBACK-003 — listado/gestión para super admin.
  • FEEDBACK-004 — notificaciones in-app al recibir feedback nuevo (ver notifications.md).

Enviar feedback ​

http
POST /feedback
Content-Type: application/json

{
  "rating": 5,
  "comment": "Me encantó el nuevo dashboard",
  "url": "https://app.nimobase.com/dashboard",
  "userAgent": "Mozilla/5.0 (...)",
  "browser": "Chrome",
  "browserVersion": "128.0",
  "os": "macOS",
  "deviceModel": "MacBook Pro",
  "screenResolution": "1920x1080",
  "viewportSize": "1440x900",
  "browserLanguage": "es-ES"
}
  • rating (1-5) es obligatorio; el resto de campos son opcionales.
  • No requiere sesión. Es un endpoint público — cualquier visitante puede enviarlo.
  • Si la petición incluye un token válido (Authorization: Bearer <token> o X-API-Key), el feedback queda asociado a userId, role y companyId de quien lo envía. Si no hay sesión, esos campos se guardan como null (feedback anónimo).
  • La metadata técnica (navegador, sistema operativo, resolución, etc.) la captura y envía el propio cliente (frontend / SDK launcher) — el backend no la deduce a partir del User-Agent.
  • Los campos de metadata tienen tope de longitud en el API (@MaxLength). El cliente del launcher trunca valores auto-capturados a esos topes antes de enviar, para que un UA o URL anómalamente largos no tumben el envío con 400. Un POST hecho a mano con campos oversized sigue respondiendo 400.
  • Todo feedback nuevo se marca internamente como "no leído" (read: false), a la espera de que un super admin lo revise.
  • Al recibirse un feedback nuevo, todos los super administradores de la plataforma reciben una notificación in-app (FEEDBACK_RECEIVED) — ver notifications.md.

Límite de envíos (rate limiting) ​

Para evitar abuso desde el widget público, el endpoint acepta como máximo 5 envíos por hora desde la misma dirección IP. Superado ese límite, responde 429 Too Many Requests hasta que la ventana de una hora se reinicia.

Consultar y gestionar feedback (super admin) ​

El feedback es un recurso de plataforma, igual que los planes de billing (BillingPlanEntity) — no tiene companyId propio para acotar por tenant. Por eso el acceso de lectura/gestión no se controla con un rol de empresa (OWNER/ADMIN), sino con el flag global isSuperAdmin del usuario, con el mismo patrón que PlansService.assertSuperAdmin():

  • Cualquier usuario autenticado que no sea super admin recibe 403 Forbidden.
  • Una petición sin token recibe 401 Unauthorized (ambas rutas están bajo el JwtAuthGuard global, no son @Public()).

Listar feedback ​

http
GET /feedback
GET /feedback?read=false
Authorization: Bearer <token-de-super-admin>
  • Devuelve todo el feedback recibido, ordenado del más reciente al más antiguo, con todo su contexto (rating, comentario, metadata técnica, identidad si aplica, fechas).
  • El query param opcional read (true/false) filtra el listado por estado leído/no-leído.

Marcar como leído ​

http
PATCH /feedback/:id/read
Authorization: Bearer <token-de-super-admin>
  • Marca el feedback indicado como read: true.
  • El estado leído/no-leído es único y compartido: no hay seguimiento por super admin. Que un super admin lo marque como leído lo marca como leído para todos.

Qué queda fuera de alcance ​

  • Adjuntar capturas de pantalla, exportación o analítica agregada — explícitamente fuera de alcance de la spec completa.
  • Estados de resolución/seguimiento más allá de leído/no-leído — explícitamente fuera de alcance.
  • Responder al usuario que envió el feedback — no hay hilo de conversación ni email de vuelta.