Files
edgar.friendly ebbd7b696e
deploy-branch / deploy (push) Successful in 2m45s
deploy-branch / teardown (push) Skipped
tests / Unitarias + componente + build (push) Failing after 3m3s
tests / Integración (Nominatim real, opt-in) (push) Skipped
tests / Unitarias + componente + build (pull_request) Failing after 2m59s
tests / Integración (Nominatim real, opt-in) (pull_request) Skipped
feat(tarjeta): rediseño de usabilidad — descripción arriba, vista previa de reseñas y barra de acciones
- La descripción del local pasa a bloque propio ENCIMA de las reseñas
- Reseñas: carga al montar con 2 visibles sin expandir; expansión con
  animación (grid-template-rows 0fr→1fr, 350ms) que revela todas + el
  formulario; pista "Ver las N reseñas" cuando hay más de 2
- Barra inferior a ancho completo: Comentar (expande+enfoca) · Reportar
  (formulario controlado) · Marcar (favorito, corazón fuera de cabecera,
  aria-pressed) · Compartir (antes en cabecera); fecha pequeñita encima
- openspec: archiva resenas-por-local (spec principal creado por sync) y
  abre tarjeta-local-rediseno (specs de tarjeta-local + resenas modificada)

Suite: 138/138 (+6 netos).
2026-10-11 23:21:22 +02:00

7.0 KiB

