From ebbd9e37629b27f82ffc90a4c5f6aea2e585b4c4 Mon Sep 17 00:00:00 2001 From: Marco Gallegos Date: Thu, 15 Jan 2026 12:11:43 -0600 Subject: [PATCH] Definicion de proyecto --- AGENTS.md | 106 ++++++++++------- PRD.md | 345 +++++++++++------------------------------------------- TASKS.md | 56 ++++----- 3 files changed, 162 insertions(+), 345 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index efaee28..b449941 100644 --- a/AGENTS.md +++ b/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. --- diff --git a/PRD.md b/PRD.md index 23cc9ec..c277f8c 100644 --- a/PRD.md +++ b/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. diff --git a/TASKS.md b/TASKS.md index 17d075f..0092d15 100644 --- a/TASKS.md +++ b/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.