2

misc/MANUAL_USUARIO.md

@@ -0,0 +1,648 @@
+# 📖 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.*