# SmashPoint - Documento de Diseño

**Fecha:** 2026-02-01
**Estado:** Aprobado
**Versión:** 1.0

---

## Resumen Ejecutivo

Sistema integral de gestión para cadena de clubes de pádel con múltiples sedes. Incluye gestión de reservas, punto de venta, torneos/ligas y membresías.

### Alcance

| Aspecto | Decisión |
|---------|----------|
| **Tipo de usuario** | Dueño de club/canchas |
| **Escala** | Múltiples sedes |
| **Modelo de negocio** | Mixto (reservas por hora + membresías) |
| **Funcionalidades** | Reservas, Torneos/Ligas, Punto de Venta, Membresías |
| **Pagos** | Efectivo, transferencias, terminal física |
| **Plataformas** | Web (admin) + App móvil (clientes) |

---

## Arquitectura

### Enfoque: Monolito Moderno

```
┌─────────────────────────────────────────┐
│           Next.js (Web + API)           │
│  ┌─────────┐ ┌─────────┐ ┌───────────┐  │
│  │ Admin   │ │ API     │ │ Auth      │  │
│  │ Panel   │ │ Routes  │ │ (NextAuth)│  │
│  └─────────┘ └─────────┘ └───────────┘  │
└─────────────────────────────────────────┘
         │                    │
         ▼                    ▼
┌─────────────────┐   ┌───────────────────┐
│   PostgreSQL    │   │  React Native App │
│   (Prisma ORM)  │   │   (Clientes)      │
└─────────────────┘   └───────────────────┘
```

### Stack Técnico

| Capa | Tecnología |
|------|------------|
| **Frontend Web** | Next.js 14, TypeScript, Tailwind CSS, shadcn/ui, React Query |
| **Backend/API** | Next.js API Routes, Prisma ORM, NextAuth.js, Zod |
| **Base de datos** | PostgreSQL |
| **Mobile** | React Native, Expo, TypeScript, NativeWind |
| **Infraestructura** | Vercel/VPS, Railway/Supabase (DB), Cloudinary |

---

## Módulos del Sistema

```
┌────────────────────────────────────────────────────────────┐
│                    SMASHPOINT - MÓDULOS                      │
├──────────────┬──────────────┬──────────────┬───────────────┤
│   RESERVAS   │    TORNEOS   │     POS      │   MEMBRESÍAS  │
│              │              │              │               │
│ • Calendario │ • Crear      │ • Productos  │ • Planes      │
│ • Disponib.  │   torneos    │ • Ventas     │ • Beneficios  │
│ • Booking    │ • Brackets   │ • Caja       │ • Renovación  │
│ • Bloqueos   │ • Rankings   │ • Cortes     │ • Historial   │
└──────────────┴──────────────┴──────────────┴───────────────┘
                              │
              ┌───────────────┴───────────────┐
              │         CORE (Base)           │
              │  • Multi-sede                 │
              │  • Usuarios y roles           │
              │  • Clientes                   │
              │  • Pagos y caja               │
              │  • Reportes                   │
              └───────────────────────────────┘
```

---

## Roles de Usuario

| Rol | Permisos |
|-----|----------|
| **Super Admin** | Todas las sedes, reportes consolidados, configuración global |
| **Admin de Sede** | Gestiona una sede específica, reservas, caja y personal |
| **Recepcionista** | Opera reservas, cobra, registra pagos, atiende clientes |
| **Cliente (App)** | Reserva canchas, ve partidos, inscribe a torneos |

---

## Modelo de Datos

### Entidades Core

