Resenas

Ruta: /teacher/reviews · Atajo: g r · Sidebar: Resenas

Gestion completa del sistema de resenas: moderar, responder, importar de plataformas externas, solicitar a alumnos y configurar automatizaciones.

---

Que hay

5 Tabs

Overview

4 KPI Cards:

• Rating medio (estrella, fondo ambar)
• Total de reviews (comentario, fondo azul)
• Tasa de respuesta % (tendencia, fondo verde)
• Este mes (calendario, fondo morado)

Distribucion de ratings: Barras horizontales 5→1 estrellas con conteos.

Reviews recientes: Primeras 5 reviews con cards completas.

Todas

Filtros:

• Busqueda full-text (debounced 300ms) por body, titulo, nombre
• Filtro por estado: pending, approved, hidden, flagged
• Filtro por source: pinteach, preply, italki, verbling, google_business, trustpilot, other

Lista paginada (20 por pagina) con review cards completas.

Solicitudes

Tabla con columnas: Alumno (avatar+nombre+email), Estado, Canal, Enviada, Completada, Rating.

Merge inteligente: Muestra TODOS los alumnos de la lista de estudiantes con su solicitud mas reciente. Si no se ha enviado solicitud, muestra boton “Enviar” inline.

Filtro por estado: not_sent, pending, completed, expired, dismissed.

Note

not_sent es un valor computado en frontend (el alumno no tiene registro de solicitud en la tabla review_requests). El enum de base de datos solo tiene: pending, completed, expired, dismissed.

Cooldown: Maximo 1 solicitud por alumno cada 7 dias.

Importar

Formulario de importacion:

• Source (requerido): preply, italki, verbling, google_business, trustpilot, other
• Nombre del reviewer (requerido)
• Rating (requerido, picker de 5 estrellas)
• Titulo (opcional)
• Body (opcional, max 2000 chars)
• URL externa (opcional)
• Fecha de display (opcional, date picker)

Note

Las reviews importadas no admiten imagenes. Solo las reviews enviadas por alumnos via ReviewForm pueden incluir imageUrls.

Configuracion

Auto-solicitud:

• Toggle activar auto-solicitud despues de sesiones
• Minutos despues de la sesion (5-1440)
• Sesiones minimas antes de solicitar (1-50)

Moderacion:

• Toggle auto-aprobar
• Rating minimo para auto-aprobar (1-5)

Display:

• Mostrar en perfil publico
• Mostrar reviews externas
• Notificar al profesor en nuevas reviews

Filtros en reviews publicas

La seccion publica del perfil (public-reviews-section.tsx) permite filtrar y ordenar reviews:

• Pills de rating: Botones 5, 4, 3, 2, 1 estrellas con comportamiento toggle. Se pueden combinar.
• Dropdown de source: Aparece solo cuando existen 2 o mas fuentes distintas. Opciones generadas dinamicamente desde availableSources.
• Dropdown de orden: Mas recientes / Mejor valoradas / Peor valoradas.
• Limpiar filtros: Enlace que resetea todos los filtros activos.

El backend (listPublic()) acepta source y sortBy como parametros. La consulta de estadisticas (barra resumen) es independiente y siempre devuelve totales sin filtrar.

---

Review card (componente)

Cada review muestra:

• Avatar o circulo de inicial
• Nombre (o “Anonimo”)
• 5 estrellas (llenas/vacias)
• Tiempo relativo (“5m”, “2h”, “3d”)
• Badge de verificacion (verde)
• Badge de source (gris, omitido para “pinteach”)
• Badge de estado (amber=pending, gray=hidden, red=flagged)
• Titulo + body
• Quick tags (badges)
• Miniaturas de imagenes (thumbnails 64x64px, object-cover, max 3) — solo si la review tiene imageUrls
• Votacion de utilidad — Boton “Fue util” con contador en reviews publicas. Los visitantes pueden votar una vez por review. El voto se registra en reviews.helpfulCount y se muestra como “X personas encontraron esto util”. La accion llama a POST /public/:slug/reviews/:id/helpful. Una cookie previene votos duplicados del mismo visitante.
• Respuesta del profesor (caja gris)
• Reviews destacadas: borde ambar + fondo ambar claro

Acciones por review

