# Btec Module Scaffold (v1.2.0)

Este flujo permite crear un módulo nuevo en minutos y mostrarlo en `modulos-btec.php` sin editar `module_manager.php` por cada módulo.

## Requisitos

- El cliente debe usar `btec-core/releases/v1.2.0` (o superior con este soporte).
- El cliente debe tener wrapper `func/module_manager.php` apuntando a `.btec-core/func/module_manager.php`.

## Tipos de módulo

### 1. Módulo instalable 100% desde UI

Aplica cuando el módulo solo necesita:

- tablas SQL
- registros de menú
- estado/licencia
- wrappers ya existentes en el cliente

En este caso, `modulos-btec.php` puede instalarlo completo desde el navegador.

### 2. Módulo `predeploy required`

Aplica cuando el módulo necesita tocar archivos PHP del cliente, por ejemplo:

- `layout/navbar.php`
- `layout/menu.php`
- wrappers nuevos como `notificaciones.php`
- helpers en `func/*.php`
- endpoints públicos o archivos que deban quedar versionados por cliente

En este caso, la instalación correcta es en dos pasos:

1. `Predeploy`: copiar/parchar archivos desde terminal o release.
2. `Install`: ejecutar la activación desde `modulos-btec.php`.

Regla práctica: si el módulo necesita escribir PHP en el cliente desde navegador, no debe depender de eso para funcionar en producción.

## 1) Generar esqueleto del módulo

```bash
/home/bitnami/htdocs/btec-core/bin/make-client-module.sh \
  /home/bitnami/htdocs/sunnydesertcabo/btec_v1 \
  blog-publicador-web \
  "Blog Publicador Web" \
  blog.php \
  paid \
  3600 \
  MXN \
  one_time
```

Para módulo de pago:

```bash
/home/bitnami/htdocs/btec-core/bin/make-client-module.sh \
  /home/bitnami/htdocs/desert/btec_v1 \
  api-whatsapp-pro \
  "Asistente WhatsApp Operativo" \
  - \
  paid \
  49.00 \
  USD \
  monthly
```

## 2) Completar implementación

Editar archivos generados:

- `func/modules/<slug>.php`
- `func/modules/<slug>.sql`

Puntos clave:

- Definir SQL idempotente (`CREATE TABLE IF NOT EXISTS`).
- Ajustar callback `btec_modules_install_<slug>` para crear menú si aplica.
- Completar detalle comercial/técnico (`characteristics`, `functions`, `benefits`).

## 2.1) Decidir si el módulo es `predeploy required`

Marca el módulo como `predeploy required` si cumple uno o más de estos casos:

- necesita agregar bloques al `navbar`
- necesita agregar enlaces persistentes al menú
- necesita wrappers como `<modulo>.php`
- necesita helper compartido en `func/`
- necesita endpoint público o archivos consumidos por el sitio web

Ejemplo real:

- `notificaciones-internas`

Este módulo requiere:

- `func/notifications.php`
- `notificaciones.php`
- `notification.php`
- parche en `layout/navbar.php`

Conclusión: no debe depender de `file_put_contents()` desde el navegador como único mecanismo de despliegue.

## 2.2) Patrón recomendado para módulos `predeploy required`

### A. Despliegue de archivos

Primero deja los archivos base en el cliente:

- helper en `func/`
- wrappers de página
- parches de `layout/`

Esto puede hacerse:

- al integrar el cliente al core
- al promover una nueva release
- con script de despliegue por lote

### B. Activación desde UI

Una vez desplegados los archivos, `modulos-btec.php` solo debe encargarse de:

- crear tablas
- registrar estado de instalación
- crear entradas en menú
- sincronizar licencias
- ejecutar migraciones SQL idempotentes

## 2.3) Checklist antes de publicar un módulo

- `php -l` sobre archivos del core
- `php -l` sobre wrappers/archivos cliente generados
- SQL idempotente
- instalador tolerante a reintentos
- update callback reutilizando install callback si aplica
- detalle comercial visible en `modulos-btec.php`
- si es `predeploy required`, documentación explícita del predeploy
- prueba en cliente canary

## 2.4) Qué no hacer

- No depender de que Apache/PHP web tenga permisos para modificar PHP del cliente.
- No usar instalación desde UI para parchar `layout/*.php` como única vía de despliegue.
- No dejar módulos mixtos donde parte crítica vive solo en base de datos y otra parte crítica nunca se desplegó al filesystem.

## 3) Instalar desde Módulos Btec

1. Abre `modulos-btec.php` del cliente.
2. El módulo aparecerá automáticamente en catálogo.
3. Si el módulo es `predeploy required`, verifica primero que los archivos base ya estén desplegados.
4. Instala o paga/instala según tipo de licencia.

## 4) Publicación web (caso Blog)

El módulo del panel (ej. `blog.php`) debe exponer datos públicos por endpoint, por ejemplo:

- `func/get_blog_public.php`

Luego el sitio público (`../index.php` o plantilla HTML) consume ese endpoint por `fetch`/AJAX y renderiza los posts.  
Recomendación: no escribir HTML estático manual por cada post; usar consumo dinámico del endpoint.

## 5) Caso especial: Notificaciones Internas

`notificaciones-internas` queda documentado como módulo `predeploy required`.

Archivos mínimos por cliente:

- `func/notifications.php`
- `notificaciones.php`
- `notification.php`
- `layout/navbar.php` con bootstrap y dropdown

Instalación correcta:

1. desplegar esos archivos en el cliente
2. correr instalación desde `modulos-btec.php`
3. validar que el badge cuente solo pendientes
4. validar que `notification.php?id=...` marque como leída