---
type: SPEC
asset_id: SPEC-REB-RClub-CatalogosAfiliacion-v01
version: v01
status: Ratificado (catálogos §2–§4 aprobados por Victor 2026-06-16) · implementación pendiente Jesús
owner: Victor Heredia
sherpa_owner: Jay
ratificador: Victor Heredia
fecha_ratificacion: 2026-06-16
dirigido_a: Victor (ratificación de catálogos) + Jesús (implementación)
fecha_creacion: 2026-06-11
fecha_ultima_actualizacion: 2026-06-16
intellbank: IB-REB-Rebelocity
subbank: —
tipo_largo: Especificación de catálogos de afiliación de Rebelocity Club (comunidad 20) para parametrizar la generación de tarjetas, más el proceso de completado y mantenimiento de los catálogos.
audiencia: Victor + Jesús (dev) + producto
proposito: Definir la porción mínima parametrizable que permite arrancar la afiliación de miembros de Rebelocity Club (tipo de afiliado, canal, convención de grupos, grupo por defecto), y el proceso/sistema para completar y alimentar esos catálogos en el tiempo. Deriva de SPEC-REB-RClub-NumeracionTarjetas-v02.
referencias_canonicas:
  - SPEC-REB-RClub-NumeracionTarjetas-v02 (esquema del PAN · decisión Opción A)
  - DC-REB-RClub-SistemaPuntosMembresias-v01 (motor Points v2 · user_cards · referrals · affiliated_organizations)
  - SPEC-REB-RClub-ArquitecturaDatos-RegistroPerfil-v01 (registro/perfil)
  - SPEC-REB-RClub-DirectorioMiembros-v02 (caso equipos de relevo 5150)
  - RFI-EL-PlataformaComunidades-AfiliacionTarjetaPuntos-v01 (capa de afiliación)
---

## Asset Header

- **Asset ID:** SPEC-REB-RClub-CatalogosAfiliacion-v01
- **Version:** v01
- **Status:** ✅ Ratificado — catálogos §2–§4 aprobados por Victor (2026-06-16). Implementación pendiente (Jesús).
- **Owner:** Victor Heredia · **Sherpa:** Jay · **Ratificador:** Victor Heredia
- **IntellBank:** IB-REB-Rebelocity
- **Tipo:** SPEC — Especificación de catálogos + proceso
- **Última actualización:** 2026-06-16

---

# SPEC · Catálogos de Afiliación — Rebelocity Club (comunidad `20`)

## Parametrización para acuñar tarjetas + proceso para alimentar los catálogos

---

## 0. Idea rectora

Para empezar a afiliar **no hace falta** tener todos los catálogos completos. El número de tarjeta (PAN, ver `…-NumeracionTarjetas-v02`) tiene cinco dimensiones; para Rebelocity Club, cuatro ya están resueltas o tienen un valor por defecto, y solo **dos catálogos pequeños y fijos** necesitan ratificación para empezar:

| Dimensión del PAN | Estado para arrancar RClub |
|---|---|
| Red (`9`) | Fija. |
| Comunidad (`20`) | Fija = Rebelocity Club. |
| **Tipo de afiliado** | **Catálogo a ratificar** (pequeño, 5–6 valores). |
| **Canal de afiliación** | **Catálogo a ratificar** (pequeño, 5–6 valores). |
| Grupo / empresa | Por defecto `0010` (individual/B2C). `0000` queda reservado como "sin asignar / inválido". Los grupos crecen **después**, bajo demanda. |
| Secuencial | Automático (lo asigna el sistema), **arranca en `100000`** (no en 1). |

> **Conclusión:** ratificando dos tablas chicas (§2 y §3) y aceptando `0010` como grupo individual por defecto (§4), ya se pueden acuñar tarjetas de los **miembros fundadores** de Rebelocity Club. El resto del catálogo (grupos) se alimenta de forma incremental.

---

## 1. Catálogo de comunidad (contexto)

| Campo | Valor |
|---|---|
| Código de comunidad (P2–P3) | `20` |
| `org_code` (Points v2) | `CLUB` |
| Modelo de arranque | **B2C individual** (grupo `0010`) — miembros fundadores |

---

## 2. Catálogo: TIPO DE AFILIADO (P8) — a ratificar

Categoría de persona, para segmentación y beneficios. Es mayormente estable; si cambia (un menor cumple 18) se trata como **reemisión** de tarjeta, no como edición. Propuesta alineada al ADN de deportes de resistencia (incluye IRONKIDS):

| Código | Tipo de afiliado | Nota |
|---|---|---|
| `0` | Atleta / titular adulto (estándar) | Default de la mayoría. |
| `1` | Menor de edad | IRONKIDS / categorías junior. Requiere consentimiento de tutor. |
| `2` | Tercera edad / máster sénior | Para beneficios o categorías de edad. |
| `3` | Condición especial / paradeporte (PcD) | Accesibilidad / inclusión. |
| `4` | Beneficiario / familiar dependiente | Afiliado vinculado a un titular. |
| `5`–`9` | Reservado | Crecimiento futuro. |