Accion	Efecto
Aprobar	Estado → approved
Ocultar	Estado → hidden (opacity reducida)
Destacar	Toggle isFeatured (max 5 por profesor). Si se intenta destacar la 6ta, muestra toast “Maximo 5 reviews destacadas”
Responder	Abre formulario de respuesta (max 1000 chars)
Eliminar respuesta	Borra teacherResponse
Eliminar review	Hard delete con confirmacion

---

Que falta

Feature	Descripcion	Estado	Implementado
Reviews con imagenes	Los alumnos pueden adjuntar hasta 3 URLs de imagen al enviar su resena via ReviewForm. Se muestran como miniaturas 64x64px en ReviewCard	✅	Batch 2
Votacion de utilidad	Boton “Fue util” en reviews publicas con contador helpfulCount. Prevencion de votos duplicados via cookie	✅	Batch 3
Limite de destacadas con feedback	Al intentar destacar la 6ta review, se muestra un toast de error. Comprobacion client-side en handleUpdate antes de la mutacion	✅	Batch 3
Traduccion automatica	Reviews en otros idiomas no se traducen. Podria integrarse Google Translate para reviews de alumnos internacionales	Aplazado

---

Que falla

No hay bugs conocidos en esta pagina.

---

Que cambiaria

Mejora	Descripcion	Dificultad	Estado	Implementado
Filtro por fecha en reviews publicas	Los filtros de rating y source ya estan implementados. Anadir un filtro por rango de fechas completaria la experiencia	Facil	✅	Batch 4
Auto-solicitud mejorada	Agregar canal de solicitud configurable (in_app, email, link) y preview del mensaje que recibira el alumno	Medio

---

Referencia tecnica

Archivos clave

Archivo	Proposito
apps/web/src/routes/teacher/reviews.lazy.tsx	Pagina principal (5 tabs)
apps/web/src/components/reviews/review-card.tsx	Card de review
apps/web/src/components/reviews/review-response-form.tsx	Formulario de respuesta
apps/web/src/components/reviews/review-settings-panel.tsx	Panel de configuracion
apps/web/src/components/reviews/import-review-form.tsx	Formulario de importacion
apps/web/src/components/reviews/review-form.tsx	Formulario de envio de resena (portal alumno)
apps/web/src/components/reviews/public-reviews-section.tsx	Seccion de resenas en perfil publico
apps/api/src/services/reviews/review-service.ts	Servicio principal
apps/api/src/services/reviews/review-request-service.ts	Solicitudes
apps/api/src/services/reviews/review-settings-service.ts	Configuracion

API

Endpoint	Metodo	Proposito
/teacher/reviews/stats	GET	KPIs y distribucion
/teacher/reviews	GET	Lista paginada con filtros
/public/:slug/reviews	GET	Reviews publicas. Params: source, sortBy (newest/highest/lowest), dateFrom, dateTo. Devuelve availableSources[]
/teacher/reviews/:id	PATCH/DELETE	Moderar / eliminar
/teacher/reviews/:id/respond	POST/DELETE	Responder / eliminar respuesta
/teacher/reviews/import	POST	Importar review externa
/teacher/reviews/requests	GET	Lista de solicitudes
/teacher/reviews/requests/send	POST	Enviar solicitud manual
/teacher/reviews/settings	GET/PATCH	Configuracion

Imagenes en reviews

• DB: reviews.imageUrls JSONB — array de URLs de imagen (strings). No hay limite en DB; la restriccion de max 3 se aplica en el formulario de alumno.
• Formulario alumno (ReviewForm): Campo “Step 4” visible tras seleccionar rating. Valida URL valida con new URL(). Muestra previsualizacion 64x64px con boton X para eliminar. Maximo 3 imagenes. Enter en el input llama addImageUrl().
• Card (ReviewCard): Bloque de miniaturas renderizado entre quick tags y la respuesta del profesor. Condicional: solo aparece si review.imageUrls && review.imageUrls.length > 0.
• API: El campo imageUrls se envia en el body de POST /student/sessions/:id/review. El endpoint de listado (GET /teacher/reviews) devuelve imageUrls[] en cada review.

Valores por defecto

Parametro	Valor
Cooldown entre solicitudes	7 dias
Ventana de edicion de resena	30 dias
Retraso auto-request	30 minutos
Sesiones minimas para solicitar	1
Maximo imagenes por review	3