load weather with button

Author: aligneddev

.specify/memory/constitution.md

@@ -279,7 +279,7 @@ All development follows Trunk-Based Development with git worktrees for parallel
 1. Create a GitHub issue describing the work
 2. Create a short-lived feature branch from `main` (e.g., `feature/issue-42-record-ride`)
 3. Use `git worktree add` to work on the branch in a separate directory when parallel work is needed
-4. Commit frequently with meaningful messages; push to remote regularly
+4. Commit frequently with meaningful messages using `semantic commits or conventional commits` format; push to remote regularly
 5. Open a PR referencing the GitHub issue (e.g., "Closes #42") as soon as the first commit is ready (draft PR for work-in-progress)
 6. Keep the branch up-to-date with `main` via rebase
 7. Once CI passes and review feedback is addressed, the owner completes the PR

specs/011-ride-weather-data/contracts/api-contracts.md

@@ -117,6 +117,35 @@ data is fetched server-side at save time inside `RecordRideService` and `EditRid
 The existing `GET /api/rides/gas-price` endpoint pattern is not replicated for weather because
 the weather lookup is tightly coupled to save time and user location (which is server-held).
 
+## Weather Preview Endpoint
+
+The explicit load-weather action uses a server-side preview endpoint so the browser never talks to
+Open-Meteo directly.
+
+### `GET /api/rides/weather?rideDateTimeLocal={iso}`
+
+Returns the weather snapshot for the authenticated rider's configured location and the supplied
+ride timestamp.
+
+```csharp
+public sealed record RideWeatherResponse(
+    DateTime RideDateTimeLocal,
+    decimal? Temperature,
+    decimal? WindSpeedMph,
+    int? WindDirectionDeg,
+    int? RelativeHumidityPercent,
+    int? CloudCoverPercent,
+    string? PrecipitationType,
+    bool IsAvailable
+);
+```
+
+Behavior:
+- Returns `200` with `IsAvailable = true` when weather data is found.
+- Returns `200` with null weather fields and `IsAvailable = false` when location is missing or no weather is available.
+- Returns `400` when `rideDateTimeLocal` is missing or invalid.
+- Returns `401` when the caller is unauthenticated.
+
 ---
 
 ## Frontend TypeScript Contracts

specs/011-ride-weather-data/quickstart.md

@@ -171,6 +171,14 @@ Map new `RideEntity` weather columns to `RideHistoryRow` and `RideDefaultsRespon
 
 ---
 
+### Step 7.5 — Add Explicit Weather Preview Endpoint
+
+Add an authenticated endpoint that accepts `rideDateTimeLocal` and returns weather fields for the
+authenticated rider's configured location. This endpoint is used by create/edit form buttons to
+fill weather values before save while keeping the weather provider server-side.
+
+---
+
 ### Step 8 — Frontend: Ride Create/Edit Form
 
 **Files** (locate existing ride form components):
@@ -192,6 +200,7 @@ Add optional weather fields to both forms:
 **UI behavior**:
 - All weather fields are optional — user can leave them empty
 - Pre-populated on edit from the stored ride values
+- Add a `Load Weather` button on create and edit that fetches weather for the currently selected ride timestamp
 - When user manually changes any field, set `weatherUserOverridden = true` before submit
 - Show in RideHistoryRow in the history table
 

specs/011-ride-weather-data/spec.md

@@ -17,8 +17,9 @@ As a rider creating or editing a ride entry, I want weather details for the ride
 
 **Acceptance Scenarios**:
 
