POS — Bitácora de Actividad
¿Qué es?
La Bitácora es un registro de auditoría inmutable de todas las acciones importantes realizadas en el sistema: quién hizo qué, cuándo y en qué sucursal. Es la herramienta del administrador para rastrear cambios, detectar irregularidades y mantener transparencia en la operación.
Se accede desde "Bitácora" en el sidebar (ícono de pergamino), URL: .../audit-log. Requiere permiso audit_log:read.
---
Pantalla de bitácora
Encabezado
- Título "Bitácora"
- Filtros avanzados
Filtros disponibles
- Módulo: Órdenes, Caja, Empleados, Configuración, Artículos, Promociones, Cupones, Categorías, Clientes, Sesiones de repartidor
- Sucursal
- Empleado
- Rango de fechas (desde/hasta)
- Límite de resultados (default 100, máximo 500)
Lista de eventos
Cada evento muestra:
- Fecha y hora exacta
- Módulo (ej. "orders", "cash_register")
- Acción (ej. "order_created", "shift_opened")
- Tipo de entidad y su ID (ej. "order #42")
- Empleado que realizó la acción (nombre + ID)
- Sucursal donde ocurrió
- Metadata — información adicional en formato JSON (montos, cambios de estado, detalles de la operación)
---
Módulos y acciones registradas
| Módulo | Acciones |
|---|---|
orders | order_created, order_approved, order_cancelled |
cash_register | shift_opened, shift_closed, movement_created |
employees | employee_created, employee_updated, employee_deleted |
settings | settings_updated, branch_settings_updated |
driver_cash_sessions | session_opened, session_closed |
articles | article_created, article_updated, article_deleted |
promotions | promotion_created, promotion_updated, promotion_deleted |
coupons | coupon_created, coupon_updated, coupon_revoked |
categories | category_created, category_updated, category_deleted |
customers | customer_created, customer_updated |
---
Cómo funciona internamente
La función logAudit() (en apps/pos/src/lib/audit.ts) se llama en cada API route después de realizar cambios importantes. Es fire-and-forget: si falla, no afecta la operación principal.
Los registros se guardan en la tabla audit_logs con:
- Snapshot del nombre del empleado (para que el historial sea legible aunque el empleado sea eliminado posteriormente)
- Metadata flexible en JSONB (el contenido varía según la acción)
---
Casos de uso del administrador
- Auditar cancelaciones: filtrar por módulo "orders" y acción "order_cancelled" para ver quién canceló qué y cuándo
- Verificar aperturas de caja: confirmar que todos los cajeros abrieron su turno correctamente
- Rastrear cambios de configuración: ver quién cambió las reglas de aprobación o los métodos de pago
- Investigar diferencias de caja: cruzar movimientos de caja con la bitácora para encontrar discrepancias