# Plan Maestro de Desarrollo: Sistema de Gestión de Inventario, Ventas y Control Financiero Multimoneda (Loha Inventario)

Basado en el análisis técnico de [Documentación del sistema.txt](file:///c:/Users/Brayh/OneDrive/Documentos/PROYECTOS/Loha-inventario/docs/Documentaci%C3%B3n%20del%20sistema.txt) y las decisiones acordadas para la arquitectura:

* **Servidor de Producción / Staging:** Servidor Debian (Nginx + PHP 8.2/8.3 + PostgreSQL 13 + Redis opcional). Sin necesidad de Node.js en el servidor.
* **Backend y Arquitectura:** Laravel 11+ (Monolito modular con Servicios de Dominio DDD).
* **Base de Datos:** PostgreSQL 13 (garantizando compatibilidad total con la versión existente del servidor).
* **Frontend:** Laravel Livewire 3 + Alpine.js + Tailwind CSS (interfaz altamente dinámica y reactiva sin recargas de página, 100% nativa de PHP).
* **Proveedor de Tasas:** DolarApi (`ve.dolarapi.com` para BCV y Paralelo/Oficial) + adaptadores para TRM/COP con capa de caché y fallback resiliente.
* **Ámbito:** Gestión y control administrativo interno propio (sin facturación fiscal por ahora).
* **Despliegue:** Proyecto único estándar de Laravel, compatible con cualquier servidor Debian vía PHP y Composer.

---

## 1. Decisiones Críticas de Arquitectura e Ingeniería

### 1.1 Moneda Funcional y Precisión Numérica
* **Moneda Base/Contable:** `USDT` (Dólar digital). Todos los costos y valoraciones de inventario y utilidades se expresan y auditan en USDT.
* **Monedas Transaccionales:** `VES` (Bolívares), `COP` (Pesos Colombianos), `USD` (Dólar efectivo) y `USDT`.
* **Tipos de Datos SQL (Compatibles con PostgreSQL 13):**
  * Tasas de cambio y montos USDT: `NUMERIC(18, 6)`
  * Montos en VES y COP: `NUMERIC(18, 2)`
  * Cantidades de inventario: `NUMERIC(12, 4)` (permite unidades enteras o fraccionables).
* **Política de Redondeo:** Redondeo bancario (*Half-to-even*) aplicado únicamente en la capa de presentación y liquidación final. Cálculos intermedios conservan precisión completa.

### 1.2 Inmutabilidad y Snapshotting Deliberado
* Ninguna transacción histórica (venta, compra, gasto, distribución) dependerá de una tasa de cambio o costo de lote "en vivo".
* Cada fila transaccional registrará copias de los valores numéricos vigentes en el instante $T$:
  * Tasa de cambio BCV / Paralelo / TRM aplicada.
  * Costo unitario en USDT del lote consumido.
  * Porcentaje accionario de cada socio al momento de la distribución.

### 1.3 Modelo FIFO Real (Primeras Entradas, Primeras Salidas)
* Cada ingreso de mercancía crea un registro en `inventory_lots` con su costo unitario en USDT y tasa congelada.
* Cada ítem vendido (`sale_items`) consume de uno o varios lotes mediante la tabla de enlace `sale_item_lot_consumptions`, guardando la cantidad extraída y el `unit_cost_usdt` en ese instante.

### 1.4 Concurrencia y No-Negatividad
* Bloqueo pesimista (`SELECT ... FOR UPDATE`) sobre la fila de saldo de stock (`stock_summaries`) durante la transacción de venta.
* Restricción de integridad en base de datos: `CHECK (quantity >= 0)` en `stock_summaries` y `CHECK (available_quantity >= 0)` en `inventory_lots`.

### 1.5 Arquitectura de Monolito Modular con Livewire 3
* **Capa de Dominio y Servicios (Backend):**
  * Servicios puros (`PricingService`, `ProfitCalculatorService`) aislados para testing sin base de datos.
  * Orquestadores transaccionales (`SalesService`, `PurchaseService`, `InventoryValuationService`).
  * Ingestor de tasas con colas / cron jobs e idempotencia.
* **Capa de Presentación Reactiva (Livewire 3 + Alpine.js):**
  * Componentes Full-Stack reactivos en tiempo real sin recarga de página:
    * `DashboardLivewire`: Métricas ejecutivas, valoración de inventario en USDT y utilidades en tiempo real.
    * `PosTerminalLivewire`: Punto de venta rápido con búsqueda instantánea y conmutador de monedas (USDT, VES, COP, USD).
    * `InventoryManagerLivewire`: Control de variantes de productos, lotes y niveles de stock.
    * `CashRegisterLivewire`: Arqueo multimoneda y movimientos de caja.
  * Cero requerimientos de Node.js en el servidor de producción.

---

## 2. Roadmap de Desarrollo por Fases

### Fase 0: Configuración de Entorno Local y Fundamentos Técnicos
*Objetivo: Dejar listos los cimientos del monolito Laravel y la base de datos PostgreSQL 13.*

1. **Estructura del Proyecto**:
   - Proyecto unificado de Laravel 11+ con Livewire 3 y Tailwind CSS.
2. **Entorno de Ejecución Local**:
   - Configuración de PHP 8.3 y Composer local o contenedorizado.
   - Conexión con instancia local de PostgreSQL (configurado para compatibilidad PG13).
   - Variables de entorno `.env` con credenciales de base de datos y llaves de cifrado.
3. **Estándares Financieros Base**:
   - Creación de helpers / Value Objects matemáticos con `bcmath` para evitar imprecisiones de coma flotante.
   - Middleware de manejo de errores uniforme en formato JSON.

---

### Fase 1: Núcleo de Catálogo, Almacenes, Lotes y Kardex FIFO
*Objetivo: Modelar productos con variantes flexibles, múltiples depósitos (VE / CO) y el motor de costos por lotes.*

1. **Catálogo de Productos Flexible (EAV)**:
   - Tablas: `categories`, `products`, `attributes`, `attribute_values`, `product_variants`.
   - `product_variants`: `sku` único a nivel DB (`UNIQUE`), código de barras, precio sugerido USDT.
2. **Depósitos y Almacenes**:
   - `locations`: Depósitos físicos (Caracas, Cúcuta, etc.).
3. **Lotes de Inventario (`inventory_lots`)**:
   - `id`, `product_variant_id`, `location_id`, `purchase_id`, `initial_quantity`, `available_quantity`, `unit_cost_usdt`, `exchange_rate_used`, `status`.
   - Constraint: `CHECK (available_quantity >= 0)`.
4. **Consumos de Lotes (`sale_item_lot_consumptions`)**:
   - `id`, `sale_item_id`, `inventory_lot_id`, `quantity`, `unit_cost_usdt`.
5. **Kardex y Saldo Corriente**:
   - `inventory_movements`: Kardex inmutable.
   - `stock_summaries`: Saldo corriente por `(product_variant_id, location_id)` con `CHECK (quantity >= 0)`.
6. **Servicio `InventoryValuationService`**:
   - Consumo FIFO por lotes y cálculo de costo ponderado real de salida.
   - Pruebas unitarias de consumo de múltiples lotes.

---

### Fase 2: Ingestión de Tasas (DolarApi), Motor de Precios y Ventas Concurrente
*Objetivo: Tasas automáticas con DolarApi, cálculo puro de precios y procesamiento de ventas atómico.*

1. **Ingestión de Tasas con DolarApi (`ExchangeRateIngestionService`)**:
   - Integración con endpoints de `ve.dolarapi.com` (Oficial BCV y Paralelo/USDT).
   - Adaptador para TRM Colombia (COP/USD).
   - Tolerancia a fallos: reintentos con backoff, almacenamiento en caché y fallback a la última tasa válida (`last_valid_rate`).
2. **Servicio Puro `PricingService`**:
   - Cálculo libre de efectos secundarios: USDT $\rightarrow$ VES (a tasa BCV o Paralelo) $\rightarrow$ COP.
3. **Orquestación de Ventas (`SalesService`)**:
   - Transacción atómica con `SELECT ... FOR UPDATE` sobre `stock_summaries` y `inventory_lots`.
   - Snapshot directo de tasas y costos en `sales` y `sale_items`.
   - Ciclo de vida de la venta (`completed`, `cancelled`) con reversión controlada de stock.
4. **Tests de Concurrencia e Inmutabilidad**:
   - Pruebas de ventas simultáneas para certificar cero sobreventas.
   - Prueba de regresión de inmutabilidad de tasas históricas.

---

### Fase 3: Tesorería Multimoneda, Gastos y Utilidad Operativa Real
*Objetivo: Control de flujos en cajas/cuentas y cálculo de utilidad neta real en USDT.*

1. **Cajas y Cuentas (`cash_accounts`, `cash_movements`)**:
   - Cajas físicas y cuentas digitales (Efectivo VES, COP, USD, Cuentas Bancarias, Wallet USDT Binance).
2. **Compras y Gastos Operativos**:
   - `purchases` vinculadas a la creación de lotes.
   - `expenses` operativos con snapshot de tasa a USDT.
3. **Conversiones y Arbitraje Cambiario (`currency_conversions`)**:
   - Registro de intercambios (ej. VES a USDT vía P2P) y registro de ganancias/pérdidas por diferencia cambiaria real.
4. **Motor de Utilidad `ProfitService`**:
   - Margen bruto por venta y utilidad neta en USDT.

---

### Fase 4: Estructura Societaria y Distribución de Utilidades
*Objetivo: Gestión de socios, aportes de capital y repartición auditable de utilidades.*

1. **Socios y Aportes (`partners`, `partner_capital_contributions`)**.
2. **Distribución de Utilidades (`profit_distributions`)**:
   - Snapshot del `% de participación del socio` en la fecha de corte.
   - Registro de retiros (`partner_withdrawals`).
3. **Permisos y Seguridad**:
   - Roles con `spatie/laravel-permission` (`Admin`, `Socio`, `Vendedor`, `Almacén`).

---

### Fase 5: Interfaz Dinámica con Livewire 3 + Alpine.js y Reportes Gerenciales
*Objetivo: Desarrollar una interfaz de usuario visualmente impresionante, fluida, responsiva y altamente dinámica sin dependencias de Node en el servidor.*

1. **Diseño y Experiencia de Usuario (UI/UX)**:
   - Paleta de colores curada y armónica (Slate/Zinc oscuro elegante con acentos esmeralda y violeta).
   - Componentes dinámicos con micro-animaciones interactivas (Alpine.js).
   - Tipografía moderna (Outfit / Inter) y diseño responsivo móvil/escritorio.
2. **Componentes Livewire del Sistema**:
   - **Dashboard Ejecutivo (`DashboardLivewire`):** KPIs en tiempo real (Valoración total de inventario en USDT, Ventas del día desglosadas por moneda, Utilidad acumulada, Gráficos interactivos).
   - **Punto de Venta (`PosTerminalLivewire`):** Selector rápido de productos por SKU/código de barras, conmutador de moneda en vivo (USDT / VES / COP / USD), cálculo instantáneo de vueltos multimoneda sin recargar página.
   - **Gestor de Inventario & Lotes (`InventoryManagerLivewire`):** Visualización reactiva de stock corriente, detalle de lotes por almacén y semáforo de existencias mínimas.
   - **Control de Cajas (`CashRegisterLivewire`):** Arqueo rápido multimoneda y transferencias entre cuentas.
   - **Distribución de Socios (`PartnerDividendsLivewire`):** Panel interactivo de utilidades y retiros por socio.

---

### Fase 6: Resiliencia, Backups y Preparación a Producción
*Objetivo: Respaldos automáticos, preparación de despliegue al servidor VPS con PostgreSQL 13.*

1. **Estrategia de Respaldos**:
   - Script de backup de PostgreSQL 13 automatizado y verificado.
2. **Telemetría y Registro de Errores**:
   - Configuración de logs estructurados y preparación para Sentry en producción.
3. **Migración de Datos y Seeders Iniciales**:
   - Carga inicial de categorías, productos de muestra, tipos de cambio iniciales y usuarios administradores.