feat(tarjeta): rediseño de usabilidad — descripción arriba, vista previa de reseñas y barra de acciones
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

- 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).
This commit is contained in:
2026-10-11 23:21:22 +02:00
parent 478943c58a
commit ebbd7b696e
17 changed files with 724 additions and 188 deletions
@@ -0,0 +1,141 @@
# 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.