-1. **Given** a user submits a new ride with a valid ride timestamp and weather data is available, **When** the server processes the save request, **Then** temperature, wind speed, wind direction, humidity, cloud cover, and precipitation type are fetched server-side and stored with the ride created event.
-2. **Given** a user edits an existing ride and updates the ride timestamp, **When** they save, **Then** the server fetches weather for the new time and stores the refreshed values with the ride updated event.
+1. **Given** a user opens the create ride page or edits a ride and chooses to load weather for the selected ride timestamp, **When** the server processes that explicit load-weather request, **Then** temperature, wind speed, wind direction, humidity, cloud cover, and precipitation type are fetched server-side and returned to the form so the fields can be filled before save.
+2. **Given** a user submits a new ride with a valid ride timestamp and weather data is available, **When** the server processes the save request, **Then** temperature, wind speed, wind direction, humidity, cloud cover, and precipitation type are fetched server-side and stored with the ride created event.
+3. **Given** a user edits an existing ride and updates the ride timestamp, **When** they save, **Then** the server fetches weather for the new time and stores the refreshed values with the ride updated event.
 
 ---
 
@@ -32,8 +33,9 @@ As a rider, I want to manually adjust weather fields when automatic values are i
 
 **Acceptance Scenarios**:
 
-1. **Given** a ride has been saved and its weather values are shown on the ride edit page, **When** the user changes one or more weather fields and saves, **Then** the user-provided values are stored as authoritative and the server does not overwrite them with a new weather fetch.
-2. **Given** automatic weather retrieval fails and a ride is saved with empty weather fields, **When** the user re-opens the ride for editing and enters weather values manually and saves, **Then** those values are stored and displayed for that ride.
+1. **Given** a ride create or edit form is visible, **When** the user clicks the load-weather button and weather data is available, **Then** the returned weather values populate the weather fields without requiring a save.
+2. **Given** a ride has been saved and its weather values are shown on the ride edit page, **When** the user changes one or more weather fields and saves, **Then** the user-provided values are stored as authoritative and the server does not overwrite them with a new weather fetch.
+3. **Given** automatic weather retrieval fails and a ride is saved with empty weather fields, **When** the user re-opens the ride for editing and enters weather values manually and saves, **Then** those values are stored and displayed for that ride.
 
 ---
 
@@ -55,6 +57,7 @@ As a rider repeatedly adding or editing rides for the same date/time context, I
 - Weather provider has no record for the ride timestamp; ride save still succeeds and weather fields remain empty unless user enters values.
 - Weather provider returns only partial weather data; available fields are populated and unavailable fields remain empty.
 - Weather provider is unreachable or times out during server-side fetch; ride save completes and weather fields are stored empty.
+- Weather preview lookup triggered from the form is unreachable or returns no data; the form remains usable and weather fields stay empty.
 - User manually enters or clears a weather field on the edit form; the submitted value (including blank) is preserved and the server does not overwrite it with a fresh weather fetch.
 - Ride time is changed during edit; the server re-fetches weather for the new time at save, but only for fields the user has not manually provided.
 
@@ -63,6 +66,8 @@ As a rider repeatedly adding or editing rides for the same date/time context, I
 ### Functional Requirements
 
 - **FR-001**: The server MUST perform a weather lookup at the time the ride create request is received; the weather fetch MUST support both historical ride times and current/live ride times.
+- **FR-001c**: The system MUST provide an explicit user action on ride create and ride edit forms to load weather for the currently selected ride timestamp before save.
+- **FR-001d**: The explicit load-weather action MUST call the server, not the frontend directly, and MUST fill the weather form fields with returned values when available.
 - **FR-001a**: The weather provider API key MUST be configurable by the user or administrator in the application's settings; the app MUST behave gracefully (empty weather fields, no error blocking save) when no API key is configured.
 - **FR-001b**: Weather fetches MUST be performed server-side only; the API key MUST NOT be exposed to or used by the frontend.
 - **FR-002**: The server MUST perform a weather lookup at the time the ride update request is received when the ride timestamp has changed; the same historical/current support applies.
@@ -81,7 +86,7 @@ As a rider repeatedly adding or editing rides for the same date/time context, I
 
 - **Ride Event Weather Snapshot**: Weather attributes stored directly on ride created and ride updated events; includes temperature, wind speed, wind direction, humidity, cloud cover, precipitation type, plus indication of whether values were user-overridden.
 - **Weather Lookup Record**: Reusable stored weather result keyed by ride timestamp rounded to the nearest hour and the user's configured location; includes retrieved weather fields, lookup timestamp, and retrieval status (success/partial/unavailable/error). All ride times within the same hour at the same location share one cache entry.
