🍽️ RestPOS - Sistema POS para Restaurantes

Sistema punto de venta completo y escalable para gestión integral de restaurantes, diseñado como Progressive Web App (PWA) para funcionar en cualquier dispositivo. Incluye arquitectura multi-tenant, actualización en tiempo real, control automatizado de inventario y está potenciado por Supabase como backend-as-a-service.

---

📋 Tabla de Contenidos

• Características
• Stack Tecnológico
• Arquitectura
• Estructura del Proyecto
• Requisitos Previos
• Instalación
• Configuración
• Uso
• Módulos del Sistema
• Workflow de Desarrollo
• Testing
• Contribución
• Licencia

---

✨ Características

Progressive Web App (PWA)

• 📱 Instalable - Funciona como app nativa en móviles, tablets y desktop
• 🔄 Modo Offline - Continúa operando sin conexión a internet
• 🚀 Rendimiento optimizado - Carga instantánea con service workers
• 🔔 Notificaciones Push - Alertas en tiempo real incluso con la app cerrada
• 📲 Responsive - Adaptado a cualquier tamaño de pantalla
• ⚡ Lighthouse Score 90+ - Rendimiento, accesibilidad y SEO optimizados

Gestión Operativa

• ✅ Órdenes en tiempo real - Sincronización instantánea entre meseros, cocina y caja
• ✅ Gestión de mesas - Estados: libre, ocupada, reservada
• ✅ Menú dinámico - Productos, categorías y modificadores personalizables
• ✅ Vista de cocina - Interface optimizada para preparación de órdenes
• ✅ Inventario automático - Descuento automático por receta de productos

Finanzas y Facturación

• 💰 Múltiples métodos de pago - Efectivo, tarjeta, transferencia, pago mixto
• 💰 División de cuenta - Split de facturas entre comensales
• 💰 Generación de PDFs - Facturas profesionales con datos fiscales
• 💰 Reportes de caja - Cierre de turno y cuadre automático

Administración

• 👥 Sistema de roles - Admin, mesero, cocina, caja con permisos granulares
• 👥 Multi-tenant - Soporte para múltiples restaurantes en una instancia
• 📊 Dashboard analytics - Métricas de ventas, productos más vendidos, rendimiento
• 🔔 Notificaciones en tiempo real - Alertas de inventario, órdenes nuevas, cambios de estado

Powered by Supabase

• 🔐 Autenticación robusta - Auth de Supabase con JWT y OAuth
• 💾 PostgreSQL gestionado - Base de datos escalable y de alto rendimiento
• 🔄 Realtime subscriptions - Actualizaciones instantáneas sin polling
• 📦 Storage integrado - Almacenamiento de imágenes de productos y logos
• 🚀 Edge Functions - Lógica serverless para procesos complejos
• 📊 Row Level Security (RLS) - Seguridad de datos a nivel de fila

---

🛠️ Stack Tecnológico

Backend

Tecnología	Versión	Propósito
Supabase	Latest	Backend-as-a-Service (BaaS)
PostgreSQL	15+	Base de datos (gestionada por Supabase)
Supabase Auth	Latest	Autenticación y autorización
Supabase Realtime	Latest	WebSockets y suscripciones en tiempo real
Supabase Storage	Latest	Almacenamiento de archivos
Edge Functions	Deno	Funciones serverless
Node.js	20.x	Runtime para scripts y workers
Express	4.18	API custom (opcional)
TypeScript	5.3	Tipado estático
Prisma	5.8	ORM (opcional para migraciones complejas)
PDFKit	0.14	Generación de PDFs

Frontend (PWA)

Tecnología	Versión	Propósito
React	18.2	Library UI
TypeScript	5.3	Tipado estático
Vite	5.0	Build tool y PWA
Vite PWA Plugin	Latest	Service Worker y manifest
TanStack Query	5.0	State management servidor
Zustand	4.4	State management cliente
Supabase JS Client	Latest	Cliente para Supabase
Tailwind CSS	3.4	Utility-first CSS
Shadcn/ui	Latest	Componentes UI
Workbox	Latest	Service Worker avanzado
IndexedDB	Native	Almacenamiento offline

DevOps

• Docker & Docker Compose
• GitHub Actions (CI/CD)
• Supabase CLI
• ESLint + Prettier
• Husky (Git hooks)

---

🏗️ Arquitectura

