Definicion de proyecto

AGENTS.md

@@ -2,34 +2,38 @@
 
 Este documento define cómo deben usarse agentes de IA (Claude, Codex, OpenCode, Gemini) dentro del proyecto SalonOS.
 
-Ningún agente tiene autoridad de producto. Todos ejecutan bajo el PRD.
+Ningún agente tiene autoridad de producto. Todos ejecutan estrictamente bajo el PRD.
 
 ---
 
 ## Principios de Uso de Agentes
 
-* Los agentes **no deciden alcance**.
-* Los agentes **no redefinen reglas de negocio**.
-* Toda salida debe ser revisable y versionable.
-* El PRD es la única fuente de verdad funcional.
+- Los agentes no deciden alcance.
+- Los agentes no redefinen reglas de negocio.
+- Los agentes no introducen lógica no descrita en el PRD.
+- Toda salida debe ser revisable, versionable y auditable.
+- El PRD es la única fuente de verdad funcional.
 
 ---
 
-## Claude — Arquitectura & Lógica
+## Claude — Arquitectura y Lógica
 
 **Rol:** Arquitecto de sistema y reglas de negocio.
 
-**Usar para:**
+**Responsabilidades explícitas alineadas al PRD:**
+- Definir la lógica de reseteo mensual de invitaciones (día 1, idempotente, auditable).
+- Especificar manejo UTC-first y puntos válidos de conversión de zona horaria.
+- Diseñar el algoritmo de generación de Short ID con reintentos por colisión.
+- Modelar estados, transiciones y edge cases críticos.
 
-* Descomposición de lógica compleja.
-* Revisión de consistencia con el PRD.
-* Diseño de flujos y algoritmos.
-* Modelado de estados y edge cases.
+**Usar para:**
+- Descomposición de lógica compleja.
+- Validación de consistencia con el PRD.
+- Diseño de flujos y contratos lógicos.
 
 **No usar para:**
-
-* Código final sin revisión.
-* Decisiones de UX visual.
+- Código final sin revisión humana.
+- Decisiones visuales o de UX.
 
 ---
 
@@ -37,58 +41,74 @@ Ningún agente tiene autoridad de producto. Todos ejecutan bajo el PRD.
 
 **Rol:** Ingeniero de backend.
 
-**Usar para:**
+**Responsabilidades explícitas alineadas al PRD:**
+- Implementar el reseteo mensual de invitaciones mediante:
+  - Cron Job o
+  - Supabase Edge Function.
+- Garantizar que todos los timestamps persistidos estén en UTC.
+- Implementar generación de Short ID (6 caracteres) con verificación de unicidad y reintentos.
+- Registrar todos los automatismos y eventos críticos en `audit_logs`.
 
-* SQL y migraciones.
-* Funciones server-side.
-* Webhooks (Stripe, WhatsApp).
-* Integraciones API.
+**Usar para:**
+- SQL, migraciones y esquemas.
+- Funciones server-side.
+- Webhooks (Stripe, WhatsApp).
+- Integraciones API.
 
 **Reglas:**
-
-* Todo código debe respetar RLS.
-* No hardcodear secretos.
+- Todo código debe respetar RLS.
+- No hardcodear secretos.
+- No persistir horas locales bajo ninguna circunstancia.
 
 ---
 
-## OpenCode — Frontend & Integración
+## OpenCode — Frontend e Integración
 
 **Rol:** Ingeniero de interfaz y pegamento.
 
-**Usar para:**
+**Responsabilidades explícitas alineadas al PRD:**
+- Convertir timestamps desde UTC a la zona horaria definida en `locations.timezone`.
+- Nunca enviar ni persistir horas locales al backend.
+- Exponer Short ID únicamente como referencia humana, nunca como identificador primario.
 
-* Componentes Next.js.
-* Integración frontend ↔ backend.
-* Manejo de estados.
-* Formularios y flujos.
+**Usar para:**
+- Componentes Next.js.
+- Integración frontend ↔ backend.
+- Manejo de estado y formularios.
+- Flujos de agenda y visualización.
 
 **Reglas:**
