# Sistema ZLETS - Control de Letras para JW DIESEL S.A.C.

Sistema web MVC en PHP puro para el registro, control y reporte de letras de cambio con alertas de vencimiento. Diseñado para hosting compartido (cPanel + MySQL + PHP 8.2).

## Contexto del Negocio

JW DIESEL S.A.C. recibe documentos de "Resumen de Canje de Facturas con Letras" de sus proveedores. Cada documento contiene múltiples letras con fechas de vencimiento escalonadas. El sistema debe:

1. **Registrar letras en lote** - Ingresando empresa, factura y cantidad de letras, el sistema genera automáticamente los campos para llenar rápidamente.
2. **Controlar vencimientos** - Alertas Toast cuando una letra está por vencer o ya venció (la empresa tiene 8 días adicionales después del vencimiento para pagar al banco).
3. **Generar reportes** - Filtrado por rango de fechas de vencimiento y empresa, agrupado por empresa, mostrando la **Fecha de Pago** (vencimiento + 8 días) en negrita. Exportable a PDF y Excel.

## Datos extraídos de las imágenes de referencia

### De `letra.jpeg` (Formulario de ingreso):
| Campo | Ejemplo |
|-------|---------|
| Empresa proveedora | J.Y.W. REPUESTOS S.A.C. |
| Serie | 001 |
| Documento SUNAT | 000000000012884 |
| Fecha Emisión Factura | 09/05/2026 |
| Moneda | USD |
| Importe Factura | 75.00 |
| Total Letras | 4,948.68 |
| Letras (1-13) | Número, Renovación, Tipo (ORI), Moneda (USD), Emisión, Plazo (días), Vencimiento, Importe |

### De `reporte.png` (Reporte semanal):
| Columna | Descripción |
|---------|-------------|
| Id | ID interno |
| N | Número de letra en el grupo |
| G | Grupo de letras |
| #Documento | Número de documento/letra |
| Fec E. | Fecha de emisión (dd/mm) |
| Fec I. | Fecha de ingreso (dd/mm) |
| Fecha Vec | Fecha de vencimiento |
| **Fecha Pag** | **Fecha de pago = Vencimiento + 8 días (en negrita)** |
| Total | Monto en USD |
| Obs. | Observaciones (checkbox) |
| D | Días restantes |
| Banco | Banco |
| E | Estado (A=Aceptada, R=Renovada) |
| # Unico Ref | Referencia única |

### De `dashboard.png`:
- Sidebar con navegación (Dashboard, Reportes, Letras, Empresas, Historial, Configuración)
- Cards de resumen (Total Letras, Letras por Vencer, Letras Vencidas, Total USD)
- Gráfico de barras (montos mensuales)
- Gráfico de pastel (estado de letras)
- Card de "Pro Access" / acceso rápido

---

## Estructura de Carpetas MVC

```
zlets/
├── index.php                    # Router principal (Front Controller)
├── .htaccess                    # Reescritura de URLs
│
├── config/
│   └── conexion.php             # Conexión PDO centralizada
│
├── controllers/
│   ├── DashboardController.php  # Dashboard con estadísticas
│   ├── LetraController.php      # CRUD de letras (registro lote)
│   ├── EmpresaController.php    # CRUD de empresas proveedoras
│   └── ReporteController.php    # Generación de reportes PDF/Excel
│
├── models/
│   ├── Letra.php                # Modelo de letras
│   ├── Empresa.php              # Modelo de empresas
│   ├── GrupoLetra.php           # Modelo de grupos de letras (lote)
│   └── Reporte.php              # Modelo para consultas de reportes
│
├── views/
│   ├── layout/
│   │   ├── header.php           # Head HTML, CDNs, inicio body
│   │   ├── sidebar.php          # Sidebar de navegación
│   │   └── footer.php           # Scripts, cierre body
│   ├── dashboard/
│   │   └── index.php            # Vista del Dashboard
│   ├── letras/
│   │   ├── index.php            # Listado de letras
│   │   ├── crear.php            # Formulario de registro en lote
│   │   └── editar.php           # Editar letra individual
│   ├── empresas/
│   │   ├── index.php            # Listado de empresas
│   │   └── form.php             # Formulario crear/editar empresa
│   └── reportes/
│       └── index.php            # Filtros y vista previa del reporte
│
├── assets/
│   ├── css/
│   │   └── styles.css           # Estilos custom (glassmorphism, etc.)
│   ├── js/
│   │   ├── app.js               # JS principal (toasts, utilidades)
│   │   ├── dashboard.js         # Charts del dashboard
│   │   ├── letras.js            # Lógica de registro en lote
│   │   └── reportes.js          # Lógica de filtros y exportación
│   └── img/
│       └── logo.png             # Logo JWDIESEL
│
├── libs/
│   ├── TCPDF/                   # Librería para generar PDF (sin composer)
│   └── PHPSpreadsheet-lite/     # Para exportar Excel (alternativa ligera)
│
├── exports/
│   └── .gitkeep                 # Carpeta temporal para archivos generados
│
├── sql/
│   └── zlets_db.sql             # Script de creación de la base de datos
│
├── basedatos.md                 # Credenciales (ya existente)
├── letra.jpeg                   # Referencia (ya existente)
├── reporte.png                  # Referencia (ya existente)
└── dashboard.png                # Referencia (ya existente)
```

