🥂 SalonOS

Exclusive Studio Management & CRM Engine Repositorio principal del sistema SalonOS.

Este README es la puerta de entrada técnica al proyecto. Define qué es este repositorio, cómo se estructura y cómo debe ser utilizado por desarrollo, producto y operación.

---

1. ¿Qué es SalonOS?

SalonOS es un sistema propietario de gestión operativa y CRM diseñado para estudios de belleza de alta exclusividad. No es una agenda genérica: coordina personas, recursos físicos, pagos, privilegios y datos bajo reglas estrictas de control y privacidad.

El sistema está diseñado para:

• Optimizar el uso de estaciones físicas.
• Proteger la base de datos de clientes.
• Controlar el crecimiento mediante invitaciones.
• Garantizar rentabilidad en días de alta demanda.
• Facilitar la operativa mediante kioskos de autoservicio.

---

2. Alcance de este Repositorio

Este repositorio contiene:

• Frontend de cliente (The Boutique).
• Dashboard administrativo (The HQ).
• Lógica de negocio de agendamiento.
• Integraciones externas (Stripe, Google Calendar, WhatsApp).
• Esquema base de datos y políticas de seguridad.

No contiene:

• Material de marketing.
• Operación manual del salón.
• Datos productivos.

---

3. Documentación Oficial

Este proyecto se rige por los siguientes documentos:

• PRD (Documento Maestro) → Definición de producto y reglas de negocio.
• README (este archivo) → Guía técnica y operativa del repo.

El PRD es la fuente de verdad funcional. El README es la guía de ejecución.

---

4. Arquitectura General

Experiencias

• The Boutique: Frontend de reserva para clientas.
• The HQ: Dashboard administrativo y CRM interno.
• The Kiosk: Sistema de autoservicio en pantalla táctil para confirmación de citas y walk-ins.

Principios

• Security by Design.
• Exclusividad curada.
• Optimización de activos.

---

5. Stack Tecnológico

• Frontend: Next.js 14 (App Router)
• UI / Estilos: Tailwind CSS + Framer Motion
• Backend: Supabase (PostgreSQL + Auth + RLS)
• Pagos: Stripe SDK
• Calendario: Google Calendar API v3 (Service Account)
• Notificaciones: WhatsApp API (Twilio / Meta)
• Storage: Supabase Storage (Buckets privados)

---

6. Estructura del Proyecto

/salonos
├── app/                # Next.js App Router
│   ├── boutique/       # Frontend clienta
│   ├── hq/             # Dashboard administrativo
│   ├── kiosk/          # Sistema de autoservicio (pantalla táctil)
│   └── api/            # API routes
│       ├── kiosk/      # Endpoints para kiosko
│       └── ...
├── components/         # Componentes UI reutilizables
│   ├── kiosk/          # Componentes del sistema de kiosko
│   └── ui/             # Componentes base (Button, Input, Card, etc.)
├── lib/                # Lógica de negocio y helpers
│   └── db/             # Tipos TypeScript del esquema
├── supabase/
│   └── migrations/     # Migraciones SQL versionadas
├── integrations/       # Stripe, Google, WhatsApp
├── styles/             # Configuración Tailwind
└── docs/               # Documentación adicional
    ├── KIOSK_SYSTEM.md           # Documentación completa del kiosko
    ├── KIOSK_IMPLEMENTATION.md   # Guía rápida de implementación
    └── RESOURCES_UPDATE.md      # Documentación de actualización de recursos

---

7. Requisitos de Entorno

• Node.js 18+
• Cuenta Supabase
• Cuenta Stripe
• Proyecto Google Cloud (Calendar API)
• Credenciales WhatsApp API

Variables de entorno obligatorias:

# Supabase
NEXT_PUBLIC_SUPABASE_URL=
NEXT_PUBLIC_SUPABASE_ANON_KEY=
SUPABASE_SERVICE_ROLE_KEY=

# Stripe
STRIPE_SECRET_KEY=
STRIPE_WEBHOOK_SECRET=

# Google Calendar
GOOGLE_SERVICE_ACCOUNT_JSON=

# WhatsApp
WHATSAPP_API_KEY=

# Kiosko (opcional - para modo kiosko)
NEXT_PUBLIC_KIOSK_API_KEY=

---

8. Setup Local

1. Clonar el repositorio

git clone <repo-url>
cd salonos

2. Instalar dependencias

npm install

3. Configurar variables de entorno

• Crear .env.local.

4. Levantar entorno local

npm run dev

---

9. Convenciones de Desarrollo

• El PRD define la lógica: no se improvisa comportamiento.
• Toda regla crítica debe vivir en backend.
• RLS obligatorio en todas las tablas sensibles.
• El frontend nunca expone datos privados del cliente.
• Cambios de alcance requieren actualización del PRD.

---

10. Estado del Proyecto

Completado ✅

• ✅ Esquema de base de datos completo
• ✅ Sistema de roles y permisos RLS
• ✅ Generadores de Short ID y códigos de invitación
• ✅ Sistema de kiosko completo
• ✅ API routes para kiosko
• ✅ Componentes UI para kiosko
• ✅ Actualización de recursos con códigos estandarizados
• ✅ Audit logging completo
• ✅ Tiers de cliente extendidos (free, gold, black, VIP)

En Progreso 🚧

• 🚧 Testing del sistema de kiosko
• 🚧 Validación de migración de recursos

Pendiente ⏳

• ⏳ API routes para cliente y staff
• ⏳ Motor de agendamiento con disponibilidad
• ⏳ Integración con Google Calendar
• ⏳ Integración con Stripe
• ⏳ HQ Dashboard (calendario multi-columna, gestión operativa)
• ⏳ The Vault (storage de fotos privadas)
• ⏳ Notificaciones y automatización
• ⏳ Landing page pública

Fase Actual

Fase 1 — Cimientos y CRM: 90% completado

• Infraestructura base: 100%
• Esquema de base de datos: 100%
• Short ID & Invitaciones: 100%
• CRM Base: 100%
• Sistema de Kiosko: 100%
• Actualización de Recursos: 100%

Advertencia: No apto para producción. Migraciones y seeds en evolución.

---

11. Sistema de Kiosko

El sistema de kiosko permite a los clientes interactuar con el salón mediante pantallas táctiles en la entrada.

Funcionalidades

• Confirmación de Citas: Los clientes confirman su llegada ingresando el código de 6 caracteres (short_id)
• Reservas Walk-in: Creación de reservas inmediatas para clientes sin cita previa
• Asignación Inteligente de Recursos: Prioridad automática (mkup > lshs > pedi > mani)

Seguridad

• Autenticación por API key de 64 caracteres
• Políticas RLS restrictivas (sin acceso a PII de clientes)
• Audit logging completo de todas las acciones

Documentación

• Guía completa: docs/KIOSK_SYSTEM.md
• Implementación rápida: docs/KIOSK_IMPLEMENTATION.md

Acceso al Kiosko

https://tu-dominio.com/kiosk/{location-id}

12. Filosofía Operativa

SalonOS no busca volumen.

Busca control, eficiencia y blindaje.

Este repositorio implementa esa filosofía a nivel de sistema.

---

Proyecto: soul23