-
-* No exponer datos privados.
-* Validaciones críticas en backend.
+- No exponer datos privados.
+- Validaciones críticas siempre en backend.
 
 ---
 
-## Gemini — QA & Seguridad
+## Gemini — QA y Seguridad
 
 **Rol:** Auditor técnico.
 
-**Usar para:**
+**Responsabilidades explícitas alineadas al PRD:**
+- Verificar que ningún timestamp no-UTC sea almacenado.
+- Auditar la idempotencia del reseteo mensual de invitaciones.
+- Detectar riesgos de colisión, enumeración o fuga de Short IDs.
+- Revisar cumplimiento de RLS y límites de acceso.
 
-* Revisión de RLS.
-* Detección de fugas de datos.
-* Edge cases de seguridad.
-* Validación de flujos críticos.
+**Usar para:**
+- Revisión de RLS.
+- Detección de fugas de datos.
+- Edge cases de seguridad.
+- Validación de flujos críticos.
 
 ---
 
-## Flujo de Trabajo Recomendado
+## Flujo de Trabajo Canónico
+
+1. El PRD define la regla.
+2. La lógica es descompuesta y formalizada.
+3. El backend implementa la regla.
+4. La interfaz conecta y presenta.
+5. Se audita y valida el cumplimiento técnico.
 
-1. PRD define la regla.
-2. Claude descompone la lógica.
-3. Codex implementa backend.
-4. OpenCode conecta UI.
-5. Gemini audita.
 
 ---
 

PRD.md

@@ -1,316 +1,111 @@
-🥂 SalonOS — Product Requirements Document (PRD)
+# PRD — SalonOS
 
-Exclusive Studio Management & CRM EngineVersión: 1.0Estado: Documento Maestro de Planificación
+## 1. Objetivo
 
-Este documento constituye la especificación definitiva del producto SalonOS. Consolida la visión de negocio, las reglas operativas, la experiencia de usuario y la arquitectura técnica. Funciona como contrato de alineación entre la dueña del negocio y el equipo de diseño y desarrollo.
+SalonOS es un sistema operativo para salones de belleza orientado a agenda, pagos, membresías e invitados, con reglas estrictas de tiempo, seguridad y automatización.
 
-1. Visión y Propósito del Proyecto
+---
 
-SalonOS no es una agenda digital. Es un sistema de gestión de activos, exclusividad y control operativo diseñado para estudios de belleza premium.
+## 2. Principios del Sistema
 
-1.1 Propósito Dual
+* UTC-first en todo el backend.
+* UUID como identificador primario interno.
+* Short ID solo para referencia humana.
+* Automatismos auditables.
+* PRD como única fuente de verdad.
 
-Para la Clienta
+---
 
-Experiencia de reserva privada, rápida y sin fricción.
+## 3. Roles y Membresías
 
-Sensación de pertenencia a un círculo exclusivo.
+### 3.1 Tiers
 
-Interfaz minimalista estilo Townhouse Beauty.
+* Free
+* Gold
 
-Para el Negocio
+### 3.2 Tier Gold — Beneficios
 
-Maximizar la rentabilidad por metro cuadrado.
+* Acceso prioritario a agenda.
+* Beneficios financieros definidos en pricing.
+* Invitaciones mensuales.
 
-Optimizar el uso de recursos físicos y humanos.
+### 3.3 Ecosistema de Exclusividad (Invitaciones)
 
-Proteger la base de datos de clientes ante rotación de personal.
+* Cada cuenta Tier Gold tiene **5 invitaciones mensuales**.
+* Las invitaciones **se resetean el día 1 de cada mes**.
+* El reseteo es automático mediante:
 
-2. Experiencia de Usuario (UX) y Filosofía de Diseño
+  * Supabase Edge Function **o**
+  * Cron Job externo.
+* El proceso debe ser:
 
-2.1 The Boutique — Interfaz de Clienta
+  * Idempotente.
+  * Auditado en `audit_logs`.
 
-Principios
+---
 
-Minimalismo extremo.
+## 4. Gestión de Tiempo y Zonas Horarias
 
-Eliminación total de fricción.
+* **Todos los timestamps se almacenan en UTC**.
+* `locations.timezone` define la zona local del salón.
+* Conversión a hora local:
 
