# 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)`.** ```sql 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 ``: 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.