---

## Diseño de Base de Datos

```sql
-- Empresas proveedoras
CREATE TABLE empresas (
    id INT AUTO_INCREMENT PRIMARY KEY,
    razon_social VARCHAR(200) NOT NULL,
    ruc VARCHAR(20),
    direccion VARCHAR(300),
    telefono VARCHAR(20),
    estado TINYINT DEFAULT 1,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
);

-- Grupos de letras (cada documento/factura ingresado)
CREATE TABLE grupos_letras (
    id INT AUTO_INCREMENT PRIMARY KEY,
    empresa_id INT NOT NULL,
    serie VARCHAR(10),
    documento_sunat VARCHAR(50),
    fecha_emision_factura DATE,
    moneda ENUM('USD','PEN') DEFAULT 'USD',
    importe_factura DECIMAL(12,2) DEFAULT 0,
    total_letras DECIMAL(12,2) DEFAULT 0,
    cantidad_letras INT DEFAULT 0,
    observaciones TEXT,
    estado TINYINT DEFAULT 1,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    FOREIGN KEY (empresa_id) REFERENCES empresas(id)
);

-- Letras individuales
CREATE TABLE letras (
    id INT AUTO_INCREMENT PRIMARY KEY,
    grupo_id INT NOT NULL,
    empresa_id INT NOT NULL,
    numero_letra VARCHAR(50) NOT NULL,
    numero_en_grupo INT DEFAULT 1,
    renovacion INT DEFAULT 0,
    tipo_letra ENUM('ORI','REN') DEFAULT 'ORI',
    moneda ENUM('USD','PEN') DEFAULT 'USD',
    fecha_emision DATE NOT NULL,
    plazo_dias INT DEFAULT 30,
    fecha_vencimiento DATE NOT NULL,
    fecha_pago DATE GENERATED ALWAYS AS (DATE_ADD(fecha_vencimiento, INTERVAL 8 DAY)) STORED,
    importe DECIMAL(12,2) NOT NULL,
    banco VARCHAR(100),
    estado ENUM('pendiente','pagada','vencida','renovada','protestada') DEFAULT 'pendiente',
    referencia_unica VARCHAR(100),
    observaciones TEXT,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    FOREIGN KEY (grupo_id) REFERENCES grupos_letras(id),
    FOREIGN KEY (empresa_id) REFERENCES empresas(id),
    INDEX idx_fecha_vencimiento (fecha_vencimiento),
    INDEX idx_fecha_pago (fecha_pago),
    INDEX idx_estado (estado),
    INDEX idx_empresa (empresa_id)
);
```

> [!IMPORTANT]
> La columna `fecha_pago` es una columna generada automáticamente como `fecha_vencimiento + 8 días`. Esto garantiza consistencia y aparecerá **en negrita** en los reportes.

---

## Proposed Changes

### 1. Configuración Base

#### [NEW] [.htaccess](file:///c:/laragon/www/zlets/.htaccess)
- Reescritura de URLs para el front controller
- Redirigir todas las peticiones a `index.php`

#### [NEW] [index.php](file:///c:/laragon/www/zlets/index.php)
- Front Controller / Router simple
- Parsear URL para determinar controlador y acción
- Rutas: `?c=dashboard`, `?c=letras&a=crear`, `?c=reportes`, etc.

#### [NEW] [conexion.php](file:///c:/laragon/www/zlets/config/conexion.php)
- Conexión PDO centralizada con patrón Singleton
- Configuración: localhost, root, sin password, zlets_db, puerto 3306
- Charset UTF-8, manejo de errores con excepciones

#### [NEW] [zlets_db.sql](file:///c:/laragon/www/zlets/sql/zlets_db.sql)
- Creación de base de datos y tablas
- Datos de prueba (empresas de ejemplo + letras simuladas)
- Empresas: DITERSA, JYW REPUESTOS S.R.L., RENUSA (de las imágenes)

---

### 2. Modelos

#### [NEW] [Letra.php](file:///c:/laragon/www/zlets/models/Letra.php)
- Métodos: `getAll()`, `getById()`, `create()`, `update()`, `delete()`
- `getProximasAVencer($dias)` - Letras que vencen en los próximos N días
- `getVencidas()` - Letras vencidas pero dentro del período de pago (+8 días)
- `getByFechasYEmpresa($fechaDesde, $fechaHasta, $empresaId)` - Para reportes
- `getEstadisticas()` - Para el dashboard

