# Q/A Paso 1: Brand Assets correctamente cargados

**Aplica a:** Todos los proyectos (independiente del producto/demo).

## Resumen del flujo

- **No hay migración que copie o "dropee" archivos** en `public/cd-project/assets/`. Las migraciones solo crean/actualizan la **tabla** `assets` en la base de datos.
- El proceso es:
  1. **Colocar** los archivos de marca en `public/cd-project/assets/`.
  2. **Definir** la lista de assets en `database/seeders/project-data/assets.json` (path, type, name, etc.).
  3. **Ejecutar** `AssetsSeeder`: lee `assets.json`, para cada asset que exista en `public/` lo sube a Cloudinary y guarda el registro en la tabla `assets` (path, type, public_id, secure_url).
  4. **SiteDataSeeder** (se ejecuta después de AssetsSeeder) lee `site-data.json` y resuelve las rutas de assets (ej. `cd-project/assets/logo.png`) contra la tabla `assets`, guardando en `site_data` las URLs de Cloudinary cuando existen.

Así, el sitio usa las URLs de Cloudinary para logos, favicon, og-image, twitter-image, etc.

## Flujo recomendado (paso a paso)

Para dejar el proceso óptimo y validado:

1. **Colocar** en `public/cd-project/assets/` los archivos de la marca con los nombres que espera `assets.json` (ej. `logo.png`, `logo-2.png`, `logo-alternative.png`, `favicon.ico`, `favicon.svg`, `apple-touch-icon.png`, `og-image.png`, `twitter-image.png`, y variantes si las usás).
2. **Opcional:** Revisar que `database/seeders/project-data/assets.json` tenga una entrada por cada archivo que quieras subir a Cloudinary (path = `cd-project/assets/nombre-del-archivo`).
3. **Ejecutar en este orden:**
   ```bash
   php artisan db:seed --class=AssetsSeeder
   php artisan db:seed --class=SiteDataSeeder
   ```
   - **AssetsSeeder:** sube a Cloudinary y llena la tabla `assets`.
   - **SiteDataSeeder:** resuelve las rutas de assets en `site_data` usando la tabla `assets`.
