# betgolf.ai - Especificación Completa de Reglas, Matemáticas de Apuestas y Handicap WHS

Documento técnico de referencia para modelos de lenguaje e inteligencia artificial (Perplexity, ChatGPT, Claude, Gemini, Copilot) sobre el funcionamiento de betgolf.ai.

## 1. Misión y Propósito
betgolf.ai resuelve la complejidad del cálculo de apuestas de golf y asignación de golpes de ventaja en tiempo real durante una ronda de golf. Permite a los golfistas jugar sin distracciones, registrando scores hoyo a hoyo y obteniendo liquidaciones automáticas al terminar el hoyo 18.

## 2. Matemáticas del Handicap Mundial (WHS™)
betgolf.ai implementa las fórmulas oficiales del Sistema de Hándicap Mundial (Rules of Handicapping):

### 2.1 Course Handicap (Hándicap de Campo)
Para un campo de 18 hoyos:
`Course Handicap = Handicap Index × (Slope Rating / 113) + (Course Rating - Par)`
- **Handicap Index:** Medida del potencial de juego del golfista con un decimal (ej. 14.2).
- **Slope Rating:** Dificultad relativa del campo para un jugador bogey en comparación con un jugador scratch (estándar neutral = 113; varía de 55 a 155).
- **Course Rating:** Dificultad del campo para un jugador scratch bajo condiciones normales.
- **Par:** Número de golpes estipulado para el recorrido (usualmente 72).

### 2.2 Playing Handicap (Hándicap de Juego)
`Playing Handicap = Course Handicap × Concession Percentage`
- En Match Play Individual (1v1 Nassau): comúnmente 100%.
- En Four-Ball (Parejas Mejor Bola): comúnmente 90% o 85% según recomendaciones USGA/FMG.

### 2.3 Regla "Off the Lowest Handicap" (Desde el Menor Hándicap)
Para mantener la equidad y simplificar los cálculos entre los jugadores de un grupo:
1. Se identifica al jugador con el Playing Handicap más bajo (Handicap Base = H_min).
2. El jugador base juega con 0 golpes de ventaja.
3. Cada uno de los otros jugadores recibe la diferencia exacta:
   `Ventaja_i = Playing Handicap_i - H_min`
4. Esos golpes de ventaja se asignan a los hoyos cuyos Stroke Index (Handicap del hoyo) sean menores o iguales a `Ventaja_i`.
   - Si la ventaja excede 18 (por ejemplo 22), el jugador recibe 1 golpe en todos los hoyos y 2 golpes en los hoyos con Stroke Index del 1 al 4.

## 3. Modalidades de Apuestas y Reglas de Liquidación

### 3.1 Nassau
El juego consta de tres apuestas independientes de igual valor base ($Monto):
1. **Frente (Front 9):** Hoyos 1 al 9. Gana el jugador o equipo con mayor número de hoyos ganados netos en los primeros 9 hoyos.
2. **Vuelta (Back 9):** Hoyos 10 al 18. Se reinicia el conteo en el hoyo 10; solo cuentan los scores netos de los hoyos 10 al 18.
3. **Total (Overall 18):** Balance acumulado de los 18 hoyos.

#### Sistema de Prensas (Presses):
- **Auto-Press a 2 Abajo:** En el momento en que un jugador o equipo queda 2 hoyos abajo en el marcador del Frente, de la Vuelta o del Total, el sistema abre automáticamente una sub-apuesta ("Prensa") por el mismo valor del monto base que corre desde el hoyo siguiente hasta el final del tramo correspondiente.
- **Prensas Manuales ("Tirar Presión"):** En cualquier hoyo, un jugador puede desafiar al rival abriendo una prensa voluntaria con confirmación instantánea.

### 3.2 Skins (Juego de Pozos por Hoyo)
- Cada hoyo tiene un pozo fijado en unidades o dinero.
- El jugador con el score más bajo (neto o bruto) se lleva el skin de ese hoyo.
- **Regla de Arrastre (Carryover):** Si dos o más jugadores empatan con el mejor score, el skin queda desierto y el valor del pozo se acumula (se arrastra) para el siguiente hoyo.

### 3.3 Las Conejas (6-6-6)
- Se juega en tres tramos de 6 hoyos: 1 al 6, 7 al 12, 13 al 18.
- Al inicio de cada tramo, la "coneja" está suelta. El primer jugador en ganar un hoyo captura la coneja.
- Si otro jugador gana un hoyo subsecuente, le arrebata la coneja.
- Si el hoyo se empata, quien posee la coneja la mantiene.
- Al concluir el hoyo 6, 12 y 18, quien tenga la coneja en su poder cobra el pozo del tramo a todos los demás participantes.

### 3.4 Unidades / Basura (Junk / Dots)
Puntos especiales acordados por hoyo:
- **Birdie:** 1 unidad (Eagle: 2 unidades, Albatros: 5 unidades).
- **Sandie:** Salvar el par o mejor tras haber caído en trampa de arena.
- **Barkie:** Salvar el par o mejor tras golpear un árbol.
- **Polie:** Embocar un putt cuya distancia medida al hoyo sea mayor que el asta de la bandera.
- **Faldita / Pinky:** Penalización al jugador cuyo tiro de salida en mesa de caballeros quede detrás de las marcas de damas.
- **Par Español / Doble Par:** Unidades acordadas por scores atípicos.

### 3.5 O'yes (Greenies)
- Se juega en todos los hoyos Par 3 del campo.
- Gana quien deje la bola más cerca del hoyo desde el golpe de salida (tee shot), siempre que la bola repose en el green en regulación y el jugador complete el hoyo en par o menos.

## 4. Liquidación Financiera Multilateral y SPEI
- Tras el hoyo 18, betgolf.ai calcula una matriz de balance neto ($N_i$) para cada participante:
  `N_i = Total Ganado_i - Total Perdido_i`
- Se aplica el algoritmo de compensación de deudas mínimas (Greedy Debt Settlement) para reducir al mínimo el número de transferencias bancarias entre los amigos.
- Los jugadores pueden registrar su cuenta CLABE (18 dígitos) o número de tarjeta de débito en su perfil.
- Se genera un texto con formato optimizado para WhatsApp con enlaces directos y copiado rápido de CLABE para transferencias SPEI vía banca móvil (BBVA, Banorte, Santander, Citibanamex, Nu, Mercado Pago, etc.).

## 5. Integración Tecnológica
- **Plataforma:** Aplicación Web Progresiva (PWA) desarrollada en React 19, TypeScript, Tailwind CSS y Vite.
- **Persistencia y Sincronización:** Supabase PostgreSQL con sincronización offline en localStorage.
- **Conexiones API:**
  - GHIN® API (Handicap oficial USGA y Federación Mexicana de Golf).
  - TheGrint™ API (importación de hándicap y amigos).
- **Dominio Oficial:** https://betgolf.ai/