Flujo de Datos y Arquitectura de Comunicaciones

Flujo de Datos y Arquitectura de Comunicaciones

Esta sección describe cómo fluye la información entre el cliente web, la API REST, la base de datos y los servicios secundarios en uunit9.

Arquitectura Global

• Frontend SPA (apps/platform): Servido por Vite en puerto 5175. Redirecciona solicitudes /api/* mediante un proxy configurado en apps/platform/vite.config.ts hacia el servidor backend.
• Backend API (apps/api): Servidor Hono/Nitro escuchando en el puerto 3001 (prefijo /api). Maneja autenticación vía Better Auth, sesión multi-tenant con orgId, endpoints de negocio y WebSocket/Bot Telegram.
• Base de Datos PostgreSQL: Escuchando en el puerto 5433 (uunit9), accedida vía Drizzle ORM.
• Servicios Secundarios:
  • Redis: Caché y estado de tareas.
  • Scheduler (scheduler.ts): Procesos cron internos (alertas de stock, limpiezas).
  • Bot de Telegram (bot.ts): Interacción y notificaciones HITL (Human-in-the-loop).
  • Ollama: Motor local de modelos de lenguaje (LLM) opcional para el asistente virtual.

Arquitectura Multi-Sucursal, Multi-Estación y Scopes de Rol

El sistema utiliza un esquema jerárquico de control de acceso y separación física de datos en 3 niveles:

$$\text{1 Organización (Tenant Empresa)} \longrightarrow \text{N Sucursales (Ubicaciones Físicas)} \longrightarrow \text{N Estaciones (Áreas de Producción)}$$

1. Entidades Principales

• Organización (organization): Dueña del catálogo maestro de menú, proveedores y configuración global del negocio.
• Sucursales (branches): Representan locales o ubicaciones físicas físicas independientes (ej: Sucursal Roma, Sucursal Polanco).
• Estaciones (stations): Áreas de preparación física dentro de una sucursal (ej: Barra, Cocina Caliente, Sushi Bar).

2. Matriz de Roles con Scopes

Los miembros de la organización (member) reciben permisos operativos acotados por ámbito (scope):

$$\text{Perfil de Personal} = { \text{userId}, \text{orgId}, \text{branchId}, \text{role}, \text{stationId} }$$

• branchId: Limita el acceso a comandas, cajas y mesas de una sucursal específica (o null para acceso global).
• stationId: En el rol de cocina / producción, restringe las comandas visibles en la pantalla KDS (/estaciones) únicamente a las partidas pertenecientes a su área de trabajo.

3. Matriz de Menú por Sucursal (menu_item_branch_overrides)

Permite que los platillos del catálogo maestro central tengan:

• Disponibilidad por sucursal (active).
• Precios diferenciados por zona (priceOverride).
• Enrutamiento a la estación de producción específica de la sucursal (stationId).

Diagrama de Secuencia: Creación y Cobro de Orden POS

sequenceDiagram
    autonumber
    actor C as Cajero / Mesero
    participant W as Web SPA (:5175)
    participant A as Hono API (:3001)
    participant D as DB Postgres (:5433)
    participant S as Scheduler / KDS

    C->>W: Selecciona mesa / Abre orden
    W->>A: POST /api/pos/orders (openOrderInput)
    A->>D: INSERT INTO orders (status: 'draft')
    D-->>A: Order Record
    A-->>W: 201 Created (Order)

    C->>W: Agrega platillos y modificadores
    W->>A: POST /api/pos/orders/:id/items (addOrderItemInput)
    A->>D: INSERT INTO order_items & recalc totals
    D-->>A: Item registrado
    A-->>W: 200 OK

    C->>W: Envía a cocina
    W->>A: POST /api/pos/orders/:id/send
    A->>D: UPDATE orders SET status = 'sent', update items
    A->>S: Notifica estación KDS
    A-->>W: 200 OK (Sent)

    C->>W: Registra pago
    W->>A: POST /api/pos/orders/:id/payments (paymentInput)
    A->>D: INSERT INTO payments & UPDATE orders status = 'paid'
    D-->>A: Payment Record
    A-->>W: 200 OK (Paid)