#### [NEW] [Empresa.php](file:///c:/laragon/www/zlets/models/Empresa.php)
- CRUD básico de empresas proveedoras

#### [NEW] [GrupoLetra.php](file:///c:/laragon/www/zlets/models/GrupoLetra.php)
- Gestión de grupos/lotes de letras
- `crearConLetras($datosGrupo, $datosLetras)` - Transacción para insertar grupo + letras

#### [NEW] [Reporte.php](file:///c:/laragon/www/zlets/models/Reporte.php)
- Consultas optimizadas para reportes agrupados por empresa
- Cálculos de totales por grupo y generales

---

### 3. Controladores

#### [NEW] [DashboardController.php](file:///c:/laragon/www/zlets/controllers/DashboardController.php)
- Obtener estadísticas: total letras, por vencer, vencidas, montos
- Datos para gráficos Chart.js (montos mensuales, estados)
- Alertas de letras próximas a vencer

#### [NEW] [LetraController.php](file:///c:/laragon/www/zlets/controllers/LetraController.php)
- `index()` - Listar letras con paginación y filtros
- `crear()` - Formulario de registro en lote (ingresa empresa + factura + cantidad → genera filas)
- `guardar()` - Procesar formulario de lote
- `editar()`, `actualizar()`, `eliminar()`
- `getAlertas()` - Endpoint JSON para alertas Toast

#### [NEW] [EmpresaController.php](file:///c:/laragon/www/zlets/controllers/EmpresaController.php)
- CRUD completo de empresas

#### [NEW] [ReporteController.php](file:///c:/laragon/www/zlets/controllers/ReporteController.php)
- `index()` - Vista con filtros (fecha desde, fecha hasta, empresa)
- `generar()` - Generar vista previa del reporte
- `exportarPDF()` - Generar PDF con TCPDF
- `exportarExcel()` - Generar Excel

---

### 4. Vistas (Frontend)

#### [NEW] [header.php](file:///c:/laragon/www/zlets/views/layout/header.php)
- CDNs: Tailwind CSS, Google Fonts (Sora + Inter), SweetAlert2, Chart.js, Font Awesome
- Meta tags, estilos glassmorphism base

#### [NEW] [sidebar.php](file:///c:/laragon/www/zlets/views/layout/sidebar.php)
- Sidebar estilo dashboard.png con glassmorphism
- Logo JWDIESEL, menú de navegación con iconos
- Indicador de sección activa

#### [NEW] [footer.php](file:///c:/laragon/www/zlets/views/layout/footer.php)
- Carga de scripts JS, inicialización de alertas Toast

#### [NEW] [views/dashboard/index.php](file:///c:/laragon/www/zlets/views/dashboard/index.php)
- 4 Cards de resumen: Total Letras, Por Vencer, Vencidas, Monto Total USD
- Gráfico de barras (Chart.js) - Montos mensuales
- Gráfico de pastel (Chart.js) - Estados de letras
- Mini sparklines en cada card

#### [NEW] [views/letras/crear.php](file:///c:/laragon/www/zlets/views/letras/crear.php)
- Step 1: Seleccionar empresa, serie, documento SUNAT, fecha emisión, moneda, importe, cantidad de letras
- Step 2: Tabla dinámica con N filas generadas automáticamente para llenar datos de cada letra
- Cálculo automático de fechas de vencimiento basado en plazo

#### [NEW] [views/letras/index.php](file:///c:/laragon/www/zlets/views/letras/index.php)
- Tabla con listado de letras, filtros, búsqueda
- Indicadores de color por estado y proximidad de vencimiento

#### [NEW] [views/reportes/index.php](file:///c:/laragon/www/zlets/views/reportes/index.php)
- Filtros: Fecha vencimiento desde, hasta, Empresa (select o "Todas")
- Vista previa tipo tabla agrupada por empresa
- Botones exportar PDF / Excel
- Fecha de pago en negrita (vencimiento + 8 días)

---

### 5. Assets (CSS/JS)

#### [NEW] [styles.css](file:///c:/laragon/www/zlets/assets/css/styles.css)
- Variables CSS con paleta de colores JWDIESEL (azul corporativo oscuro)
- Clases glassmorphism (backdrop-blur, transparencias)
- Animaciones suaves, sombras difuminadas
- Estilos para sidebar, cards, tablas, formularios

#### [NEW] [app.js](file:///c:/laragon/www/zlets/assets/js/app.js)
- Configuración global de SweetAlert2 en modo Toast
- Sistema de notificaciones para alertas de vencimiento
- Funciones utilitarias (formatear fechas, moneda)
- Carga automática de alertas al iniciar