```prisma
// Organización y Sedes
model Organization {
  id        String   @id @default(cuid())
  name      String
  logo      String?
  sites     Site[]
  users     User[]
  clients   Client[]
  createdAt DateTime @default(now())
}

model Site {
  id             String       @id @default(cuid())
  organizationId String
  organization   Organization @relation(fields: [organizationId], references: [id])
  name           String
  address        String
  phone          String?
  openTime       String       // "08:00"
  closeTime      String       // "22:00"
  courts         Court[]
  users          User[]
  products       Product[]
  tournaments    Tournament[]
  createdAt      DateTime     @default(now())
}

model Court {
  id           String        @id @default(cuid())
  siteId       String
  site         Site          @relation(fields: [siteId], references: [id])
  name         String
  type         CourtType     @default(DOUBLES)
  pricePerHour Decimal
  premiumPrice Decimal?      // Precio horario premium
  status       CourtStatus   @default(ACTIVE)
  bookings     Booking[]
}

enum CourtType {
  SINGLES
  DOUBLES
  MIXED
}

enum CourtStatus {
  ACTIVE
  MAINTENANCE
  INACTIVE
}

// Usuarios y Clientes
model User {
  id             String       @id @default(cuid())
  organizationId String
  organization   Organization @relation(fields: [organizationId], references: [id])
  siteId         String?
  site           Site?        @relation(fields: [siteId], references: [id])
  email          String       @unique
  password       String
  name           String
  phone          String?
  role           UserRole
  createdAt      DateTime     @default(now())
}

enum UserRole {
  SUPER_ADMIN
  SITE_ADMIN
  RECEPTIONIST
}

model Client {
  id             String        @id @default(cuid())
  organizationId String
  organization   Organization  @relation(fields: [organizationId], references: [id])
  email          String        @unique
  password       String
  name           String
  phone          String?
  photo          String?
  balance        Decimal       @default(0)
  membership     Membership?
  bookings       Booking[]
  createdAt      DateTime      @default(now())
}

// Reservas
model Booking {
  id          String        @id @default(cuid())
  courtId     String
  court       Court         @relation(fields: [courtId], references: [id])
  clientId    String
  client      Client        @relation(fields: [clientId], references: [id])
  date        DateTime
  startTime   String        // "10:00"
  endTime     String        // "11:00"
  price       Decimal
  status      BookingStatus @default(PENDING)
  paymentType PaymentType?
  isPaid      Boolean       @default(false)
  notes       String?
  payments    Payment[]
  createdAt   DateTime      @default(now())
  createdBy   String?       // User ID si fue creada por staff
}

enum BookingStatus {
  PENDING
  CONFIRMED
  CANCELLED
  COMPLETED
}

enum PaymentType {
  CASH
  TRANSFER
  CARD_TERMINAL
}

// Pagos
model Payment {
  id        String      @id @default(cuid())
  amount    Decimal
  method    PaymentType
  reference String?
  bookingId String?
  booking   Booking?    @relation(fields: [bookingId], references: [id])
  saleId    String?
  sale      Sale?       @relation(fields: [saleId], references: [id])
  createdBy String      // User ID
  createdAt DateTime    @default(now())
}

// Membresías
model MembershipPlan {
  id             String       @id @default(cuid())
  organizationId String
  name           String
  price          Decimal
  freeHours      Int
  bookingDiscount Int         // Porcentaje
  storeDiscount  Int          // Porcentaje
  extraBenefits  String?
  memberships    Membership[]
}

model Membership {
  id        String         @id @default(cuid())
  clientId  String         @unique
  client    Client         @relation(fields: [clientId], references: [id])
  planId    String
  plan      MembershipPlan @relation(fields: [planId], references: [id])
  startDate DateTime
  endDate   DateTime
  hoursUsed Int            @default(0)
  status    MembershipStatus @default(ACTIVE)
}

enum MembershipStatus {
  ACTIVE
  EXPIRED
  CANCELLED
}

// Punto de Venta
model ProductCategory {
  id       String    @id @default(cuid())
  name     String
  products Product[]
}

model Product {
  id         String          @id @default(cuid())
  siteId     String
  site       Site            @relation(fields: [siteId], references: [id])
  categoryId String
  category   ProductCategory @relation(fields: [categoryId], references: [id])
  name       String
  price      Decimal
  stock      Int             @default(0)
  minStock   Int             @default(5)
  saleItems  SaleItem[]
}

model Sale {
  id        String     @id @default(cuid())
  siteId    String
  items     SaleItem[]
  total     Decimal
  payments  Payment[]
  createdBy String
  createdAt DateTime   @default(now())
}

model SaleItem {
  id        String  @id @default(cuid())
  saleId    String
  sale      Sale    @relation(fields: [saleId], references: [id])
  productId String
  product   Product @relation(fields: [productId], references: [id])
  quantity  Int
  price     Decimal
}

// Control de Caja
model CashRegister {
  id           String   @id @default(cuid())
  siteId       String
  openedBy     String
  closedBy     String?
  openingAmount Decimal
  closingAmount Decimal?
  expectedAmount Decimal?
  openedAt     DateTime @default(now())
  closedAt     DateTime?
  status       CashRegisterStatus @default(OPEN)
}

enum CashRegisterStatus {
  OPEN
  CLOSED
}

// Torneos
model Tournament {
  id           String              @id @default(cuid())
  siteId       String
  site         Site                @relation(fields: [siteId], references: [id])
  name         String
  description  String?
  date         DateTime
  endDate      DateTime?
  type         TournamentType
  category     String?             // A, B, C o null si no aplica
  maxTeams     Int
  price        Decimal
  status       TournamentStatus    @default(DRAFT)
  inscriptions TournamentInscription[]
  matches      Match[]
}

enum TournamentType {
  SINGLE_ELIMINATION
  DOUBLE_ELIMINATION
  ROUND_ROBIN
  LEAGUE
}

enum TournamentStatus {
  DRAFT
  OPEN
  IN_PROGRESS
  FINISHED
  CANCELLED
}

model TournamentInscription {
  id           String     @id @default(cuid())
  tournamentId String
  tournament   Tournament @relation(fields: [tournamentId], references: [id])
  player1Id    String
  player2Id    String?    // Para parejas
  teamName     String?
  createdAt    DateTime   @default(now())
}

model Match {
  id           String     @id @default(cuid())
  tournamentId String
  tournament   Tournament @relation(fields: [tournamentId], references: [id])
  round        Int
  position     Int
  team1Id      String?
  team2Id      String?
  score1       String?
  score2       String?
  winnerId     String?
  courtId      String?
  scheduledAt  DateTime?
  status       MatchStatus @default(PENDING)
}

enum MatchStatus {
  PENDING
  IN_PROGRESS
  FINISHED
}
```

