trading-platform/docs/02-definicion-modulos/OQI-001-fundamentos-auth/historias-usuario/US-AUTH-004-oauth-facebook.md

id	title	type	status	priority	epic	story_points	created_date	updated_date
US-AUTH-004	OAuth Facebook	User Story	To Do	Alta	OQI-001	3	2025-12-05	2026-01-04

US-AUTH-004: OAuth Facebook

Version: 1.0.0 Fecha: 2025-12-05 Estado: Pendiente Story Points: 3 Prioridad: P1 (Alta) Épica: OQI-001

---

Historia de Usuario

Como visitante o usuario de Trading Platform Quiero poder registrarme e iniciar sesión usando mi cuenta de Facebook Para tener un acceso rápido y sencillo sin crear una nueva contraseña

---

Criterios de Aceptación

AC-001: Botón de Facebook visible

Dado que estoy en la página de registro o login Cuando veo las opciones de autenticación Entonces debería ver un botón "Continuar con Facebook" Y debería tener el color y logo oficial de Facebook

AC-002: Flujo de OAuth

Dado que hago click en "Continuar con Facebook" Cuando se abre la ventana de Facebook Entonces debería:

1. Ver la pantalla de autorización de Facebook
2. Poder revisar los permisos solicitados
3. Poder autorizar o cancelar

AC-003: Permisos solicitados

Dado que estoy en la pantalla de autorización de Facebook Cuando reviso los permisos Entonces la app debería solicitar únicamente:

• Email
• Nombre público
• Foto de perfil

AC-004: Primer registro exitoso

Dado que es mi primera vez usando Facebook OAuth Cuando autorizo los permisos Entonces debería:

1. Crear mi cuenta automáticamente
2. Recibir un JWT token
3. Ser redirigido al dashboard
4. Ver mi nombre y foto de Facebook
5. NO necesitar verificación de email

AC-005: Login existente

Dado que ya tengo una cuenta vinculada con Facebook Cuando uso "Continuar con Facebook" Entonces debería:

1. Iniciar sesión automáticamente
2. Ser redirigido al dashboard
3. NO ver pantalla de registro

AC-006: Email ya registrado con otro método

Dado que mi email de Facebook ya está registrado con email/password Cuando intento usar Facebook OAuth Entonces debería ver un mensaje:

• "Este email ya está registrado. ¿Deseas vincular tu cuenta de Facebook?" Y debería poder vincular las cuentas

AC-007: Cancelación del flujo

Dado que inicio el flujo de Facebook OAuth Cuando cancelo en la ventana de Facebook Entonces debería:

1. Volver a la página de login/registro
2. Ver un mensaje "Autenticación cancelada"
3. Poder intentar con otro método

AC-008: Error de Facebook

Dado que hay un error en el servicio de Facebook Cuando intento autenticarme Entonces debería ver un mensaje:

• "Error al conectar con Facebook. Intenta más tarde" Y debería poder usar otro método de autenticación

---

Mockup

┌─────────────────────────────────────────────────────────────┐
│                                                             │
│              🌟 Bienvenido a Trading Platform                     │
│                                                             │
│  ┌─────────────────────────────────────────────────────┐   │
│  │               📧 Email                               │   │
│  └─────────────────────────────────────────────────────┘   │
│                                                             │
│  ┌─────────────────────────────────────────────────────┐   │
│  │          🔵 Continuar con Facebook                   │   │
│  └─────────────────────────────────────────────────────┘   │
│                                                             │
│  ┌─────────────────────────────────────────────────────┐   │
│  │               🔴 Continuar con Google                │   │
│  └─────────────────────────────────────────────────────┘   │
│                                                             │
│  [Twitter/X]  [Apple]  [GitHub]                            │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Ventana de Facebook OAuth:
┌─────────────────────────────────────────────────────────────┐
│  facebook.com                                          ✕    │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│              Trading Platform desea acceder a:                     │
│                                                             │
│  ✓ Tu nombre y foto de perfil                              │
│  ✓ Tu dirección de email                                   │
│                                                             │
│  ┌─────────────────────────────────────────────────────┐   │
│  │              Continuar como Juan Pérez               │   │
│  └─────────────────────────────────────────────────────┘   │
│                                                             │
│  Cancelar                                                   │
│                                                             │
└─────────────────────────────────────────────────────────────┘

---

