Vitrina — Integración HelpU

1. División de responsabilidades

2. Empresa en HelpU (bd_helpu)

Reutiliza el modelo existente de empresa cliente por producto (como Huella/Habitta).

Campos adicionales en formulario checkout Vitrina (fase 2):

• store_slug — URL pública deseada (/t/{slug}), validado único en VitrinaApp
• store_tagline — eslogan inicial (opcional)
• admin_name — nombre del usuario administrador
• admin_password — solo en alta nueva; o invitación por correo

3. Tenant en VitrinaApp

Cada empresa contratada = un registro tenants + al menos un users con tenant_id.

4. Planes propuestos (catálogo HelpU App)

Métrica de facturación: productos activos en la tienda (análogo a unidades Habitta / alumnos Huella).

Periodos: mensual y anual (misma estructura planes + tarifas en App).

5. Estados comerciales (tenants.estado_comercial)

6. Flujos

6.1 Contratación (cliente nuevo)

1. PW: checkout.php?producto=vitrina&plan=…
2. Consulta NIT: GET /api/empresas/consulta?producto=vitrina&nit=…
3. Alta: POST /api/empresas con producto=vitrina → crea empresa en HelpU + tenant inactivo en VitrinaApp
4. Pago Wompi → POST /api/pagos/confirmar → activa plan, estado_comercial=activo, correo bienvenida
5. Cliente entra a {VITRINA_APP_URL}/admin/login

6.2 Demo / registro de interés

1. POST /api/demos con producto=vitrina
2. SuperAdmin aprueba → provisiona tenant demo + 30 días activo_hasta

6.3 Operación diaria

El negocio usa solo VitrinaApp. HelpU no interviene salvo soporte o cambio de plan.

7. Esquema VitrinaApp (campos nuevos en tenants)

helpu_empresa_id  BIGINT UNSIGNED NULL UNIQUE  -- FK lógica bd_helpu.empresas
nit               VARCHAR(20) NULL INDEX
plan_codigo       VARCHAR(40) NULL
estado_comercial  VARCHAR(20) DEFAULT 'demo'   -- demo|activo|suspendido|cancelado
activo_hasta      DATE NULL
provisioned_at    TIMESTAMP NULL

Se elimina users.is_super_admin del producto (super-admin solo en HelpU App).

8. API interna (fase 3)

Auth: Authorization: Bearer {HELPU_WS_TOKEN} o X-Helpu-Ws-Token (mismo token del mostrador).

HelpU App usa VitrinaAppClient contra VITRINA_APP_URL; si la API no responde, fallback a SQLite (DB_VITRINA_DATABASE).

9. Roadmap

13. Fase 13 — Producción (go-live)

URL pública acordada: https://vitrina.helpu.com.co (multi-tenant por /t/{slug}, no subdominio por cliente).

13.1 Variables por sistema

13.2 Cola de correos

Correos de bienvenida, pedidos y cambio de estado se encolan. En producción:

# Migrar tablas de cola (si aún no existen)
php artisan queue:table
php artisan migrate

# Worker (supervisor, systemd o servicio Windows)
php artisan queue:work --tries=3 --timeout=90

Mail recomendado: Resend (MAIL_MAILER=resend, RESEND_API_KEY) con remitente verificado notificacionesautomaticas@helpu.com.co.

13.3 Cron

En App y VitrinaApp (misma hora, sin solaparse):

* * * * * cd /ruta/App && php artisan schedule:run
* * * * * cd /ruta/VitrinaApp && php artisan schedule:run

Comando diario: vitrina:procesar-vencimientos a las 02:00 America/Bogota.

13.4 Verificación pre-deploy

# HelpU PW (desde el servidor web)
php tools/test-vitrina-produccion.php

# HelpU App
php artisan vitrina:verificar-produccion --strict

# VitrinaApp
php artisan vitrina:verificar-produccion --strict

El flag --strict convierte advertencias (debug activo, cola sync, URLs locales) en código de salida distinto de cero.

13.5 Checklist go-live

1. DNS y TLS para vitrina.helpu.com.co apuntando al servidor VitrinaApp.
2. Token HELPU_WS_TOKEN idéntico en PW, App y VitrinaApp.
3. Wompi producción en params.php (claves pub_prod_ / prv_prod_).
4. APP_DEBUG=false y APP_ENV=production en App y VitrinaApp.
5. Worker de cola activo en ambas apps.
6. Cron schedule:run en ambas apps.
7. Smoke PW: php tools/test-vitrina-ws.php.
8. Compra de prueba starter + correo de acceso + tienda /t/{slug}.

12. Fase 12 — QA y pruebas E2E

12.1 Automatizadas (PHPUnit)

# HelpU App
cd App && composer install && vendor\bin\phpunit --filter Vitrina

# VitrinaApp
cd VitrinaApp && vendor\bin\phpunit tests\Feature

12.2 Smoke manual (PW)

Con App WS activo: php tools/test-vitrina-ws.php o php tools/test-helpu-ws.php (incluye Vitrina).

12.3 Checklist manual E2E

1. PW vitrina.php: gate nuevo / ya tengo tienda → planes → checkout Wompi (starter).
2. PW: rango >500 o plan Enterprise → contacto con datos prellenados.
3. VitrinaApp /t/demo-shop: compra COD y correo de pedido.
4. Admin tienda: cambiar estado pedido → correo al cliente.
5. HelpU App SuperAdmin: suspender tienda → banner solo lectura en tienda pública.
6. Cron vitrina:procesar-vencimientos en App y VitrinaApp.

11. Fase 11 — Enterprise y cotización

Planes vitrina_enterprise y rangos con requiere_cotizacion (>500 productos) no permiten pago en línea: el visitante es dirigido a contacto con contexto prellenado.

Tests: App/tests/Feature/PlanesApiTest.php (cotizar vitrina), VitrinaEmpresaConsultaTest.php.

10. Fase 10 — UX tienda pública (VitrinaApp)

Cuando estado_comercial=suspendido (p. ej. tras vencimiento en fase 9), la tienda pública permanece visible en modo consulta.

Tests: VitrinaApp/tests/Feature/ShopSuspendedTest.php, OrderStatusNotificationTest.php.

14. Fase 14 — Documentación y cierre

Entregables de referencia para operación, soporte y desarrollo:

Repositorios: HelpU/pw (comercial), App (WS + consola), VitrinaApp (producto tenant).

15. Decisiones cerradas

Fuera de alcance MVP (futuro)

• Límite de pedidos por mes o por plan.
• Subdominio dedicado por cliente (mitienda.helpu.com.co).
• OAuth centralizado en HelpU App para todos los productos.
• Pasarela Wompi embebida por tenant (hoy: contra entrega y flujo comercial HelpU).