# 📘 MANUAL DE INSTRUCCIONES: SKILL CORPORATIVO & DESPLIEGUE EN CPANEL (BANAHOSTING)

---

## 📑 ÍNDICE GENERAL
1. [PARTE 1: Cómo Instalar y Utilizar el Skill "corporate-fullstack-rbac"](#parte-1-cómo-instalar-y-utilizar-el-skill-corporate-fullstack-rbac)
2. [PARTE 2: Guía Paso a Paso para Instalar en cPanel de BanaHosting](#parte-2-guía-paso-a-paso-para-instalar-en-cpanel-de-banahosting)
3. [PARTE 3: Recursos y Archivos de Descarga Listos](#parte-3-recursos-y-archivos-de-descarga-listos)

---

# PARTE 1: CÓMO INSTALAR Y UTILIZAR EL SKILL "corporate-fullstack-rbac"

Este Skill contiene la **arquitectura estándar reutilizable** para que cualquier nuevo sistema que desarrolles tenga desde el inicio:
- Sistema de **Usuarios, Roles y Permisos Granulares (RBAC)** por menú y función (`puede_ver`, `puede_crear`, `puede_editar`, `puede_eliminar`, `puede_exportar`).
- Interfaz **SPA moderna** con ocultamiento reactivo de menús y modal de **Matriz Gráfica de Permisos**.
- Backend seguro con **Node.js, Express, JWT y Bcrypt**.
- Motor de reportes en **Excel Corporativo (`exceljs`)** con logo incrustado, cabeceras combinadas de 2 niveles y fórmulas vivas.

---

### 1.1. Ubicaciones del Skill en tu Computadora

El Skill puede guardarse en dos ubicaciones estratégicas:
1. **Global (Automático para cualquier nuevo proyecto):**
   `C:\Users\<TuUsuario>\.gemini\config\skills\corporate-fullstack-rbac\SKILL.md` (o `~/.gemini/config/skills/...`)
2. **Local (En el proyecto actual):**
   `.agents\skills\corporate-fullstack-rbac\SKILL.md`

---

### 1.2. Cómo usar el Skill en un Nuevo Proyecto

Cuando inicies un nuevo sistema en otra carpeta o para otro cliente, simplemente inicia tu conversación con el asistente diciendo:

> *"Inicia este nuevo proyecto siguiendo las directrices de la skill corporate-fullstack-rbac"*

El asistente leerá automáticamente las plantillas y configurará:
1. Las tablas base en la base de datos (`usuarios`, `roles`, `rol_permisos`).
2. El middleware de backend `requirePermission(modulo, accion)`.
3. El frontend con el sidebar dinámico y la matriz interactiva de roles.

---

### 1.3. Cómo llevar este Skill a otra computadora
Si cambias de máquina o quieres compartirlo:
1. Copia el archivo `corporate-fullstack-rbac-skill.zip` o la carpeta `corporate-fullstack-rbac`.
2. Pégalo en la ruta de configuración global de la nueva PC:
   `~/.gemini/config/skills/corporate-fullstack-rbac/SKILL.md`
   *(En Windows: `C:\Users\<TuUsuario>\.gemini\config\skills\corporate-fullstack-rbac\SKILL.md`)*

---

# PARTE 2: GUÍA PASO A PASO PARA INSTALAR EN CPANEL (BANAHOSTING)

El proyecto ya está empaquetado en el archivo liviano `pulsocorp_cpanel_deploy.zip` (~380 KB, sin `node_modules`).

---

### 🔹 PASO 1: Crear la Base de Datos MySQL en cPanel
1. Entra a tu **cPanel** de BanaHosting.
2. Ve a la sección **Bases de Datos** $\rightarrow$ **Bases de datos MySQL®**.
3. **Crear base de datos:** Escribe un nombre (ej. `contador`). El nombre completo será algo como `tuusuario_contador`. Haz clic en **Crear base de datos**.
4. **Crear usuario MySQL:** En la misma pantalla, baja a *Usuarios MySQL*. Crea un usuario (ej. `admin_contador`) y define una contraseña segura. **Apunta la contraseña**.
5. **Vincular usuario:** En *Añadir usuario a la base de datos*, selecciona el usuario y la base de datos creados. Haz clic en **Añadir**, marca **TODOS LOS PRIVILEGIOS (ALL PRIVILEGES)** y haz clic en **Hacer cambios**.
6. **Importar tablas iniciales:**
   - Vuelve al inicio de cPanel y entra a **phpMyAdmin**.
   - Haz clic sobre la base de datos creada en el panel izquierdo.
   - Ve a la pestaña superior **Importar (Import)**.
   - Selecciona el archivo `database_schema_pulsocorp.sql` y haz clic en **Importar** (abajo del todo).

---

### 🔹 PASO 2: Crear la Aplicación Node.js en cPanel
1. En cPanel, ve a la sección **Software** $\rightarrow$ **Setup Node.js App** (o *Configurar aplicación Node.js*).
2. Haz clic en el botón azul **Create Application**.
3. Completa los campos:
   - **Node.js version:** Selecciona `18.x` o `20.x`.
   - **Application mode:** `Production`.
   - **Application root:** Escribe el nombre de la carpeta (ej. `reportes` o `pulsocorp`).
   - **Application URL:** Selecciona tu dominio o subdominio (ej. `reportes.tudominio.com`).
   - **Application startup file:** Escribe: `server.js`
4. Haz clic en **CREATE** (arriba a la derecha).

---

### 🔹 PASO 3: Subir los Archivos del Proyecto
1. En cPanel, entra al **Administrador de Archivos (File Manager)**.
2. Entra a la carpeta de tu aplicación creada en el Paso 2 (ej. `/home/tuusuario/reportes`).
3. Haz clic en **Cargar (Upload)** arriba y sube el archivo comprimido `pulsocorp_cpanel_deploy.zip`.
4. Una vez subido al 100%, haz clic derecho sobre `pulsocorp_cpanel_deploy.zip` y selecciona **Extract (Extraer)**.

---

### 🔹 PASO 4: Configurar el Archivo `.env` en el Servidor
1. En el Administrador de Archivos, activa la vista de archivos ocultos (en la esquina superior derecha: **Configuración** $\rightarrow$ marcar **Mostrar archivos ocultos (dotfiles)** $\rightarrow$ Guardar).
2. Crea o edita el archivo `.env` en la raíz de la carpeta de la aplicación con los datos del Paso 1:

```ini
PORT=3000
NODE_ENV=production

# Conexión a Base de Datos MySQL
DB_HOST=localhost
DB_PORT=3306
DB_USER=tuusuario_admin_contador
DB_PASSWORD=tu_password_de_mysql
DB_NAME=tuusuario_contador

# Clave secreta para Tokens JWT
JWT_SECRET=super_secret_corporate_key_2026_pulsocorp_prod
```
3. Guarda el archivo `.env`.

---

### 🔹 PASO 5: Instalar Dependencias (`Run NPM Install`)
1. Vuelve a **Setup Node.js App** en cPanel.
2. Haz clic en el icono del **lápiz (Editar)** de tu aplicación.
3. Haz clic en el botón **Run NPM Install** (o *NPM Install*). cPanel instalará todas las librerías automáticamente en 1 minuto.
4. Haz clic en el botón superior **RESTART** (Reiniciar aplicación).

---

### 🔹 PASO 6: Activar Certificado SSL (HTTPS)
1. En cPanel, busca **SSL/TLS Status**.
2. Selecciona tu dominio o subdominio y haz clic en **Run AutoSSL**.
3. En pocos minutos tu sitio web cargará seguro con `https://`.

---

### 🔑 Credenciales de Acceso Inicial
- **URL:** `https://tudominio.com` (o subdominio configurado)
- **Usuario Administrador:** `admin@contador.corp`
- **Contraseña:** `Admin2026!`

*(Puedes modificar estos accesos o crear nuevos roles y usuarios desde la pestaña **Gestión de Usuarios** y **Roles y Permisos**)*.

---

# PARTE 3: RECURSOS Y ARCHIVOS DE DESCARGA LISTOS

Todos estos archivos ya se encuentran generados en la raíz del proyecto para tu uso inmediato:

1. 📦 **Paquete Completo para cPanel:** `pulsocorp_cpanel_deploy.zip` *(~380 KB)*
2. 📄 **Script SQL de Base de Datos:** `database_schema_pulsocorp.sql`
3. ⚙️ **Plantilla de Variables de Entorno:** `.env.production.example`
4. 🛡️ **Skill Completo en ZIP:** `corporate-fullstack-rbac-skill.zip`
5. 📘 **Manual de Instrucciones:** `INSTRUCCIONES.md`