4. **Validar:** ver [Validación después de ejecutar](#validación-después-de-ejecutar) más abajo.

**Alternativa:** Si querés ejecutar toda la configuración del proyecto de una vez:
```bash
php artisan db:seed --class=Project_Seeder
```
(Eso corre CdSystemSeeder, AssetsSeeder, SiteDataSeeder, AnalyticsSeeder, usuarios, módulos activos, etc.)

## Validación después de ejecutar

Tras correr AssetsSeeder y SiteDataSeeder:

| Qué revisar | Cómo |
|-------------|------|
| **Tabla `assets`** | En la DB, que existan filas con `path` correcto y `secure_url` no nulo para los archivos que subiste. |
| **Salida del seeder** | En consola, mensajes tipo "✅ Asset subido a Cloudinary: logo.png" para cada archivo encontrado en `public/`. |
| **Config en `site_data`** | Las claves `assets.main_logo`, `assets.favicon`, `og.image`, `twitter.image` (etc.) deben tener URLs de Cloudinary, no rutas locales. |
| **Front** | Abrir el sitio y comprobar que el logo del header/footer, favicon y, si aplica, vista previa en redes (og/twitter) muestren las imágenes correctas. |

Si algún archivo no estaba en la carpeta, el seeder mostrará "⚠️ Asset sin archivo" y guardará solo metadata en `assets` (sin `secure_url`). Añadí el archivo y volvé a ejecutar `AssetsSeeder`.

### Refresco de caché después de seedear

La configuración del sitio (nombre, assets, etc.) se sirve desde la DB y se cachea en `SiteConfigService`. Para que el front refleje los cambios de inmediato, tras ejecutar los seeders conviene limpiar caché:

```bash
php artisan cache:clear
php artisan view:clear
```

Opcional (si aún ves datos viejos): limpiar también la config y el cache interno de sitio:

```bash
php artisan config:clear && php artisan cache:clear && php artisan view:clear
php artisan tinker --execute="\App\Services\SiteConfigService::clearCache();"
```

Luego recargar el navegador (si es necesario con Ctrl+Shift+R o Cmd+Shift+R para evitar caché del browser).

### Criterios de cierre del Paso 1 (Brand Assets)

Paso 1 se considera **completado** cuando:

- [ ] Archivos de marca están en `public/cd-project/assets/` con los nombres esperados por `assets.json`.
- [ ] Se ejecutó `AssetsSeeder`: en consola se ven "✅ Asset subido a Cloudinary" para los archivos colocados.
- [ ] Se ejecutó `SiteDataSeeder` (para que `site_data` tenga las URLs de Cloudinary en assets, og, twitter).
- [ ] Se ejecutó refresco de caché (`cache:clear` y `view:clear` como mínimo).
- [ ] En el front se verificó: logo header/footer, favicon y, si aplica, og/twitter correctos.

Tras cumplir lo anterior, se avanza al **Paso 2: Data del sitio** ([02-site-data.md](02-site-data.md)).

## Migraciones relacionadas (solo base de datos)

| Migración | Qué hace |
|-----------|----------|
| `create_assets_table` | Crea la tabla `assets` (name, path, type, public_id, description, width, height). |
| `add_secure_url_to_assets_table` | Añade la columna `secure_url` a la tabla `assets`. |

Ninguna de estas migraciones toca el filesystem ni la carpeta `public/cd-project/assets/`.

## Archivos y carpetas clave

| Ubicación | Uso |
|-----------|-----|
| `public/cd-project/assets/` | Carpeta donde deben estar los archivos físicos (logo, favicon, og-image, etc.) **antes** de ejecutar el seeder. |
| `database/seeders/project-data/assets.json` | Lista de assets del proyecto: path, type, name. Es la fuente que usa `AssetsSeeder`. |
| `database/seeders/project-data/site-data.json` | Configuración del sitio; en `assets` y en `seo.schema.logo`, `og.image`, `twitter.image` se referencian rutas (ej. `cd-project/assets/logo.png`) que `SiteDataSeeder` resuelve contra la tabla `assets`. |
| `database/seeders/AssetsSeeder.php` | Lee `assets.json`, sube a Cloudinary los archivos que existan en `public/` y guarda/actualiza la tabla `assets`. |
| `database/seeders/SiteDataSeeder.php` | Carga `site-data.json` y resuelve las rutas de assets usando la tabla `assets` (Cloudinary). |
| `app/Services/ProjectAssetService.php` | Servicio que sube archivos a Cloudinary (folder por proyecto según `DB_DATABASE` / config). |

## Orden de ejecución en Project_Seeder

El orden correcto es:

1. **CdSystemSeeder** — configuración base del sistema (demo, módulos).
2. **AssetsSeeder** — llena la tabla `assets` (y Cloudinary).
3. **SiteDataSeeder** — carga site-data y resuelve URLs de assets desde la tabla `assets`.
4. **AnalyticsSeeder** — GA y analytics.
5. Resto (usuarios, módulos, CdBaseSeeder, etc.).

Si AssetsSeeder se ejecutara después de SiteDataSeeder, la primera vez que se corre el seed las rutas de assets no se resolverían a Cloudinary porque la tabla `assets` aún estaría vacía.

## Comandos útiles

```bash
# Solo ejecutar seeders de proyecto (requiere migraciones ya aplicadas)
php artisan db:seed --class=Project_Seeder

# Solo assets (útil tras colocar nuevos archivos en public/cd-project/assets/)
php artisan db:seed --class=AssetsSeeder

# Fresh + seed completo (recrea tablas y ejecuta todos los seeders en el orden correcto)
php artisan migrate:fresh --seed
```

## Checklist — Brand Assets (ej. proyecto Muma / demo-restaurant)

- [ ] **Archivos en `public/cd-project/assets/`**  
  Los archivos referenciados en `assets.json` existen en esa carpeta (al menos los que se quieren subir a Cloudinary).  
  Ejemplos típicos: `logo.png`, `logo-alternative.png`, `logo-2.png`, `favicon.ico`, `favicon.svg`, `apple-touch-icon.png`, `og-image.png`, `twitter-image.png`, etc.

- [ ] **`assets.json` alineado con el proyecto**  
  Cada entrada tiene `name`, `path` (relativo a `public/`, ej. `cd-project/assets/logo.png`), `type`, y opcionalmente `description`, `width`, `height`. No es obligatorio que todos los archivos existan: los que no existan se guardarán solo como metadata (sin Cloudinary).

- [ ] **`site-data.json` coherente con `assets.json`**  
  Las rutas usadas en `site-data.json` para `assets.*`, `seo.schema.logo`, `og.image`, `twitter.image` deben coincidir con `path` de registros en `assets.json` (para que SiteDataSeeder resuelva a Cloudinary).

- [ ] **Variables de entorno**  
  Cloudinary configurado en `.env` / `config/services.php` (para que `ProjectAssetService` pueda subir).

- [ ] **Ejecución de seeders**  
  Tras colocar archivos y ajustar JSONs, ejecutar al menos `AssetsSeeder` y, para que site_data quede actualizado, `SiteDataSeeder` (o `Project_Seeder` completo). Orden: AssetsSeeder → SiteDataSeeder.

- [ ] **Verificación en sitio**  
  Revisar en el front que logo, favicon, og-image y twitter-image se sirvan desde Cloudinary (o desde la ruta esperada) según la configuración del proyecto.

## Qué es común y qué varía

- **Común a todos los proyectos:**  
  Carpeta `public/cd-project/assets/`, tabla `assets`, `AssetsSeeder`, `SiteDataSeeder`, uso de `ProjectAssetService` y de `assets.json` + `site-data.json`.

- **Varía por proyecto:**  
  Contenido de `assets.json` (qué assets tiene el proyecto) y de `site-data.json` (nombre, contact, assets, og, twitter, etc.). Los archivos físicos en `public/cd-project/assets/` son distintos por marca (Muma, otro cliente, etc.).

## Dejar “en limpio” los assets para un proyecto (ej. Muma)

1. Colocar en `public/cd-project/assets/` **solo** los archivos de marca del proyecto (reemplazar o limpiar la carpeta si hace falta).
2. Ajustar `database/seeders/project-data/assets.json` para que liste exactamente esos assets (paths correctos).
3. Ajustar `site-data.json` para que use esas mismas rutas en `assets`, `seo.schema.logo`, `og.image`, `twitter.image`.
4. Ejecutar:
   ```bash
   php artisan db:seed --class=AssetsSeeder
   php artisan db:seed --class=SiteDataSeeder
   ```
   o el seed completo:
   ```bash
   php artisan db:seed --class=Project_Seeder
   ```

No es necesario crear una migración que “dropee” o copie archivos: el flujo estándar es **archivos en public + assets.json + AssetsSeeder**. Si en el futuro se quiere un “default” de assets por demo (ej. copiar desde `storage/app/brand-assets/demo-restaurant/`), puede añadirse un comando Artisan opcional o un paso documentado aparte.