feat(score): grade the forecast-rain cap by how far away the rain is

A flat 59 cap kicked in the moment Open-Meteo saw rain anywhere in its
16 h horizon, so a beach with a fine morning and showers at 16:00 sat in
yellow from breakfast. The cap now falls linearly from none at >=6 h to
59 at <=1 h (5h 92, 4h 84, 3h 75, 2h 67); a text-only AEMET signal with
no hour is treated as ~3 h (75). The reason still names "lluvia
prevista" whether or not the cap bites, and active rain (55) keeps
overriding any forecast. computeBeachScore takes an injectable clock.

The API publishes topeValor next to topeAplicado so the score card can
say the actual limit instead of a hardcoded 59; older backends fall back
to the old constants.

Claude-Session: https://claude.ai/code/session_01CZeTJqzoJxUKi7uWcVDnoj

Author: oscaruiz

backend/src/__tests__/BeachScorer.test.ts

@@ -15,6 +15,7 @@ import {
   ForecastEnrichment,
   RAIN_SCORE_CAP,
   RAIN_FORECAST_SCORE_CAP,
+  rainForecastCap,
 } from '../domain/use-cases/BeachScorer';
 import { Weather } from '../domain/entities/Weather';
 import { FlagStatus } from '../domain/entities/Flag';
@@ -475,12 +476,72 @@ describe('computeBeachScore con lluvia prevista', () => {
     enrichment: makeEnrichment({ waves: 'débil', uvIndex: 4 }),
   });
 
