# Manual de instalación
### finanzas_agencia · Inventiva Agencia de Marketing

## 1. Requisitos

- XAMPP con PHP 8.2+ y MySQL/MariaDB 10.4+
- Carpeta del proyecto copiada dentro de `C:\xampp\htdocs\finanzas_agencia` (o la ruta equivalente en Mac/Linux)

## 2. Crear la base de datos

1. Abrir **phpMyAdmin** (`http://localhost/phpmyadmin`).
2. Ir a la pestaña **Importar**.
3. Importar **un solo archivo**: `sql/instalacion_completa.sql`

Ese único archivo trae todo: crea la base de datos, las 32 tablas, roles y permisos de los 4 perfiles,
y **tus datos reales** migrados desde tu Excel histórico (cuentas bancarias, movimientos, clientes,
facturas, recibos, beneficiarios, gastos fijos, empleados y suscripciones). No trae ningún usuario
todavía — eso se crea en el siguiente paso, con tu propia contraseña.

No hace falta crear la base de datos manualmente antes: el propio script la crea sola.

## 3. Configurar la conexión

Abrir `config/database.php` y verificar que coincida con tu XAMPP (por defecto no hace falta tocar nada):

```php
define('DB_HOST', 'localhost');
define('DB_NAME', 'finanzas_agencia');
define('DB_USER', 'root');
define('DB_PASS', '');
```

## 4. Crear el usuario administrador

1. Ir a: `http://localhost/finanzas_agencia/public/instalar.php`
2. Completar nombre, correo (opcional) y una contraseña de al menos 8 caracteres — **la que tú elijas**.
3. Al confirmar, el sistema crea el usuario `admin` con rol **Gerencia** (acceso total) y el archivo
   `instalar.php` se autodestruye por seguridad.

Si por algún motivo necesitas volver a ejecutar el instalador, vuelve a copiar ese único archivo desde
el ZIP original.

## 5. Ingresar al sistema

`http://localhost/finanzas_agencia/public/index.php`

Usuario: `admin` — con la contraseña que definiste en el paso 4.

## 6. Qué incluye el sistema

**Base**: cuentas financieras, movimientos de caja/banco (ingresos, egresos, transferencias,
planificados), dashboard gerencial con gráficos, usuarios/roles/permisos y auditoría.

**Cartera**: Clientes (con detección de duplicados y estado de cuenta), Proveedores, Directorio de
Beneficiarios, Facturas y Recibos (que generan automáticamente su Cuenta por Cobrar si quedan
pendientes), Cuentas por Cobrar consolidadas con antigüedad, registro de cobros (totales o parciales)
y Gestiones de Cobranza.

**Obligaciones**: Cuentas por Pagar, Planes de Pago de largo plazo (con generación automática de
cuotas), Gastos Fijos (con botón para generar la cuenta por pagar del mes en un clic), Sueldos
(empleados + planilla mensual editable) y Suscripciones (el pago avanza automáticamente el ciclo).

**Proyectos/Campañas y Análisis**: rentabilidad real por proyecto (con/sin pass-through), Proyección
de Flujo de Caja a 7/15/30/60/90 días, 6 Reportes Gerenciales exportables a CSV, Alertas automáticas,
Importador CSV de movimientos, y Auditoría con detalle de cambios.

## 7. Datos reales incluidos (migrados desde tu Excel)

- 3 cuentas financieras reales: Cuenta Corriente BNB, Caja de Ahorro BG (Banco Ganadero) y Cuenta
  Corriente BU (Banco Unión) — con sus saldos actuales ya cuadrados contra tu Excel.
- 2.503 movimientos bancarios históricos (2024-2026).
- 42 clientes, 99 facturas, 179 recibos.
- 15 beneficiarios (tu directorio de pagos a terceros).
- 23 gastos fijos, 9 empleados/colaboradores recurrentes, 7 suscripciones.
- 4 roles: Gerencia, Administrador Financiero, Cobranzas, Consulta/Auditor (sin usuarios creados
  todavía — el primero lo creas tú en el paso 4).

Algunos movimientos quedaron sin categoría asignada (la categorización se hizo por palabras clave
de forma automática); puedes completarla manualmente desde el sistema cuando tengas tiempo.

## 8. Migración a servidor en la nube


El sistema se diseñó desde el día uno para correr igual en XAMPP local y en cualquier hosting o
servidor en la nube (DigitalOcean, Hostinger, servidor propio, etc.), sin cambiar estructura ni rutas.

**Lo que se autodetecta solo (no hay que tocar nada):**
- `BASE_URL`: se arma sola a partir de la URL real con la que se accede, sin importar si el dominio
  apunta a la raíz del proyecto o directamente a la carpeta `public/`.
- Cookies de sesión: se marcan automáticamente como seguras (`secure`) en cuanto el sitio corre bajo
  HTTPS, que es lo normal en cualquier hosting en la nube.

**Checklist de migración (solo 4 pasos):**

1. Subir todos los archivos del proyecto al hosting (vía FTP, Git, o el panel del proveedor).
2. Crear la base de datos en el hosting e importar `sql/instalacion_completa.sql`.
3. Editar `config/database.php` con las 4 credenciales del hosting (host, nombre de BD, usuario, contraseña).
4. Editar `config/config.php` y cambiar `define('APP_DEBUG', true);` a `define('APP_DEBUG', false);`
   — esto evita que el sistema le muestre errores técnicos detallados a cualquier visitante.

Después de eso, correr `public/instalar.php` una vez en el nuevo servidor para crear el usuario
administrador (cada entorno genera su propio hash de contraseña, por eso no se puede copiar
directamente de la base de XAMPP).

**No hace falta:**
- Tocar ningún controlador, modelo o vista.
- Cambiar rutas de `url()` o `redirigir()` en el código — todas usan `BASE_URL` internamente.
- Instalar Composer ni ninguna dependencia adicional (el proyecto no usa ninguna).

**Requisito del hosting:** PHP 8.2 o superior con las extensiones `pdo_mysql` habilitada (estándar en
cualquier hosting compartido moderno). La extensión `mbstring` es recomendable pero no obligatoria,
el sistema funciona igual sin ella.

## 9. Seguridad ya implementada en esta fase

- Contraseñas con `password_hash()` (bcrypt)
- Bloqueo temporal tras 5 intentos fallidos de login (15 minutos)
- Sesiones con cookie `httponly`
- Token CSRF en todos los formularios
- PDO con prepared statements en el 100% de las consultas
- Bitácora de auditoría en login/logout, creación/edición de cuentas, movimientos y usuarios
- Baja lógica (nunca DELETE) en cuentas, movimientos y usuarios