Arquitectura del ecosistema
Las tres piezas de ElVendedor, la responsabilidad de cada una, el flujo offline-first y quién es la autoridad de cada dato.
ElVendedor no es un programa único: es un ecosistema de tres aplicaciones que se prometen cosas entre sí mediante contratos versionados. Esta página describe qué hace cada pieza, cómo fluye la información cuando no hay internet y qué fuente manda cuando dos datos se contradicen. Léela antes de desplegar un cliente nuevo o de tocar una forma de payload.
Panorama: tres piezas, un contrato
| Pieza | Stack | Rol | Se instala como |
|---|---|---|---|
el-vendedor |
Ionic 8 + Angular 17 + Capacitor 6; PouchDB sobre SQLite | Cliente móvil: POS, inventario, compras, gastos, deudas, lotes, catálogo online, marketplace, licencias y terminal del hub de restaurante | APK de Android (staging y producción) |
el-vendedor-desktop |
Electron 42 + Vite + JavaScript; PouchDB sobre IndexedDB | Cliente escritorio: POS y caja, compras, inventario, facturación fiscal, reportes de cierre y hub LAN de restaurante | Instaladores de Windows y Linux (squirrel, deb, rpm, zip) |
el-vendedor-back |
Laravel 12 + Sanctum + Inertia/Vue 3; SQLite o MySQL | Autoridad: sync v1, licencias, catálogo online, marketplace, backoffice y caja por REST | Servicio PHP detrás de HTTPS |
Los tres comparten lo mismo en la versión de producto 2.1.6:
- protocolo de sincronización
1(cabeceraX-Sync-Version); - contrato de datos
1(contract_versiondel bootstrap); - cabeceras
Authorization,X-Client-App-Versiony, en el pull,X-Client-Entities; - las bases de producción y staging del backend.
La versión de producto, la del protocolo y la del contrato de datos son tres números distintos y se suben por motivos distintos. El detalle está en Compatibilidad de versiones.
Qué hace cada pieza
Cliente móvil
Es el motor operativo del vendedor y la implementación de referencia del producto. Escribe siempre en local y sincroniza después. Además de la operación diaria, es el único cliente que gestiona licencias y trial, que emite invitaciones de vendedor, que administra lotes con vencimiento, y el único que publica catálogo online y marketplace. Como terminal de restaurante, consulta mesas y emite comandos contra el hub del escritorio.
Cliente escritorio
Cubre el mostrador fijo y el trabajo de oficina: caja con arqueo, reportes de cierre imprimibles y facturación fiscal con series, numeración y huella. Es la única pieza que emite y reimprime facturas, y la única que puede ser hub LAN de restaurante: sirve la red del local, arbitra mesas y comandas y no depende de internet para el servicio.
Backend
No reemplaza la operación local: consolida los cambios de varios dispositivos, valida reglas globales, marca conflictos, audita y redistribuye. Es la autoridad de licencias, numeración fiscal y pertenencia de los datos a un negocio.
Flujo offline-first
El principio es que ninguna operación de negocio (vender, comprar, mover inventario, cambiar un precio) espera a la red para darse por hecha.
- Escritura local. La operación se guarda en la base local del dispositivo y
se registra en una cola de salida (
sync_outbox) con unevent_idestable. - Bootstrap. Un equipo nuevo pide
GET /api/v1/sync/bootstrapy recibe contrato, negocio actual, estado de licencia, catálogo de licencia, límites de lote y lista de entidades soportadas. - Pull. El cliente pide los cambios desde su cursor. El formato recomendado
es
v3:<N>, un orden global porserver_versiondel negocio; una instalación nueva arranca env3:0. El formatov2-serialse conserva por compatibilidad. - Push. El cliente envía su cola en lotes con
event_idcomo clave de idempotencia. El servidor respondeaccepted,duplicatesyrejected. - Conflictos. Cuando dos equipos tocan lo mismo o se repite una clave
crítica, el servidor conserva un registro de conflicto y el cliente lo
muestra para que una persona decida (
keep_remote,discard_local,reviewed).
El stock no se sincroniza como valor absoluto. Viaja como eventos discretos (movimientos, ajustes, ventas, compras, mermas) y cada cliente reconstruye su proyección; así dos equipos offline no se sobrescriben el inventario.
El backend no es la fuente del día a día
Si el servidor se cae, el local sigue vendiendo, cobrando y emitiendo. La nube se usa para consolidar, respaldar y reportar; por eso el contrato tolera clientes desconectados durante días.
Quién es la autoridad de cada dato
| Dato | Autoridad | Cómo se propaga |
|---|---|---|
| Negocio, usuarios y roles | Backend | bootstrap.current_business, employees |
| Licencia y vencimiento | Backend | bootstrap.current_business.license y cada business_profile |
| Limpieza de datos del negocio | Backend | data_reset_version; el cliente borra su copia local |
| Catálogo de productos, precios, almacenes y POS | Dueño, desde el cliente | Push de catálogo; el servidor consolida |
| Ventas, compras y gastos | El dispositivo que las crea | Eventos inmutables por push |
| Factura fiscal | Escritorio (emisión) y backend (unicidad) | Push de invoices y pull para el resto |
| Sesión de caja y su arqueo | Backend (REST) con lease del dispositivo que abre | cash-register REST; el servidor arbitra |
| Stock por almacén | Derivado de eventos | Cada cliente lo recalcula al aplicar deltas |
| Plano de salón y comandas | Hub del escritorio | Comandos LAN; la venta se crea al cobrar |
| Catálogo online y marketplace | Backend, alimentado desde el móvil | Entidades catalog_* y marketplace_* |
| Fotos de producto | El dispositivo | No viajan: son locales por equipo |
Hub LAN de restaurante
El escritorio levanta un servidor HTTP y un WebSocket en la red del local
(puerto por defecto 3897) y las terminales móviles se conectan a él. El hub es
la autoridad dentro del WiFi: mesas, comandas, bloqueo de cobro y cierre. El
flujo vivo no pasa por el backend; la nube solo recibe después la venta cerrada.
- Cabeceras del contrato LAN:
AuthorizationyX-Restaurant-Device-Id. - Una comanda abierta no es una venta contable ni descuenta inventario: la
venta nace en
confirm_paymenty el inventario se mueve al cobrar. - El hub controla el bloqueo de cobro para evitar dobles cobros.
El contrato completo y el procedimiento de puesta en marcha están en Red de restaurante.
Licencias y arranque comercial
El backend sustituye al antiguo gestor de licencias. Cada equipo se activa con
un token propio ligado a su device_id, y el estado viaja también por sync: el
móvil revalida cada 12 horas y, sin red, aplica una gracia de 7 días. El gate
de escrituras del push viene apagado por defecto; cuando se enciende, un
negocio sin licencia vigente recibe 403 con error.code = license_invalid en
sync/push.
Activación desde escritorio
El escritorio muestra el estado y el vencimiento de la licencia, pero todavía no tiene flujo de activación propio: la activación y la renovación se gestionan desde la app móvil o el backoffice. Es una decisión de producto pendiente de cerrar, no un defecto del contrato.
Cómo seguir
- El contrato formal de datos está en Sincronización y su operación diaria en Sincronización en producción.
- El mapa de código por repositorio está en Estructura de repositorios.
- El despliegue del servicio central está en Despliegue del backend.
¿Falta algo o encontraste un error?
Ayúdanos a mejorar esta documentación con tu experiencia real.
Escribir a soporte