QuantifyGourmet

Imported from Alexis9520/posada-test (QuantifyGourmet/AGENTS.md). Install upstream with npx skills add Alexis9520/posada-test --skill QuantifyGourmet. Copyright stays with the author.

AGENTS.md - QuantifyGourmet Frontend

Este documento está diseñado para ser leído por agentes de IA. Proporciona información esencial sobre la arquitectura, convenciones y procesos del proyecto.

Visión General del Proyecto

QuantifyGourmet Frontend es una aplicación web de Punto de Venta (POS) profesional diseñada para restaurantes y pollerías. El sistema actual soporta múltiples sedes (Pollería y Restaurante) con roles específicos para cada tipo de usuario.

Nombre del Proyecto

• Nombre comercial: La Posada - Sistema de Gestión Multi-Sede v2.0
• Nombre técnico: my-v0-project (package.json)

Propósito Principal

Sistema POS completo que gestiona:

• Toma de pedidos en mesas (meseros)
• Gestión de cocina (tickets/comandas)
• Procesamiento de pagos (cajeros)
• Administración de productos, personal y configuración (administradores)
• Visualización de plano de mesas interactivo

Stack Tecnológico

Framework Principal

• Next.js 15.2.4 - Framework React con App Router
• React 18 - Biblioteca UI
• TypeScript 5 - Tipado estático

Estilos y UI

• Tailwind CSS 4.1.9 - Framework CSS utilitario
• PostCSS 8.5 - Procesador CSS
• shadcn/ui - Componentes UI basados en Radix UI (estilo "new-york")
• Lucide React - Iconografía
• Framer Motion - Animaciones

Gestión de Estado

• Zustand - Estado global con persistencia
• Immer - Mutaciones inmutables

Formularios y Validación

• React Hook Form - Manejo de formularios
• Zod - Validación de esquemas

Otros Paquetes Clave

• @dnd-kit - Drag and drop (core, sortable, utilities)
• Recharts - Visualización de datos
• date-fns - Manipulación de fechas
• react-hot-toast / sonner - Notificaciones

Estructura del Proyecto

FrontendQuantifyGourmet/
├── app/                    # Next.js App Router
│   ├── admin/             # Panel de administración
│   │   ├── _components/   # Componentes internos de admin
│   │   ├── dishes/        # Gestión de platos
│   │   ├── menus/         # Gestión de menús
│   │   └── waiter-sales/  # Reportes de ventas por mesero
│   ├── cashier/           # Interfaz de cajero
│   ├── dashboard/         # Dashboard principal
│   ├── history/           # Historial de órdenes
│   ├── kitchen/           # Interfaz de cocina
│   ├── reports/           # Reportes
│   ├── tables/            # Plano de mesas interactivo
│   │   ├── components/    # Componentes del plano
│   │   │   ├── ChairItem.tsx       # Componente de silla visual
│   │   │   ├── FloorPlanCanvas.tsx # Canvas interactivo
│   │   │   ├── TableItem.tsx       # Componente de mesa con estados
│   │   │   ├── TablePopup.tsx      # Popup de acciones de mesa
│   │   │   └── WoodBackground.tsx  # Fondo de madera
│   │   ├── hooks/         # Hooks específicos
│   │   │   └── useFloorPlan.ts     # Hook de gestión del plano
│   │   └── types/         # Tipos TypeScript
│   │       └── floorplan.ts        # Tipos alineados con API Mesas
│   ├── globals.css        # Estilos globales con Tailwind v4
│   ├── layout.tsx         # Layout raíz
│   └── page.tsx           # Página de login
├── components/            # Componentes reutilizables
│   ├── ui/               # Componentes shadcn/ui
│   ├── cash-register/    # Componentes de caja
│   ├── menu-builder/     # Constructor de menús
│   ├── productos/        # Gestión de productos
│   └── reports/          # Componentes de reportes
├── hooks/                # Custom React Hooks
├── lib/                  # Utilidades y estado global
│   ├── store.ts          # Zustand store (estado POS)
│   ├── utils.ts          # Funciones utilitarias (cn)
│   └── cookies.ts        # Gestión de cookies
├── docs/                 # Documentación de APIs
│   ├── api-auth.md
│   ├── api-productos.md
│   ├── api-sedes.md
│   └── api-usuarios.md
├── public/               # Archivos estáticos
└── capturas/             # Capturas de pantalla