---

## 3. Catálogo: CANAL DE AFILIACIÓN (P9) — a ratificar

Categoría de **cómo entró** el miembro. El afiliador específico (qué embajador, qué evento exacto) va en BD; aquí solo la categoría. Propuesta basada en los canales reales de Rebelocity (LinkedIn/landing, eventos, embajadores, sponsors, referidos):

| Código | Canal | Nota |
|---|---|---|
| `0` | Directo / web (landing + onboarding KatIA) | Default del tráfico orgánico. |
| `1` | Promotor / embajador | Campo, influencers, capitanes de club. |
| `2` | Club / equipo deportivo | Alta a través de un club afiliado. |
| `3` | Evento | 5150 · IRONMAN 70.3 · L'Étape · IRONKIDS. |
| `4` | Alianza / sponsor | Frutika · Ueno/ITTI · Powerade · GenTV. |
| `5` | Referido (member-get-member) | **Se enlaza con el sistema de referidos** de Points v2 (`referrals`). |
| `6`–`9` | Reservado | Crecimiento futuro. |

---

## 4. Catálogo: GRUPO / EMPRESA (P4–P7) — convención + crecimiento bajo demanda

Para RClub el grueso es **individual** (`0010`). Los grupos solo se crean cuando aparece una entidad real (un club, un sponsor que activa una cohorte, un evento que emite tarjetas). Convención de numeración (ajustada 2026-06-16 para evitar el "look" de tarjeta vacía/de prueba):

| Bloque | Uso | Ejemplos |
|---|---|---|
| `0000` | **Reservado — "sin asignar / inválido"** (sentinel) | Nunca se emite. Evita confundir grupo con campo vacío. |
| `0001`–`0009` | Reservado / sistema | Sandbox, migraciones, casos especiales. |
| `0010` | **Individual / B2C (default)** | Miembros fundadores, altas directas. |
| `0011`–`0099` | Marcas / sponsors | Cohorte Frutika, cohorte Powerade. |
| `0100`–`0999` | Clubs / equipos deportivos | Tri-club X, equipo de relevo Y. |
| `1000`–`8999` | Cohortes de evento | Finishers 5150-2026, IRONKIDS-2026. |
| `9000`–`9999` | Reservado / pruebas | Sandbox, migraciones. |

> Cada grupo, al darse de alta, recibe el **siguiente código libre dentro de su bloque** y arranca su propio secuencial. **El secuencial arranca en `100000`** (no en 1) para que ningún número revele la escala ni se vea un `000003`; da ~900,000 miembros por bucket (rango `100000`–`999999`).

---

## 5. Mínimo viable para acuñar la primera tarjeta

Con esto el sistema ya puede generar un PAN válido:

```
Comunidad = 20 (fija)
Grupo     = 0010 (default individual)
Tipo      = (del catálogo §2, según el alta)
Canal     = (del catálogo §3, según el alta)
Secuencial= siguiente disponible para (20, 0010), arranca en 100000
Luhn      = calculado
```

Ejemplo — primer miembro fundador, atleta adulto, alta web (secuencial `100000`):
`9 20 0010 0 0 100000` → PAN **`9200 0100 0100 0007`** *(dígito Luhn verificado).*

---

## 6. Proceso para COMPLETAR el catálogo (una sola vez, ahora)

1. **Ratificar §2 (tipo de afiliado)** — Victor confirma o ajusta los 5 valores.
2. **Ratificar §3 (canal)** — Victor confirma o ajusta los 6 valores.
3. **Aceptar la convención de grupos §4** y el default `0010` (`0000` reservado como inválido).
4. **Sembrar en BD** — Jesús carga estos valores en las tablas de catálogo (`affiliate_types`, `affiliation_channels`, `card_groups`) y registra la comunidad `20`/`CLUB`.
5. **Smoke test** — acuñar 3–5 tarjetas de prueba (sandbox grupo `9000`), validar unicidad + Luhn, y borrar.

Tras estos 5 pasos, la afiliación de RClub queda **abierta**.

---

## 7. El SISTEMA para ALIMENTAR el catálogo en el tiempo (3 fases)

La pregunta de fondo ("cómo lo voy alimentando") se resuelve por fases, de lo más simple a lo más automatizado:

**Fase 0 — Fuente de verdad documental (ahora).**
El catálogo vive ratificado en este SPEC. Cualquier valor nuevo se agrega aquí (sube versión) y Jesús lo siembra en BD. Sirve para arrancar sin construir nada.

