feat(club-005): club registered users: account linking and automatic recovery

work/artifacts/CLUB-005/architect.md

@@ -0,0 +1,34 @@
+# Architect — CLUB-005
+
+## Objetivo
+Vincular socios anónimos a cuentas registradas de usuario, restaurar la tarjeta automáticamente al login y manejar fusión segura de membresías.
+
+## Diseño
+
+### 1. Restauración automática de tarjeta al login
+El endpoint `GET /club/me` ya lo hace — comprueba `userId` primero, luego cae back a device token. No se necesita cambio.
+
+### 2. Vincular miembro anónimo a cuenta registrada (`PATCH /club/me`)
+- El frontend llama a este endpoint después de login/register cuando hay cookie `mdv_club`
+- Requiere sesión (autenticado)
+- Usa el device token de la cookie para encontrar el socio anónimo
+- Actualiza `user_id` del socio anónimo al userId de la sesión
+- Si el usuario ya tiene un socio vinculado → retorna `linked: false`, no sobreescribe
+
+### 3. Fusión de membresías (`POST /club/merge`)
+- Para cuando el usuario tiene un socio anónimo (device) Y un socio registrado (userId)
+- El socio registrado es el primario (se conserva)
+- El socio anónimo se marca como `merged`, su saldo se suma al primario
+- Los dispositivos del anónimo se transfieren al primario
+- Los recovery codes del anónimo expiran (no se transfieren)
+
+### Seguridad
+- `PATCH /club/me` requiere sesión — no se puede vincular sin estar autenticado
+- `POST /club/merge` requiere sesión y solo usa el socio del usuario autenticado como primario
+- La transacción de merge usa `FOR UPDATE` para evitar race conditions
+
+### Endpoints nuevos
+| Método | Ruta | Auth | Descripción |
+|--------|------|------|-------------|
+| PATCH | `/club/me` | sesión | Vincular miembro anónimo a cuenta |
+| POST | `/club/merge` | sesión | Fusionar miembro anónimo en el registrado |