Depot POS — Visión General
¿Qué es el POS?
El POS (Punto de Venta) de Depot es una aplicación web progresiva (PWA) construida con Next.js 15, desplegada en https://pos.depot.center. Es la aplicación principal del sistema: desde aquí los cajeros registran ventas, los gerentes configuran el negocio, los dueños revisan métricas, y los repartidores gestionan sus entregas.
El POS es multi-sucursal y multi-rol: un mismo negocio puede tener varias sucursales, y cada empleado tiene un rol que define exactamente qué puede ver y hacer.
---
Acceso y autenticación
Cómo entrar
- El usuario entra a
https://pos.depot.center - Clerk gestiona el inicio de sesión (correo/contraseña u OAuth)
- Si el usuario pertenece a una organización Clerk (un negocio), accede directamente al POS
- Si la empresa nunca ha completado el onboarding, es redirigido al Asistente de configuración inicial (
/onboarding)
Sesión de empleado (PIN / QR)
Una vez dentro de la organización, el POS puede requerir que cada empleado se identifique con un PIN de 4 o 6 dígitos (o código QR) antes de operar. Esto es independiente del login de Clerk: es un segundo nivel de autenticación pensado para terminales compartidas.
- La pantalla de bloqueo aparece sobre todo el contenido cuando no hay empleado activo
- El administrador configura el método en Configuración POS → Autenticación (
/settings) - Si
authMethod = "none", no se pide ningún PIN y cualquiera puede usar la terminal
---
Estructura de navegación (Sidebar)
La barra lateral izquierda es colapsable (solo iconos o iconos + texto). Se muestra en todas las pantallas del POS. Los elementos que aparecen dependen del rol del empleado activo y de los módulos habilitados para la empresa.
| Ítem de navegación | URL relativa | Módulo necesario | Permiso requerido |
|---|---|---|---|
| Dashboard | /dashboard | siempre | audit_log:read |
| Nueva venta | /home-products | siempre | orders:create |
| Órdenes | /orders | siempre | orders:read |
| Cajas | /cash-register | enableCashRegister | cash_register:read |
| Clientes | /customers | enableCustomers | customers:read |
| Promociones | /promotions | enablePromotions | promotions:read |
| Cupones | /coupons | enableCoupons | coupons:read |
| Empleados | /employees | siempre | employees:read |
| Logística | /logistics | enableLogistics | logistics:read |
| Producción | /production | enableProduction | inventory:read |
| Bitácora | /audit-log | siempre | audit_log:read |
| Asistente IA | /ai-assistant | siempre (redirige al widget) | ninguno (todos) |
| Sección Catálogo | — | — | articles:read |
| └ Artículos | /articles | — | articles:read |
| └ Categorías | /categories | — | articles:read |
| └ Modificadores | /ingredients | — | articles:read |
| └ Ingredientes de composición | /composition-ingredients | — | articles:read |
| Sección Inventario | — | enableInventory | inventory:read |
| └ Stock general | /inventory | — | — |
| └ Catálogo de ítems | /inventory/items | — | — |
| └ Ajustar stock | /inventory/adjust | — | — |
| └ Transferencias | /inventory/transfers | — | — |
| └ Movimientos | /inventory/movements | — | — |
| Sección Configuración | — | — | settings:read |
| └ POS | /settings | — | — |
| └ Pagos y órdenes | /payment-settings | — | — |
| └ Campos de clientes | /customer-settings | — | — |
| └ Sucursales | /branches | — | — |
| └ Roles y permisos | /roles | — | — |
En la parte inferior del sidebar aparece el avatar del empleado activo o del usuario Clerk con opciones para cerrar sesión.
---
Selector de sucursal
En la parte superior del header aparece un selector de sucursal. Al cambiar de sucursal:
- Se recarga la configuración de POS y órdenes aplicada a esa sucursal
- Las órdenes y el inventario se filtran a esa sucursal
- Si el empleado activo no está asignado a la sucursal seleccionada, aparece un aviso de advertencia en la pantalla de venta
Los empleados con roles owner o admin pueden acceder a todas las sucursales. Otros roles solo ven las que tienen asignadas.
---
Multi-tenancy
Cada empresa está aislada por companyId (UUID). Todos los datos, configuraciones, empleados, artículos y órdenes pertenecen a un companyId específico. No hay cruce de datos entre empresas.
---
Modos de operación
El POS está diseñado para usarse en:
- Computadora de escritorio o laptop — layout completo con sidebar desplegado
- Tablet — sidebar colapsado, carrito en panel lateral
- Smartphone — carrito como botón flotante y drawer inferior
---
Asistente IA (Sales Agent)
El POS integra el Sales Agent Widget como botón flotante en la esquina inferior derecha. Está disponible para todos los usuarios.
- Se activa con el botón en el sidebar o con el atajo Cmd+K (Mac) / Ctrl+K (Windows)
- La página
/ai-assistantdel sidebar redirige directamente al widget — no hay una pantalla separada - El widget recibe automáticamente el contexto de la empresa (
companyId), sucursal activa y rol del empleado - Usa el Bearer token de Clerk para llamar a las APIs del negocio en nombre del usuario
---
Actualizaciones en tiempo real
El POS usa Ably para recibir eventos en tiempo real:
Órdenes
- Nuevas órdenes aparecen automáticamente en la pantalla de Órdenes
- El contador de órdenes pendientes/listas en el sidebar se actualiza sin recargar
- Los cambios de estado hechos desde la Kitchen app se reflejan inmediatamente
- Canal:
company:{companyId}:orders— eventosorder.created,order.updated
Catálogo
- La pantalla de Artículos se actualiza automáticamente cuando se crea, edita o elimina un artículo desde cualquier terminal
- La pantalla de Categorías se actualiza al cambiar categorías
- La pantalla de Modificadores se actualiza al cambiar grupos
- Canal:
company:{companyId}:catalog— eventosarticle.updated,category.updated,modifier-group.updated
Esto permite que múltiples sesiones (por ejemplo, varios administradores editando el catálogo simultáneamente) vean los cambios en tiempo real sin necesidad de recargar la página.