# ZLETS - Walkthrough de Implementación

## Resumen

Se implementó el **sistema ZLETS** completo para **JW DIESEL S.A.C.** - un sistema MVC en PHP puro para el registro, control y reporte de letras de cambio con alertas de vencimiento.

### Estadísticas del proyecto
| Métrica | Valor |
|---------|-------|
| Archivos creados | 33 |
| Tablas en BD | 3 (empresas, grupos_letras, letras) |
| Datos de prueba | 5 empresas, 11 grupos, 30 letras |
| Controladores | 4 (Dashboard, Letras, Empresas, Reportes) |
| Modelos | 4 (Empresa, GrupoLetra, Letra, Reporte) |

---

## Páginas Implementadas

### 1. Dashboard
Página principal con estadísticas, gráficos Chart.js y alertas de vencimiento.

![Dashboard con cards, gráficos y alertas](C:/Users/MOD-09/.gemini/antigravity-ide/brain/76fce837-a6cc-4c75-aae4-0678a1e4f727/dashboard_full_maximized_1783025236060.png)

**Funcionalidades:**
- 4 cards de estadísticas: Letras Pendientes (24), Por Vencer (5), Vencidas (8), Monto Pendiente ($9,407.78)
- Gráfico de barras (montos mensuales por vencimiento)
- Gráfico doughnut (distribución de estados: 24 pendientes, 6 pagadas)
- Alertas de vencimiento con niveles de urgencia
- Listado de empresas proveedoras con montos pendientes

---

### 2. Listado de Letras
Tabla completa de todas las letras con filtros y acciones.

![Listado de letras con filtros y tabla](C:/Users/MOD-09/.gemini/antigravity-ide/brain/76fce837-a6cc-4c75-aae4-0678a1e4f727/letras_listado_1783025278795.png)

**Funcionalidades:**
- Filtros por empresa y estado
- Tabla con: ID, Empresa, Nº Letra, Tipo, Moneda, Emisión, Vencimiento, F. Pago (+8d), Importe, Días, Estado
- Cambio de estado inline vía AJAX (SweetAlert2)
- Indicadores de color por urgencia (rojo para vencidas, ámbar para próximas)
- Acciones: Editar, Eliminar (con confirmación)

---

### 3. Registro de Letras en Lote
Formulario para ingresar múltiples letras de una factura rápidamente.

![Formulario de registro en lote con 5 filas generadas](C:/Users/MOD-09/.gemini/antigravity-ide/brain/76fce837-a6cc-4c75-aae4-0678a1e4f727/letras_5_rows_generadas_1783025358814.png)

**Funcionalidades:**
- Step 1: Datos de la factura (empresa, serie, documento SUNAT, fecha, moneda, importe)
- Botón "Generar" crea N filas dinámicamente
- Cada fila: Nº Letra, Renovación, Tipo, Moneda, Emisión, Plazo, Vencimiento, F. Pago (auto), Importe, Banco
- Cálculo automático de fechas de vencimiento y pago
- Total calculado en tiempo real

---

### 4. Reporte de Letras
Reporte filtrado por rango de fechas y empresa, con exportación PDF/Excel.

![Reporte completo agrupado por empresa](C:/Users/MOD-09/.gemini/antigravity-ide/brain/76fce837-a6cc-4c75-aae4-0678a1e4f727/reporte_completo_1783025373803.png)

**Funcionalidades:**
- Filtros: Fecha vencimiento desde/hasta, empresa (o todas)
- Encabezado estilo imagen de referencia (JW DIESEL S.A.C., rango de fechas)
- Tabla agrupada por empresa con totales por grupo
- **Fecha de Pago en negrita** (vencimiento + 8 días)
- Columnas: Id, N, G, #Documento, Fec E., Fec I., Fecha Vec, Fecha Pag, Total, Obs, D, Banco, E, # Unico Ref
- Exportar a Excel (CSV con BOM UTF-8)
- Exportar a PDF (vista de impresión con estilos apaisados)
- Leyenda con significado de columnas

---

### 5. Empresas Proveedoras
Cards de empresas con progreso de pago.

