## 1) Resumen

TiendaPuntos & CanjesWhatsAppVideoChatFinanzasExcel Import

Bonuz es una solución de e‑commerce con fidelización nativa: registro de clientes, puntos y canjes, niveles (Plata/Oro/Diamante), mensajes por categoría, slot de video en recarga, chat (global y susurros), pedido por WhatsApp y panel de finanzas con filtros y exportación. 100% responsive.

## 2) Requisitos

- Servidor: Linux + Apache o Nginx, HTTPS activo.
- PHP: 8.1+ con extensiones: `pdo_mysql`, `mbstring`, `openssl`, `json`, `curl`, `zip`.
- DB: MySQL/MariaDB 10+.
- Límites sugeridos: `memory_limit 256M`, `upload_max_filesize 16M`, `post_max_size 16M`.

## 3) Estructura del paquete

    /install/
      db.sql                # estructura + semillas DEMO (sin datos reales)
    /config/
      .env.example          # copia a .env (ver sección 5)
    /docs/
      index.html            # esta documentación
    /tools/ (opcional)
      hash.php              # genera bcrypt para ADMIN_PASS_HASH (borrar tras usar)
    /uploads/
      .htaccess             # sin índices y sin ejecución PHP
    config/.htaccess        # deny all
    README.md
    LICENSE.txt

Si tu dump se llama `/script/superca1_demo.sql`, puedes mantenerlo, pero se recomienda renombrar a `/install/db.sql` para simplificar soporte y revisión.

## 4) Instalación rápida

### 4.1 Crear base de datos

1. cPanel → MySQL® Database Wizard → crea DB y usuario → marca ALL PRIVILEGES.

### 4.2 Importar esquema y demo

1. cPanel → phpMyAdmin → selecciona tu DB → pestaña Import.
2. Choose file → selecciona `install/db.sql` (o `script/superca1_demo.sql`) → Go.

### 4.3 Configurar variables (.env)

1. Copia `config/.env.example` → renómbralo a `config/.env`.
2. Edita las claves de conexión y marca:

    DB_HOST=localhost
    DB_NAME=tu_db
    DB_USER=tu_usuario
    DB_PASS=tu_pass

    APP_NAME="Bonuz"
    CURRENCY_CODE="USD"
    LOYALTY_COIN_NAME="Puntos"
    LOYALTY_EARN_PER_USD=30
    LOYALTY_REDEEM_USD_PER_POINT=1
    LOYALTY_LEVELS="Plata:100,Oro:250,Diamante:500"

    FX_ENABLED=false
    FX_PROVIDER=none

    # Genera el hash y pégalo aquí (ver tools/hash.php)
    # ADMIN_PASS_HASH=$2y$...

### 4.4 Generar hash de administrador

1. Sube `/tools/hash.php` temporalmente.
2. Visítalo: `https://TU_DOMINIO/tools/hash.php?p=TuClaveSegura` → copia resultado `$2y$...`
3. Pega en `ADMIN_PASS_HASH` de tu `.env` y borra `tools/hash.php`.

### 4.5 HTTPS y redirección

- cPanel → SSL/TLS Status → AutoSSL.
- cPanel → Domains → Force HTTPS Redirect en tu dominio/subdominio.

## 5) Configuración (.env)

- `APP_NAME`: nombre visible en la cabecera y email.
- `CURRENCY_CODE`: `USD`, `EUR`, etc. El símbolo se puede mapear en la vista.
- `LOYALTY_EARN_PER_USD`: USD gastados por 1 punto (p. ej., `30`).
- `LOYALTY_REDEEM_USD_PER_POINT`: valor de 1 punto en USD (p. ej., `1`).
- `LOYALTY_LEVELS`: formato `"Plata:100,Oro:250,Diamante:500"`.
- `FX_ENABLED`/`FX_PROVIDER`: desactiva FX en demo (`false/none`).
- `ADMIN_PASS_HASH`: hash bcrypt generado con `tools/hash.php`.

## 6) Seguridad

- Autenticación con `password_hash/password_verify` (bcrypt).
- `/config/.htaccess` con deny-all (impide leer `.env` por web).
- `/uploads/.htaccess`: sin ejecución de PHP y sin listado de directorios.
- Forzar HTTPS; no dejes instaladores ni herramientas en producción.

    # /config/.htaccess
    <IfModule mod_authz_core.c>
      Require all denied
    </IfModule>
    <IfModule !mod_authz_core.c>
      Deny from all
    </IfModule>

    # /uploads/.htaccess
    Options -Indexes
    <FilesMatch "\.(php|php\d+)$">
      Deny from all
    </FilesMatch>

Demo pública: usa `robots.txt` para no indexar:

    User-agent: *
    Disallow: /

## 7) Uso del sistema (operativa)

### 7.1 Productos y categorías

- Crear/editar productos, stock y visibilidad (disponible/no disponible).
- Mensajes por categoría: “En oferta”, “Próximamente”, etc.

### 7.2 Fidelización (puntos, canjes, niveles)

- Regla por defecto: 1 punto cada 30 USD; 1 punto = 1 USD.
- Niveles por umbral de puntos: Plata/Oro/Diamante.
- El admin confirma pagos y canjes; se registran en historial.

### 7.3 WhatsApp ordering

- El cliente envía pedido con método de entrega y pago; llega prellenado a WhatsApp.

### 7.4 Video y anuncios

- Slot de video en recarga (ideal para promociones o avisos globales).

### 7.5 Chat

- Global con opción de “susurro”/privado y subida de archivos (según límites).

### 7.6 Finanzas

- Totales, compras procesadas, filtros por día/fecha y exportación.

### 7.7 Importación por Excel

- Descarga la plantilla, completa columnas obligatorias y sube el archivo.

## 8) FAQ / Errores comunes

“Error de conexión a DB” → revisa `DB_HOST/DB_NAME/DB_USER/DB_PASS` y privilegios.

“No sale candado (HTTPS)” → corre AutoSSL y activa Force HTTPS.

“WhatsApp no abre” → valida teléfono en formato internacional y esquemas `https://wa.me/`.

“No veo niveles/puntos correctos” → revisa variables de `.env` y confirma pagos/canjes en admin.

“¿Dónde va la DB?” → no va en carpetas; se importa en phpMyAdmin dentro del servidor MySQL.

## 9) Actualizaciones

- Respalda DB y /config/.env.
- Sube archivos nuevos y ejecuta migraciones si vienen en `/install/migrations`.
- Purga cachés de tu hosting si aplica.

## 10) Soporte

Adsolutions — “Publicidad que mueve un mundo”
Horario: L–V 09:00–18:00 (CLT) · SLA 24 h
Email: Adsolutions@adsolutionsword.com · Web: adsolutionsword.com

## 11) Licencia y terceros

- Licencia/EULA: ver `LICENSE.txt` incluido en el paquete.
- Librerías de terceros (ejemplos): Bootstrap (MIT), jQuery (MIT), Chart.js (MIT).

## 12) Changelog

- 1.0 — 12/09/2025: Versión inicial.