# Automatic Provider Location Time Zone Design

## Goal

Simplify provider location registration by removing the technical URL identifier from the portal and resolving an IANA time zone automatically from the point selected on the Google map.

## Approved experience

- The provider no longer sees or edits `slug`. The API already creates a unique slug from the location name when the field is absent.
- The time zone is a required select backed by PHP's IANA identifier catalog, not a free-text field.
- Selecting the browser location, clicking the map, or dragging its marker resolves the time zone from the selected latitude and longitude.
- The select remains available as a manual fallback when Google cannot resolve the coordinates or the service is unavailable.
- Existing locations retain and display their saved time zone until the map point changes.
- Status text explains whether the time zone is pending, resolving, resolved, or requires manual selection in Spanish and English.

## Architecture

The browser never calls the Google Time Zone API directly. A protected `GET /mi-prestador/timezone` route validates coordinates and delegates to an Application handler. The handler depends on a small gateway contract implemented by an Infrastructure HTTP adapter for Google's Time Zone API.

`GOOGLE_TIMEZONE_API_KEY` is required for automatic detection and must be a dedicated server-restricted key. It never falls back to the browser-restricted `GOOGLE_MAPS_API_KEY`. The adapter does not cache results and returns only an allowlisted IANA `timeZoneId`; upstream messages, keys, and diagnostics are never projected to the browser.

The provider ViewModel exposes the same-origin resolver URL and the IANA time-zone list. Blade renders the select and localized help. A focused JavaScript module owns request construction, stale-response protection, select updates, and localized status feedback.

## Data flow

1. The provider selects a map position.
2. Existing map logic updates address, coordinates, place ID, source, and confirmation.
3. The timezone ViewModel clears the previous automatic result and requests the protected resolver using latitude and longitude.
4. The web adapter calls Google's HTTPS Time Zone endpoint with `location`, current Unix `timestamp`, and the server-side key.
5. A successful `OK` response with a valid IANA identifier updates the required select.
6. A stale response is ignored. A failed response leaves the select available for manual selection and displays localized guidance.
7. The existing location payload validates and submits the selected IANA identifier to api.mycode.cl.

## Error and security rules

- Coordinate validation happens before any external request.
- The route requires the provider web session and is throttled.
- Empty keys, connection failures, non-2xx responses, non-`OK` Google statuses, malformed JSON, and invalid identifiers become a neutral `502` response.
- The browser shows a localized neutral message and never displays the upstream body.
- The API key is sent only from the server adapter to Google.
- Manual selection is required before saving if automatic resolution fails.

## Testing

- Feature tests cover route protection, coordinate validation, success projection, missing keys, Google failures, and secret redaction.
- Rendering tests verify the slug control is absent, the required time-zone select and resolver URL are present, and both locales render correct guidance.
- JavaScript tests cover request construction, automatic selection, failure fallback, invalid payloads, and stale response suppression.
- Existing provider, architecture, and full PHP suites must remain green; the provider bundle is rebuilt before integration.