Saltar al contenido principal

Módulo de Gastos y Facturación

Este documento define la arquitectura y el modelo de negocio para el procesamiento de egresos en la plataforma Yuruary. El sistema sigue un modelo de Máquina de Estados atado a ciclos mensuales de facturación.

1. El Flujo de Negocio (Explicado Simple)​

Para entender cómo fluye el dinero y la deuda en el sistema, debemos separar los conceptos:

  1. El Proveedor (Supplier): Es la empresa o técnico que presta el servicio (ej. "Ascensores Schindler"). Se registra una sola vez en el Directorio de Proveedores.
  2. El Gasto (Expense): Es la factura física que entrega el proveedor (ej. "Mantenimiento preventivo - $100").
  3. El Periodo de Facturación (Billing Period): Es la "caja" que agrupa todos los gastos de un mes específico.
  4. La Distribución (Distribution): Es el proceso matemático donde agarramos los $100 del gasto y los dividimos en "cuentas por pagar" pequeñitas para cada residente, según su Alícuota.

Diagrama del Ciclo de Vida del Mes (Billing Period)​

2. Tipos de Distribución (distribution_scope)​

Cuando un gasto se registra, el administrador debe definir a quién se le va a cobrar. El backend procesa esto de tres formas:

  • GLOBAL (Gastos Comunes): Se divide el total entre todas las unidades del condominio usando la Alícuota General.
  • SECTOR (Gastos Sectorizados): Se divide el total solo entre las unidades de una Torre/Agrupación específica, usando la Alícuota de Torre.
  • UNIT_DIRECT (Gastos Individuales): Se cobra un monto directamente a una o varias unidades específicas, ignorando la alícuota (Ej. Reparación de una filtración interna, o reserva de área común).

3. Contrato de API (Internal API - Staff)​

Nota para Backend: Estos endpoints deben respetarse estrictamente para que el Frontend (Desktop Client) funcione correctamente de forma atómica.

Dominio: Proveedores (/internal/suppliers)​

Mantener los proveedores como un CRUD independiente.

  • GET /internal/suppliers - Lista proveedores (Buscador).
  • POST /internal/suppliers - Registra un nuevo proveedor.

Dominio: Gastos (/internal/expenses)​

El gasto se conecta con el proveedor y define su alcance.

Crear Gasto (POST /internal/expenses)

// Request Body
{
  "supplier_id": "uuid-1234",
  "billing_period_id": "uuid-5678",
  "amount": 150.50,
  "currency": "USD",
  "description": "Mantenimiento de ascensor",
  "distribution_scope": "GLOBAL", // Enum: GLOBAL, SECTOR, UNIT_DIRECT
  "target_id": null, // Solo requerido si es SECTOR (envía sector_id) o UNIT_DIRECT (array de unit_ids)
  "auto_distribute": true // Si es true, el backend ejecuta la matemática en este mismo endpoint.
}

Dominio: Facturación y Periodos (/internal/billing)​

Controla el estado del mes. Solo un usuario con rol MANAGER o superior debe tener acceso a estas rutas.

  • POST /internal/billing/open-period - Abre un nuevo mes.
  • POST /internal/billing/generate-preliminary - Bloquea la carga de gastos y genera el reporte PDF de revisión.
  • POST /internal/billing/close-period - Cierra el mes, genera la deuda formal a los residentes y dispara notificaciones.