# Admin UI Asset Versioning 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:** Garantizar que todas las vistas de MyCode Control carguen el sistema visual claro vigente y no reutilicen CSS o JavaScript oscuros de versiones anteriores.

**Architecture:** Los estilos ya están unificados en los archivos segmentados de `public/css/admin-panel`; el defecto está en sus URLs estables. La vista generará una versión de recurso a partir de `config('app.web_version')` y la aplicará a cada CSS y al bundle administrativo. Un contrato de vista comprobará que ningún recurso local del panel quede sin versión.

**Tech Stack:** Laravel Blade, PHPUnit, CSS segmentado, JavaScript compilado con Laravel Mix.

---

### Task 1: Probar el contrato de caché del panel

**Files:**
- Create: `tests/Feature/AdminPanelAssetVersioningTest.php`
- Modify: `resources/views/admin/partials/styles.blade.php`
- Modify: `resources/views/admin/panel.blade.php`

- [ ] **Step 1: Escribir la prueba que falla**

Crear una prueba que autentique una sesión administrativa, solicite la vista del panel y extraiga todos los `href` y `src` locales bajo `css/admin-panel`, `css/mycode-design-tokens.css` y `js/admin/app.js`.

```php
public function test_every_local_admin_asset_is_versioned(): void
{
    config(['app.web_version' => '9.8.7']);
    $response = $this->withSession($this->adminSession())->get('/admin');
    $response->assertOk();
    $html = $response->getContent();

    preg_match_all(
        '#(?:href|src)="([^"]+(?:mycode-design-tokens|admin-panel|js/admin/app)[^"]*)"#',
        $html,
        $matches
    );

    $this->assertNotEmpty($matches[1]);
    foreach ($matches[1] as $asset) {
        $this->assertStringContainsString('?v=9.8.7', $asset);
    }
}
```

- [ ] **Step 2: Ejecutar la prueba en rojo**

Run: `php artisan test tests/Feature/AdminPanelAssetVersioningTest.php`

Expected: FAIL porque las URLs actuales no contienen `?v=9.8.7`.

- [ ] **Step 3: Versionar todos los estilos**

Al inicio de `resources/views/admin/partials/styles.blade.php`:

```blade
@php($adminAssetVersion = rawurlencode((string) config('app.web_version', '0')))
```

Agregar `?v={{ $adminAssetVersion }}` a cada recurso local cargado por el parcial, incluido `mycode-design-tokens.css`.

- [ ] **Step 4: Versionar el bundle**

En `resources/views/admin/panel.blade.php`:

```blade
<script src="{{ asset('js/admin/app.js') }}?v={{ rawurlencode((string) config('app.web_version', '0')) }}" defer></script>
```

- [ ] **Step 5: Ejecutar la prueba en verde**

Run: `php artisan test tests/Feature/AdminPanelAssetVersioningTest.php tests/Feature/AdminPanelAccessTest.php`

Expected: PASS.

### Task 2: Proteger toda la cobertura visual

**Files:**
- Modify: `tests/js/admin-global-visual.test.js`
- Verify: `public/css/admin-panel/01.css` through `16-service-catalogs.css`

- [ ] **Step 1: Ampliar el contrato visual**

Comprobar selectores de login, shell, panel, estadísticas, gráficos, usuarios, proveedores, catálogos, errores, tablas, filtros, formularios y modales. Verificar:

```js
assert.match(css, /color-scheme:\s*light/);
assert.match(css, /\.mc-admin-table/);
assert.match(css, /\.mc-admin-modal/);
assert.match(css, /\.mc-admin-catalog/);
assert.match(css, /var\(--mc-accent\)/);
```

- [ ] **Step 2: Ejecutar el contrato**

Run: `npm run test:admin-visual`

Expected: PASS sin volver a introducir tokens oscuros.

- [ ] **Step 3: Compilar**

Run: `npm run production`

Expected: exit 0 y `public/js/admin/app.js` actualizado.

### Task 3: Verificación visual real

**Files:**
- Verify only.

- [ ] **Step 1: Levantar Laravel y API simulada**

Run: `php artisan serve --host=127.0.0.1 --port=58988`

- [ ] **Step 2: Abrir sesión administrativa**

Usar el navegador local con sesión administrativa y visitar:

- `/admin`
- `/admin/users`
- `/admin/service-providers`
- `/admin/service-catalogs`
- `/admin/app-errors`

- [ ] **Step 3: Comprobar estilos calculados**

En cada vista comprobar fondo claro, paneles blancos, azul MyCode, acento coral, tipografías Plus Jakarta Sans/Bricolage Grotesque y ausencia de desbordamiento a 390 px.

- [ ] **Step 4: Verificar URLs**

Confirmar en el DOM que todos los recursos administrativos locales contienen la versión web actual.