# Provider Location Time Zone Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Hide provider location slugs and automatically resolve a required IANA time zone from Google map coordinates with a safe manual fallback.

**Architecture:** A protected web controller delegates to an Application use case backed by a Google Time Zone Infrastructure adapter. The provider ViewModel supplies the resolver route and IANA catalog, while a focused JavaScript module handles asynchronous map-to-timezone UI state and stale responses.

**Tech Stack:** Laravel 13, Blade, Laravel HTTP client, Google Time Zone API, JavaScript ES2020, Laravel Mix, PHPUnit, Node assertions.

---

### Task 1: Protected time-zone resolver

**Files:**
- Create: `app/Application/Provider/ProviderTimezoneGateway.php`
- Create: `app/Application/Provider/ResolveProviderTimezone.php`
- Create: `app/Infrastructure/Http/GoogleMapsTimezoneApi.php`
- Create: `app/Presentation/Http/Controllers/Web/ProviderTimezoneController.php`
- Modify: `app/Providers/AppServiceProvider.php`
- Modify: `config/services.php`
- Modify: `.env.example`
- Modify: `routes/web.php`
- Create: `tests/Feature/ProviderTimezoneResolutionTest.php`

- [ ] Write feature tests proving authentication, latitude/longitude validation, `OK` projection, invalid Google payload rejection, missing-key behavior, and diagnostic redaction.
- [ ] Run `php artisan test --compact tests/Feature/ProviderTimezoneResolutionTest.php` and confirm RED because the route and resolver do not exist.
- [ ] Add the gateway contract and handler, implement the HTTPS adapter with finite timeouts and IANA allowlisting, bind it exclusively to a dedicated server-side `GOOGLE_TIMEZONE_API_KEY`, then add the protected throttled route and thin controller.
- [ ] Run the focused feature test and confirm GREEN.

### Task 2: Provider form contract and localization

**Files:**
- Modify: `app/Presentation/ViewModels/ProviderPortalConfigFactory.php`
- Modify: `app/Presentation/ViewModels/ProviderPortalConfigViewModel.php`
- Modify: `resources/views/provider/portal.blade.php`
- Modify: `resources/views/provider/partials/location-form.blade.php`
- Modify: `resources/lang/es/provider_portal.php`
- Modify: `resources/lang/en/provider_portal.php`
- Modify: `tests/Feature/ProviderPortalLocationTest.php`
- Modify: `tests/Feature/ProviderPortalLocalizationTest.php`

- [ ] Add failing rendering tests that reject `name="slug"`, require a `timezone` select, expose only the same-origin resolver URL, and verify ES/EN automatic/fallback guidance.
- [ ] Run the two focused feature files and confirm RED against the current text inputs.
- [ ] Remove the slug control, add the required IANA select and live status region, extend the ViewModel with `timezoneUrl` and `timezones`, and add both locale catalogs.
- [ ] Run the focused rendering tests and confirm GREEN.

### Task 3: Automatic browser resolution

**Files:**
- Create: `resources/js/provider/10-location-timezone.js`
- Modify: `resources/js/provider/00-config.js`
- Modify: `resources/js/provider/00-i18n-validation.js`
- Modify: `resources/js/provider/09-location-fields.js`
- Modify: `resources/js/provider/09-location-payload.js`
- Modify: `resources/js/provider/12-location-browser.js`
- Modify: `webpack.mix.js`
- Modify: `tests/js/provider-location.test.js`

- [ ] Add failing Node tests for same-origin configuration, query construction, automatic select updates, failure fallback, stale response suppression, and omission of the slug from create/update payloads.
- [ ] Run `node tests/js/provider-location.test.js` and confirm RED because the module and automatic flow do not exist.
- [ ] Implement the focused timezone ViewModel, connect it to map and browser-geolocation changes, remove slug payload handling, and add localized runtime messages.
- [ ] Run `npm run test:provider` and confirm GREEN.

### Task 4: Bundle, version, review, and integration

**Files:**
- Modify: `public/js/provider/app.js` (generated)
- Modify: `VERSION`

- [ ] Run `npm run production`, remove the untracked generated `public/mix-manifest.json`, and increment the compatible patch version from `1.7.8` to `1.7.9` unless the version hook indicates otherwise.
- [ ] Run `npm run test:provider`, `node --test tests/js/*.test.js`, `php artisan architecture:audit --strict`, and `php artisan test --compact --do-not-cache-result`.
- [ ] Run `git diff --check`, inspect the graph change report, and request an independent code review; resolve all Critical and Important findings.
- [ ] Commit, fast-forward `master`, repeat verification on the merged result, push `origin/master`, and provide deployment commands for `/var/www/html/webmycode`.