marcogll/AnchorOS
1
0
Fork 0
mirror of https://github.com/marcogll/AnchorOS.git synced 2026-03-15 16:24:30 +00:00
Code Issues Packages Projects Releases Wiki Activity

Definicion de proyecto

Browse Source
This commit is contained in:
Marco Gallegos
2026-01-15 12:11:43 -06:00
parent 11c0a43b61
commit ebbd9e3762
3 changed files with 162 additions and 345 deletions
Download Patch File Download Diff File Expand all files Collapse all files

106
AGENTS.md
View File

@@ -2,34 +2,38 @@
Este documento define cómo deben usarse agentes de IA (Claude, Codex, OpenCode, Gemini) dentro del proyecto SalonOS. 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 ## Principios de Uso de Agentes
* Los agentes **no deciden alcance**. - Los agentes no deciden alcance.
* Los agentes **no redefinen reglas de negocio**. - Los agentes no redefinen reglas de negocio.
* Toda salida debe ser revisable y versionable. - Los agentes no introducen lógica no descrita en el PRD.
* El PRD es la única fuente de verdad funcional. - 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. **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. **Usar para:**
* Revisión de consistencia con el PRD. - Descomposición de lógica compleja.
* Diseño de flujos y algoritmos. - Validación de consistencia con el PRD.
* Modelado de estados y edge cases. - Diseño de flujos y contratos lógicos.
**No usar para:** **No usar para:**
- Código final sin revisión humana.
* Código final sin revisión. - Decisiones visuales o de UX.
* Decisiones de UX visual.
--- ---
@@ -37,58 +41,74 @@ Ningún agente tiene autoridad de producto. Todos ejecutan bajo el PRD.
**Rol:** Ingeniero de backend. **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. **Usar para:**
* Funciones server-side. - SQL, migraciones y esquemas.
* Webhooks (Stripe, WhatsApp). - Funciones server-side.
* Integraciones API. - Webhooks (Stripe, WhatsApp).
- Integraciones API.
**Reglas:** **Reglas:**
- Todo código debe respetar RLS.
* Todo código debe respetar RLS. - No hardcodear secretos.
* 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. **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. **Usar para:**
* Integración frontend ↔ backend. - Componentes Next.js.
* Manejo de estados. - Integración frontend ↔ backend.
* Formularios y flujos. - Manejo de estado y formularios.
- Flujos de agenda y visualización.
**Reglas:** **Reglas:**
- No exponer datos privados.
* No exponer datos privados. - Validaciones críticas siempre en backend.
* Validaciones críticas en backend.
--- ---
## Gemini — QA & Seguridad ## Gemini — QA y Seguridad
**Rol:** Auditor técnico. **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. **Usar para:**
* Detección de fugas de datos. - Revisión de RLS.
* Edge cases de seguridad. - Detección de fugas de datos.
* Validación de flujos críticos. - 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.
--- ---

345
PRD.md
View File

@@ -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.

56
TASKS.md
View File

@@ -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. Este documento define las tareas ejecutables del proyecto **SalonOS**, alineadas estrictamente con el PRD. Ninguna tarea puede introducir lógica no documentada.
Las tareas están alineadas estrictamente con el PRD. No se permite introducir lógica no documentada.
--- ---
## Convenciones ## 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. * Las reglas de negocio viven en backend.
* Todo automatismo debe ser auditable.
* Ningún agente redefine alcance. * 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. * Crear proyecto Supabase.
* Configurar Auth (Magic Links Email/SMS). * 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:** **Output:**
* Supabase project configurado. * Proyecto Supabase operativo.
* Policies iniciales documentadas. * Policies iniciales documentadas.
--- ---
### 1.2 Esquema de Base de Datos Inicial ### 1.2 Esquema de Base de Datos Inicial
Tablas: Tablas obligatorias:
* locations * locations (incluye timezone)
* resources * resources
* staff * staff
* services * services
@@ -44,27 +44,30 @@ Tablas:
Tareas: Tareas:
* Definir migraciones SQL. * Definir migraciones SQL versionadas.
* Claves foráneas y constraints. * Claves foráneas y constraints.
* Campos de auditoría (`created_at`, `updated_at`). * Campos de auditoría (`created_at`, `updated_at`).
**Output:** **Output:**
* Migraciones versionadas. * Migraciones SQL.
* Diagrama lógico. * Diagrama lógico.
--- ---
### 1.3 Short ID & Invitaciones ### 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. * 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:** **Output:**
* Funciones backend. * Funciones backend.
* Tests unitarios. * Tests unitarios.
* Registros en `audit_logs`.
--- ---
@@ -88,7 +91,7 @@ Tareas:
* Validación Staff: * Validación Staff:
* Horario laboral. * Horario laboral.
* Eventos en Google Calendar. * Eventos bloqueantes en Google Calendar.
* Validación Recurso: * Validación Recurso:
@@ -99,15 +102,14 @@ Tareas:
**Output:** **Output:**
* Algoritmo de disponibilidad. * Algoritmo de disponibilidad.
* Tests de colisión. * Tests de colisión y concurrencia.
--- ---
### 2.2 Servicios Express (Dual Staff) ### 2.2 Servicios Express (Dual Staff)
* Búsqueda de dos colaboradoras simultáneas. * Búsqueda de dos colaboradoras simultáneas.
* Bloqueo de Sillón de Pedicura. * Bloqueo del recurso principal requerido.
* Liberación de mesa secundaria.
* Aplicación automática de Premium Fee. * Aplicación automática de Premium Fee.
**Output:** **Output:**
@@ -120,7 +122,7 @@ Tareas:
### 2.3 Google Calendar Sync ### 2.3 Google Calendar Sync
* Integración vía Service Account. * Integración vía Service Account.
* Sync bidireccional. * Sincronización bidireccional.
* Manejo de conflictos. * Manejo de conflictos.
**Output:** **Output:**
@@ -134,8 +136,8 @@ Tareas:
### 3.1 Stripe — Depósitos Dinámicos ### 3.1 Stripe — Depósitos Dinámicos
* Regla $200 vs 50%. * Regla $200 vs 50% según día.
* Asociación pago ↔ booking. * Asociación pago ↔ booking (UUID interno, Short ID visible).
**Output:** **Output:**
@@ -146,7 +148,7 @@ Tareas:
### 3.2 No-Show Logic ### 3.2 No-Show Logic
* Ventana 12h. * Ventana de cancelación 12h (UTC).
* Penalización automática. * Penalización automática.
* Override Admin. * Override Admin.
@@ -162,13 +164,13 @@ Tareas:
### 4.1 Calendario Multi-Columna ### 4.1 Calendario Multi-Columna
* Vista por staff. * Vista por staff.
* Bloques de 15 min. * Bloques de 15 minutos.
--- ---
### 4.2 Gestión Operativa ### 4.2 Gestión Operativa
* Recursos. * Recursos físicos.
* Staff. * Staff.
* Traspaso entre sucursales. * Traspaso entre sucursales.
@@ -176,19 +178,19 @@ Tareas:
### 4.3 The Vault ### 4.3 The Vault
* Upload fotos privadas. * Upload de fotos privadas.
* Formularios técnicos. * Formularios técnicos.
--- ---
## FASE 5 — Automatización y Lanzamiento ## FASE 5 — Automatización y Lanzamiento
* WhatsApp confirmaciones. * Confirmaciones por WhatsApp.
* Recibos digitales. * Recibos digitales.
* Landing Believers. * Landing Page Believers.
--- ---
## Regla Final ## 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.