┌─────────────────────────────────────────────────────────────┐
│                  CAPA DE PRESENTACIÓN (PWA)                  │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐      │
│  │   Meseros    │  │    Cocina    │  │     Caja     │      │
│  │  (React PWA) │  │  (React PWA) │  │  (React PWA) │      │
│  │  + Service   │  │  + Service   │  │  + Service   │      │
│  │    Worker    │  │    Worker    │  │    Worker    │      │
│  └──────────────┘  └──────────────┘  └──────────────┘      │
│         │                  │                  │             │
│         └──────────────────┼──────────────────┘             │
│                            │                                │
│                   ┌────────▼─────────┐                      │
│                   │  IndexedDB Cache │ (Offline Storage)    │
│                   └────────┬─────────┘                      │
└─────────────────────────────────────────────────────────────┘
                             │
                    ┌────────▼─────────┐
                    │  Supabase Client │
                    │   (supabase-js)  │
                    └────────┬─────────┘
                             │
┌─────────────────────────────────────────────────────────────┐
│                   SUPABASE BACKEND (BaaS)                    │
│  ┌────────────────────────────────────────────────────┐     │
│  │              Supabase Realtime Engine              │     │
│  │        (WebSockets + PostgreSQL Subscriptions)     │     │
│  └────────────────────────────────────────────────────┘     │
│  ┌────────────────────────────────────────────────────┐     │
│  │                 Supabase Auth                      │     │
│  │         (JWT + Row Level Security Policies)        │     │
│  └────────────────────────────────────────────────────┘     │
│  ┌────────────────────────────────────────────────────┐     │
│  │            PostgreSQL Database (Managed)           │     │
│  │         Multi-tenant con restaurant_id             │     │
│  │         + Row Level Security (RLS) activo          │     │
│  └────────────────────────────────────────────────────┘     │
│  ┌────────────────────────────────────────────────────┐     │
│  │              Supabase Storage                      │     │
│  │         (Imágenes de productos y logos)            │     │
│  └────────────────────────────────────────────────────┘     │
│  ┌────────────────────────────────────────────────────┐     │
│  │              Edge Functions (Deno)                 │     │
│  │    - Generación de PDFs                            │     │
│  │    - Procesamiento de pagos                        │     │
│  │    - Cálculos complejos de inventario              │     │
│  └────────────────────────────────────────────────────┘     │
└─────────────────────────────────────────────────────────────┘

Flujo de Datos en Tiempo Real (Realtime)

1. Mesero crea orden → INSERT en tabla orders
2. Supabase Realtime detecta cambio
3. Broadcast a todos los clientes suscritos
4. Cocina recibe notificación → Actualiza UI
5. Cambio de estado → Propagación bidireccional

Modo Offline (PWA)

1. Service Worker intercepta requests
2. Si hay conexión → Fetch de Supabase
3. Si no hay conexión → Lee de IndexedDB
4. Cuando se restaura conexión → Sincroniza cambios pendientes

---

📁 Estructura del Proyecto

restpos/
├── backend/                 # API Node.js + Express
│   ├── src/
│   │   ├── config/         # Configuraciones (DB, JWT, etc)
│   │   ├── controllers/    # Controladores de rutas
│   │   ├── middlewares/    # Auth, validación, errores
│   │   ├── services/       # Lógica de negocio
│   │   ├── routes/         # Definición de endpoints
│   │   ├── utils/          # Helpers y utilidades
│   │   ├── types/          # Tipos TypeScript
│   │   ├── socket/         # Lógica Socket.io
│   │   └── index.ts        # Entry point
│   ├── prisma/
│   │   ├── schema.prisma   # Modelo de datos
│   │   ├── migrations/     # Migraciones SQL
│   │   └── seed.ts         # Datos iniciales
│   ├── tests/              # Tests unitarios e integración
│   ├── .env.example
│   ├── package.json
│   └── README.md
│
├── frontend/               # App React + TypeScript
│   ├── src/
│   │   ├── components/    # Componentes reutilizables
│   │   ├── pages/         # Vistas principales
│   │   ├── hooks/         # Custom hooks
│   │   ├── services/      # API clients
│   │   ├── store/         # Zustand stores
│   │   ├── types/         # Tipos TypeScript
│   │   ├── utils/         # Helpers
│   │   ├── App.tsx
│   │   └── main.tsx
│   ├── public/
│   ├── .env.example
│   ├── package.json
│   └── README.md
│
├── docs/                  # Documentación adicional
│   ├── ENVIRONMENT.md     # Guía de variables de entorno
│   
│       
│
├── docker-compose.yml     # Orquestación de servicios
├── .gitignore
├── .eslintrc.json
├── .prettierrc
└── README.md              # Este archivo