-Diseño aspiracional, no comercial.
+  * Solo en frontend.
+  * Solo en notificaciones (WhatsApp / Email).
+* Backend, reglas de negocio y validaciones **operan exclusivamente en UTC**.
 
-Características Clave
+---
 
-Tipografía serif premium.
+## 5. Agenda y Bookings
 
-Espacios amplios y navegación guiada.
+### 5.1 Identificadores
 
-Sin contraseñas: autenticación vía Magic Links (Email / SMS).
+* Cada booking tiene:
 
-Flujo Lineal de Reserva
+  * `id` (UUID, primario).
+  * `short_id` (6 caracteres alfanuméricos).
 
-Selección de sucursal.
+### 5.2 Short ID — Reglas
 
-Selección de servicio(s).
+* Se genera antes de persistir el booking.
+* Debe verificarse unicidad.
+* Si existe colisión:
 
-Asignación de staff.
+  * Reintentar generación hasta ser único.
+* El Short ID:
 
-Selección de horario.
+  * Es referencia de pago.
+  * Es identificador operativo.
+  * **No sustituye** el UUID.
 
-Pago de depósito.
+---
 
-Confirmación.
+## 6. Pagos
 
-No existen bifurcaciones innecesarias.
+* Stripe como proveedor principal.
+* El Short ID se utiliza como referencia visible.
+* UUID se mantiene interno.
 
-2.2 The HQ — Dashboard Administrativo
+---
 
-Principios
+## 7. Auditoría
 
-Claridad operativa.
+* Toda acción automática o crítica debe registrarse en `audit_logs`.
+* Incluye:
 
-Control visual inmediato.
+  * Reseteo de invitaciones.
+  * Cambios de estado de bookings.
+  * Eventos de pago.
 
-Optimizado para escritorio y tablet.
+---
 
-Características
+## 8. Límites de los Agentes de IA
 
-Estética SquareUI.
+* Ningún agente puede modificar reglas aquí descritas.
+* Toda implementación debe alinearse estrictamente a este PRD.
 
