# Sprint 5 y 6 · Reportes, Configuración, Perfiles y Automatización

**ZIP:** `facturaos_sprint5.zip`
**Archivos nuevos:** 20
**Acumulado total:** 68 archivos PHP + vistas + migraciones

---

## Qué resuelve este sprint

El cierre completo del sistema: el contador tiene los reportes para la D-104, el gerente puede configurar todo desde la UI, los permisos se editan visualmente, y el sistema opera solo vía scheduler.

---

## Pendientes estructurales cerrados

| # | Archivo | Problema resuelto |
|---|---|---|
| 1 | `StockInsuficienteException.php` | Referenciada en `StockService` — ahora existe |
| 2 | `Models/Sistema.php` | Modelos `Auditoria` y `CierreDia` con helper `registrar()` |
| 3 | `errors/403.blade.php` | Vista de acceso denegado referenciada en `bootstrap/app.php` |
| 4 | `DocumentoDetalle.php` + vista | Ruta `documentos.detalle` tenía componente faltante |
| 5 | `web.php` reescrito | Agrega rutas `factura.nota-credito`, imports completos |
| 6 | `Auditoria::registrar()` | Helper estático para loguear acciones desde cualquier punto |
| 7 | `routes/console.php` | Scheduler completo del sistema |

---

## Sprint 5 · Reportes, Configuración y Perfiles

### `app/Services/Reportes/ReporteVentasService.php`

**Qué hace:** Genera el Excel de ventas en formato compatible con la D-104.

**Estructura del Excel:**

**Pestaña 1 · Detalle comprobantes (20 columnas):**
Fecha, consecutivo, tipo, clave Hacienda, cédula receptor, nombre receptor, condición, subtotal bruto, descuentos, base 13%, IVA 13%, base 4%, IVA 4%, IVA 4% con devolución, IVA 4% sin devolución, base 2%, IVA 2%, total IVA, devolución IVA, total comprobante.

**Pestaña 2 · Resumen D-104:**
Totales agrupados por tarifa con el cálculo de IVA neto a declarar (cobrado − devoluciones). Formato visual con colores y totales resaltados.

**Uso desde Livewire:**
```php
app(ReporteVentasService::class)->descargar($empresa_id, '2026-06-01', '2026-06-30');
```

**Métodos estáticos (para el preview en pantalla):**
- `datos(...)` → Collection con todos los comprobantes del período
- `resumenD104(...)` → array con totales por tarifa

**Requiere:** `composer require maatwebsite/excel`

---

### `app/Services/Reportes/ReporteGastosService.php`

**Qué hace:** Genera el Excel de gastos con crédito fiscal para D-104.

**Estructura del Excel:**

**Pestaña 1 · Detalle gastos (13 columnas):**
Fecha, tipo, consecutivo, clave Hacienda, cédula proveedor, nombre, categoría, condición, total, IVA pagado, IVA acreditable, IVA no acreditable, estado Hacienda.

**Pestaña 2 · Crédito fiscal D-104:**
Total gastos por categoría + IVA pagado total + IVA acreditable (crédito fiscal) + IVA no acreditable. El contador usa este número directamente en la casilla de crédito fiscal.

---

### `app/Livewire/Reportes/ReporteVentas.php` y `ReporteGastos.php`

**Qué hacen:** Componentes con selector de período, accesos rápidos (este mes, mes anterior, trimestre), preview en pantalla de los datos y botón de exportación.

**El preview muestra:**
- KPIs del período (comprobantes, venta neta, IVA, total)
- Tabla resumen por tarifa (para verificar antes de exportar)
- Tabla con los primeros 15 registros (el Excel tiene todos)

**`#[Renderless]`** en el método `exportar()` — necesario en Livewire 3 para que la descarga de archivos funcione correctamente.

---

### `app/Livewire/Configuracion/DatosEmpresa.php`

**Qué hace:** Módulo de configuración con 4 secciones navegables:

**Sección: Datos generales**
- Razón social, nombre comercial, cédula, actividad económica
- Correos de facturación y contabilidad
- Ambiente Hacienda (sandbox/producción)
- Parámetros: plazo de crédito, umbral de ajuste de inventario

**Sección: Certificado digital**
- Upload del `.p12` con validación inmediata del PIN
- Muestra fecha de vencimiento y nombre del titular
- Alerta si está próximo a vencer
- El PIN se cifra con `encrypt()` antes de guardar
- El `.p12` se almacena fuera del webroot con nombre UUID

**Sección: Personalización de documentos**
- Color primario y secundario con picker + input HEX + preview en tiempo real
- Upload de logo
- Nombre y cargo del responsable (firma del PDF)
- Mensaje de footer y términos y condiciones

**Sección: Correo electrónico**
- SMTP: host, puerto, usuario, contraseña (cifrada), cifrado
- Plantillas para FE y NC: asunto y cuerpo con variables `{cliente}`, `{numero}`, etc.
- Firma personalizable del correo
- La contraseña solo se actualiza si se envía una nueva

---

### `app/Livewire/Perfiles/PerfilesIndex.php`