-- **Ride Entry Form Weather Fields**: Editable fields shown on both create and edit pages. On create, fields start empty and are optionally filled by the user before saving; server auto-fills only unsubmitted fields. On edit, fields are pre-populated with the previously saved weather values so the user can review and override before saving.
+- **Ride Entry Form Weather Fields**: Editable fields shown on both create and edit pages. On create, fields may start empty or with prior ride defaults and can be explicitly filled by a load-weather action before saving; server auto-fills only unsubmitted fields at save. On edit, fields are pre-populated with the previously saved weather values so the user can review, reload weather for the current timestamp, and override before saving.
 
 ## Clarifications
 

specs/011-ride-weather-data/tasks.md

@@ -133,6 +133,21 @@
 
 ---
 
+## Phase 7: Explicit Weather Load Actions
+
+**Purpose**: Add a user-triggered weather fetch button on create and edit forms that fills weather fields before save.
+
+- [X] T047 [P] [US1] Update the feature spec for explicit load-weather actions on create and edit forms in `specs/011-ride-weather-data/spec.md`
+- [X] T048 [P] [US1] Add backend/frontend contract coverage for a weather preview endpoint in `src/BikeTracking.Api/Contracts/RidesContracts.cs` and `src/BikeTracking.Frontend/src/services/ridesService.ts`
+- [X] T049 [P] [US1] Add endpoint coverage for explicit weather loading in `src/BikeTracking.Api.Tests/Endpoints/RidesEndpointsTests.cs`
+- [X] T050 [P] [US2] Add frontend tests for load-weather buttons in `src/BikeTracking.Frontend/src/pages/RecordRidePage.test.tsx` and `src/BikeTracking.Frontend/src/pages/HistoryPage.test.tsx`
+- [X] T051 [US1] Add authenticated weather preview endpoint in `src/BikeTracking.Api/Endpoints/RidesEndpoints.cs`
+- [X] T052 [US1] Add create-page load-weather action in `src/BikeTracking.Frontend/src/pages/RecordRidePage.tsx`
+- [X] T053 [US2] Add edit-page load-weather action in `src/BikeTracking.Frontend/src/pages/HistoryPage.tsx`
+- [X] T054 [US1] Update supporting docs/examples for the preview endpoint in `specs/011-ride-weather-data/quickstart.md`, `specs/011-ride-weather-data/contracts/api-contracts.md`, and `src/BikeTracking.Api/BikeTracking.Api.http`
+
+---
+
 ## Dependencies
 
 ```text

src/BikeTracking.Api.Tests/Endpoints/RidesEndpointsTests.cs

@@ -234,6 +234,61 @@ public async Task GetGasPrice_WithoutAuth_Returns401()
         Assert.Equal(HttpStatusCode.Unauthorized, response.StatusCode);
     }
 
+    [Fact]
+    public async Task GetRideWeather_WithConfiguredLocation_ReturnsWeatherData()
+    {
+        await using var host = await RecordRideApiHost.StartAsync();
+        var userId = await host.SeedUserAsync("WeatherPreview");
+        await host.SeedUserSettingsAsync(userId, latitude: 40.71m, longitude: -74.01m);
+
+        var response = await host.Client.GetWithAuthAsync(
+            "/api/rides/weather?rideDateTimeLocal=2026-03-20T10:30:00",
+            userId
+        );
+
+        Assert.Equal(HttpStatusCode.OK, response.StatusCode);
+        var payload = await response.Content.ReadFromJsonAsync<RideWeatherResponse>();
+        Assert.NotNull(payload);
+        Assert.True(payload.IsAvailable);
+        Assert.Equal(72.5m, payload.Temperature);
+        Assert.Equal(10.3m, payload.WindSpeedMph);
+        Assert.Equal(250, payload.WindDirectionDeg);
+        Assert.Equal(65, payload.RelativeHumidityPercent);
+        Assert.Equal(30, payload.CloudCoverPercent);
+    }
+
+    [Fact]
+    public async Task GetRideWeather_WithInvalidDateTime_Returns400()
+    {
+        await using var host = await RecordRideApiHost.StartAsync();
+        var userId = await host.SeedUserAsync("WeatherPreviewBadDate");
+
+        var response = await host.Client.GetWithAuthAsync(
+            "/api/rides/weather?rideDateTimeLocal=not-a-date-time",
+            userId
+        );
+
+        Assert.Equal(HttpStatusCode.BadRequest, response.StatusCode);
+    }
+
+    [Fact]
+    public async Task GetRideWeather_WithoutLocation_ReturnsUnavailableShape()
+    {
+        await using var host = await RecordRideApiHost.StartAsync();
+        var userId = await host.SeedUserAsync("WeatherPreviewNoLocation");
+
+        var response = await host.Client.GetWithAuthAsync(
+            "/api/rides/weather?rideDateTimeLocal=2026-03-20T10:30:00",
+            userId
+        );
+
+        Assert.Equal(HttpStatusCode.OK, response.StatusCode);
+        var payload = await response.Content.ReadFromJsonAsync<RideWeatherResponse>();
+        Assert.NotNull(payload);
+        Assert.False(payload.IsAvailable);
+        Assert.Null(payload.Temperature);
+    }
+
     [Fact]
     public async Task PostRecordRide_WithGasPrice_PersistsGasPrice()
     {
@@ -763,6 +818,24 @@ public async Task<long> SeedUserAsync(string displayName)
             return user.UserId;
         }
 
+        public async Task SeedUserSettingsAsync(long userId, decimal latitude, decimal longitude)
+        {
+            using var scope = app.Services.CreateScope();
+            var dbContext = scope.ServiceProvider.GetRequiredService<BikeTrackingDbContext>();
+
+            dbContext.UserSettings.Add(
+                new UserSettingsEntity
+                {
+                    UserId = userId,
+                    Latitude = latitude,
+                    Longitude = longitude,
+                    UpdatedAtUtc = DateTime.UtcNow,
+                }
+            );
+
+            await dbContext.SaveChangesAsync();
+        }
+
         public async Task<int> RecordRideAsync(
             long userId,
             decimal miles,

src/BikeTracking.Api/BikeTracking.Api.http

@@ -40,6 +40,11 @@ GET {{ApiService_HostAddress}}/api/rides/defaults
 Accept: application/json
 X-User-Id: {{RiderId}}
 
+### Load weather for create/edit form
+GET {{ApiService_HostAddress}}/api/rides/weather?rideDateTimeLocal=2026-03-26T07:30:00
+Accept: application/json
+X-User-Id: {{RiderId}}
+
 ### Get quick ride options
 GET {{ApiService_HostAddress}}/api/rides/quick-options
 Accept: application/json

src/BikeTracking.Api/Contracts/RidesContracts.cs

@@ -57,6 +57,17 @@ public sealed record GasPriceResponse(
     string? DataSource
 );
 
+public sealed record RideWeatherResponse(
+    DateTime RideDateTimeLocal,
+    decimal? Temperature,
+    decimal? WindSpeedMph,
+    int? WindDirectionDeg,
+    int? RelativeHumidityPercent,
+    int? CloudCoverPercent,
+    string? PrecipitationType,
+    bool IsAvailable
+);
+
 public sealed record QuickRideOption(decimal Miles, int RideMinutes, DateTime LastUsedAtLocal);
 
 public sealed record QuickRideOptionsResponse(

src/BikeTracking.Api/Endpoints/RidesEndpoints.cs

@@ -1,6 +1,8 @@
 using BikeTracking.Api.Application.Rides;
 using BikeTracking.Api.Contracts;
+using BikeTracking.Api.Infrastructure.Persistence;
 using Microsoft.AspNetCore.Mvc;
+using Microsoft.EntityFrameworkCore;
 
 namespace BikeTracking.Api.Endpoints;
 
@@ -38,6 +40,15 @@ public static IEndpointRouteBuilder MapRidesEndpoints(this IEndpointRouteBuilder
             .Produces<ErrorResponse>(StatusCodes.Status401Unauthorized)
             .RequireAuthorization();
 
+        group
+            .MapGet("/weather", GetRideWeather)
+            .WithName("GetRideWeather")
+            .WithSummary("Get weather preview for a ride timestamp")
+            .Produces<RideWeatherResponse>(StatusCodes.Status200OK)
+            .Produces<ErrorResponse>(StatusCodes.Status400BadRequest)
+            .Produces<ErrorResponse>(StatusCodes.Status401Unauthorized)
+            .RequireAuthorization();
+
         group
             .MapGet("/quick-options", GetQuickRideOptions)
             .WithName("GetQuickRideOptions")
@@ -191,6 +202,93 @@ CancellationToken cancellationToken
         }
     }
 
+    private static async Task<IResult> GetRideWeather(
+        HttpContext context,
+        [FromQuery] string? rideDateTimeLocal,
+        [FromServices] BikeTrackingDbContext dbContext,
+        [FromServices] IWeatherLookupService weatherLookupService,
+        CancellationToken cancellationToken
+    )
+    {
+        var userIdString = context.User.FindFirst("sub")?.Value;
+        if (!long.TryParse(userIdString, out var riderId) || riderId <= 0)
+            return Results.Unauthorized();
+
+        if (
+            string.IsNullOrWhiteSpace(rideDateTimeLocal)
+            || !DateTime.TryParse(rideDateTimeLocal, out var parsedRideDateTimeLocal)
+        )
+        {
+            return Results.BadRequest(
+                new ErrorResponse(
+                    "INVALID_REQUEST",
+                    "rideDateTimeLocal query parameter is required and must be a valid date time."
+                )
+            );
+        }
+
+        try
+        {
+            var userSettings = await dbContext
+                .UserSettings.AsNoTracking()
+                .SingleOrDefaultAsync(settings => settings.UserId == riderId, cancellationToken);
+
+            if (
+                userSettings?.Latitude is not decimal latitude
+                || userSettings.Longitude is not decimal longitude
+            )
+            {
+                return Results.Ok(
+                    new RideWeatherResponse(
+                        RideDateTimeLocal: parsedRideDateTimeLocal,
+                        Temperature: null,
+                        WindSpeedMph: null,
+                        WindDirectionDeg: null,
+                        RelativeHumidityPercent: null,
+                        CloudCoverPercent: null,
+                        PrecipitationType: null,
+                        IsAvailable: false
+                    )
+                );
+            }
+
+            var weather = await weatherLookupService.GetOrFetchAsync(
+                latitude,
+                longitude,
+                parsedRideDateTimeLocal.ToUniversalTime(),
+                cancellationToken
+            );
+
+            return Results.Ok(
+                new RideWeatherResponse(
+                    RideDateTimeLocal: parsedRideDateTimeLocal,
+                    Temperature: weather?.Temperature,
+                    WindSpeedMph: weather?.WindSpeedMph,
+                    WindDirectionDeg: weather?.WindDirectionDeg,
+                    RelativeHumidityPercent: weather?.RelativeHumidityPercent,
+                    CloudCoverPercent: weather?.CloudCoverPercent,
+                    PrecipitationType: weather?.PrecipitationType,
+                    IsAvailable: weather is not null
+                )
+            );
+        }
+        catch
+        {
+            return Results.Ok(
+                new RideWeatherResponse(
+                    RideDateTimeLocal: parsedRideDateTimeLocal,
+                    Temperature: null,
+                    WindSpeedMph: null,
+                    WindDirectionDeg: null,
+                    RelativeHumidityPercent: null,
+                    CloudCoverPercent: null,
+                    PrecipitationType: null,
+                    IsAvailable: false
+                )
+            );
+        }
+    }
+
     private static async Task<IResult> GetRideHistory(
         HttpContext context,
         GetRideHistoryService historyService,