---

📦 Requisitos Previos

• Node.js 20.x o superior
• Cuenta de Supabase (gratuita disponible en supabase.com)
• Supabase CLI instalado globalmente
• Git para control de versiones
• pnpm o npm como gestor de paquetes
• Navegador moderno con soporte para Service Workers (Chrome, Firefox, Safari, Edge)

---

🚀 Instalación

1. Clonar el repositorio

git clone https://github.com/tu-usuario/restpos.git
cd restpos

2. Configurar Supabase

Crear proyecto en Supabase

1. Ir a supabase.com y crear cuenta
2. Crear nuevo proyecto
3. Copiar Direct URL y URI con pooling

Migrar

# Aplicar migraciones
supabase db push

3. Configurar variables de entorno

# Backend 
cp backend/.env.example backend/.env

# Frontend
cp frontend/.env.example frontend/.env

Ver ENVIRONMENT.md para detalles completos.

4. Instalar PWA en tu dispositivo

1. Abre la app en tu navegador
2. Busca el ícono de "Instalar" en la barra de direcciones
3. Haz clic en "Instalar RestPOS"
4. La app se instalará como aplicación nativa

---

⚙️ Configuración

Supabase

Políticas de Row Level Security (RLS)

Todas las tablas principales tienen RLS habilitado para seguridad multi-tenant:

-- Ejemplo: Tabla orders
ALTER TABLE orders ENABLE ROW LEVEL SECURITY;

-- Policy: Los usuarios solo ven órdenes de su restaurante
CREATE POLICY "Users can only see their restaurant orders"
ON orders FOR SELECT
USING (restaurant_id = auth.jwt() ->> 'restaurant_id');



#### Realtime Subscriptions

```typescript
// Suscribirse a cambios en órdenes
const subscription = supabase
  .channel('orders-channel')
  .on(
    'postgres_changes',
    { 
      event: '*', 
      schema: 'public', 
      table: 'orders',
      filter: `restaurant_id=eq.${restaurantId}`
    },
    (payload) => {
      console.log('Order changed:', payload);
      // Actualizar UI en tiempo real
    }
  )
  .subscribe();

🧩 Módulos del Sistema

1. Autenticación (/auth)

• Login con email/password a través de Supabase Auth
• Magic Links (login sin contraseña)
• OAuth providers (Google, GitHub, etc.)
• Registro de usuarios
• Roles: Admin, Mesero, Cocina, Caja
• Row Level Security (RLS) automático

2. Dashboard (/dashboard)

• Métricas de ventas del día
• Productos más vendidos
• Alertas de inventario bajo
• Actividad reciente

3. Órdenes (/orders)

• Crear orden (mesa o delivery)
• Estados: pendiente → en proceso → lista → entregada
• Editar órdenes activas
• Agregar/eliminar productos
• Modificadores de productos

4. Mesas (/tables)

• Gestión de mesas
• Estados: libre, ocupada, reservada
• Asignación de meseros
• Tiempo de ocupación

5. Menú (/menu)

• CRUD de productos
• Categorías
• Modificadores (extras, sin ingredientes)
• Precios y disponibilidad
• Asociación con ingredientes (recetas)
• Upload de imágenes a Supabase Storage

6. Cocina (/kitchen)

• Vista en tiempo real con Supabase Realtime
• Cambio de estados
• Priorización de órdenes
• Notificaciones Push a meseros
• Actualización automática sin recargar

7. Inventario (/inventory)

• CRUD de ingredientes
• Consumo automático por orden
• Alertas de stock mínimo
• Historial de movimientos

8. Facturación (/billing)

• Métodos de pago múltiples
• División de cuenta
• Generación de PDF con Edge Function
• Impresión térmica
• Aplicación de descuentos

9. Reportes (/reports)

• Reporte de caja (por turno/día)
• Reporte de inventario
• Reporte de ventas por producto
• Exportación a Excel/PDF

10. Gestión (/management)

• CRUD de usuarios
• CRUD de empleados
• CRUD de proveedores
• Configuración de descuentos
• Configuración del restaurante

---

Tipos de Commits

• feat: Nueva funcionalidad
• fix: Corrección de bug
• refactor: Refactorización sin cambio funcional
• perf: Mejora de rendimiento
• docs: Cambios en documentación
• test: Agregar/modificar tests
• chore: Tareas de mantenimiento

🔗 Enlaces Útiles

• Documentación de Supabase
• Supabase JavaScript Client
• Guía de PWA con Vite
• Row Level Security en Supabase
• Realtime con Supabase

---