Convenciones de Código

Importaciones

• Usar el alias @/* para imports absolutos desde la raíz
• Ejemplo: import { Button } from "@/components/ui/button"

Tipado

• Todos los archivos deben ser .ts o .tsx
• Definir interfaces para props de componentes
• Usar tipos del store para entidades de negocio

Nomenclatura

• Componentes: PascalCase (e.g., TableCard.tsx)
• Hooks: camelCase con prefijo use (e.g., useProductos.ts)
• Utilidades: camelCase (e.g., cookies.ts)
• Tipos/Interfaces: PascalCase (e.g., TableStatus, MenuItem)

Colores del Tema (Brand)

El proyecto usa una paleta de colores cálida orientada a restaurantes:

• Primario: #FFA142 (naranja cálido)
• Secundario: #A65F33 (marrón tierra)
• Fondo: #FFF5ED (crema cálido)
• Bordes: #FFE0C2 (melocotón claro)
• Éxito: #10b981 (verde)
• Error: #ef4444 (rojo)

Estilos CSS

• Usar Tailwind CSS para estilos inline
• Para colores del tema, usar las variables CSS definidas en globals.css
• Clases utilitarias personalizadas en @layer utilities

Arquitectura de Autenticación

Flujo de Login

1. Usuario ingresa DNI y contraseña en / (login page)
2. Se hace POST a ${NEXT_PUBLIC_API_URL}/auth/login
3. Backend devuelve: token, refreshToken, userId, rol, sedeNombre, etc.
4. Frontend mapea roles del backend a roles internos:
   • ADMIN_SISTEMA/ADMIN_SEDE → admin
   • MOZO → waiter
   • CAJERO/CAJA → cashier
   • COCINERO/COCINA → kitchen
5. Se almacena en localStorage y cookies para middleware
6. Redirección según rol:
   • kitchen → /kitchen
   • cashier → /cashier
   • admin → /dashboard
   • Otros → /tables

Middleware (middleware.ts)

• Protege rutas privadas verificando cookie auth_token
• Rutas públicas: /, /login, /register, /forgot-password
• Ignora archivos estáticos (/_next, /api, etc.)
• Redirige a / si no hay token

Estado de Usuario

Almacenado en Zustand store (lib/store.ts):

interface User {
  id: string;
  dni: string;
  name: string;
  role: "admin" | "waiter" | "cashier" | "kitchen";
  site: "polleria" | "restaurante";
  token?: string;
  refreshToken?: string;
  expiresIn?: number;
}

Estado Global (Zustand Store)

Ubicación: lib/store.ts

Entidades Principales

• currentUser - Usuario autenticado
• tables - Mesas del restaurante
• menuItems - Productos del menú (desde backend)
• kitchenTickets - Comandas en cocina
• orderHistory - Historial de órdenes completadas
• notifications - Notificaciones del sistema
• menus - Menús configurables
• cashSession - Sesión de caja actual

Persistencia

• Solo currentUser se persiste en localStorage
• Nombre del storage: 'pos-storage'

Acciones Principales

• login(dni, password) - Autenticación
• logout() - Cierre de sesión (llama a backend)
• refreshSession() - Renovación de tokens
• addOrderToTable() - Agregar ítems a mesa
• sendToKitchen() - Enviar comanda a cocina
• processPayment() - Procesar pago
• fetchProducts() - Cargar productos desde API

Integración con Backend

Configuración

Variable de entorno: NEXT_PUBLIC_API_URL

• Producción: https://apigourmet.enricer.me/api/v1
• Desarrollo: http://localhost:8080/api/v1

Endpoints Principales

Autenticación (/auth)

• POST /auth/login - Login con DNI/password
• POST /auth/refresh - Renovar tokens
• POST /auth/logout - Cerrar sesión

Productos (/productos)

• GET /productos - Listar productos (paginado)
• POST /productos - Crear producto
• PUT /productos/{id} - Actualizar producto
• PATCH /productos/{id}/precio - Actualizar precio
• DELETE /productos/{id} - Eliminar producto

Mesas (/mesas)

Ubicación: hooks/useMesas.ts

Endpoints implementados según docs/api-mesas.md:

• GET /mesas/sede/{sedeId} - Listar mesas por sede
• GET /mesas/{id} - Obtener mesa por ID
• GET /mesas/sede/{sedeId}/resumen - Resumen de mesas (KPIs)
• POST /mesas/sede/{sedeId} - Crear mesa (ADMIN)
• PUT /mesas/{id} - Actualizar mesa completa (Layout Designer)
• PATCH /mesas/{id}/estado - Cambiar estado de mesa (MOZO)
• DELETE /mesas/{id} - Eliminar mesa (marcar INACTIVA)

Mapeo de Estados:

Mapeo de Formas:

Ver documentación completa en /docs/.

Headers Requeridos

{
  "Authorization": "Bearer {token}",
  "Content-Type": "application/json"
}

Comandos de Desarrollo

Instalación

# Usando npm
npm install

# Usando bun (recomendado)
bun install

Desarrollo

# Servidor de desarrollo con Turbo
npm run dev
# o
bun dev

Build

# Compilar para producción
npm run build
# o
bun run build

Producción

# Iniciar servidor de producción
npm run start
# o
bun start

Linting

npm run lint

Configuración de Next.js

Archivo: next.config.mjs

{
  eslint: {
    ignoreDuringBuilds: true,  // Ignora errores ESLint en build
  },
  typescript: {
    ignoreBuildErrors: true,   // Ignora errores TypeScript en build
  },
  images: {
    unoptimized: true,         // Desactiva optimización de imágenes
  },
}

Páginas y Roles

Hooks Personalizados Importantes

useProductos

Ubicación: hooks/useProductos.ts

Gestión completa de productos con paginación:

const {
  productos,
  loading,
  error,
  pagination,
  fetchProductos,
  createProducto,
  updateProducto,
  updatePrecio,
  deleteProducto,
} = useProductos();

useMesas

Ubicación: hooks/useMesas.ts

Hook para gestión completa de mesas conectado al backend:

const {
  mesas,           // Mesa[] - Lista de mesas del backend
  loading,         // boolean
  error,           // string | null
  resumen,         // ResumenMesas | null - KPIs
  fetchMesas,      // () => Promise<void>
  getMesaById,     // (id: string) => Promise<Mesa | null>
  createMesa,      // (data: CreateMesaData) => Promise<Mesa | null>
  updateMesa,      // (id: string, updates: UpdateMesaRequest) => Promise<Mesa | null>
  updateMesaEstado,// (id: string, status: TableStatus) => Promise<boolean>
  deleteMesa,      // (id: string) => Promise<boolean>
  saveAllMesas,    // () => Promise<boolean>
} = useMesas({ sedeId });

useFloorPlan

Ubicación: app/tables/hooks/useFloorPlan.ts

Gestión del plano de mesas interactivo con drag & drop. Renderiza mesas reales del backend + sillas visuales generadas dinámicamente. Solo las mesas persisten en el backend; las sillas son puramente visuales.

Gestión de Notificaciones

El sistema usa react-hot-toast para notificaciones:

import { toast } from "react-hot-toast";

// Éxito
toast.success("Operación exitosa");

// Error
toast.error("Mensaje de error");

// Info
toast("Mensaje informativo", { icon: "🔧" });

Consideraciones de Seguridad

1. Tokens: Almacenados en localStorage (cliente) y cookies (middleware)
2. Middleware: Verifica autenticación en cada ruta protegida
3. API Calls: Incluyen Bearer token en header Authorization
4. Logout: Llama a endpoint backend y limpia storage local

Testing

Actualmente el proyecto no tiene tests configurados. Para agregar:

# Instalar dependencias de testing
npm install --save-dev jest @testing-library/react @testing-library/jest-dom

Notas para Desarrolladores

1. Mock Data: El store incluye datos de prueba (mockMenuItems, mockTables) que se pueden usar para desarrollo sin backend.

2. Categorías de Productos: Las categorías del backend vienen en UPPERCASE y se mapean a formato Title Case en el frontend.

3. Sedes: El sistema distingue entre "polleria" y "restaurante". Los productos pueden estar disponibles en una o ambas sedes.

4. Plano de Mesas: Usa @dnd-kit para drag & drop. Los datos se persisten en localStorage bajo la clave "floorPlan".

5. Imágenes: Se usan URLs de Unsplash para imágenes de productos en modo desarrollo.

Documentación Adicional

• Documentación de APIs: /docs/*.md
• Componentes UI: Ver components/ui/ (shadcn/ui)
• Tipos TypeScript: Ver lib/store.ts para entidades principales