OnAPB-Carrere_Demartin/misc/MANUAL_USUARIO.md

# 📖 Manual de Usuario — OnAPB
### Sistema de Gestión de Asociación de Básquet
> **Sitio:** [onapb.com](https://onapb.com)

---

## ¿A quién está dirigido este manual?

OnAPB es utilizado por cuatro tipos de personas. Este manual explica paso a paso qué puede hacer cada una:

| Capítulo | Perfil |
|---|---|
| [Capítulo 1](#cap1) | Visitantes (sin cuenta) |
| [Capítulo 2](#cap2) | Jugadores federados |
| [Capítulo 3](#cap3) | Aficionados / Hinchas |
| [Capítulo 4](#cap4) | Administradores de Club |
| [Capítulo 5](#cap5) | Súper Administradores (OnAPB) |

---

<a name="cap1"></a>
## 📌 Capítulo 1 — Visitante (Sin cuenta)

Cualquier persona puede ingresar a **onapb.com** sin necesidad de registrarse y acceder a información pública de la liga.

### 1.1 Página de Inicio (`/`)

Al entrar al sitio el visitante encuentra:

- **Carrusel / Hero**: Diapositivas destacadas configuradas por la asociación (noticias importantes, convocatorias, avisos).
- **Próximos Partidos**: Listado de los eventos más cercanos con día, hora y equipos.
- **Noticias recientes**: Artículos publicados por OnAPB.
- **Sponsors**: Franja rotativa con los patrocinadores de la liga visible en el pie de página.

### 1.2 Cartelera de Eventos (`/eventos`)

- Ver todos los partidos programados: próximos, en curso y finalizados.
- Cada tarjeta de evento muestra: equipos, categoría, fecha, hora y sede.
- Hacer clic en un evento abre el **detalle del partido** con información completa.
- Si el partido ya fue jugado, se muestran los marcadores finales.

### 1.3 Tabla de Posiciones y Goleadores de Torneo

- Desde la sección de torneos se puede ver:
  - **Posiciones** por grupo o categoría.
  - **Tabla de goleadores** del torneo con puntos acumulados.
  - **Bracket de Playoffs**: diagrama del cuadro eliminatorio cuando corresponde.

### 1.4 Noticias (`/noticias`)

- Listado de artículos publicados por la asociación con imagen, título y texto completo.

### 1.5 Promociones y Lugares con Beneficios (`/promos`)

- Mapa y/o listado de locales comerciales asociados que ofrecen descuentos a miembros de OnAPB.
- Ver información de cada comercio (nombre, dirección, beneficio).
- Para **obtener el QR de descuento** es necesario tener una cuenta y estar logueado.

### 1.6 Registrarse (`/asociate`)

Para obtener todos los beneficios del sistema, el visitante puede crear una cuenta. Existen dos vías:

#### Vía A — Registrarse como Aficionado
1. Ir a `/asociate` y seleccionar la pestaña **"Soy Aficionado"**.
2. Completar el formulario: Nombre, Apellido, DNI, Email, Fecha de Nacimiento (opcional), Teléfono (opcional), Localidad (opcional), Contraseña.
3. Resolver el **captcha de seguridad** (Cloudflare Turnstile).
4. Hacer clic en **Registrarme**.
5. El sistema envía un **correo de bienvenida** a la dirección ingresada.
6. ✅ Listo. Ya se puede iniciar sesión con DNI y contraseña.

#### Vía B — Activar cuenta como Jugador Federado
> *Para jugadores que ya fueron cargados en el sistema por el administrador de su club.*

1. Ir a `/asociate` y seleccionar la pestaña **"Soy Jugador"**.
2. Ingresar Nombre, Apellido y DNI (tal como aparecen en la ficha).
3. Aceptar los términos y hacer clic en **Buscar**.
4. El sistema valida los datos con el padrón. Si hay coincidencia, muestra la ficha del jugador (nombre, club, categoría).
5. Completar el formulario de activación: Email, Teléfono (opcional), Contraseña.
6. Resolver el **captcha de seguridad**.
7. Hacer clic en **Activar mi cuenta**.
8. El sistema envía un **correo de bienvenida**.
9. ✅ Listo. La cuenta queda activa y se puede iniciar sesión.

> **Nota:** Si el DNI no se encuentra en el padrón de jugadores, el sistema sugiere registrarse como Aficionado.

### 1.7 Iniciar Sesión

- Desde el menú superior hacer clic en **"Iniciar Sesión"** o ir a la pantalla de login.
- Se muestra un formulario con dos pestañas:
  - **Jugadores / Aficionados**: ingresar DNI y contraseña + captcha.
  - **Administradores**: ingresar usuario y contraseña + captcha.

### 1.8 Recuperar Contraseña (`/recuperar`)

En caso de olvidar la contraseña:
1. Ir a `/recuperar`.
2. Ingresar el **DNI** y la **dirección de email** asociados a la cuenta.
3. El sistema envía un enlace de restablecimiento válido por **1 hora**.
4. Hacer clic en el enlace del correo y establecer la nueva contraseña (mínimo 6 caracteres, requiere confirmación).

---

<a name="cap2"></a>
## 🏅 Capítulo 2 — Jugador Federado

Un jugador que ya activó su cuenta (Vía B de `/asociate`) tiene acceso a un **Panel de Usuario** con funcionalidades específicas para deportistas federados.

### 2.1 Iniciar Sesión

- En la pantalla de login, pestaña **"Jugadores / Aficionados"**.
- Ingresar **DNI** y **contraseña**.
- El sistema detecta automáticamente si la cuenta corresponde a un Jugador o Aficionado.

### 2.2 Panel de Usuario (`/panel-usuario`)

Al acceder al panel, el jugador ve de un vistazo:

- Sus **datos personales**: nombre, DNI, club, categoría calculada automáticamente por edad.
- Sus **equipos asignados** (puede pertenecer a varios equipos dentro de su club).
- **Resumen de QRs**: cantidad de pases de eventos solicitados.
- **Notificaciones** del sistema (ícono en el menú superior con contador).

### 2.3 Solicitar QR para un Partido

Esta es la funcionalidad principal del jugador federado. Permite obtener un **código QR de acceso** a un evento.

**Pasos:**
1. Desde el menú público o desde el panel, ir a **Eventos** y buscar el partido deseado.
2. Entrar al **detalle del partido**.
3. Si el partido está en estado *Próximo* o *En Curso*, aparece el botón **"Solicitar QR"**.
4. Hacer clic en el botón. El sistema verifica automáticamente:
   - Si el jugador **pertenece a uno de los equipos** del partido → genera la cantidad de QRs configurada (por defecto 3, para repartir entre familiares/acompañantes). Tipo: `invitado`.
   - Si el jugador es de **categoría Libre** pero no juega ese partido → genera 1 QR con descuento del 50%. Tipo: `libre_50`.
   - Si el jugador no cumple ninguna condición → el botón no estará disponible o muestra un mensaje explicativo.
5. ✅ El sistema genera los QRs y envía un **correo con los códigos** al email registrado.
6. El jugador es redirigido automáticamente a **Mis QRs** para ver los códigos generados.

> **Restricción:** Solo se puede solicitar QR una vez por partido. Si ya se solicitó, el botón queda inhabilitado con un mensaje informativo.

### 2.4 Mis QRs (`/panel-usuario/mis-qrs`)

- Lista de todos los códigos QR del jugador, ordenados del más reciente al más antiguo.
- Cada QR muestra:
  - Imagen del código QR (escaneable)
  - Evento al que pertenece (equipos, fecha, hora)
  - Estado: **Válido** / **Usado** (según si fue escaneado en puerta)
  - Tipo de QR (invitado, libre_50, etc.)
- Se puede filtrar por evento específico.

### 2.5 Beneficios de Promociones

1. Ir a **Promos** desde el menú principal.
2. Ver el mapa/listado de locales con beneficios.
3. Hacer clic en **"Obtener mi QR de beneficio"** en el local deseado.
4. El sistema genera un **QR de descuento único** para ese local.
5. Ver el QR en pantalla para presentarlo en el comercio.

> **Restricción:** Solo se puede generar 1 QR por local por usuario.

### 2.6 Seguir Equipos

- Desde la página pública de un equipo (`/equipos/{id}`), hacer clic en **"Seguir"**.
- Acceder a **Mis Equipos Seguidos** desde el Panel para ver el historial de partidos de los equipos favoritos.
- Hacer clic nuevamente en "Seguir" en un equipo ya seguido lo deja de seguir (toggle).

### 2.7 Notificaciones (`/notificaciones`)

- El ícono de campana en el menú muestra la cantidad de notificaciones no leídas.
- Las notificaciones pueden ser generadas por el sistema automáticamente (ej: "Tus QRs para el partido del sábado están disponibles").
- Desde el centro de notificaciones se puede:
  - **Marcar como leída** una notificación individual.
  - **Marcar todas como leídas**.
  - **Eliminar** notificaciones individuales.
  - **Eliminar todas** las notificaciones.

### 2.8 Editar Datos Personales

Desde el Panel de Usuario, sección **"Mi Cuenta"**:
- Actualizar **email** y **teléfono**.
- Los jugadores no pueden modificar su nombre, DNI o fecha de nacimiento (esos datos son gestionados por el admin del club).

### 2.9 Cambiar Contraseña

Desde el Panel de Usuario, sección **"Seguridad"**:
1. Ingresar la contraseña actual.
2. Ingresar la nueva contraseña (mínimo 6 caracteres).
3. Confirmar la nueva contraseña.
4. Guardar cambios.

### 2.10 Cerrar Sesión

- Hacer clic en **"Cerrar Sesión"** en el menú (esquina superior derecha o menú hamburguesa en móvil).
- La sesión se cierra de forma segura.

---

<a name="cap3"></a>
## 🎉 Capítulo 3 — Aficionado / Hincha

El aficionado tiene las mismas capacidades que el jugador en lo que respecta a disfrute de la plataforma, con algunas diferencias en la lógica de los QRs.

### 3.1 Inicio de Sesión y Registro

Idéntico al Jugador: login con DNI + contraseña. El registro es mediante la **Vía A** descripta en el Capítulo 1.

### 3.2 Panel de Usuario

Igual al del Jugador, con las siguientes diferencias visibles:
- **No se muestra** información de club ni categoría federada.
- El campo **"Localidad"** sí es editable (además de email y teléfono).

### 3.3 Solicitar QR para un Partido

El aficionado puede solicitar 1 QR por partido. A diferencia del jugador federado:
- No hay distinción por equipo ni categoría.
- Se genera 1 QR de tipo `publico`.
- En el futuro (Fase 6), este QR estará sujeto al pago de la entrada; actualmente se genera de forma directa.

El proceso es idéntico a los pasos 1–5 del apartado 2.3.

### 3.4 Mis QRs, Promociones, Notificaciones y Cuenta

Funciona exactamente igual que para el Jugador (ver apartados 2.4 al 2.10).

---

<a name="cap4"></a>
## 🏢 Capítulo 4 — Administrador de Club

El Admin de Club es el responsable designado de gestionar su institución dentro de OnAPB. Accede al panel de administración pero con alcance limitado exclusivamente a los datos de su club.

### 4.1 Inicio de Sesión

- En la pantalla de login, pestaña **"Administradores"**.
- Ingresar **usuario** (asignado por un Súper Admin) y **contraseña**.

### 4.2 Dashboard del Admin de Club (`/admin`)

Al ingresar, el Admin de Club ve:
- **Estadísticas rápidas** de su club: cantidad de equipos, jugadores y eventos relacionados.
- Nombre e identificación de su club.
- Accesos rápidos a los módulos disponibles.

### 4.3 Gestión de Jugadores (`/admin/jugadores`)

#### Ver listado de jugadores
- Lista de todos los jugadores pertenecientes a su club.
- Búsqueda por nombre, apellido o DNI.
- Cada jugador muestra: nombre, DNI, fecha de nacimiento, categoría (calculada automáticamente) y estado (activo/inactivo).

#### Crear un nuevo jugador
1. Hacer clic en **"Nuevo Jugador"**.
2. Completar el formulario:
   - DNI, Nombre, Apellido, Fecha de Nacimiento.
   - Club de Origen (puede ser cualquier club del sistema — útil para jugadores con pase).
   - El campo "Club Actual" se asigna automáticamente al club del administrador.
3. Guardar.
4. El jugador se crea con estado **inactivo**. Necesitará completar su registro en `/asociate` para activar su cuenta.

> **Validación:** Si el DNI ya existe en el sistema, se muestra un error indicando a qué club pertenece el jugador actualmente.

#### Editar un jugador
- Modificar datos básicos (nombre, apellido, fecha de nacimiento, teléfono).
- No puede cambiar el club actual del jugador (eso requiere un pase gestionado por el SuperAdmin).

#### Eliminar un jugador
- El jugador se marca como eliminado (SoftDelete). No se borra físicamente.

#### Importar jugadores desde CSV
1. Hacer clic en **"Importar CSV"**.
2. Subir un archivo CSV en formato CAB (Argentina Basketball) o formato interno.
3. El sistema detecta automáticamente el formato y procesa cada fila.
4. Al finalizar, muestra un resumen: nuevos creados, omitidos (ya existían), errores.

#### Exportar jugadores a CSV
- Descargar el listado completo de jugadores del club en formato CSV.
- Compatible con el reimportador interno del sistema.

### 4.4 Gestión de Equipos (`/admin/equipos`)

#### Ver listado de equipos
- Lista de los equipos del club con cantidad de jugadores.

#### Crear un nuevo equipo
1. Hacer clic en **"Nuevo Equipo"**.
2. Seleccionar **Categoría** (ej: U13, U15, U17, Primera) y Division (A, B, etc.).
3. El club se asigna automáticamente.

#### Editar y eliminar equipos
- Modificar categoría y división.
- Eliminar (SoftDelete).

#### Gestionar jugadores del equipo
1. Desde el listado de equipos, hacer clic en el ícono de jugadores (**"Ver Plantel"**).
2. Ver la lista de jugadores asignados a ese equipo.
3. **Agregar jugador**: buscar por nombre/apellido/DNI (búsqueda en tiempo real) y hacer clic en "Agregar".
   - Solo se pueden agregar jugadores del mismo club.
   - El sistema previene la asignación duplicada.
4. **Remover jugador**: hacer clic en "Quitar" al lado del jugador.

### 4.5 Editar Identidad Visual del Club (`/admin/clubes/{id}/editar`)

El Admin de Club puede personalizar la apariencia de su club dentro del sistema:

- **Logo/Escudo**: subir una imagen (JPEG, PNG, WEBP, máx. 1MB) que aparecerá asociada al club en toda la plataforma.
- **Fondo de QR** (QR Background): subir una imagen que se usará como fondo decorativo en los códigos QR generados para los partidos de su club.
- **Color de texto del QR**: ingresar un color hexadecimal para personalizar la tipografía sobre el QR.

### 4.6 Gestión de Pases / Traspasos (`/admin/pases`)

Los pases son solicitudes formales para transferir un jugador de un club a otro.

#### Solicitar un pase
1. Ir a **Pases** y hacer clic en **"Nuevo Pase"**.
2. Seleccionar el jugador a transferir y el club de destino.
3. Enviar la solicitud.
4. El Súper Admin recibirá la solicitud para aprobarla o rechazarla.

#### Ver estado de pases
- Listado de todos los pases solicitados por el club.
- Estado posible: **Pendiente**, **Aprobado**, **Rechazado**.

### 4.7 Escanear QR en Eventos (`/admin/escanear-qr`)

Esta funcionalidad es para usar en la puerta del evento el día del partido.

1. Ir a **"Escanear QR"** en el menú.
2. Seleccionar el **evento** (partido) a gestionar. Solo aparecen eventos relacionados con su club.
3. Activar la **cámara** del dispositivo o ingresar manualmente el código del QR.
4. El sistema valida el QR en tiempo real:
   - ✅ **QR Válido**: muestra nombre del titular, tipo de QR y pasa el estado a "Usado".
   - ❌ **QR Inválido o Ya Usado**: muestra el error correspondiente.

### 4.8 Cerrar Sesión

- Hacer clic en **"Cerrar Sesión"** en el menú del panel administrador.

---

<a name="cap5"></a>
## 👑 Capítulo 5 — Súper Administrador (OnAPB)

El Súper Admin tiene control total sobre todas las entidades del sistema. Es el personal de la asociación OnAPB.

### 5.1 Inicio de Sesión

Igual que el Admin de Club: pestaña "Administradores", usuario y contraseña.

### 5.2 Dashboard del Súper Admin (`/admin`)

Al ingresar, el Súper Admin ve:
- **Estadísticas globales**: total de clubes, equipos, jugadores, eventos, promociones y noticias en todo el sistema.
- Accesos rápidos a todos los módulos.

---

### 5.3 Módulo de Clubes (`/admin/clubes`)

#### Ver todos los clubes
- Lista de todos los clubes registrados con conteo de equipos y jugadores.

#### Crear un club
1. Clic en **"Nuevo Club"**.
2. Ingresar ID Club (numérico) y Nombre.
3. Guardar.

#### Editar un club
- Modificar nombre, logo, fondo de QR y color de texto. (Igual que el Admin de Club pero con acceso a cambiar el nombre también).

#### Eliminar un club
- El club se marca como eliminado (SoftDelete). Los equipos y jugadores asociados quedan preservados.

---

### 5.4 Módulo de Equipos (`/admin/equipos`)

Idéntico al del Admin de Club pero con visión global (todos los clubes). Al crear un equipo, el Súper Admin puede seleccionar cualquier club del sistema.

---

### 5.5 Módulo de Jugadores (`/admin/jugadores`)

#### Ver todos los jugadores
- Lista global de todos los jugadores de todos los clubes.
- Filtro por nombre, apellido o DNI.
- Paginación de 25 registros por página.

#### Crear, editar, eliminar jugador
- Idéntico al Admin de Club pero con acceso a cambiar el **Club Actual** (útil para finiquitar traspasos).

#### Importar / Exportar CSV
- Importación masiva de jugadores en formato CAB, Interno o Legado.
- Importar para un club específico (seleccionado en el formulario).

---

### 5.6 Módulo de Eventos / Partidos (`/admin/eventos`)

#### Ver todos los eventos
- Lista de todos los partidos con filtros por estado: Próximos, En Curso, Finalizados.

#### Crear un nuevo partido
1. Clic en **"Nuevo Evento"**.
2. Completar:
   - **Nombre del evento** (generado automáticamente en base a equipos).
   - **Equipo Local** y **Equipo Visitante** (deben ser de la misma categoría y grupo si pertenecen a un torneo).
   - **Fecha**, **Hora de Inicio** y **Hora de Fin**.
   - **Sede**.
   - **Torneo** (opcional): asignar el evento a un torneo existente.
   - **Límite de QRs por jugador** (configurable).
3. Guardar. El evento queda en estado **"Próximo"**.

#### Editar un partido
- Modificar cualquier campo del evento.

#### Registrar resultados
1. Desde el listado de eventos, entrar al evento.
2. Ir a la sección **"Cargar Estadísticas"** o **"Resultado"**.
3. Ingresar marcador local y marcador visitante.
4. Registrar puntos individuales por jugador (para la tabla de goleadores).
5. Guardar. El evento cambia automáticamente a estado **"Finalizado"**.

#### Eliminar un evento
- El evento se marca como eliminado (SoftDelete). Los QRs asociados se limpian.

---

### 5.7 Módulo de Torneos (`/admin/torneos`)

#### Crear un torneo
1. Clic en **"Nuevo Torneo"**.
2. Ingresar nombre y año.
3. Guardar.

#### Añadir equipos al torneo
Desde la vista del torneo:
1. Buscar el equipo a agregar.
2. Asignarle un **grupo** (ej: Grupo A, Grupo B) si aplica.
3. Guardar.

#### Generar Fixture de Fase Regular
1. Desde el torneo, ir a **"Generar Fixture"**.
2. Configurar la cantidad de vueltas (ida, ida y vuelta).
3. El sistema genera un **preview** de todos los partidos a jugarse.
4. Confirmar para crear los eventos en el sistema.

#### Importar resultados históricos
- Subir un CSV con resultados de partidos ya jugados para cargar históricos de torneos anteriores.

#### Gestionar Playoffs
1. Al finalizar la fase regular, ir a **"Playoffs"**.
2. Configurar cuántos equipos clasifican a playoffs.
3. Generar el bracket eliminatorio.
4. A medida que se juegan los partidos, **"Avanzar ganador"** al siguiente cruce.

#### Ver posiciones y goleadores
- Desde `/torneos/{id}/posiciones`: tabla de posiciones filtrable por grupo/categoría.
- Desde `/torneos/{id}/goleadores`: ranking de anotadores.
- Desde `/torneos/{id}/playoffs`: bracket visual del cuadro eliminatorio.

---

### 5.8 Módulo de Pases / Traspasos (`/admin/pases`)

#### Ver todos los pases
- Lista de todas las solicitudes de traspaso pendientes, aprobadas y rechazadas.

#### Aprobar o rechazar un pase
1. Desde el listado, hacer clic en el pase pendiente.
2. Revisar los datos: jugador, club origen, club destino.
3. Hacer clic en **"Aprobar"** → el jugador cambia de club automáticamente.
4. O hacer clic en **"Rechazar"** → el pase queda como rechazado y el jugador permanece en su club actual.

#### Crear un pase directamente
El Súper Admin puede ejecutar una transferencia sin necesidad de solicitud previa, seleccionando jugador, club destino y guardando.

---

### 5.9 Módulo de Noticias (`/admin/noticias`)

#### Crear una noticia
1. Clic en **"Nueva Noticia"**.
2. Completar: Título, Contenido (texto largo), Imagen (opcional).
3. Guardar. La noticia aparece en `/noticias`.

#### Editar y eliminar noticias
- Actualizar cualquier campo.
- Eliminar elimina la noticia del sitio público.

---

### 5.10 Módulo de Promociones (`/admin/promociones`)

#### Crear una promoción / local con beneficio
1. Clic en **"Nueva Promoción"**.
2. Completar: Nombre del local, Descripción del beneficio, Dirección, Imagen, Coordenadas (para el mapa).
3. Guardar. El local aparece en `/promos`.

#### Editar y eliminar promociones
- Actualizar información del local.
- Eliminar la promoción del sistema.

---

### 5.11 Módulo de Carrusel / Hero (`/admin/carousel`)

El carrusel es la sección de diapositivas destacadas en la portada del sitio.

#### Agregar una diapositiva
1. Clic en **"Nueva Diapositiva"**.
2. Subir una imagen (recomendado: formato ancho/horizontal).
3. Completar un enlace opcional (ej: enlace a una noticia o evento).
4. Guardar.

#### Editar y eliminar diapositivas
- Actualizar imagen o enlace.
- Eliminar la diapositiva del carrusel.

---

### 5.12 Módulo de Sponsors (`/admin/sponsors`)

#### Agregar un sponsor
1. Clic en **"Nuevo Sponsor"**.
2. Subir el logo del patrocinador.
3. Ingresar URL del sitio del sponsor (opcional).
4. Guardar. El logo aparece en la franja rotativa del pie de página.

#### Editar y eliminar sponsors
- Reemplazar logo o cambiar URL.
- Eliminar el sponsor de la franja.

---

### 5.13 Módulo de Usuarios Administradores (`/admin/usuarios`)

#### Ver todos los administradores
- Lista de todos los usuarios con acceso al panel de administración.

#### Crear un nuevo administrador
1. Clic en **"Nuevo Usuario Admin"**.
2. Ingresar:
   - **Usuario** (nombre de login).
   - **Contraseña**.
   - **Rol**: `1 = Súper Admin` o `2 = Admin de Club`.
   - **Club** (solo si rol 2): asociar al club que administrará.
3. Guardar.

#### Editar y eliminar administradores
- Cambiar contraseña, rol o club asignado.
- Eliminar el acceso de un administrador.

---

### 5.14 Módulo de Categorías (`/admin/categorias`)

Las categorías definen los rangos de edad de los jugadores (ej: U13 = 12-13 años).

#### Crear una categoría
1. Ingresar nombre (ej: "U13"), edad mínima (ej: 12) y edad máxima (ej: 13).
2. Marcar si es **"Categoría Libre"** (los jugadores de esta categoría obtienen 50% de descuento en entradas).
3. Guardar.

#### Editar y eliminar categorías
- Las categorías modificadas se aplican automáticamente a todos los jugadores ya existentes (la categoría se calcula dinámicamente).

---

### 5.15 Escanear QR en Eventos (`/admin/escanear-qr`)

Idéntico al del Admin de Club, pero con visión de todos los eventos del sistema. Ver apartado 4.7 para el proceso detallado.

---

### 5.16 Configuración General (`/admin/configuracion`)

Ajustes globales del sistema:
- Frecuencia de backups automáticos.
- Otros parámetros de comportamiento del sistema.

---

### 5.17 OnAPB Genius — Asistente de IA

El portal incluye un asistente conversacional basado en IA (Google Gemini) que permite consultar y operar el sistema mediante lenguaje natural. Se invoca desde el botón flotante del chat.

**Quién puede usar qué:**

| Rol | Tools disponibles |
|---|---|
| Visitante / Aficionado / Jugador | Chat de ayuda general del portal (sin acceso a operaciones) |
| Administrador de Club | Solo tools de **lectura** |
| Súper Administrador | Lectura + **escritura** + **rollback** |

**Tools disponibles para Súper Admin:**

**Lectura (consulta de datos):**
- `listar_torneos` — Lista todos los torneos con ID, nombre y fechas. Usala cuando necesites buscar el ID de un torneo por su nombre.
- `listar_equipos` — Lista equipos. Filtros opcionales: `id_torneo`, `grupo` ("A", "B", ...).
- `listar_eventos` — Lista partidos. Filtros opcionales: `fecha_desde`, `fecha_hasta` (formato YYYY-MM-DD), `id_torneo`.

**Escritura (modifican la base de datos — requieren tu confirmación explícita):**
- `crear_partido` — Crea un nuevo partido. Campos: `id_equipo_local`, `id_equipo_visitante`, `fecha_evento`, `hora_inicio`, `hora_fin`, `sede`, `id_torneo`.
- `cargar_puntaje` — Actualiza el marcador de un partido existente. Campos: `id_evento` (UUID), `marcador_local`, `marcador_visitante`.
- `redactar_noticia` — Publica una noticia. Campos: `titulo`, `contenido`, `id_torneo` (opcional), `categoria` (opcional).

**Rollback (deshacer una creación):**
- `eliminar_noticia` — Borra una noticia por su `id_noticia` (numérico).
- `eliminar_partido` — Borra (soft delete) un partido por su `id_evento` (UUID).

**Cómo se usa (flujo típico):**

1. Escribí en lenguaje natural lo que querés ("creá una noticia sobre el partido del sábado", "qué equipos hay en el torneo Apertura", "cargá el marcador del partido de ayer 78 a 65").
2. Si pedís una acción de escritura, Genius **primero te muestra un resumen** con los datos a usar y te pregunta "¿Confirmás?". Tenés que responder "sí", "dale", "confirmo" u "ok" para que ejecute.
3. Tras crear algo, Genius te devuelve el ID del recurso. Guardalo por si querés revertir.
4. Para deshacer: pedile "eliminá la noticia ID X" o "borrá el partido que acabás de crear". Volverá a pedir confirmación antes de borrar.

**Buenas prácticas:**

- Si mencionás un torneo/equipo por nombre, Genius usa `listar_torneos` / `listar_equipos` para resolver el ID. No hace falta que lo sepas de memoria.
- Verificá siempre el resumen de confirmación antes de responder "sí". La IA puede interpretar mal fechas o nombres ambiguos.
- Si algo sale mal, revisá `storage/logs/laravel.log` donde quedan registrados los errores de las tools.
- Los límites de la cuenta gratuita de Gemini están configurados en `.env` (`GENIUS_MAX_MESSAGES_PER_SESSION`, `GENIUS_SESSION_WINDOW_MINUTES`). Podés ajustarlos si cambia el uso.

---

## ❓ Preguntas Frecuentes

**¿Cómo sé si ya tengo una cuenta de jugador?**
Si sos jugador federado, tu DNI ya está en el sistema cargado por el admin de tu club. Solo debés ir a `/asociate` → pestaña "Soy Jugador" e ingresar tus datos para activar la cuenta.

**¿Puedo tener cuenta de jugador Y de aficionado con el mismo DNI?**
No. El sistema detecta si ya existe un registro (como jugador o aficionado) y te informa antes de permitir el registro.

**¿Qué pasa si el QR que generé fue escaneado?**
El estado del QR cambia a "Usado" y no puede ser utilizado nuevamente. Cada QR tiene un solo uso.

**¿Puedo generar el QR de una promo más de una vez?**
No. Por cada usuario y cada promoción, solo se puede generar un QR de beneficio.

**¿Qué significa cada tipo de QR?**
- `invitado` → Jugador que pertenece a un equipo del partido. Puede generar múltiples (para acompañantes).
- `libre_50` → Jugador de categoría Libre. Obtiene descuento del 50% en la entrada.
- `publico` → Aficionado. Acceso estándar.

---

*Manual redactado para el Proyecto Integrador OnAPB — Taller de Integración, FCYT UADER 2026.*