-Calendario multi-columna:
-
-Columnas: profesionales.
-
-Filas: bloques de 15 minutos.
-
-Vista tipo Fresha, sin sobrecarga visual.
-
-3. Módulos y Lógica de Negocio
-
-3.1 Motor de Disponibilidad "Double-Lock"
-
-Una cita solo puede existir si se validan simultáneamente dos capas:
-
-Capa Humana
-
-Colaboradora activa.
-
-Dentro de horario laboral.
-
-Sin conflicto en Google Calendar personal.
-
-Capa Física
-
-Recurso físico requerido disponible.
-
-Sin colisión con otra reserva.
-
-Regla de Prioridad Dinámica
-Si existen más colaboradoras que estaciones físicas, el sistema limita la agenda según el recurso disponible.
-
-3.2 Servicios Express (Dual Staff)
-
-Servicios simultáneos diseñados para optimizar el tiempo de la clienta.
-
-Reglas
-
-Requiere dos colaboradoras disponibles en el mismo rango.
-
-Uso obligatorio del Sillón de Pedicura para Mani + Pedi.
-
-La mesa de manicura queda liberada para otra venta.
-
-Se aplica automáticamente un Premium Fee.
-
-El sistema trata el servicio dual como una sola entidad lógica.
-
-3.3 Ecosistema de Exclusividad (Invite-Only)
-
-No existe registro abierto.
-
-Reglas de Acceso
-
-Agenda solo disponible con código de invitación válido.
-
-Cuotas por Tier
-
-Regular: 2 invitaciones (lifetime).
-
-Gold: 5 invitaciones nuevas por mes.
-
-VIP: Ilimitadas.
-
-Tier Especial
-
-Believer: Clientas fundadoras.
-
-Ascienden a Gold con solo 2 citas completadas.
-
-3.4 Blindaje y Privacidad de Datos
-
-Vista del Staff
-
-Nombre de la clienta.
-
-Tier.
-
-Historial técnico.
-
-Información Oculta al Staff
-
-Teléfono.
-
-Email.
-
-Historial financiero.
-
-Audit Trail
-
-Toda acción queda registrada:
-
-Usuario.
-
-Timestamp.
-
-Motivo del cambio.
-
-4. Gestión Financiera y Depósitos Dinámicos
-
-4.1 Booking Fees
-
-Días Valle (Dom–Mié)
-
-Depósito fijo: $200 MXN.
-
-Días Premium (Jue–Sáb)
-
-Anticipo: 50% del total.
-
-Cada cita genera un Short ID de 6 caracteres, que funciona como:
-
-Referencia de pago.
-
-Identificador operativo.
-
-4.2 Política No-Show
-
-Captura de tarjeta vía Stripe.
-
-Ventana de cancelación: 12 horas.
-
-Penalización automática si no cumple.
-
-Condonación manual solo por Admin.
-
-5. Operación de Staff — The Vault
-
-Al cerrar una cita, la documentación es obligatoria.
-
-Contenido
-
-Fórmulas técnicas.
-
-Productos utilizados.
-
-Fotos Antes / Después.
-
-Traspaso de Personal
-
-Módulo para mover colaboradoras entre sucursales.
-
-Reasignación automática de citas.
-
-La información pertenece al negocio, no al staff.
-
-6. Arquitectura Técnica
-
-6.1 Stack
-
-Frontend: Next.js 14 + 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).
-
-7. Esquema de Base de Datos (Sugerido)
-
-locations
-
-resources
-
-staff
-
-services
-
-customers
-
-invitations
-
-bookings
-
-audit_logs
-
-Todas las tablas protegidas mediante Row Level Security.
-
-8. Roadmap de Desarrollo
-
-Fase 1 — Cimientos (Semanas 1–2)
-
-DB y Auth.
-
-Invitaciones.
-
-Tiers.
-
-Short IDs.
-
-Fase 2 — Motor de Agenda (Semanas 3–5)
-
-Doble Capa.
-
-Servicios Express.
-
-Google Calendar Sync.
-
-Fase 3 — Pagos (Semanas 6–7)
-
-Depósitos dinámicos.
-
-No-show logic.
-
-Fase 4 — HQ Dashboard (Semanas 8–9)
-
-Calendario multi-columna.
-
-Gestión de recursos.
-
-The Vault.
-
-Fase 5 — Lanzamiento (Semana 10)
-
-WhatsApp.
-
-Landing Believers.
-
-9. Resumen de Valor para la Dueña
-
-SalonOS entrega:
-
-Blindaje total del negocio.
-
-Optimización real del espacio físico.
-
-Crecimiento orgánico controlado.
-
-Protección financiera ante cancelaciones.
-
-Este documento define la visión técnica oficial de SalonOS. Cualquier modificación posterior al inicio de la Fase 1 impacta alcance, tiempos y costos.
-
-Proyecto: soul23
+---
 
+## 9. Estado del Documento
 
+Este PRD es la fuente única de verdad funcional del sistema SalonOS.

TASKS.md

@@ -1,15 +1,14 @@
-# TASKS.md — Plan de Ejecución por Agentes
+# TASKS.md — Plan de Ejecución por Fases
 
-Este documento define las tareas ejecutables del proyecto SalonOS, descompuestas para trabajo asistido por modelos (Claude, Codex, OpenCode, Gemini) y desarrollo humano.
-
-Las tareas están alineadas estrictamente con el PRD. No se permite introducir lógica no documentada.
+Este documento define las tareas ejecutables del proyecto **SalonOS**, alineadas estrictamente con el PRD. Ninguna tarea puede introducir lógica no documentada.
 
 ---
 
 ## Convenciones
 
-* Cada tarea debe producir artefactos verificables (código, migraciones, tests, docs).
+* Cada tarea produce artefactos verificables (código, migraciones, tests, documentación).
 * Las reglas de negocio viven en backend.
+* Todo automatismo debe ser auditable.
 * Ningún agente redefine alcance.
 
 ---
@@ -20,20 +19,21 @@ Las tareas están alineadas estrictamente con el PRD. No se permite introducir l
 
 * Crear proyecto Supabase.
 * Configurar Auth (Magic Links Email/SMS).
