- spec principal pasarela-proponer-local sincronizado con el delta (descripción opcional, orden de 6 pantallas, filtro sobre descripción) - cambio archivado en archive/2026-10-11-pasarela-descripcion-opcional - nuevo cambio resenas-por-local: reseñas anónimas estilo 4chan, media agregada, publicación directa + reportes, rate-limit (artefactos 4/4)
142 lines
7.0 KiB
Markdown
142 lines
7.0 KiB
Markdown
# 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 `<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.
|