Files
localesp/openspec/specs/resenas-por-local/spec.md
T
edgar.friendly 2fa95840a7
deploy-branch / deploy (push) Successful in 2m40s
deploy-branch / teardown (push) Skipped
tests / Unitarias + componente + build (push) Failing after 2m57s
tests / Integración (Nominatim real, opt-in) (push) Skipped
tests / Unitarias + componente + build (pull_request) Failing after 3m8s
tests / Integración (Nominatim real, opt-in) (pull_request) Skipped
openspec: archiva tarjeta-local-rediseno (sync aplicado)
- spec principal nuevo tarjeta-local (estructura + barra de acciones)
- resenas-por-local actualizado: vista previa de 3 en grid, cierre por
  tres vías, acciones por tarjeta (Borrar propias / Reportar ajenas)
- cambio archivado en archive/2026-10-11-tarjeta-local-rediseno
2026-10-12 22:45:18 +02:00

112 lines
7.2 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Reseñas por local
## Purpose
Reseñas anónimas múltiples por local (issue #6): una por dispositivo, editables y borrables por su autor; la puntuación del local pasa a ser la media de sus reseñas. Publicación directa con filtro de palabras, reportes y moderación admin; identidad anónima con huella corta por local (estilo 4chan, sin datos personales) y rate-limit por IP como defensa anti-boicot base.
## Requirements
### Requirement: Una reseña por dispositivo y local
El sistema SHALL permitir como máximo una reseña por dispositivo y local; enviar una reseña cuando ya existe una del mismo dispositivo SHALL actualizar (editar) la existente en lugar de crear una duplicada.
#### Scenario: Primera reseña
- **WHEN** un dispositivo envía `puntuacion` (1–5) y un comentario opcional a un local sin reseña previa suya
- **THEN** la reseña se crea con fecha y queda visible en la lista del local
#### Scenario: Reenvío edita la existente
- **WHEN** un dispositivo que ya reseñó un local envía de nuevo una reseña para ese local
- **THEN** la reseña previa se actualiza (puntuacion y comentario) y se registra la fecha de edición, sin crear duplicados
#### Scenario: Borrado de la propia reseña
- **WHEN** un dispositivo solicita borrar su reseña de un local
- **THEN** la reseña desaparece de la lista y la puntuación del local se recalcula
### Requirement: Valoración obligatoria 1–5 y comentario opcional
La reseña SHALL contener una valoración de 1 a 5 estrellas obligatoria y un comentario opcional de como máximo 500 caracteres; las escrituras fuera de ese contrato SHALL rechazarse con error 400.
#### Scenario: Reseña sin puntuacion
- **WHEN** se envía una reseña sin puntuacion o fuera del rango 1–5
- **THEN** el servidor responde 400 y no se crea ni modifica ninguna reseña
#### Scenario: Comentario demasiado largo
- **WHEN** se envía un comentario de más de 500 caracteres
- **THEN** el servidor responde 400
### Requirement: Media agregada en la puntuación del local
El sistema SHALL mantener `locales.puntuacion` como la media (entero redondeado) de las reseñas vigentes del local, recalculada al crear, editar o borrar una reseña; sin reseñas SHALL valer 0. Los consumidores existentes (estrellas de la tarjeta, popup del mapa, orden "★ Mejor" y media global) SHALL funcionar sin cambios.
#### Scenario: Recálculo al crear
- **WHEN** un local sin reseñas recibe una reseña de 5 estrellas y luego otra de 4
- **THEN** tras la primera la puntuación del local es 5, y tras la segunda es 5 (media 4.5 redondeada al entero más próximo, ROUND de SQLite)
#### Scenario: Recálculo al borrar
- **WHEN** se borra la única reseña de un local
- **THEN** la puntuación del local vuelve a 0
### Requirement: Identidad anónima con huella corta
El sistema SHALL identificar a quien reseña mediante un identificador de dispositivo aleatorio (sin datos personales) y SHALL mostrar cada reseña como "Anónimo" seguida de una huella corta estable por local (derivada del identificador de dispositivo y del local, no reversible y no rastreable entre locales) junto a su fecha.
#### Scenario: Visualización anónima
- **WHEN** se lista las reseñas de un local
- **THEN** cada reseña se muestra como anónima con su huella corta y su fecha, sin exponer el identificador completo del dispositivo
#### Scenario: Huella estable dentro de un local
- **WHEN** el mismo dispositivo reseña (o edita su reseña en) un local
- **THEN** la huella mostrada es la misma en todas las reseñas de ese local para ese dispositivo
### Requirement: Publicación directa con filtro de palabras
Las reseñas SHALL publicarse inmediatamente al enviarse, aplicando el filtro de palabras prohibidas al comentario; un comentario con palabras no permitidas SHALL rechazarse con el aviso correspondiente.
#### Scenario: Palabra prohibida en el comentario
- **WHEN** se envía una reseña cuyo comentario contiene una palabra no permitida
- **THEN** el servidor responde con error y la reseña no se publica
#### Scenario: Publicación inmediata
- **WHEN** una reseña válida se envía
- **THEN** queda visible en la lista del local sin intervención del administrador
### Requirement: Rate limiting de escrituras
El sistema SHALL limitar la frecuencia de escrituras de reseñas (crear/editar/borrar) por dirección IP, rechazando con error 429 los excesos, como defensa base contra el boicot automatizado.
#### Scenario: Límite excedido
- **WHEN** una misma IP supera el límite de escrituras de reseñas en la ventana configurada
- **THEN** las peticiones adicionales reciben 429 y no modifican datos
### Requirement: Reporte y moderación de reseñas
El sistema SHALL permitir reportar una reseña concreta (reusando el flujo de reportes) y SHALL ofrecer al administrador, bajo el prefijo admin, el listado de reseñas y el borrado de cualquiera de ellas, recalculando la media al borrar.
#### Scenario: Reportar una reseña
- **WHEN** un usuario reporta una reseña de un local
- **THEN** el reporte aparece en la lista de reportes del admin identificado como reporte de esa reseña
#### Scenario: Borrado admin
- **WHEN** el administrador borra una reseña desde el panel
- **THEN** la reseña desaparece y la puntuación del local se recalcula
### Requirement: Sección de reseñas desplegable en la tarjeta del local
La tarjeta de cada local SHALL incluir una sección "★ media · Reseñas (N)" que carga sus reseñas al montar la tarjeta y muestra las 3 primeras en una fila de tarjetas que ocupa toda la anchura de la tarjeta; al expandirla, una animación amplía la tarjeta revelando el resto de reseñas en el mismo grid y el formulario inline plano (estrellas interactivas 1–5 y comentario opcional de 500 caracteres). Cada tarjeta de reseña SHALL incluir un botón "Borrar" cuando sea propia del dispositivo y un botón "Reportar" cuando sea ajena. La sección SHALL poder cerrarse desde la cabecera, desde el botón "Comentar" de la barra inferior (que alterna) y desde un botón "Cerrar" del formulario.
#### Scenario: Vista previa sin expandir
- **WHEN** se muestra la tarjeta de un local con reseñas
- **THEN** la sección presenta la media, el total y las 3 reseñas más recientes en fila ocupando toda la anchura, sin interacción
#### Scenario: Expansión animada
- **WHEN** el usuario expande la sección de reseñas
- **THEN** la tarjeta se amplía con una animación que revela el resto de reseñas en el mismo grid y el formulario
#### Scenario: Cierre accesible
- **WHEN** la sección está expandida
- **THEN** puede cerrarse desde la cabecera, pulsando de nuevo "Comentar" o con el botón "Cerrar" del formulario
#### Scenario: Expandir y reseñar
- **WHEN** el usuario expande la sección de reseñas y envía estrellas (y opcionalmente comentario)
- **THEN** su reseña aparece en la lista y la cabecera actualiza número y media
#### Scenario: La propia reseña es editable y borrable desde su tarjeta
- **WHEN** el dispositivo ya tiene reseña en ese local
- **THEN** el formulario aparece precargado al expandir (Actualizar) y su tarjeta de reseña incluye un botón "Borrar"
#### Scenario: Reportar una reseña ajena
- **WHEN** el usuario pulsa "Reportar" en una tarjeta de reseña ajena
- **THEN** se envía el reporte de esa reseña y la tarjeta lo refleja