Design: Reseñas múltiples por local (issue #6)

Context

La issue #6 pide comentarios y valoraciones múltiples por local (una reseña por usuario, editable). Entrevista con el usuario (2026-10-11):

  • Identidad v1: anónima estilo 4chan — huella de dispositivo, sin cuentas; "ya añadiremos cuentas". Preocupación explícita: boicots y DDoS.
  • UI: sección desplegable en la propia tarjeta del local.
  • Display del reseñador: "Anónimo" con inicial/huella + fecha.
  • Modelo de datos: tabla resenas + media agregada en locales.puntuacion (elegido en la primera ronda de entrevista).
  • Moderación: publicación directa + reportes (como el flujo actual de reportes de locales).

Estado actual: sin autenticación alguna (tabla users vacía de código); locales.puntuacion es un entero único casi siempre 0 (estrellas read-only en LocalCard, media global y orden "★ Mejor" en App.jsx); reportes tiene flujo admin completo (listar/descartar); filtro de palabras centralizado en config.filtro_palabras.

Goals / Non-Goals

Goals:

  • Una reseña por dispositivo y local, editable y borrable por su autor.
  • Media de reseñas visible donde ya hay estrellas, sin tocar consumidores.
  • Resistencia base al boicot de contenido (rate-limit, unicidad, filtro, moderación) manteniendo cero fricción (sin registro).
  • Anonimato sin datos personales, con huella corta legible por local.

Non-Goals:

  • Cuentas de usuario / login (futuro; diseño prepara la migración).
  • Reseñas anónimas firmadas criptográficamente o prueba-de-trabajo (se valoran como endurecimiento posterior si hay abuso real).
  • Moderación previa (cola de aprobación) — se publican directamente.
  • Mitigación de DDoS volumétrico (borde/infra: proxy con rate-limit, fail2ban o CDN delante; fuera de este cambio).
  • Editar la descripcion del local ni tocar la pasarela.

Decisions

  1. deviceId aleatorio en localStorage como identidad v1 (UUID v4). Anónimo, cero fricción, sin PII. Se envía en el POST/DELETE (el servidor no puede fiarse de él para autenticar, pero sí para la unicidad y la propiedad lógica de la reseña). Alternativa descartada: huella derivada del request (IP+UA): frágil (IP dinámica) y colisiona en redes compartidas (CGNAT móviles muy comunes en España).

  2. Esquema: tabla resenas con UNIQUE(localId, deviceId).

    CREATE TABLE IF NOT EXISTS resenas (
      id TEXT PRIMARY KEY,
      localId TEXT NOT NULL,
      deviceId TEXT NOT NULL,
      puntuacion INTEGER NOT NULL CHECK (puntuacion BETWEEN 1 AND 5),
      comentario TEXT,
      fecha TEXT DEFAULT CURRENT_TIMESTAMP,
      fechaEdicion TEXT,
      UNIQUE (localId, deviceId)
    );
    

    Editar = UPDATE de la misma fila (+fechaEdicion). "Una por usuario" se garantiza por constraint, no por código. reportes gana resenaId TEXT nullable (ensureColumn, sin migración destructiva). Futuro cuentas: columna userId nullable + migración deviceId→userId; el UNIQUE se mueve a (localId, userId) cuando exista.

  3. Media agregada en locales.puntuacion. Tras cada crear/editar/borrar: UPDATE locales SET puntuacion = ROUND(AVG(...)) (0 si no quedan reseñas). Así LocalCard, el popup del mapa, el orden "★ Mejor" y la media global consumen el campo tal cual, sin cambios. Alternativa descartada: media calculada en cada lectura (obliga a tocar todos los consumidores y las queries de listado).

  4. API REST siguiente la convención del repo:

    • GET /api/locales/:id/resenas → 200 lista pública (sin deviceId completo: solo huella corta por reseña).
    • POST /api/locales/:id/resenas { deviceId, puntuacion, comentario } → upsert (201 crea; 200 actualiza la propia). Simplifica el cliente: un solo botón "Publicar/Actualizar".
    • DELETE /api/locales/:id/resenas?deviceId=... → 200 borra la propia.
    • $PREFIX/resenas → 200 lista admin; DELETE $PREFIX/resenas/:id → 200 borra (moderación), recalcula media.
    • Reporte de reseña: reusa POST /api/locales/:id/reportar con { motivo, comentario, resenaId }.
  5. Hucha corta estilo 4chan por local: # + 3 primeros hex del sha256(deviceId + localId). Estable por local (permite seguir el hilo de un "anónimo" dentro del mismo local), no reversible al deviceId y no rastreable entre locales. Alternativa descartada: huella global — permitiría perfilar a un anónimo entre todos los locales.

  6. Anti-boicot por capas (todo server-side, en memoria):

    • express-rate-limit (o tabla simple en memoria si se prefiere cero dependencias) sobre POST/DELETE de reseñas: p. ej. 10/hora por IP.
    • Unicidad (localId, deviceId) — un dispositivo no inflaba la media.
    • Filtro de palabras en el comentario + maxLength 500.
    • Moderación reactiva: reportes visibles en el panel → borrado admin. Registro de la razón por la que NO PoW/HMAC-token en v1: complejidad de implementación y UX; con rate-limit + unicidad + moderación el coste de un boicot coordinado ya no es trivial. Endurecemos si pasa.
  7. UI: desplegable en LocalCard. Cabecera "Reseñas (N) · ★media" clicable que expande <ResenasLocal>: lista (huella, estrellas, comentario, fecha, "editada") + formulario inline (StarRating interactivo + textarea 500 + Publicar/Actualizar/Borrar). Carga perezosa (solo al expandir). Alternativa descartada: modal de detalle — más navegación para el caso de uso dominante (leer reseñas al comparar).

Risks / Trade-offs

  • [deviceId en localStorage es falsificable → boicot con N dispositivos artificiales] → rate-limit por IP + unicidad + reportes + borrado admin; endurecimiento posterior (PoW/cuentas) si se materializa.
  • [Media secuestrable por primeros votantes] → es la naturaleza de una media; con volumen se corrige sola y la moderación cubre abuso evidente.
  • [localStorage compartido/borrado → el usuario pierde su reseña] → aceptable en v1 anónima (sin identidad portátil); las cuentas lo resolverán.
  • [Escribir en locales desde el endpoint de reseñas acopla tablas] → recálculo centralizado en un helper recalcularMedia(localId) usado por todas las vías (crear/editar/borrar/admin).
  • [Comentario publicado sin revisión previa] → elegido por el usuario; mitigado por filtro de palabras, reportes y borrado admin inmediato.

Migration Plan

Solo aditivo (CREATE TABLE + ensureColumn): desplegar y ya. Las puntuacion históricas (mayormente 0) pasan a significar "sin reseñas"; si algún local tuviera puntuación manual heredada, se mantiene hasta la primera reseña (decisión documentada; no hay camino de datos conocido con puntuaciones manuales). Rollback = revert; la tabla queda huérfana sin efecto.

Open Questions

  • ¿Rate-limit exacto (10/hora/IP es un punto de partida razonable)? Se ajusta tras ver tráfico real.
  • ¿Tope de longitud del comentario 500? Alineado con la filosofía "corto" de la descripción de la pasarela (200) pero algo más holgado.