---

## Flujos Principales

### Flujo de Reserva - Cliente (App)

1. Cliente abre app y selecciona sede
2. Elige fecha en calendario
3. Ve horarios disponibles con precios
4. Selecciona horario y confirma
5. Reserva queda como PENDIENTE
6. Al llegar, staff cobra y marca como PAGADA

### Flujo de Reserva - Recepcionista (Web)

1. Ve calendario visual de canchas
2. Click en slot disponible
3. Busca cliente existente o crea nuevo
4. Si cliente presente: cobra y confirma
5. Si no presente: reserva pendiente

### Flujo de Venta POS

1. Recepcionista abre pantalla de caja
2. Agrega productos al ticket
3. Opcionalmente agrega reserva al mismo ticket
4. Selecciona método de pago
5. Registra pago y cierra venta

### Flujo de Torneo

1. Admin crea torneo (nombre, fecha, categoría, precio)
2. Abre inscripciones
3. Clientes se inscriben desde app
4. Admin cierra inscripciones y genera bracket
5. Asigna horarios y canchas
6. Registra resultados de partidos
7. Sistema avanza bracket automáticamente

---

## Diseño Visual

### Paleta de Colores

| Uso | Color | Hex |
|-----|-------|-----|
| Primario | Azul profundo | #1E3A5F |
| Acento | Verde pádel | #22C55E |
| Fondo | Blanco/Gris claro | #F8FAFC |
| Texto | Gris oscuro | #1E293B |
| Éxito | Verde | #22C55E |
| Alerta | Ámbar | #F59E0B |
| Error | Rojo suave | #EF4444 |

### Principios de Diseño

1. **Minimalista**: Solo información esencial en pantalla
2. **Touch-friendly**: Botones grandes en móvil (mínimo 44px)
3. **Feedback visual**: Confirmaciones claras, estados visibles
4. **Responsive**: Admin funciona en desktop y tablet
5. **Modo oscuro**: Opcional para ambas plataformas
6. **Consistencia**: Mismos patrones en web y móvil

### Componentes UI (shadcn/ui)

- Calendario de reservas (vista día/semana)
- Cards para estadísticas
- Tablas con filtros y búsqueda
- Modales para formularios
- Toast notifications
- Sidebar navegación colapsable

---

## Estructura del Proyecto

```
smashpoint/
├── apps/
│   ├── web/                  # Next.js (Admin + API)
│   │   ├── app/
│   │   │   ├── (admin)/      # Panel administrativo
│   │   │   │   ├── dashboard/
│   │   │   │   ├── bookings/
│   │   │   │   ├── pos/
│   │   │   │   ├── tournaments/
│   │   │   │   ├── clients/
│   │   │   │   ├── memberships/
│   │   │   │   ├── reports/
│   │   │   │   └── settings/
│   │   │   ├── (auth)/
│   │   │   │   ├── login/
│   │   │   │   └── forgot-password/
│   │   │   └── api/
│   │   │       ├── auth/
│   │   │       ├── bookings/
│   │   │       ├── clients/
│   │   │       ├── courts/
│   │   │       ├── products/
│   │   │       ├── sales/
│   │   │       ├── tournaments/
│   │   │       └── reports/
│   │   ├── components/
│   │   │   ├── ui/           # shadcn components
│   │   │   ├── booking/
│   │   │   ├── pos/
│   │   │   └── layout/
│   │   └── lib/
│   │       ├── db.ts
│   │       ├── auth.ts
│   │       └── utils.ts
│   │
│   └── mobile/               # React Native (Clientes)
│       ├── app/              # Expo Router
│       │   ├── (tabs)/
│       │   │   ├── index.tsx      # Home/Reservar
│       │   │   ├── bookings.tsx   # Mis reservas
│       │   │   ├── tournaments.tsx
│       │   │   └── profile.tsx
│       │   ├── (auth)/
│       │   └── booking/[id].tsx
│       ├── components/
│       └── services/
│           └── api.ts
│
├── packages/
│   └── shared/
│       ├── types/
│       └── validations/
│
├── prisma/
│   ├── schema.prisma
│   └── seed.ts
│
├── docs/
│   └── plans/
│
├── turbo.json
├── package.json
└── README.md
```

---

## Consideraciones de Seguridad

- Autenticación JWT con refresh tokens
- Passwords hasheados con bcrypt
- Validación de inputs con Zod
- Rate limiting en API
- CORS configurado correctamente
- Variables sensibles en environment

---

## Próximos Pasos

1. Inicializar monorepo con Turborepo
2. Configurar base de datos y Prisma
3. Implementar autenticación
4. Desarrollar módulo de reservas (core)
5. Agregar POS
6. Implementar torneos
7. Desarrollar app móvil
8. Testing y QA
9. Deploy a producción

---

*Documento generado colaborativamente - Febrero 2026*