POS_cafeteria

Imported from TDanyStark/POS_cafeteria (AGENTS.md). Install upstream with npx skills add TDanyStark/POS_cafeteria. Copyright stays with the author.

POS Cafetería — Contexto del Proyecto

Descripción

Sistema POS (Point of Sale) para mini cafetería. Digitaliza la operación diaria con control de inventario, caja, ventas, clientes y reportes en tiempo real.

Skill Activo

Cargar antes de cualquier tarea: fullstack-expert-slim-react Ruta: file:///C:/Users/USER/.agents/skills/fullstack-expert-slim-react/SKILL.md

Este skill define todas las convenciones de arquitectura, nomenclatura, UI y patrones que deben seguirse estrictamente en este proyecto.

Stack Tecnológico

Estructura de Directorios

POS_cafeteria/
├── api/                          # Backend Slim PHP
│   ├── src/
│   │   ├── Application/
│   │   │   ├── Actions/          # Controllers (un archivo por action)
│   │   │   └── Middleware/       # JWT, Role, CashRegister, etc.
│   │   ├── Domain/
│   │   │   ├── Entities/         # Modelos de dominio
│   │   │   ├── Repositories/     # Interfaces de repositorio
│   │   │   └── Services/         # Lógica de negocio
│   │   └── Infrastructure/
│   │       ├── Persistence/      # Implementaciones de repositorio (MySQL)
│   │       └── Mail/             # PHPMailer service
│   ├── database/
│   │   ├── migrations/           # Phinx migrations
│   │   └── seeders/              # Datos de prueba
│   └── public/                   # Entry point (index.php)
│
└── frontend/                     # React + TypeScript + Vite
    └── src/
        ├── components/
        │   └── shared/           # Componentes reutilizables
        ├── pages/                # Una carpeta por página
        │   └── Pos/
        │       ├── CustomerSelector.tsx
        │       └── CustomerFormModal.tsx
        ├── hooks/                # Custom hooks (useXxx.ts)
        ├── stores/               # Zustand stores
        ├── types/                # Interfaces TypeScript (espejo del backend)
        ├── utils/                # Helpers y funciones puras
        └── lib/                  # Configuración axios, queryClient, etc.

Modelo de Datos

users            → id, name, email, password, role (admin|cashier), active, timestamps
categories       → id, name, slug, timestamps
products         → id, category_id, name, price, stock, min_stock, active, timestamps
customers        → id, name, phone(nullable), email(nullable), timestamps

cash_registers   → id, user_id, opened_at, closed_at, initial_amount, final_amount,
                   declared_amount, difference, status (open|closed), timestamps
cash_movements   → id, cash_register_id, user_id, type (in|out), amount,
                   description, timestamps

sales            → id, cash_register_id, user_id, customer_id(nullable),
                   total, payment_method (cash|transfer),
                   amount_paid, change_amount, notes, timestamps
sale_items       → id, sale_id, product_id, quantity, unit_price, subtotal

email_settings   → id, smtp_host, smtp_port, smtp_user, smtp_pass,
                   from_name, notification_email, active

Endpoints API (/api/v1/)

Páginas Frontend

Reglas de Negocio Críticas

Caja (Cash Register)

• Sin caja abierta: El sistema bloquea ventas y redirige a abrir caja.
• Caja anterior sin cerrar: Antes de abrir una nueva caja, el sistema obliga a cerrar la del turno anterior.
• Apertura: Requiere ingresar saldo inicial (conteo físico de efectivo).
• Cierre: Calcula saldo_esperado = initial_amount + ingresos_efectivo - egresos. El cajero declara el monto físico. Se registra la diferencia (sobrante/faltante) pero no bloquea el cierre.

Ventas

• POST /sales verifica existencia de cash_register con status = open para el user_id. Sin caja abierta → 403.
• El descuento de stock ocurre en la misma transacción DB. Si un producto no tiene stock suficiente → la venta se rechaza completa.
• customer_id es nullable. Las ventas anónimas son válidas.
• Las ventas registran el user_id del cajero que las realizó.

Clientes

• El nombre es el único campo obligatorio. teléfono y email son opcionales.
• La búsqueda en el POS se realiza por nombre, teléfono o email.
• El POS permite el registro rápido de clientes mediante un modal sin abandonar el flujo de venta.

Notificaciones Email

• Se disparan después de confirmar cada venta.
• Son asíncronas: no bloquean la respuesta al frontend.
• Si el envío falla, se loguea el error pero la venta queda registrada correctamente.

Roles

• admin: acceso total a todos los módulos.
• cashier: acceso solo a /pos, /cash-register, /sales (sus propias ventas) y /dashboard.

Seeders por Defecto

Dark Mode

El proyecto tiene soporte completo de dark mode con tres modos: light, dark y system (predeterminado).

Arquitectura

• Tailwind v4: @custom-variant dark (&:is(.dark *)) para el toggle manual con clase .dark en <html>.
• Sistema por defecto: @media (prefers-color-scheme: dark) en index.css aplica las variables cuando <html> no tiene .light ni .dark.
• useTheme hook (src/hooks/useTheme.ts): gestiona el estado del tema, persiste en localStorage (pos-theme), escucha cambios del sistema cuando está en modo system.
• ThemeProvider (src/components/shared/ThemeProvider.tsx): provee el contexto del tema a toda la app. Está montado en main.tsx como el wrapper más externo.

Lógica de clases en <html>

Reglas para los agentes

• Todas las vistas DEBEN tener soporte dark mode. Usar siempre las variables semánticas de Shadcn (bg-background, text-foreground, bg-card, text-muted-foreground, etc.), NUNCA colores hardcodeados como bg-white o text-gray-900.
• Si necesitas un color que cambie con el tema, usa dark: variant: className="bg-white dark:bg-gray-900".
• Para toggle de tema en la UI (botón en el header/sidebar), usar useThemeContext() del ThemeProvider.
• No usar document.documentElement.classList directamente — siempre via el hook useTheme o useThemeContext.

Ejemplo de uso del toggle

import { useThemeContext } from '@/components/shared/ThemeProvider'

function ThemeToggle() {
  const { theme, setTheme } = useThemeContext()
  return (
    <button onClick={() => setTheme(theme === 'dark' ? 'light' : 'dark')}>
      {theme === 'dark' ? 'Claro' : 'Oscuro'}
    </button>
  )
}

Convenciones (resumen rápido)

• Rutas API: siempre /api/v1/... en plural y kebab-case
• Tablas DB: plural y snake_case
• Clases PHP: PascalCase
• Variables/métodos PHP: camelCase
• Componentes React: PascalCase, un componente por archivo .tsx
• Custom Hooks: useXxx.ts
• Estado en URL: filtros, paginación y búsquedas siempre en query params (?page=1&category=bebidas)
• Paginación: obligatoria en todos los endpoints que retornen colecciones
• Errores backend: siempre { "success": false, "message": "...", "errors": {} }
• Feedback UI: solo Toast/Notificaciones de Shadcn, nunca alert()
• Dark mode: siempre usar variables semánticas Shadcn, nunca colores hardcodeados

Migraciones:

• Correr migraciones pendientes composer migrate

• Poblar datos de prueba composer seed

• Reset completo (borrar todo y volver a crear) composer reset