# Grupo

Endpoints para la pantalla de **Grupos** en la app DeportesCam.
Todos requieren Bearer token (`auth:api_padel`).

---

## Flujo para crear un grupo

```
1. Abrir pantalla "Crear grupo"
   └── GET /grupo/datos-formulario
       └── Retorna nombre y noJugador del socio autenticado para pre-poblar el form

2. Usuario escribe en el buscador para agregar miembros
   └── GET /registro-padel/buscar?search=...
       └── Retorna socios activos que coincidan con el término

3. Usuario selecciona miembros de los resultados (front maneja la selección)

4. Usuario completa el nombre del grupo y confirma
   └── POST /grupo/guardar   ← (próximamente)
       ├── grupoAlias
       ├── idDeporte (Base64)
       └── miembros: [idRegistroPadel, ...]
```

---

## GET /deportescam/grupo/datos-formulario

Retorna los datos del socio autenticado para pre-poblar el formulario de creación de grupo.

**Autenticación:** Requerida  
**Middleware:** `auth:api_padel`, `seguridadFSG`, `throttle:60,1`

### Respuesta 200

```json
{
  "success": true,
  "message": "Datos obtenidos correctamente.",
  "data": {
    "nombre": "CENTRO ASTURIANO DE MÉXICO",
    "noJugador": 3
  }
}
```

---

## GET /deportescam/registro-padel/buscar

Busca socios activos por número de jugador o nombre del beneficiario.
Usar al seleccionar miembros durante la creación de un grupo.
Retorna máximo **20 resultados**.

**Autenticación:** Requerida  
**Middleware:** `auth:api_padel`, `seguridadFSG`, `throttle:60,1`

### Query params

| Param | Tipo | Requerido | Descripción | Ejemplo |
|-------|------|-----------|-------------|---------|
| `search` | string | Sí | Término de búsqueda — busca en número de jugador y nombre del beneficiario | `ASTURIANO` |

```
GET /api/v1/deportescam/registro-padel/buscar?search=asturiano
GET /api/v1/deportescam/registro-padel/buscar?search=3
```

### Respuesta 200

```json
{
  "success": true,
  "message": "Búsqueda realizada correctamente.",
  "data": [
    {
      "idRegistroPadel": "MQ==",
      "noJugador": 3,
      "nombre": "CENTRO ASTURIANO DE MÉXICO",
      "username": "GAMP230618"
    },
    {
      "idRegistroPadel": "Mg==",
      "noJugador": 7,
      "nombre": "ASTURIANO NORTE",
      "username": "ANOR240101"
    }
  ]
}
```

> **Nota:** El front maneja el estado de selección — el backend siempre retorna los resultados de búsqueda sin importar qué esté seleccionado.  
> `idRegistroPadel` viene en **Base64** para usarse directamente al crear el grupo.

### Respuesta 422 — Sin término de búsqueda

```json
{
  "success": false,
  "message": "Debe indicar un término de búsqueda."
}
```

### Respuesta 401 — Token inválido o ausente

```json
{
  "message": "Unauthenticated."
}
```

### Respuesta 500 — Error interno

```json
{
  "success": false,
  "message": "Descripción del error interno."
}
```

---

## POST /deportescam/grupo/guardar

Crea un nuevo grupo con los miembros seleccionados.
El socio autenticado **debe estar incluido** en la lista de miembros.
Genera automáticamente el `grupoNo` (año + secuencial de 6 dígitos, ej. `2026000001`).
Registra una invitación en `pad_solicitudgrupo` por cada miembro con estado `Solicitada`.
Bitácora acción **31**.

**Autenticación:** Requerida  
**Middleware:** `auth:api_padel`, `seguridadFSG`, `throttle:60,1`

### Body (JSON)

| Campo | Tipo | Requerido | Descripción | Ejemplo |
|-------|------|-----------|-------------|---------|
| `grupoAlias` | string | Sí | Nombre del grupo (mín. 3, máx. 150 caracteres) | `Los Ases del Pádel` |
| `idDeporte` | string | Sí | ID del deporte en **Base64** | `Mg==` |
| `miembros` | array | Sí | IDs de los socios en **Base64** (debe incluir al socio autenticado) | `["MQ==","Mg=="]` |
 
```json
{
  "grupoAlias": "Los Ases del Pádel",
  "idDeporte": "Mg==",
  "miembros": ["MQ==", "Mg==", "Mw=="]
}
```

### Respuesta 200 — Grupo creado

```json
{
  "success": true,
  "message": "Grupo creado correctamente.",
  "data": {
    "idGrupo": "MQ==",
    "grupoNo": "2026000001"
  }
}
```

### Respuesta 422 — Socio autenticado no incluido

```json
{
  "success": false,
  "status": 422,
  "message": "Tienes errores de validación",
  "errors": {
    "miembros": ["Debes incluirte como miembro del grupo."]
  }
}
```

### Respuesta 422 — Grupo duplicado (mismo nombre y miembros)

```json
{
  "success": false,
  "status": 422,
  "message": "Tienes errores de validación",
  "errors": {
    "grupoAlias": ["Ya tienes un grupo con el mismo nombre y los mismos miembros."]
  }
}
```

### Respuesta 422 — Errores de validación

```json
{
  "success": false,
  "status": 422,
  "message": "Tienes errores de validación",
  "errors": {
    "grupoAlias": ["El nombre del grupo debe tener al menos 3 caracteres."],
    "idDeporte": ["El deporte seleccionado no existe."]
  }
}
```

### Respuesta 500 — Error interno

```json
{
  "success": false,
  "message": "Ocurrió un error al crear el grupo. Intente de nuevo."
}
```

> El error queda registrado en `base_error` con el contexto completo: alias del grupo, deporte, número de miembros e `idRegistroPadel` del socio que realizó la operación.

### Respuesta 401 — Token inválido o ausente

```json
{
  "message": "Unauthenticated."
}
```