**Qué hace:** Módulo de perfiles de acceso con editor visual de permisos y gestión de usuarios.

**Vista: Perfiles**
- Lista de perfiles con contador de usuarios
- Al seleccionar un perfil, se carga la matriz de permisos
- Matriz: 14 módulos × 6 acciones = 84 permisos por perfil
- Cada celda es un `<select>` con 3 opciones: ✓ Permitido / ✕ Denegado / ⚠ Con aprobación
- Los colores de los selects cambian según el nivel (verde/gris/naranja)
- Botón "Guardar permisos" hace `updateOrCreate` de los 84 permisos

**Vista: Usuarios**
- Listado con perfil, último acceso y estado
- Crear nuevo usuario con validación de email único por empresa
- Editar: puede cambiar nombre, email, perfil y estado
- Activar/desactivar con confirmación (no puede desactivarse a sí mismo)
- La contraseña se hashea con `Hash::make()` — nunca en texto plano

---

## Sprint 6 · Commands y automatización

### `app/Console/Commands/AutomatizacionCommands.php`

**Contiene 4 commands en un archivo:**

**`ActualizarEstadoCxC`** (`facturaos:actualizar-cxc`):
```sql
UPDATE cuentas_por_cobrar
SET estado = 'vencido'
WHERE fecha_vencimiento < TODAY()
  AND estado IN ('pendiente', 'parcial')
```
Una sola query, cero loops en PHP.

**`ActualizarEstadoCxP`** (`facturaos:actualizar-cxp`):
Mismo patrón para proveedores.

**`ProcesarColaHacienda`** (`facturaos:cola-hacienda`):
Consulta `hacienda_cola` buscando pendientes con `proximo_intento <= now()` y despacha `EnviarFacturaHacienda` por cada uno.

**`SincronizarCabys`** (`facturaos:sincronizar-cabys`):
Descarga el catálogo desde `https://api.hacienda.go.cr/fe/cabys`. Soporta paginación para traer los ~15,000 registros. Usa `--todas` para sincronización completa. Por defecto solo la primera página.

---

### `app/Jobs/NotificarStockMinimo.php`

**Qué hace:** Envía un correo HTML al email de contabilidad con la lista de productos bajo mínimo.

**Cuándo se despacha:** Desde `StockService::salida()` cuando el stock resultante ≤ `stock_minimo`. Se despacha una sola vez por empresa (no por producto individual).

**El correo incluye:**
- Tabla con producto, bodega, stock actual y mínimo configurado
- Diseño HTML con tabla formateada

---

### `routes/console.php` — Scheduler completo

```
23:55  →  facturaos:cierre-dia
00:05  →  facturaos:actualizar-cxc
00:06  →  facturaos:actualizar-cxp
*/15   →  facturaos:cola-hacienda  (07:00-22:00)
06:00  →  hacienda:sincronizar-xml
dom 01 →  facturaos:sincronizar-cabys
*/15   →  queue:monitor
```

**Configurar en cPanel:**
```bash
* * * * * cd /home/USUARIO/public_html && php artisan schedule:run >> /dev/null 2>&1
```

**Configurar Supervisor para el queue worker:**
```ini
[program:facturaos-worker]
command=php /home/USUARIO/public_html/artisan queue:work --tries=5 --timeout=60
autostart=true
autorestart=true
```

---

## Comandos de instalación completa

```bash
# 1. Clonar / descomprimir el proyecto
cd /home/USUARIO/public_html

# 2. Instalar dependencias
composer install --no-dev --optimize-autoloader
composer require livewire/livewire barryvdh/laravel-dompdf maatwebsite/excel

# 3. Configurar entorno
cp .env.example .env
php artisan key:generate

# 4. Migrar y sembrar
php artisan migrate
php artisan db:seed

# 5. Sincronizar catálogo CABYS (primera vez)
php artisan facturaos:sincronizar-cabys --todas

# 6. Descargar XSD de Hacienda
mkdir -p storage/app/xsd
# Descargar de https://www.hacienda.go.cr/ATV/ComprobanteElectronico/docs/esquemas/
# y colocar los .xsd en storage/app/xsd/

# 7. Permisos de storage
chmod -R 775 storage bootstrap/cache

# 8. Configurar cron (ver arriba)
# 9. Iniciar queue worker con Supervisor (ver arriba)
# 10. Acceder: https://tudominio.cr/
#     Login: admin@clinicavida.cr / Admin1234!
```

---

## Estado final del sistema

| Sprint | Contenido | Estado |
|---|---|---|
| Sprint 1 | Núcleo fiscal, Auth, Nueva factura | ✅ |
| Sprint 2 | Documentos, PDF, Ticket, Correo | ✅ |
| Sprint 3 | CxC, CxP, Gastos XML, XmlParser | ✅ |
| Sprint 4 | Dashboard, Caja, Inventario, REP | ✅ |
| Sprint 5 | Reportes, Configuración, Perfiles | ✅ |
| Sprint 6 | Commands, Scheduler, Automatización | ✅ |
| Estructurales | Exception, modelos, 403, detalle | ✅ |