Tareas Técnicas

Database (DB)

• Agregar campos a tabla users:

  ALTER TABLE users ADD COLUMN facebook_id VARCHAR(255) UNIQUE;
  ALTER TABLE users ADD COLUMN avatar_url TEXT;
  

• Tabla oauth_connections:

  CREATE TABLE oauth_connections (
    id UUID PRIMARY KEY,
    user_id UUID REFERENCES users(id),
    provider VARCHAR(50), -- 'facebook', 'google', etc
    provider_user_id VARCHAR(255),
    access_token TEXT,
    refresh_token TEXT,
    token_expires_at TIMESTAMP,
    created_at TIMESTAMP DEFAULT NOW(),
    updated_at TIMESTAMP DEFAULT NOW(),
    UNIQUE(provider, provider_user_id)
  );
  

Backend (BE)

• Configurar Facebook App en Meta Developers
• Obtener App ID y App Secret
• Endpoint GET /api/v1/auth/facebook
  • Redirige a Facebook OAuth
• Endpoint GET /api/v1/auth/facebook/callback
  • Recibe código de autorización
  • Intercambia por access token
  • Obtiene datos del usuario
  • Crea o actualiza usuario
  • Genera JWT token
• Service FacebookOAuthService
  • getAuthorizationUrl()
  • exchangeCodeForToken()
  • getUserProfile()
  • linkAccount()
• Manejo de refresh tokens
• Tests unitarios (8 casos)
• Tests de integración con mock de Facebook API

Frontend (FE)

• Botón "Continuar con Facebook"
• Manejo de popup o redirect de OAuth
• Recepción de callback
• Almacenamiento de token JWT
• Estado de loading durante OAuth
• Manejo de errores
• Modal de vinculación de cuentas
• Tests con React Testing Library

Testing (QA)

• E2E: Registro nuevo con Facebook
• E2E: Login existente con Facebook
• E2E: Vinculación de cuentas
• E2E: Cancelación del flujo
• E2E: Permisos rechazados
• Test de seguridad: Validación de tokens
• Test de seguridad: CSRF protection
• Mock de Facebook API para tests

---

Dependencias

• Bloqueantes:

  • Cuenta de Facebook Developer
  • Configuración de dominio verificado
  • SSL/HTTPS en producción

• Deseables:

  • US-AUTH-003: Para mantener consistencia con Google OAuth

---

Definition of Ready (DoR)

• Facebook App creada y configurada
• Credenciales de desarrollo disponibles
• Mockups aprobados
• API contract definido
• Política de privacidad publicada (requerido por Facebook)

---

Definition of Done (DoD)

• Código implementado y revisado
• Tests unitarios con 80%+ cobertura
• Tests de integración pasando
• Tests E2E implementados
• Facebook App Review aprobado (para producción)
• Documentación actualizada
• Manejo de errores completo
• Logs implementados
• QA aprobado en staging
• Deploy a producción exitoso

---

Notas Técnicas

Facebook OAuth Flow

1. Frontend redirige a /api/v1/auth/facebook
2. Backend redirige a Facebook con:
   • client_id
   • redirect_uri
   • scope=email,public_profile
   • state (CSRF token)
3. Usuario autoriza en Facebook
4. Facebook redirige a redirect_uri con code
5. Backend intercambia code por access_token
6. Backend obtiene perfil del usuario
7. Backend crea/actualiza usuario
8. Backend genera JWT y redirige a frontend

Facebook API Endpoints

• Authorization: https://www.facebook.com/v18.0/dialog/oauth
• Token exchange: https://graph.facebook.com/v18.0/oauth/access_token
• User info: https://graph.facebook.com/v18.0/me?fields=id,name,email,picture

Environment Variables

FACEBOOK_APP_ID=your_app_id
FACEBOOK_APP_SECRET=your_app_secret
FACEBOOK_CALLBACK_URL=https://trading.com/api/v1/auth/facebook/callback

Security Considerations

• Validar state parameter para prevenir CSRF
• No almacenar access tokens en localStorage
• Usar refresh tokens cuando sea posible
• Validar que el email viene de Facebook
• Rate limiting en endpoints de OAuth

---

Requerimientos Relacionados

• RF-AUTH-003: OAuth Social

Especificaciones Relacionadas

• ET-AUTH-002: JWT Tokens
• ET-AUTH-004: OAuth Integration