-  it('capa a RAIN_FORECAST_SCORE_CAP (59): amarillo suave, por encima del 55 de lluvia activa', () => {
+  it('inminente (1 h): capa a RAIN_FORECAST_SCORE_CAP (59), por encima del 55 de lluvia activa', () => {
     const { weather, flag, enrichment } = perfect();
     const r = computeBeachScore(weather, flag, enrichment, undefined, null, makeForecastSignal());
     expect(r.score).toBe(RAIN_FORECAST_SCORE_CAP);
     expect(r.score).toBeLessThan(60);
     expect(r.score).toBeGreaterThan(RAIN_SCORE_CAP);
+    expect(r.topeValor).toBe(RAIN_FORECAST_SCORE_CAP);
+  });
+
+  describe('el tope se relaja con la distancia (rainForecastCap)', () => {
+    it.each([
+      [7, 100],
+      [6, 100],
+      [5, 92],
+      [4, 84],
+      [3, 75],
+      [2, 67],
+      [1, 59],
+      [0, 59],
+      [-2, 59],
+    ])('%s h → tope %s', (horas, tope) => {
+      expect(Math.round(rainForecastCap(horas))).toBe(tope);
+    });
+
+    it('sin hora (sólo texto AEMET) se trata como ~3 h → 75', () => {
+      expect(Math.round(rainForecastCap(null))).toBe(75);
+    });
+  });
+
+  it('lluvia a 7 h: se avisa pero no se penaliza', () => {
+    const { weather, flag, enrichment } = perfect();
+    const now = Date.now();
+    const lejana = makeForecastSignal({ firstAt: now + 7 * 3_600_000 });
+    const seca = computeBeachScore(weather, flag, enrichment, undefined, null, null, undefined, undefined, now);
+    const r = computeBeachScore(weather, flag, enrichment, undefined, null, lejana, undefined, undefined, now);
+    expect(r.score).toBe(seca.score);
+    expect(r.tope).toBeNull();
+    expect(r.topeValor).toBeNull();
+    expect(buildRankingReason(r.subScores, weather, flag, enrichment, null, lejana)).toContain('lluvia prevista');
+  });
+
+  it('lluvia a 3 h: tope intermedio de 75', () => {
+    const { weather, flag, enrichment } = perfect();
+    const now = Date.now();
+    const media = makeForecastSignal({ firstAt: now + 3 * 3_600_000 });
+    const r = computeBeachScore(weather, flag, enrichment, undefined, null, media, undefined, undefined, now);
+    expect(r.score).toBe(75);
+    expect(r.tope).toBe('lluvia_prevista');
+    expect(r.topeValor).toBe(75);
+  });
+
+  it('sólo texto AEMET (sin hora): mismo 75 intermedio', () => {
+    const { weather, flag, enrichment } = perfect();
+    const texto = makeForecastSignal({ firstAt: null, mmMax: null, sources: ['AEMET'] });
+    const r = computeBeachScore(weather, flag, enrichment, undefined, null, texto);
+    expect(r.score).toBe(75);
+    expect(r.tope).toBe('lluvia_prevista');
+  });
+
+  it('la lluvia ACTIVA gana aunque la prevista esté lejos', () => {
+    const { weather, flag, enrichment } = perfect();
+    const lejana = makeForecastSignal({ firstAt: Date.now() + 7 * 3_600_000 });
+    const r = computeBeachScore(weather, flag, enrichment, undefined, makeRain(), lejana);
+    expect(r.score).toBe(RAIN_SCORE_CAP);
+    expect(r.tope).toBe('lluvia');
+    expect(r.topeValor).toBe(RAIN_SCORE_CAP);
   });
 
   it('la lluvia ACTIVA gana a la prevista (55 < 59)', () => {

backend/src/__tests__/featuredOutlook.test.ts

@@ -175,7 +175,9 @@ describe('GetFeaturedBeaches — lluvia prevista sobre un cielo que se abre', ()
   function conLluviaPrevista(): RainNowcast {
     return {
       ...nowcast(tramos(0)),
-      upcoming: { expected: true, firstAt: AHORA.getTime() + 2 * 3_600_000, mmMax: 1.2 },
+      // One hour away: close enough for the full 59 cap. Further out the cap
+      // relaxes (2 h → 67) and the 67 the sky bonus reaches would slip under it.
+      upcoming: { expected: true, firstAt: AHORA.getTime() + 1 * 3_600_000, mmMax: 1.2 },
     };
   }
 

backend/src/application/dtos/FeaturedBeachDTO.ts

@@ -86,6 +86,8 @@ export interface FeaturedBeachDTO {
   subpuntuaciones: SubPuntuacionesDTO | null;
   pronostico: PronosticoDTO | null;
   topeAplicado: TopeDTO | null;
+  /** The cap value behind `topeAplicado`; null when no cap clipped the score. */
+  topeValor: number | null;
   /** WHEN to go today. Null outside the beach window, with the hourly source
    *  down, or when no stretch is good enough to recommend. */
   ventanaDia: VentanaDiaDTO | null;

backend/src/application/mappers/FeaturedBeachMapper.ts

@@ -26,6 +26,7 @@ export interface FeaturedBeachResult {
   subScores?: SubScores | null;
   outlook?: OutlookSignal | null;
   tope?: ScoreCap | null;
+  topeValor?: number | null;
   /** Best stretch of the remaining beach window. Absent on the excluded path. */
   ventanaDia?: DayWindowSignal | null;
   /** Aggregated rain nowcast; the score already reads it, the DTO publishes it. */
@@ -122,6 +123,7 @@ export class FeaturedBeachMapper {
           }
         : null,
       topeAplicado: r.tope ?? null,
+      topeValor: r.topeValor ?? null,
       ventanaDia: mapVentanaDia(r.ventanaDia),
       oleaje: r.enrichment?.waves ?? null,
       lluvia: r.rain ? LegacyDetailsMapper.mapLluvia(r.rain) : null,

backend/src/domain/use-cases/BeachScorer.ts

@@ -15,12 +15,32 @@ import type { OutlookSignal } from './WeatherOutlook';
 export const RAIN_SCORE_CAP = 55;
 
 /**
- * Cap when rain is FORECAST (next ~6h or today per AEMET) but it is not yet
- * raining: also yellow (<60), but above the active-rain cap → hierarchy
- * raining (55) < going to rain (59) < dry.
+ * Cap when rain is FORECAST and IMMINENT but it is not yet raining: also
+ * yellow (<60), but above the active-rain cap → hierarchy raining (55) <
+ * about to rain (59) < dry. This is the floor of `rainForecastCap`: the
+ * further away the rain, the higher the cap, until it stops mattering.
  */
 export const RAIN_FORECAST_SCORE_CAP = 59;
 
+/**
+ * Forecast rain this far away (hours) does not cap at all — it is still
+ * NAMED in the reasons ("lluvia prevista"), but a beach with a fine morning
+ * and showers at 16:00 must outscore one that is grey all day. Open-Meteo
+ * looks 16 h ahead, so without this a single evening slot painted the whole
+ * coast yellow from breakfast.
+ */
+export const RAIN_FORECAST_FREE_HOURS = 6;
+
+/** Forecast rain this close (hours) gets the full `RAIN_FORECAST_SCORE_CAP`. */
+export const RAIN_FORECAST_FULL_HOURS = 1;
+
+/**
+ * Hours assumed when the signal has no time at all (AEMET text: "chubascos
+ * por la tarde"). Rain is coming today, we just do not know when: neither
+ * ignored nor treated as imminent.
+ */
+export const RAIN_FORECAST_UNKNOWN_HOURS = 3;
+
 /**
  * How much the next few hours can move the score, up or down. Eight points is
  * enough to cross the green band (a beach at 57 that is clearing reaches 65)
@@ -146,6 +166,37 @@ export interface ScoringResult {
    * capped" instead of leaving the numbers looking broken.
    */
   tope: ScoreCap | null;
+  /**
+   * The cap value that clipped the score, null when none did. Published so
+   * the interface can say "limited to 75" instead of hardcoding a number the
+   * graded forecast cap no longer honours.
+   */
+  topeValor: number | null;
+}
+
+// ---------------------------------------------------------------------------
+// Forecast rain cap, graded by distance
+// ---------------------------------------------------------------------------
+
+/** Hours until the first wet slot; null when the signal carries no time. */
+export function hoursUntilRain(forecast: RainForecastSignal, now: number): number | null {
+  if (forecast.firstAt == null) return null;
+  return (forecast.firstAt - now) / 3_600_000;
+}
+
+/**
+ * Cap for forecast rain as a function of how far away it is. At or beyond
+ * `RAIN_FORECAST_FREE_HOURS` there is no cap (SCORE_MAX); from there it falls
+ * linearly to `RAIN_FORECAST_SCORE_CAP` at `RAIN_FORECAST_FULL_HOURS` and
+ * stays there for anything closer — including a first slot already in the
+ * past, which remains "forecast" until the nowcast actually sees rain (and
+ * that one caps harder, at RAIN_SCORE_CAP).
+ */
+export function rainForecastCap(hours: number | null): number {
+  const h = hours ?? RAIN_FORECAST_UNKNOWN_HOURS;
+  const span = RAIN_FORECAST_FREE_HOURS - RAIN_FORECAST_FULL_HOURS;
+  const t = Math.max(0, Math.min(1, (h - RAIN_FORECAST_FULL_HOURS) / span));
+  return RAIN_FORECAST_SCORE_CAP + (SCORE_MAX - RAIN_FORECAST_SCORE_CAP) * t;
 }
 
 // ---------------------------------------------------------------------------
@@ -405,6 +456,8 @@ export function computeBeachScore(
   rainForecast?: RainForecastSignal | null,
   flagOperators: readonly string[] = LEGACY_FLAG_OPERATORS,
   outlook?: OutlookSignal | null,
+  /** Injectable clock: the forecast cap depends on how far away the rain is. */
+  now: number = Date.now(),
 ): ScoringResult {
   const isSurf = attributes?.surf === true;
   const hasFlagService = flagOperators.length > 0;
@@ -442,18 +495,25 @@ export function computeBeachScore(
   if (delta > 0) score += delta;
 
   let tope: ScoreCap | null = null;
-
-  // FORECAST rain (next few hours): soft yellow.
-  if (rainForecast?.expected && score > RAIN_FORECAST_SCORE_CAP) {
-    score = RAIN_FORECAST_SCORE_CAP;
-    tope = 'lluvia_prevista';
+  let topeValor: number | null = null;
+
+  // FORECAST rain: a cap that tightens as the rain gets closer. Far enough
+  // away it is SCORE_MAX and never bites — the reason still names it.
+  if (rainForecast?.expected) {
+    const cap = Math.round(rainForecastCap(hoursUntilRain(rainForecast, now)));
+    if (score > cap) {
+      score = cap;
+      tope = 'lluvia_prevista';
+      topeValor = cap;
+    }
   }
 
   // Rain detected now (multi-source signal): the beach can never be "good",
   // no matter what happens with the other factors. It beats the forecast one.
   if (rain?.status === 'raining' && score > RAIN_SCORE_CAP) {
     score = RAIN_SCORE_CAP;
     tope = 'lluvia';
+    topeValor = RAIN_SCORE_CAP;
   }
 
   // A DETERIORATION lands after the caps, so it counts below them too. The
@@ -469,7 +529,7 @@ export function computeBeachScore(
   // put a score outside it into the API, the bands or the map colours.
   score = Math.max(0, Math.min(SCORE_MAX, score));
 
-  return { score, subScores, tope };
+  return { score, subScores, tope, topeValor };
 }
 
 // ---------------------------------------------------------------------------

backend/src/domain/use-cases/GetFeaturedBeaches.ts

@@ -146,7 +146,7 @@ export class GetFeaturedBeaches {
       // forecast claims.
       const ventanaDia = buildDayWindow(rain?.outlook, new Date(), rain);
 
-      const { score, subScores, tope } = computeBeachScore(
+      const { score, subScores, tope, topeValor } = computeBeachScore(
         weather,
         flag,
         enrichment,
@@ -181,6 +181,7 @@ export class GetFeaturedBeaches {
         subScores,
         outlook: resolvePublishedOutlook(outlook, rainForecast),
         tope,
+        topeValor,
         ventanaDia,
       };
 

frontend/src/pages/playa-detalle/ScoreCard.tsx

@@ -15,7 +15,11 @@ import {
   sinFragmentoDePronostico,
 } from '../../shared/i18n/apiText';
 
-/** Cap values applied by the backend (`RAIN_SCORE_CAP` / `RAIN_FORECAST_SCORE_CAP`). */
+/**
+ * Cap texts, with the value the backend used to apply when it did not send
+ * `topeValor`. The forecast cap is graded now (59 imminent → none at 6 h), so
+ * the published value wins; 59 is only the floor an old backend enforced.
+ */
 const TOPES: Record<'lluvia' | 'lluvia_prevista', { clave: ClaveTexto; valor: number }> = {
   lluvia: { clave: 'detalle.scoreInfo.topeLluvia', valor: 55 },
   lluvia_prevista: { clave: 'detalle.scoreInfo.topeLluviaPrevista', valor: 59 },
@@ -67,7 +71,9 @@ const ScoreCard: React.FC<{
   const pronostico = puntuada.pronostico ?? null;
   const desglose = puntuada.subpuntuaciones ?? null;
   const escala = maximos ?? MAXIMOS_POR_DEFECTO;
-  const tope = puntuada.topeAplicado ? TOPES[puntuada.topeAplicado] : null;
+  const tope = puntuada.topeAplicado
+    ? { ...TOPES[puntuada.topeAplicado], valor: puntuada.topeValor ?? TOPES[puntuada.topeAplicado].valor }
+    : null;
 
   const razon = pronostico
     ? sinFragmentoDePronostico(puntuada.razonRanking)

frontend/src/services/api.ts

@@ -542,6 +542,8 @@ export interface FeaturedBeach {
   subpuntuaciones?: SubPuntuaciones | null;
   pronostico?: Pronostico | null;
   topeAplicado?: 'lluvia' | 'lluvia_prevista' | null;
+  /** The cap value behind `topeAplicado`. Older backends do not send it. */
+  topeValor?: number | null;
   oleaje?: string | null;
   ventanaDia?: VentanaDia | null;
   /**

frontend/src/test/characterization/beachDetailPage.test.tsx

@@ -20,7 +20,7 @@
  */
 
 import React from 'react';
-import { fireEvent, screen } from '@testing-library/react';
+import { fireEvent, screen, waitFor } from '@testing-library/react';
 import type { PlayaDetalle, LluviaActual } from '../../services/api';
 import PlayaDetallePage from '../../pages/PlayaDetalle';
 import { renderWithProviders } from '../render';
@@ -793,3 +793,44 @@ describe('PlayaDetalle — estados', () => {
     expect(container.querySelector('.error-container')).toBeNull();
   });
 });
+
+// ---------------------------------------------------------------------------
+
+/**
+ * LAST on purpose: it swaps the `/featured` response, and the 5 min module
+ * cache in `services/api.ts` would hand that swapped ranking to any test that
+ * ran after it (same debt the states file documents).
+ */
+describe('PlayaDetalle — tope publicado', () => {
+  it('la nota del tope enseña el valor que publica el backend, no el 59 a fuego', async () => {
+    // The forecast cap is graded now: rain 3 h away caps at 75, not 59.
+    const conTope = {
+      ...featuredResponse,
+      resumenTodas: featuredResponse.resumenTodas.map((b) =>
+        b.codigo === '3908503'
+          ? { ...b, puntuacion: 75, topeAplicado: 'lluvia_prevista' as const, topeValor: 75 }
+          : b,
+      ),
+    };
+    // `/featured` is cached in `services/api.ts` for 5 min against Date.now(),
+    // and earlier tests filled it under the REAL clock. Stepping the fake clock
+    // past that (real now + TTL) is what lets THIS response in.
+    jest.useRealTimers();
+    const despues = new Date(Date.now() + 10 * 60_000);
+    jest.useFakeTimers().setSystemTime(despues);
+    installFetchMock([
+      route(FEATURED, { json: conTope }),
+      route(DETAILS, { json: buildAemetDetail(despues) }),
+    ]);
+
+    const { container } = renderDetalle('3908503');
+    await screen.findByText('Puntuación de hoy');
+    // The score arrives from the (uncached) /featured after the detail does.
+    await waitFor(() => expect(container.querySelector('.score-badge-num')).toHaveTextContent('75'));
+    fireEvent.click(screen.getByText('Cómo se calcula'));
+
+    expect(container.querySelector('.pd-score-tope')).toHaveTextContent(
+      'Se espera lluvia: la nota se limita a 75',
+    );
+  });
+});