# Changelog - Sistema de Gestión Ozado

## [2.2.0] - 2026-02-04

### Estado: ✅ VERSIÓN ESTABLE

### Resumen
Implementación completa del modelo financiero Opción 1 (Cliente como HUB) con:
- Adelantos (anticipos) de clientes
- Aplicación de adelantos a receivables
- Estado de cuenta calculado en tiempo real
- Integración completa en ficha del cliente

---

### Nuevas Funcionalidades

#### Módulo de Adelantos (FASE A + B)
- **Registro de adelantos**: Fecha, monto, moneda, método, referencia, comprobante (Drive URL)
- **Listado en ficha cliente**: Tab "Adelantos" con columnas Fecha, Monto, Aplicado, Disponible, Estado
- **Aplicación a documentos**: Modal para seleccionar receivable y monto a aplicar
- **Historial de aplicaciones**: Botón "Historial" para ver detalle de aplicaciones por adelanto
- **Estados automáticos**: `available` → `applied` cuando se consume completamente

#### Modelo Financiero (Opción 1)
- **Tabla `advances`**: Adelantos de clientes con status y applied_amount
- **Tabla `advance_allocations`**: Aplicaciones de adelantos a receivables
- **Tabla `payments`**: Pagos de clientes (estructura lista, UI parcial)
- **Tabla `payment_allocations`**: Aplicaciones de pagos a receivables
- **Cálculo de saldos**: `balance = total - pagos_aplicados - adelantos_aplicados`
- **Estado de cuenta**: Reporte calculado desde receivables (no tabla adicional)

#### Ficha del Cliente Mejorada
- **Tab "Documentos"**: Muestra receivables con Total | Pagado | Saldo | Estado
- **Tab "Adelantos"**: CRUD completo con aplicación a documentos
- **Tab "Estado de cuenta"**: KPIs consolidados (Total facturado, Pagado, Pendiente, Adelantos disponibles)
- **Tab "Pagos"**: Registro y listado de pagos (aplicación similar a adelantos)

---

### Mejoras Técnicas

#### Consistencia y Seguridad
- **Transacciones DB**: `apply_advance_to_receivable` usa BEGIN/COMMIT/ROLLBACK
- **Bloqueo optimista**: `SELECT ... FOR UPDATE` para prevenir condiciones de carrera
- **Protección doble submit**: JavaScript deshabilita botón submit tras primer click
- **Validaciones backend**:
  - `amount > 0`
  - `amount <= saldo_adelanto`
  - `amount <= saldo_documento`
  - `receivable.client_id == advance.client_id`

#### Servicios Creados
- `app/services/payments_service.php`: Gestión de pagos y cálculo de balances
- `app/services/advances_service.php`: Gestión de adelantos y aplicaciones

#### Endpoints API
- `public/api/advances.php`: create_advance, apply_advance
- `public/api/payments.php`: create_payment, apply_payment

---

### Archivos Modificados

| Archivo | Cambios |
|---------|---------|
| `public/client_view.php` | Tabs Documentos, Pagos, Adelantos, Estado de cuenta mejorados |
| `app/db/schema.php` | Definiciones de payments, payment_allocations |
| `app/services/advances_service.php` | Transacciones y validaciones mejoradas |
| `docs/db_audit_report.md` | Actualizado a v2.1 con estado completo |

---

### Checklist de Pruebas Funcionales

- [x] Crear adelanto PEN y USD
- [x] Validaciones: monto requerido, fecha requerida
- [x] Listado con saldo disponible correcto
- [x] Link comprobante abre en nueva pestaña
- [x] Estado inicial: "Disponible"
- [x] Aplicar parcial y verificar saldo
- [x] Aplicar total y verificar status "Aplicado"
- [x] Impedir sobre-aplicar (error si monto > saldo)
- [x] Aplicar a 2 documentos distintos
- [x] Historial muestra aplicaciones correctas
- [x] Tab Documentos muestra Pagado/Saldo actualizado

---

### Código Legacy Revisado

| Campo | Uso | Estado |
|-------|-----|--------|
| `financial_document_id` | Calendario → Documentos | ✅ En uso |
| `quote_id` | Cotizaciones | ✅ En uso |

---

### Próximos Pasos (v2.3)

1. Completar UI de pagos (similar a adelantos)
2. Dashboard con KPIs de CxC por cliente
3. Reportes de estado de cuenta exportables (PDF)
4. Notificaciones de vencimientos

---

### Notas de Compatibilidad

- Compatible con datos existentes (migraciones no destructivas)
- `financial_documents` se mantiene para documentos SUNAT formales
- `receivables` es la fuente principal de CxC

---

**Backup recomendado antes de continuar con nuevos cambios.**