# XPERT Billing

Motor de tarifario y facturación para operaciones de depósito, pensado desde
el día uno como **producto independiente** — no un módulo dentro de un WMS.
Se conecta a uno o más WMS externos (el primero: `xpert-3pl`) consultando un
endpoint de exportación de solo lectura, nunca compartiendo base de datos.

Este repo es un **esqueleto**: arranca, tiene login, y una tabla vacía de
empresas cliente. El motor de cálculo de tarifas, la generación de facturas,
y la sincronización contra xpert-3pl **todavía no están implementados**.

## Por qué existe separado

Ver la memoria del proyecto (`project_xpert3pl_billing_module_design.md`) para
el análisis completo. En resumen:

1. **Cumplimiento tributario** (Facturación Electrónica Paraguay / SIFEN-SET)
   es un dominio regulatorio propio, con su propio ritmo de cambios — no debe
   acoplarse al ciclo de vida de un WMS.
2. **Empaquetado comercial**: algunos clientes solo quieren el WMS + reportes
   y facturan con su propio sistema contable; otros van a pagar por la
   emisión completa. Un producto separado se vende/activa como SKU propio.
3. **Reutilización futura**: bien desacoplado, podría venderse a operadores
   3PL que no usan XPERT como WMS.

## Stack

Igual que xpert-3pl / wms-app-comfar a propósito (mismo patrón ya probado,
nada nuevo que aprender): PHP plano sin framework, MySQL vía PDO, SPA de un
solo archivo en JS vanilla, autenticación JWT propia.

## Modelos de cobro que el tarifario (`billing_rules`) contempla

- **Almacenaje**: por pallet/día, por m³/día, por ubicación(bin)/día, por unidad/día.
- **Manipulación**: por unidad recibida/pickeada/empacada/despachada, por línea/pedido.
- **Mínimo garantizado**: cargo fijo mensual.
- **Custom**: para acuerdos que no entran en las categorías anteriores.

Un contrato real de cliente es casi siempre una combinación de varias filas
vigentes por período (`valid_from`/`valid_to`).

## Cómo se integraría con un WMS (diseño, no construido)

xpert-3pl (o cualquier otro WMS conectado) expondría `GET /api/billing-export/events`
protegido con una API key propia (mismo patrón que ya usa para integraciones
por empresa: `company_settings.inbound_api_key_enc`, cifrado con `Crypto`).
Este sistema **tira** de esos datos (pull, no push) y calcula todo con su
propio motor — el WMS de origen no necesita saber que este sistema existe.

## Correr en local

1. Crear la base de datos y aplicar `database/migrations/001_schema.sql`.
2. Configurar variables de entorno (`DB_HOST`, `DB_DATABASE`, `DB_USERNAME`,
   `DB_PASSWORD`, `JWT_SECRET`, `ENCRYPTION_KEY`) o editar los defaults en
   `src/config/app.php` (son solo para desarrollo local, cambiar en producción).
3. Crear el usuario admin: `php scripts/create_admin.php admin <password>`.
4. Servir `public/` con Apache/PHP (mismo esquema de vhost que xpert-3pl).

## Qué falta construir (en orden sugerido)

1. CRUD de `billing_rules` (tarifario por empresa) + pantalla.
2. Cliente HTTP que sincroniza `companies_ref` contra el endpoint de
   exportación del WMS conectado.
3. Motor que calcula `billing_events` a partir de los eventos exportados
   (manipuleo primero, es más simple; almacenaje después, necesita snapshots
   periódicos de ocupación).
4. Reporte de costeo exportable (primer entregable con valor real).
5. Generación de facturas (`invoices`/`invoice_lines`) a partir de
   `billing_events` de un período.
6. Si hace falta emitir comprobantes legales: Facturación Electrónica
   Paraguay (SIFEN/SET) — investigar aparte, es su propio proyecto de
   cumplimiento dentro de este.