**Fase 1 — Tabla de configuración + alta asistida (corto plazo).**
Los catálogos viven en tablas (`affiliate_types`, `affiliation_channels`, `card_groups`). Alta de un grupo nuevo vía un endpoint/admin simple que **asigna automáticamente el siguiente código libre del bloque**, valida unicidad y registra metadatos (nombre, estado, fechas). Reutiliza los endpoints de organizaciones/miembros que ya contempla el RFI.

**Fase 2 — Admin UI + autoservicio (mediano plazo).**
Pantalla interna para crear grupos/canales/tipos sin tocar BD; opcionalmente, autoservicio para que un club o sponsor solicite su grupo y quede en estado `pending` hasta aprobación. Integra atribución comercial por afiliador si se requiere (comisiones).

### 7.1 Gobernanza del catálogo (reglas permanentes)

- **Owner por catálogo:** tipo de afiliado y canal → Producto/Victor. Grupos → operación de afiliación.
- **Asignación de código:** siempre el **siguiente libre** del bloque; **nunca se reutiliza** un código dado de baja.
- **Estados:** cada entrada tiene `activo | inactivo | pending`. Inactivar no borra ni libera el código.
- **Versionado:** cambios a los catálogos fijos (tipo/canal) suben versión de este SPEC; alta de grupos no requiere nueva versión (es operación normal).
- **Inmutabilidad aguas abajo:** cambiar el código de un valor ya usado en tarjetas emitidas está **prohibido** (rompería PANs). Si hay error, se crea valor nuevo y se migra por reemisión.

---

## 8. Flujo de alta de un miembro (afiliación → acuñado del PAN)

```
1. Captura de alta (form / evento / club / API)
   → datos del registro (ver SPEC-…-RegistroPerfil) + grupo + tipo + canal + afiliador
2. Persistir en `affiliations` (incluye affiliated_by_user_id = afiliador específico)
3. Card Service (único autorizado a acuñar):
   a. Resuelve community_code (20) + group_code
   b. Pide secuencial atómico a card_sequences(20, group)
   c. Arma base15 = 9·20·grupo·tipo·canal·secuencial
   d. Calcula Luhn → PAN de 16 díg.
   e. Inserta en user_cards (card_id UUID + card_number PAN + qr_secret)
4. Devuelve tarjeta digital (PAN visible + QR firmado sobre card_id)
```

> **Nota de arquitectura:** que **un solo servicio** (Card Service) tenga el monopolio de acuñar PANs centraliza Luhn, la asignación de secuencial y la unicidad. Todos los canales de alta (web, evento, club, import masivo) llaman a ese servicio; ninguno arma el número por su cuenta.

---

## 9. Sugerencias adicionales (más allá de lo que pediste)

1. **Arrancar B2C puro (grupo `0010`).** No fragmentar en grupos al inicio. Para el rally de miembros fundadores y los equipos de relevo del 5150, `0010` basta. Crea grupos solo cuando un club o sponsor real lo justifique. Evita "boil the ocean".
2. **Card Service como único acuñador** (ver §8) — decisión arquitectónica que conviene fijar desde el día 1.
3. **Import masivo de eventos.** Para finishers de 5150/70.3 ya existentes, prever una carga batch que cree altas → cohorte de evento (bloque `1000+`) → tarjetas. Convierte tu base de eventos en miembros con tarjeta de un golpe.
4. **Enlazar canal `5` (referido) con el motor de referidos** que ya existe en Points v2: la afiliación por referido alimenta a la vez el PAN (canal 5) y los puntos de referido (+200/+100). Doble valor sin doble trabajo.
5. **Tarjeta fundadora como gancho.** Aunque el nivel no va en el número, sí puedes marcar a los primeros N como "fundadores" en BD/arte (badge) — palanca de pertenencia para el lanzamiento.

---

## 10. Pendientes / decisiones para Victor

| # | Decisión | Quién | Estado |
|---|---|---|---|
| 1 | Ratificar catálogo **tipo de afiliado** (§2) | Victor | ✅ Ratificado 2026-06-16 |
| 2 | Ratificar catálogo **canal** (§3) | Victor | ✅ Ratificado 2026-06-16 |
| 3 | Aceptar convención de **grupos** (§4) y default `0010` (`0000` = reservado/inválido) | Victor | ✅ Ratificado 2026-06-16 |
| 4 | ¿Arrancamos **B2C puro** o habrá grupos/clubs desde el día 1? | Victor | ⏳ Pendiente |
| 5 | ¿Hay **import masivo** de finishers de eventos en el arranque? | Victor | ⏳ Pendiente |
| 6 | Sembrar catálogos en BD + smoke test | Jesús | ⏳ Pendiente (desbloqueado) |

---

> **Tripleta WORX** — Owner: Victor Heredia · Sherpa: Jay · Ratificador: Victor Heredia. **Catálogos §2–§4 ratificados 2026-06-16** → afiliación de Rebelocity Club habilitada. Quedan pendientes las decisiones operativas #4–#5 y la siembra en BD (#6).