-* Definir RLS global por rol (Admin / Manager / Staff / Customer).
+* Definir roles: Admin / Manager / Staff / Customer.
+* Configurar RLS base por rol.
 
 **Output:**
 
-* Supabase project configurado.
+* Proyecto Supabase operativo.
 * Policies iniciales documentadas.
 
 ---
 
 ### 1.2 Esquema de Base de Datos Inicial
 
-Tablas:
+Tablas obligatorias:
 
-* locations
+* locations (incluye timezone)
 * resources
 * staff
 * services
@@ -44,27 +44,30 @@ Tablas:
 
 Tareas:
 
-* Definir migraciones SQL.
+* Definir migraciones SQL versionadas.
 * Claves foráneas y constraints.
 * Campos de auditoría (`created_at`, `updated_at`).
 
 **Output:**
 
-* Migraciones versionadas.
+* Migraciones SQL.
 * Diagrama lógico.
 
 ---
 
 ### 1.3 Short ID & Invitaciones
 
-* Generador de Short ID (6 chars, collision-safe).
+* Implementar generador de Short ID (6 chars, collision-safe).
+* Validación de unicidad antes de persistir booking.
 * Generador y validación de códigos de invitación.
-* Lógica de cuotas por Tier.
+* Lógica de cuotas mensuales por Tier.
+* Reseteo automático de invitaciones el día 1 de cada mes (UTC).
 
 **Output:**
 
 * Funciones backend.
 * Tests unitarios.
+* Registros en `audit_logs`.
 
 ---
 
@@ -88,7 +91,7 @@ Tareas:
 * Validación Staff:
 
   * Horario laboral.
-  * Eventos en Google Calendar.
+  * Eventos bloqueantes en Google Calendar.
 
 * Validación Recurso:
 
@@ -99,15 +102,14 @@ Tareas:
 **Output:**
 
 * Algoritmo de disponibilidad.
-* Tests de colisión.
+* Tests de colisión y concurrencia.
 
 ---
 
 ### 2.2 Servicios Express (Dual Staff)
 
 * Búsqueda de dos colaboradoras simultáneas.
-* Bloqueo de Sillón de Pedicura.
-* Liberación de mesa secundaria.
+* Bloqueo del recurso principal requerido.
 * Aplicación automática de Premium Fee.
 
 **Output:**
@@ -120,7 +122,7 @@ Tareas:
 ### 2.3 Google Calendar Sync
 
 * Integración vía Service Account.
-* Sync bidireccional.
+* Sincronización bidireccional.
 * Manejo de conflictos.
 
 **Output:**
@@ -134,8 +136,8 @@ Tareas:
 
 ### 3.1 Stripe — Depósitos Dinámicos
 
-* Regla $200 vs 50%.
-* Asociación pago ↔ booking.
+* Regla $200 vs 50% según día.
+* Asociación pago ↔ booking (UUID interno, Short ID visible).
 
 **Output:**
 
@@ -146,7 +148,7 @@ Tareas:
 
 ### 3.2 No-Show Logic
 
-* Ventana 12h.
+* Ventana de cancelación 12h (UTC).
 * Penalización automática.
 * Override Admin.
 
@@ -162,13 +164,13 @@ Tareas:
 ### 4.1 Calendario Multi-Columna
 
 * Vista por staff.
-* Bloques de 15 min.
+* Bloques de 15 minutos.
 
 ---
 
 ### 4.2 Gestión Operativa
 
-* Recursos.
+* Recursos físicos.
 * Staff.
 * Traspaso entre sucursales.
 
@@ -176,19 +178,19 @@ Tareas:
 
 ### 4.3 The Vault
 
-* Upload fotos privadas.
+* Upload de fotos privadas.
 * Formularios técnicos.
 
 ---
 
 ## FASE 5 — Automatización y Lanzamiento
 
-* WhatsApp confirmaciones.
+* Confirmaciones por WhatsApp.
 * Recibos digitales.
-* Landing Believers.
+* Landing Page Believers.
 
 ---
 
 ## Regla Final
 
-Si una tarea no está aquí, no existe.
+Si una tarea no está aquí, no existe. Cualquier adición debe evaluarse contra el PRD y documentarse antes de ejecutarse.