Saltar al contenido principal

Comentarios de Usuarios — Referencia Técnica

← Volver a Comentarios de Usuarios

Dónde vive esto​

Backend

Frontend

  • apps/frontend-nextjs/src/page-components/settings/FeedbackPage.tsx (enrutado en apps/frontend-nextjs/src/app/settings/feedback/page.tsx, enlazado desde Settings → Send feedback) — el formulario de envío, el historial de "Your submissions" (myFeedback), y el tablero votable de "Community feature requests" (publicFeedback + upvoteFeedback/downvoteFeedback). Las operaciones de GraphQL se declaran de forma inline en el componente (aún sin hooks generados, mismo patrón que SocialLinksPage.tsx).
  • apps/frontend-admin/src/app/feedback/page.tsx + FeedbackContent.tsx — la cola de priorización de administración (/feedback, requiere MANAGE_FEEDBACK). Ver Comentarios de usuarios (administración) para toda la superficie de GraphQL de administración y los detalles del permiso.

Checklist de implementación técnica​

  • submitFeedback — conectado: SubmitFeedbackInput → resolver → user-feedback.manager.js#submitFeedback; usado por FeedbackPage.tsx
  • myFeedback — conectado, autenticado; usado por la lista "Your submissions" de FeedbackPage.tsx
  • feedbackById — conectado, autenticado, solo para el propietario (resuelve a null si quien llama no es dueño del elemento)
  • publicFeedback — conectado; tablero votable, por defecto feedbackType: feature_request; usado por "Community feature requests" de FeedbackPage.tsx
  • upvoteFeedback / downvoteFeedback — conectados, deduplicados por usuario mediante user_feedback_vote; usados por FeedbackPage.tsx
  • Los atajos submitBugReport / submitFeatureRequest — existen solo como métodos del manager; no se exponen como mutations de GraphQL
  • getMostUpvoted — existe solo como método del manager; no se expone como query de GraphQL (la query publicFeedback ya ordena por votos a favor y sirve como la tabla de clasificación pública)
  • Revisión de administrador (adminGetFeedback, adminGetFeedbackStats, adminUpdateFeedbackStatus, adminSetFeedbackPriority, adminRespondToFeedback) — conectados en el schema de administración, protegidos por MANAGE_FEEDBACK, con un frontend de administración real en /feedback. Ver Comentarios de usuarios (administración). markAsResolved/getMostUpvoted/getByStatus/getByPriority siguen existiendo solo en el manager (sin uso por ningún resolver - los dos últimos son código muerto que quedó de antes de que getAllFeedback/getAll incorporaran soporte de filtros).

Tipos de comentarios​

TipoDescripción
bugAlgo está roto o no funciona como se espera
feature_requestSolicitud de una nueva funcionalidad
generalComentario general
complaintQueja sobre la plataforma u otro usuario
suggestionIdea de mejora

Enviar comentarios​

submitFeedback crea un nuevo elemento de comentario. feedbackType determina cómo se enruta. title es el resumen de una línea; description es el texto completo. La respuesta incluye el status inicial (pending).

mutation SubmitFeedback($input: SubmitFeedbackInput!) {
  submitFeedback(input: $input) {
    id feedbackType title status createdAt
  }
}

Campos de SubmitFeedbackInput: feedbackType (requerido — bug | feature_request | general | complaint | suggestion), title (requerido), description (requerido), category (opcional, p. ej. ui_ux | performance | feature | content | security | privacy | other; por defecto other), platform (opcional; por defecto web), satisfactionRating (entero opcional de 1 a 5).

El manager también expone los envoltorios de conveniencia submitBugReport(userId, title, description) / submitFeatureRequest(userId, title, description) que establecen feedbackType automáticamente, pero no se exponen como mutations de GraphQL — en su lugar, el cliente establece feedbackType directamente en SubmitFeedbackInput (ver el selector de tipo de FeedbackPage.tsx).

Consultas de usuario​

