# cd-frontend-dev — Guía de uso

> Última actualización: 2026-05-04 (v2 — repo expandido a layout/CSS/skins/JS).
> Docs hermanas en este directorio: [`anatomia-de-un-demo.md`](anatomia-de-un-demo.md), [`sync-architecture.md`](sync-architecture.md).
> Doc operativa del flujo PRs: [`../infrastructure/06-frontend-pr-workflow.md`](../infrastructure/06-frontend-pr-workflow.md).

Repo de desarrollo frontend para el sistema BewPro. Contiene los archivos visuales editables de cada demo (vistas Blade + CSS + skins + JS), montados como volúmenes sobre la imagen Docker del backend pre-buildeada de `cd-system`.

---

## Índice

1. [Arquitectura](#1-arquitectura)
2. [Requisitos](#2-requisitos)
3. [Setup inicial (dev nuevo)](#3-setup-inicial-dev-nuevo)
4. [Flujo de trabajo diario](#4-flujo-de-trabajo-diario)
5. [Cambiar el demo activo](#5-cambiar-el-demo-activo)
6. [Comandos disponibles](#6-comandos-disponibles)
7. [Workflow de sync a cd-system](#7-workflow-de-sync-a-cd-system)
8. [Configuración del workflow (maintainer)](#8-configuración-del-workflow-maintainer)
9. [Actualizar la imagen Docker](#9-actualizar-la-imagen-docker)
10. [Troubleshooting](#10-troubleshooting)

---

1## 1. Arquitectura

```
cd-system (privado — backend)          cd-frontend-dev (frontend devs)
├── Dockerfile                         ├── docker-compose.yml
├── .docker/                           ├── .env.docker
│   ├── apache.conf                    ├── Makefile
│   ├── entrypoint.sh                  ├── resources/views/modules/cd-base/frontend/
│   └── switch-demo.sh                 │   ├── demos/demo-restaurant/
└── .github/workflows/                 │   ├── demos/demo-law-firm-2/
    └── build-image.yml                │   └── ... (18 demos)
                                       └── .github/workflows/
                                           └── sync-to-main.yml
```

**Flujo de la imagen:**
```
push a cd-system → GitHub Actions buildea → imagen en GHCR (pública)
                                                    ↓
                              cd-frontend-dev hace docker compose pull
```

**Flujo de cambios:**
```
dev edita vistas → git push cd-frontend-dev/main
                              ↓
              GitHub Actions detecta cambios en resources/ o public/
                              ↓
              Abre PR automático en cd-system para revisión
```

---

## 2. Requisitos

| Herramienta | Versión mínima | Instalación |
|---|---|---|
| Docker Desktop | 4.x | [docker.com](https://www.docker.com/products/docker-desktop/) |
| Git | 2.x | [git-scm.com](https://git-scm.com/) |
| make (opcional) | cualquiera | `winget install GnuWin32.Make` |

> El dev **no necesita** PHP, Composer, Node.js ni acceso a `cd-system`.

---

## 3. Setup inicial (dev nuevo)

### 3.1 Clonar el repo

```bash
git clone https://github.com/LACOMPANIADIGITAL/cd-frontend-dev.git
cd cd-frontend-dev
```

### 3.2 Levantar el entorno

```bash
docker compose pull        # descarga la imagen pre-buildeada
docker compose up -d       # levanta app (Laravel + Apache) y MySQL
```

La primera vez tarda ~2 min mientras:
- Descarga la imagen de GHCR
- Corre `migrate:fresh --seed`
- Activa el demo por defecto (`demo-restaurant`)

### 3.3 Verificar que todo funciona

```bash
docker compose logs -f app
```

Cuando aparezca `App lista en http://localhost:8080`, abrís el browser en esa URL.

### 3.4 Credenciales de la DB local (solo si necesitás conectarte con un cliente)

| Campo | Valor |
|---|---|
| Host | `127.0.0.1` |
| Puerto | `3307` |
| Base de datos | `cd_frontend_dev` |
| Usuario | `laravel` |
| Password | `secret` |

---

## 4. Flujo de trabajo diario

```bash
# Al arrancar el día
docker compose up -d

# Editar vistas Blade en:
# resources/views/modules/cd-base/frontend/demos/<demo>/

# Las vistas están montadas como volumen → los cambios se ven
# al recargar el browser sin reiniciar el container.

# Al terminar
docker compose down
```

---

## 5. Cambiar el demo activo

```bash
docker compose exec app switch-demo demo-law-firm-2
```

El script automáticamente:
1. Crea el demo en la tabla `demos` si no existe
2. Marca `is_active=1` en la DB
3. Limpia `config:clear`, `cache:clear` y `view:clear`

Recargás el browser y el demo cambia.

**Demos disponibles:**

| Slug | Nombre |
|---|---|
| `demo-accounting-1` | Accounting 1 |
| `demo-accounting-2` | Accounting 2 |
| `demo-architecture-2` | Architecture 2 |
| `demo-business-consulting` | Business Consulting |
| `demo-construction` | Construction |
| `demo-construction-2` | Construction 2 |
| `demo-creative-agency-2` | Creative Agency 2 |
| `demo-creative-portfolio` | Creative Portfolio |
| `demo-digital-agency-2` | Digital Agency 2 |
| `demo-insurance` | Insurance |
| `demo-law-firm-2` | Law Firm 2 |
| `demo-marketing-1` | Marketing 1 |
| `demo-photography-3` | Photography 3 |
| `demo-product-landing` | Product Landing |
| `demo-real-estate` | Real Estate |
| `demo-restaurant` | Restaurant *(default)* |
| `demo-sass` | SaaS |
| `demo-transportation-logistic` | Transportation & Logistic |

---

## 6. Comandos disponibles

### Con make

```bash
make up                          # levanta los containers (con pull)
make down                        # para los containers
make demo DEMO=demo-restaurant   # cambia el demo activo
make list                        # lista demos desde la DB
make logs                        # muestra logs del app
make shell                       # abre bash dentro del container
make reset                       # migrate:fresh --seed + activa demo default
```

### Sin make (Windows nativo)

```bash
docker compose up -d
docker compose down
docker compose exec app switch-demo demo-restaurant
docker compose exec app php artisan demo:switch --list
docker compose logs -f app
docker compose exec app bash
docker compose exec app php artisan migrate:fresh --seed --force
```

---

## 7. Workflow de sync a cd-system

> Doc operativo completo (3 etapas, comandos, troubleshooting): `docs/bewpro2.0/infrastructure/06-frontend-pr-workflow.md` en `cd-system`.

### ¿Cómo funciona? (v2 — desde 2026-05-04)

Cada vez que hacés push a `main` con cambios en `resources/**` o `public/**`, GitHub Actions:

1. Detecta los archivos modificados (vs el push anterior).
2. Clona `cd-system` en la branch `staging-frontend` (zona de revisión).
3. Copia los archivos al mismo path.
4. **Crea o actualiza** un PR contra `staging-frontend` con:
   - Branch fija: `frontend-sync/pending`
   - Título fijo: `[Frontend] cambios pendientes desde cd-frontend-dev`
   - Label: `frontend`

### ⚠️ Importante: el PR es acumulativo

**No abre un PR por push**. Si hacés 5 pushes seguidos sin que el maintainer mergee, los 5 cambios se acumulan en el mismo PR `frontend-sync/pending`.

Cuando el maintainer mergea ese PR a `staging-frontend`, la branch se borra y tu próximo push abre un PR nuevo.

### Ejemplo de flujo típico

```bash
# Dev edita una vista
vim resources/views/modules/cd-base/frontend/demos/demo-restaurant/welcome.blade.php

# Commitea y pushea
git add resources/
git commit -m "feat(restaurant): nuevo hero con video background"
git push origin main

# → GitHub Actions actualiza el PR "frontend-sync/pending" en cd-system
#    (lo crea si no existía, le agrega un commit si ya estaba abierto)
```

### ¿Y qué pasa después? (las 3 etapas)

1. **Etapa 1 — Auto** (~30s): el PR aparece en cd-system contra `staging-frontend`. Vos no hacés nada.
2. **Etapa 2 — Maintainer review**: revisa el diff y mergea a `staging-frontend`. Cero side effects (los devs frontend NO ven todavía el cambio).
3. **Etapa 3a — Promote a `main`**: el maintainer abre PR `staging-frontend → main` y mergea. Esto dispara el rebuild de la imagen Docker (~3-5 min). Cuando hagas `docker compose pull` vas a ver tu cambio reflejado.
4. **Etapa 3b — Promote a `cd-system`**: PR `main → cd-system`, mergea, dispara deploy a `bewpro.com` (~1m11s).

> Tu trabajo termina en el push. Si querés saber cuándo tu cambio llegó a producción, mirá `https://github.com/LACOMPANIADIGITAL/cd-system/pulls?q=label:frontend`.

### ¿Qué archivos se sincronizan?

Solo los que cambian en `resources/**` y `public/**`. Archivos como `Makefile`, `.env.docker` o `docker-compose.yml` **nunca** se sincronizan a `cd-system`.

### ¿Cuándo NO se actualiza el PR?

- El push solo tocó archivos fuera de `resources/` o `public/` → el workflow no corre.
- Los archivos cambiados son idénticos a los que ya están en `staging-frontend` → no hay diff que pushear.

### Buenas prácticas para devs frontend

1. **No hardcodees colores ni fonts**. Usá CSS variables del sistema de skin (`var(--brand-primary)`, `var(--brand-font-heading)`).
2. **Probá el cambio con `switch-demo`** antes de pushear.
3. **Si vas a iterar mucho, mejor commitear local y hacer 1 push final**. Cada push genera un commit más en el PR acumulado.
4. **Si el maintainer te pide cambios en el PR**, fixealo en cd-frontend-dev y volvé a pushear. El PR se va a actualizar solo (NO abrás otro).
5. **Coordinate con otros devs frontend** antes de pushear si saben que hay un PR de ellos en vuelo. Por convención, **1 dev frontend en vuelo a la vez** para evitar mezclar cambios en el mismo PR `frontend-sync/pending`.

---

## 8. Configuración del workflow (maintainer)

### Secret requerido en cd-frontend-dev

| Secret | Descripción |
|---|---|
| `CD_SYSTEM_PAT` | Personal Access Token con scope `repo` sobre `LACOMPANIADIGITAL/cd-system` |

**Cómo crearlo:**
1. GitHub → avatar → Settings → Developer settings → Personal access tokens → Tokens (classic)
2. New token → scope: `repo` → Generate
3. `cd-frontend-dev` → Settings → Secrets and variables → Actions → New secret → `CD_SYSTEM_PAT`

### Agregar un nuevo dev al repo

1. `cd-frontend-dev` → Settings → Collaborators → Add people
2. El dev clona y sigue el [Setup inicial](#3-setup-inicial-dev-nuevo)

### Cambiar el demo por defecto al levantar

Editar `.env.docker`:
```
CD_THEME_DEMO=demo-law-firm-2
```
Luego:
```bash
docker compose down && docker compose up -d
```

---

## 9. Actualizar la imagen Docker

La imagen `ghcr.io/lacompaniadigital/cd-system:latest` se rebuildeará automáticamente en `cd-system` cuando cambien:

- `Dockerfile`
- `.docker/**`
- `app/**`, `config/**`, `database/**`, `routes/**`
- `composer.json` / `composer.lock`

Para consumir la nueva imagen en `cd-frontend-dev`:

```bash
docker compose pull
docker compose down && docker compose up -d
```

### Forzar rebuild manual

En `cd-system` → Actions → **Build & Push Docker Image** → **Run workflow**.

---

## 10. Troubleshooting

### El container no levanta / error de MySQL

```bash
docker compose logs db     # ver logs de MySQL
docker compose down -v     # borrar volúmenes y empezar de cero
docker compose up -d
```

### La web muestra error 500

```bash
docker compose exec app php artisan config:clear
docker compose exec app php artisan cache:clear
docker compose exec app cat storage/logs/laravel.log | tail -50
```

### El demo no cambia después de switch-demo

```bash
docker compose exec app php artisan cache:clear
docker compose exec app php artisan config:clear
# Recargar el browser con Ctrl+Shift+R (hard refresh)
```

### El PR no apareció en cd-system

1. Verificar que el push tocó archivos en `resources/` o `public/`
2. Ir a `github.com/LACOMPANIADIGITAL/cd-frontend-dev/actions`
3. Buscar el run de `Sync to cd-system`
4. Si falló, revisar que el secret `CD_SYSTEM_PAT` esté vigente

### El PAT expiró

1. Crear un nuevo PAT en GitHub (scope `repo`)
2. Actualizar el secret `CD_SYSTEM_PAT` en `cd-frontend-dev` → Settings → Secrets