2026-09-22 — Saldo retirable, estadísticas históricas y anuncios recurrentes

Para las aplicaciones móviles (clientes y cisterneros) y el panel administrativo.

Summary

Esta actualización introduce mejoras clave en las finanzas de los conductores, la consistencia de métricas históricas y la gestión de comunicaciones en la plataforma:

1. Retenciones por deuda en efectivo: Se garantiza que un conductor con comisiones en efectivo pendientes no pueda retirar balance acumulado sin antes cubrir su deuda física.
2. Ganancias acumuladas reales: En las estadísticas históricas de los conductores (/drivers/me/stats), la métrica allTime.earningsUSD ahora se calcula directamente sobre la suma histórica de ganancias recibidas en pedidos completados, desacoplándola de la billetera y de los retiros efectuados.
3. Desglose financiero consistente: En los recibos contables de órdenes, la comisión de la plataforma se calcula sobre el precio base del servicio (base_price_usd), garantizando total coherencia con el modelo de comisiones y el fondo solidario.
4. Anuncios y avisos recurrentes: El módulo de anuncios (/api/v1/admin/announcements) ahora permite programar envíos periódicos (diarios, semanales o mensuales) con control de fecha límite (recurrence_end_at), despachados automáticamente por el programador de tareas y recibidos en el inbox de notificaciones móviles.

Changes

1. Billetera y saldo retirable (GET /wallet/me)

El campo withdrawableUSD en GET /api/v1/wallet/me aplica la fórmula:

$$\text{withdrawableUSD} = \max(0, \text{balanceUSD} - \text{pendingPayoutUSD} - \text{cashDebtUSD})$$

• Si la deuda en efectivo supera el balance disponible neto de retiros pendientes, el monto retirable será $0.00.
• Los conductores no pueden solicitar un pago (POST /wallet/me/payouts) por un monto superior a withdrawableUSD.

Ver Wallet y Business logic → Driver wallet & cash debt.

2. Estadísticas de conductor (GET /drivers/me/stats y GET /driver/stats)

• Se corrigió el cálculo de allTime.earningsUSD: anteriormente utilizaba el balance actual de la billetera o métricas de corto plazo; ahora agrega la suma histórica de driver_receives de todas las órdenes entregadas.
• Los retiros o transferencias ya no reducen esta métrica histórica de rendimiento laboral.
• El recibo de conductor GET /api/v1/driver/orders/{orderId}/receipt ahora expone formalmente el aporte solidario gemelo de Agüita (aguita_solidary_usd).

Ver Drivers.

3. Desglose contable y comisiones en órdenes

• En GET /api/v1/orders/{orderId}/receipt y GET /api/v1/driver/orders/{orderId}/receipt, la comisión de Agüita (aguita_commission_usd) se aplica sobre el monto base (base_price_usd).
• Se mantiene la compatibilidad con el fondo de solidaridad y el cálculo inverso en contraofertas de conductores.

Ver Orders y Modelo de Distribución de Ingresos.

4. Avisos y anuncios administrativos recurrentes

Nuevos campos y capacidades en POST /api/v1/admin/announcements y en la tabla de anuncios:

• Los anuncios programados y recurrentes son procesados de manera desatendida mediante ProcessScheduledAnnouncements cada minuto.
• Cada instancia enviada genera notificaciones push (FCM) y se almacena en el inbox de notificaciones de las aplicaciones móviles bajo el tipo announcement.

Ver Admin announcements y Notifications.