# Manual de Onboarding — Sistematlan

> **Audiencia:** Equipo interno de Sistematlan (2 personas).  
> **Propósito:** Guía de referencia para provisionar un cliente nuevo en el modelo enterprise actual y para cuando se migre al modelo SaaS con ixtlisoft.

---

## Modelo actual: Enterprise (provisionamiento manual)

En este modelo, Sistematlan provee toda la infraestructura. El cliente no toca servidores. Sistematlan hace el deploy, la configuración y las actualizaciones.

### Cuándo aplica
- Cliente con servidor propio o VPS gestionado por Sistematlan
- Cliente con dominio propio
- Contrato de mantenimiento incluido

### Clientes activos

| Cliente | Servidor | Dominio | Estado |
|---------|----------|---------|--------|
| Ópticas Orlando | DAMP (local) + opticas-dev | dev-opticasorlando.sistematlan.com | Producción |
| Las Lupas | — | — | En provisionamiento |

---

## Checklist de provisionamiento — cliente nuevo

### 1. Infraestructura
- [ ] Crear VPS o espacio en servidor compartido
- [ ] Configurar dominio/subdominio y apuntarlo al servidor
- [ ] Instalar PHP 8.1+, MySQL 8.0+, Caddy/Nginx
- [ ] Generar certificado SSL (Let's Encrypt)
- [ ] Crear base de datos vacía y usuario MySQL con permisos

### 2. Código
- [ ] Clonar el repo en el servidor
  ```bash
  git clone <repo> ~/www/<cliente>
  cd ~/www/<cliente>
  composer install --no-dev --optimize-autoloader
  ```
- [ ] Copiar `.env.docker` como base del `.env` del cliente
  ```bash
  cp .env.docker .env
  ```
- [ ] Editar `.env` con los datos del cliente (ver sección Variables)
- [ ] Correr migraciones
  ```bash
  php spark migrate
  ```

### 3. Wizard de primera configuración
Abrir el dominio del cliente en el navegador. El sistema detecta que no hay tiendas y redirige automáticamente a `/setup`.

El cliente (o Sistematlan en su nombre) completa:
- **Paso 1 — Tienda:** nombre, dirección, teléfono, WhatsApp, enlace Google Maps
- **Paso 2 — Banco:** cuenta bancaria principal (omitible)
- **Paso 3 — Admin:** usuario, email y contraseña del administrador

### 4. Verificación post-install
- [ ] Login con el usuario admin recién creado
- [ ] Confirmar que el dashboard carga sin errores
- [ ] Confirmar que el landing público muestra los datos correctos
- [ ] Revisar logs: `writable/logs/log-YYYY-MM-DD.log`

---

## Variables `.env` por cliente

Llenar estas variables en el `.env` del servidor del cliente antes o después del wizard.

### Identidad y branding
```
app.title        = 'Nombre comercial completo'
app.titleShort   = 'Nombre corto'
app.email        = 'correo@cliente.com'
app.phone        = '+52 123 456 7890'
app.whatsapp     = '521234567890'        # con código de país, sin +
app.facebook     = 'https://www.facebook.com/...'
app.hours        = 'Lun-Sab: 10AM-2PM / 4PM-7:30PM'
app.tagline      = 'Descripción corta del negocio para el landing'
```

### Base de datos
```
database.default.hostname = localhost
database.default.database = nombre_bd
database.default.username = usuario_bd
database.default.password = contraseña_bd
database.default.port     = 3306
```

### App
```
app.baseURL       = 'https://dominio.com/'
CI_ENVIRONMENT    = production
app.forceGlobalSecureRequests = true
```

### Almacenamiento S3 (si aplica)
```
s3.bucket   = nombre-bucket
s3.key      = ACCESS_KEY
s3.secret   = SECRET_KEY
s3.region   = us-east-1
s3.endpoint = https://...
```

---

## Actualizaciones a clientes existentes

```bash
ssh <servidor-cliente>
cd ~/www/<cliente>
git pull
composer install --no-dev --optimize-autoloader
php spark migrate
php spark cache:clear
```

> Si hay cambios en assets (CSS/JS), correr `npm run build` antes del deploy y commitear el resultado.

### Regla: nunca editar código directamente en producción
Todo cambio va por el flujo: `development` → PR → `main` → deploy. Si hay un hotfix urgente, se hace en una rama `fix/...`, se mergea y se despliega.

---

## Separación de datos entre clientes

Cada cliente tiene:
- **Su propio servidor** (o espacio aislado)
- **Su propia base de datos**
- **Su propio `.env`** (nunca se commitea al repo)

El repo contiene código genérico. Los datos de cada cliente viven únicamente en su servidor. Un `git pull` nunca sobreescribe datos de cliente.

---

## Modelo futuro: SaaS con ixtlisoft

> Estado: planificado para cuando haya 3+ clientes activos.

### Cómo cambia el modelo

| Hoy (enterprise) | Futuro (SaaS) |
|------------------|---------------|
| Sistematlan crea BD manualmente | BD se crea automáticamente al registro |
| Sistematlan edita `.env` | Panel de admin de ixtlisoft |
| Cliente recibe credenciales por correo | Cliente completa wizard en el navegador |
| Deploy manual por cliente | Un deploy actualiza todos los tenants |
| Facturación por contrato | Facturación recurrente (Stripe/MercadoPago) |

### Arquitectura objetivo (Opción C acordada)
- Una sola instancia de CI4
- Un `TenantFilter` que detecta el hostname y conecta a la BD del tenant correspondiente
- Registro de tenants en una BD maestra (`ixtlisoft_registry`)
- El wizard actual se convierte en el onboarding de cada tenant nuevo

### Lo que ya está listo para SaaS
- [x] Wizard de primera configuración (`/setup`)
- [x] Variables de branding en `.env` (sin datos hardcodeados)
- [x] Landing dinámico (sucursales desde BD, contacto desde `.env`)
- [x] Migraciones limpias (sin datos de cliente en el código)

### Lo que falta para SaaS
- [ ] `TenantFilter` — detectar hostname → seleccionar BD
- [ ] BD maestra `ixtlisoft_registry` con tabla de tenants
- [ ] Panel de registro público en ixtlisoft.com
- [ ] Aprovisionamiento automático de BD al registro
- [ ] Facturación recurrente
- [ ] Panel de superadmin de ixtlisoft

---

## Contacto y accesos

> Completar con datos reales antes de usar en producción.

| Cliente | SSH | Panel hosting | BD |
|---------|-----|---------------|----|
| Ópticas Orlando | `ssh opticas-dev` | — | DAMP local |
| Las Lupas | — | — | — |

---

*Documento interno de Sistematlan. No distribuir a clientes.*