#### [NEW] [dashboard.js](file:///c:/laragon/www/zlets/assets/js/dashboard.js)
- Inicialización de Chart.js para barras y pastel
- Fetch de datos desde endpoint JSON del controlador

#### [NEW] [letras.js](file:///c:/laragon/www/zlets/assets/js/letras.js)
- Generación dinámica de filas en el formulario de lote
- Cálculo automático de fechas y totales
- Validaciones del formulario

#### [NEW] [reportes.js](file:///c:/laragon/www/zlets/assets/js/reportes.js)
- Lógica de filtros del reporte
- Descarga de PDF/Excel vía fetch

---

### 6. Exportaciones (PDF/Excel)

> [!NOTE]
> Para mantener el proyecto **sin Composer**, usaré:
> - **PDF**: Generación HTML-to-PDF usando `dompdf` (versión standalone descargable) o una solución más ligera con generación HTML directa que el navegador puede imprimir como PDF (`window.print()` con estilos de impresión).
> - **Excel**: Generación nativa de CSV/XLSX usando PHP headers + formato de tabla HTML que Excel puede abrir, o PHPSpreadsheet standalone.
> 
> **Enfoque inicial recomendado**: Usar `window.print()` con CSS `@media print` para PDF y generación de CSV nativo para Excel. Esto elimina dependencias externas. Si necesitas PDFs más elaborados, podemos integrar TCPDF después.

---

## Simulación de Datos

Se insertarán datos de prueba basados en las imágenes:

### Empresas:
1. **DITERSA** - RUC: ejemplo
2. **JYW REPUESTOS S.R.L.** - RUC: ejemplo  
3. **RENUSA** - RUC: ejemplo

### Letras simuladas (basadas en letra.jpeg):
- JYW REPUESTOS: 13 letras, Serie 001, Doc. SUNAT 000000000012884, Emisión 14/05/2026, Plazo 30-90 días, Vencimiento 13/06/2026 a 12/08/2026, Importes ~380.67 USD c/u
- DITERSA: 1 letra, Doc. 2084046, Vencimiento 22/06/2026, USD 398.00
- RENUSA: 2 letras, Doc. 540071351/00 y 8675

---

## Sistema de Alertas

Las alertas Toast se mostrarán automáticamente al cargar cualquier página:

| Condición | Color | Mensaje |
|-----------|-------|---------|
| Vence hoy | 🔴 Rojo | "¡Letra #XXX de EMPRESA vence HOY!" |
| Vence en 1-3 días | 🟠 Naranja | "Letra #XXX vence en N días" |
| Vence en 4-7 días | 🟡 Amarillo | "Letra #XXX vence en N días" |
| Vencida (1-8 días) | 🔴 Rojo pulsante | "¡URGENTE! Letra #XXX venció hace N días. Quedan X días para pagar al banco" |
| Vencida > 8 días | ⚫ Negro | "¡CRÍTICO! Letra #XXX excedió el plazo de pago" |

---

## User Review Required

> [!IMPORTANT]
> **Exportación PDF/Excel**: Recomiendo iniciar con `window.print()` + CSS de impresión para PDF y CSV nativo para Excel. Esto evita descargar librerías externas pesadas (TCPDF ~15MB, PHPSpreadsheet ~50MB). ¿Estás de acuerdo o prefieres integrar TCPDF/PHPSpreadsheet desde el inicio?

> [!IMPORTANT]
> **Autenticación**: Las imágenes no muestran login. ¿Necesitas un sistema de login (usuario/contraseña) o será un sistema de acceso directo (interno)?

---

## Open Questions

1. **¿Hay un logo de JWDIESEL** que pueda usar, o debo generar uno?
2. **Bancos**: En la imagen de la letra aparecen: Continental, Wiese Sudameris, Interbank, Pichincha, Cartera, MiBanco, Interamericano, Scotiabank. ¿Debo crear un catálogo de bancos o se ingresa como texto libre?
3. **Monedas**: ¿El sistema manejará solo USD o también PEN (Soles)?
4. **¿Quieres que el sistema actualice automáticamente** el estado de letras vencidas mediante un cron job o solo visualmente al abrir la página?

---

## Verification Plan

### Automated Tests
```bash
# Verificar que PHP no tenga errores de sintaxis
php -l index.php
php -l config/conexion.php
php -l controllers/DashboardController.php
# ... para cada archivo PHP

# Verificar que la base de datos se crea correctamente
mysql -u root -e "SOURCE sql/zlets_db.sql"
```

### Manual Verification
- Abrir `http://localhost/zlets/` y verificar el dashboard con gráficos
- Registrar un lote de letras y verificar que se guardan correctamente
- Verificar que las alertas Toast aparecen para letras próximas a vencer
- Generar reporte filtrado y verificar que la fecha de pago (+8 días) aparece en negrita
- Exportar a PDF y Excel y verificar formato
- Verificar diseño responsive y glassmorphism