myFeedback muestra el historial de envíos del usuario actual con actualizaciones de estado en vivo, incluyendo cualquier adminResponse.

query MyFeedback($limit: Int, $offset: Int) {
  myFeedback(limit: $limit, offset: $offset) {
    id feedbackType title description status priority upvotes adminResponse createdAt
  }
}

feedbackById obtiene un solo elemento por id — quien llama debe ser el propietario, de lo contrario resuelve a null.

query FeedbackById($id: ID!) {
  feedbackById(id: $id) {
    id feedbackType title description status priority adminResponse createdAt
  }
}

Votación​

Los miembros de la comunidad pueden señalar qué solicitudes de funcionalidades o reportes de errores les importan más. upvoteFeedback / downvoteFeedback se deduplican por usuario mediante la tabla user_feedback_vote (una fila por usuario por elemento de comentario): votar de nuevo desactiva el voto, y votar en sentido contrario lo cambia. Los conteos desnormalizados upvotes/downvotes viven en user_feedback, y UserFeedback.myVote refleja el voto actual de quien llama ('up' | 'down' | null).

publicFeedback es el tablero público y votable — ordena por upvotes de forma descendente, por defecto usa feedbackType: feature_request, y acepta 'all' para explorar todos los tipos. No existe una query separada mostUpvotedFeedback; el orden de publicFeedback ya sirve como tabla de clasificación.

mutation UpvoteFeedback($feedbackId: ID!)   { upvoteFeedback(feedbackId: $feedbackId) { id upvotes downvotes myVote } }
mutation DownvoteFeedback($feedbackId: ID!) { downvoteFeedback(feedbackId: $feedbackId) { id upvotes downvotes myVote } }

query PublicFeedback($feedbackType: String, $limit: Int, $offset: Int) {
  publicFeedback(feedbackType: $feedbackType, limit: $limit, offset: $offset) {
    id title description feedbackType status upvotes downvotes myVote createdAt
    user { id username }
  }
}

Ciclo de vida del estado​

pending → in_review → in_progress → resolved
                    ↘ rejected
                    ↘ duplicate

Este es el conjunto validado por el método updateStatus del manager, expuesto como adminUpdateFeedbackStatus en el schema de administración (ver "Gestión de administrador" a continuación).

Gestión de administrador​

graphql/resolvers/admin/user-feedback-admin.resolver.js conecta las operaciones orientadas a administración, protegidas por context.admin + el permiso MANAGE_FEEDBACK (ver Comentarios de usuarios (administración) para la checklist completa, los detalles del permiso y la referencia de GraphQL):

  • adminGetFeedback → user-feedback.manager.js#getAllFeedback — lista comentarios con filtros opcionales de status/priority/feedbackType, paginados
  • adminUpdateFeedbackStatus → updateStatus — mueve un elemento a través del ciclo de vida anterior
  • adminSetFeedbackPriority → setPriority — asigna urgencia (low / medium / high / critical)
  • adminRespondToFeedback → el nuevo método del manager respondToFeedback — establece adminResponse, reviewedBy (el id del administrador que llama) y reviewedAt juntos en una sola acción
  • adminGetFeedbackStats → getFeedbackStats — desglose por tipo, estado y prioridad, además de los totales de votos

markAsResolved (establece status: 'resolved', resolvedAt, y un campo resolution de texto libre que en realidad no es una columna de UserFeedback - un no-op preexistente) no tiene resolver y no lo usa el frontend de administración, que maneja el estado por completo a través de adminUpdateFeedbackStatus.

adminResponse está expuesta en myFeedback / feedbackById / publicFeedback, además del schema de administración, por lo que una respuesta escrita mediante adminRespondToFeedback aparece de inmediato en FeedbackPage.tsx.

Niveles de prioridad​

PrioridadDescripción
lowProblema menor, sin urgencia
mediumPrioridad predeterminada
highImpacto significativo
criticalBloqueante / urgente