![Cards de empresas proveedoras](C:/Users/MOD-09/.gemini/antigravity-ide/brain/76fce837-a6cc-4c75-aae4-0678a1e4f727/empresas_listado_1783025382943.png)

**Funcionalidades:**
- Cards glassmorphism por empresa
- Letras pendientes y monto pendiente
- Barra de progreso de pago
- Acciones: Editar, Activar/Desactivar
- Botón crear nueva empresa

---

## Video de Pruebas

![Video de pruebas completas del sistema](C:/Users/MOD-09/.gemini/antigravity-ide/brain/76fce837-a6cc-4c75-aae4-0678a1e4f727/letras_empresas_test_1783025266551.webp)

---

## Sistema de Alertas

Las alertas Toast (SweetAlert2) se disparan automáticamente al cargar cada página:

| Condición | Tipo | Color |
|-----------|------|-------|
| Vence en 4-7 días | Info | Azul |
| Vence en 1-3 días | Warning | Ámbar |
| Vence hoy | Error | Rojo |
| Vencida (quedan días para pagar) | Error | Rojo |
| Excedió plazo de pago (+8 días) | Error Crítico | Rojo pulsante |

> [!IMPORTANT]
> La **fecha de pago** se calcula automáticamente como `fecha_vencimiento + 8 días` en la base de datos (columna generada). Esto asegura que siempre sea consistente.

---

## Estructura de Archivos Final

```
zlets/
├── .htaccess                           # URL rewriting
├── index.php                           # Front Controller / Router
├── config/
│   └── conexion.php                    # PDO Singleton
├── controllers/
│   ├── DashboardController.php         # Dashboard + gráficos
│   ├── LetraController.php             # CRUD letras + lote
│   ├── EmpresaController.php           # CRUD empresas
│   └── ReporteController.php           # Reportes + exportación
├── models/
│   ├── Empresa.php                     # Modelo empresas
│   ├── GrupoLetra.php                  # Modelo grupos (transacciones)
│   ├── Letra.php                       # Modelo letras + estadísticas
│   └── Reporte.php                     # Consultas agrupadas
├── views/
│   ├── layout/
│   │   ├── header.php                  # CDNs + head
│   │   ├── sidebar.php                 # Navegación + top bar
│   │   └── footer.php                  # Scripts + alertas
│   ├── dashboard/
│   │   └── index.php                   # Vista dashboard
│   ├── letras/
│   │   ├── index.php                   # Listado
│   │   ├── crear.php                   # Registro en lote
│   │   └── editar.php                  # Editar individual
│   ├── empresas/
│   │   ├── index.php                   # Listado cards
│   │   └── form.php                    # Crear/Editar
│   └── reportes/
│       ├── index.php                   # Filtros + tabla
│       └── print.php                   # Vista impresión PDF
├── assets/
│   ├── css/
│   │   └── styles.css                  # Glassmorphism + dark theme
│   └── js/
│       ├── app.js                      # Toasts + alertas + utils
│       ├── dashboard.js                # Chart.js initialization
│       ├── letras.js                   # Lote + AJAX estado
│       └── reportes.js                 # Impresión PDF
├── sql/
│   └── zlets_db.sql                    # Base de datos + datos de prueba
└── [archivos referencia]
    ├── basedatos.md
    ├── letra.jpeg
    ├── reporte.png
    └── dashboard.png
```

---

## Tecnologías Utilizadas

| Tecnología | Uso |
|-----------|-----|
| PHP 8.2 | Backend MVC puro OOP |
| MySQL | Base de datos (PDO) |
| Tailwind CSS (CDN) | Framework CSS responsive |
| Chart.js (CDN) | Gráficos de barras y doughnut |
| SweetAlert2 (CDN) | Toasts y confirmaciones |
| Font Awesome (CDN) | Iconos |
| Google Fonts | Sora (títulos) + Inter (texto) |

## Acceso

- **URL**: [http://localhost/zlets/](http://localhost/zlets/)
- **Base de datos**: zlets_db (localhost, root, sin contraseña)
