Daily Work Area

Daily Work-Area Pre-Cache Behavior

Scope

This document defines the once-per-day work-area screen flow that pre-warms weather cache entries from a farmer-selected circular work area.

Canonical Flow

  1. When the Home/work-area screen becomes focused, the app checks whether the local calendar day has already shown the work-area pre-cache modal.
  2. If the day has not shown the modal, a blocking full-screen modal asks the farmer to define today’s work area by tapping a map center point, selecting an address suggestion, or finding a typed address, then choosing a radius.
  3. The modal seeds from today’s saved area first; otherwise it pre-fills from the most recent prior work area within the fallback window; otherwise it opens centered on Sacramento and may recenter once to current device location if foreground permission succeeds before the farmer edits.
  4. Save today’s area persists one DailyWorkAreaCircle for the current local day and marks the day handled.
  5. Use previous work day is available only when a saved work area exists within the previous 7 local calendar days; it does not create a new circle for today, but it does mark today handled after pre-cache runs.
  6. A top-right Close action is available only when no recent fallback exists; it dismisses the already-shown daily prompt without warming weather cells.
  7. The chosen circle is expanded by one weather-cache cell (2.5 km) for safety, converted into deduped cache-cell center points, and passed to precacheWeatherForLocations(...).
  8. precacheWeatherForLocations(...) warms one forecast cell per unique location by fetching and storing a fresh 24-hour forecast horizon for that cell.
  9. Manual reopen/edit from Home uses the same modal and re-runs pre-cache when the farmer saves a new circle later that day.

Persistence Rules

  • One circle is stored per local day key (YYYY-MM-DD in device-local time).
  • Prompt-shown state is stored separately from daily circles so app launch alone cannot suppress the work-area prompt before the farmer reaches the Home/work-area screen.
  • Fallback lookup only considers the most recent prior saved work day within 7 days.
  • Daily pre-cache treats the current hour as part of the horizon when the upstream NDFD response includes it; otherwise it accepts the next 24 contiguous forecast hours.

Invariants

  • Daily work-area pre-caching does not change prediction weather sourcing; foreground and background predictions still use live device location.
  • Pre-cache writes must go through precacheWeatherForLocations(...), which uses a dedicated fetch/store warming path rather than the single-hour getWeatherPointCached(...) lookup contract.
  • The modal is blocking only for the first focused Home/work-area screen visit of the local day where the modal has not already appeared; later edits are user-initiated from Home and are dismissible.