# TRACEABILITY.yml - OQI-001 Fundamentos y Autenticación
# Mapeo de requerimientos a implementación

version: "1.0.0"
epic: OQI-001
name: "Fundamentos y Autenticación Multi-proveedor"
updated: "2025-12-05"
status: completed

# Resumen de trazabilidad
summary:
  total_requirements: 5
  total_specs: 5
  total_user_stories: 12
  total_files_implemented: 25
  test_coverage: "TBD"

# Mapeo de Requerimientos Funcionales
requirements:
  RF-AUTH-001:
    name: "OAuth Multi-proveedor"
    status: implemented
    specs:
      - ET-AUTH-001
    user_stories:
      - US-AUTH-003
      - US-AUTH-004
      - US-AUTH-005
      - US-AUTH-006
      - US-AUTH-007
    implementation:
      backend:
        - path: apps/backend/src/modules/auth/services/oauth.service.ts
          description: "Servicio OAuth para todos los proveedores"
        - path: apps/backend/src/modules/auth/controllers/auth.controller.ts
          methods:
            - getOAuthUrl
            - handleOAuthCallback
            - unlinkOAuthProvider
        - path: apps/backend/src/modules/auth/auth.routes.ts
          routes:
            - "GET /auth/oauth/:provider/url"
            - "POST /auth/oauth/:provider"
            - "DELETE /auth/oauth/:provider"
      frontend:
        - path: apps/frontend/src/modules/auth/components/SocialLoginButtons.tsx
          description: "Botones de login social"
        - path: apps/frontend/src/modules/auth/pages/AuthCallback.tsx
          description: "Página de callback OAuth"
      database:
        - path: apps/database/schemas/01b_oauth_providers.sql
          tables:
            - oauth_accounts
          enums:
            - auth_provider_enum
    tests:
      - path: apps/backend/tests/auth/oauth.service.test.ts
        status: pending

  RF-AUTH-002:
    name: "Autenticación Email/Password"
    status: implemented
    specs:
      - ET-AUTH-002
      - ET-AUTH-003
    user_stories:
      - US-AUTH-001
      - US-AUTH-002
      - US-AUTH-011
    implementation:
      backend:
        - path: apps/backend/src/modules/auth/services/email.service.ts
          description: "Servicio de autenticación por email"
        - path: apps/backend/src/modules/auth/services/token.service.ts
          description: "Servicio de tokens JWT"
        - path: apps/backend/src/modules/auth/controllers/auth.controller.ts
          methods:
            - register
            - login
            - logout
            - refreshToken
            - forgotPassword
            - resetPassword
            - verifyEmail
        - path: apps/backend/src/modules/auth/validators/auth.validators.ts
          description: "Validadores Zod"
      frontend:
        - path: apps/frontend/src/modules/auth/pages/Login.tsx
        - path: apps/frontend/src/modules/auth/pages/Register.tsx
        - path: apps/frontend/src/modules/auth/pages/ForgotPassword.tsx
        - path: apps/frontend/src/modules/auth/pages/ResetPassword.tsx
        - path: apps/frontend/src/modules/auth/pages/VerifyEmail.tsx
      database:
        - path: apps/database/schemas/01_public_schema.sql
          tables:
            - users
            - user_profiles
            - email_verifications
            - password_reset_tokens
    tests:
      - path: apps/backend/tests/auth/email.service.test.ts
        status: pending

  RF-AUTH-003:
    name: "Autenticación por Teléfono"
    status: implemented
    specs:
      - ET-AUTH-004
    user_stories:
      - US-AUTH-008
      - US-AUTH-009
    implementation:
      backend:
        - path: apps/backend/src/modules/auth/services/phone.service.ts
          description: "Servicio de autenticación por teléfono (Twilio)"
        - path: apps/backend/src/modules/auth/controllers/auth.controller.ts
          methods:
            - sendPhoneOTP
            - verifyPhoneOTP
      frontend:
        - path: apps/frontend/src/modules/auth/components/PhoneLoginForm.tsx
          description: "Formulario de login por teléfono"
      database:
        - path: apps/database/schemas/01b_oauth_providers.sql
          tables:
            - phone_verifications
          enums:
            - phone_channel_enum
      external:
        - service: Twilio
          usage:
            - SMS OTP
            - WhatsApp OTP
    tests:
      - path: apps/backend/tests/auth/phone.service.test.ts
        status: pending

  RF-AUTH-004:
    name: "Two-Factor Authentication"
    status: implemented
    specs:
      - ET-AUTH-005
    user_stories:
      - US-AUTH-010
    implementation:
      backend:
        - path: apps/backend/src/modules/auth/services/twofa.service.ts
          description: "Servicio 2FA con TOTP"
        - path: apps/backend/src/modules/auth/controllers/auth.controller.ts
          methods:
            - setup2FA
            - enable2FA
            - verify2FA
            - disable2FA
            - getBackupCodes
      frontend:
        - path: apps/frontend/src/modules/settings/pages/Security.tsx
          description: "Configuración de 2FA"
      database:
        - path: apps/database/schemas/01_public_schema.sql
          columns:
            - users.two_factor_enabled
            - users.two_factor_secret
            - users.backup_codes
    tests:
      - path: apps/backend/tests/auth/twofa.service.test.ts
        status: pending

  RF-AUTH-005:
    name: "Gestión de Sesiones"
    status: implemented
    specs:
      - ET-AUTH-002
    user_stories:
      - US-AUTH-012
    implementation:
      backend:
        - path: apps/backend/src/modules/auth/services/token.service.ts
          methods:
            - generateTokens
            - verifyAccessToken
            - verifyRefreshToken
            - rotateRefreshToken
            - revokeRefreshToken
        - path: apps/backend/src/modules/auth/controllers/auth.controller.ts
          methods:
            - getSessions
            - revokeSession
            - revokeAllSessions
        - path: apps/backend/src/core/middleware/auth.middleware.ts
          description: "Middleware de autenticación"
      frontend:
        - path: apps/frontend/src/modules/settings/pages/Sessions.tsx
          description: "Gestión de sesiones activas"
      database:
        - path: apps/database/schemas/01b_oauth_providers.sql
          tables:
            - sessions
    tests:
      - path: apps/backend/tests/auth/session.service.test.ts
        status: pending

# Mapeo de archivos de configuración
config_files:
  backend:
    - path: apps/backend/src/config/index.ts
      description: "Configuración centralizada"
    - path: apps/backend/.env.example
      description: "Variables de entorno de ejemplo"
  frontend:
    - path: apps/frontend/src/stores/auth.store.ts
      description: "Store de autenticación Zustand"
    - path: apps/frontend/src/services/api.ts
      description: "Cliente API con interceptores"

# Dependencias externas
external_dependencies:
  npm_backend:
    - name: jsonwebtoken
      version: "^9.0.2"
      usage: "JWT tokens"
    - name: bcryptjs
      version: "^2.4.3"
      usage: "Password hashing"
    - name: passport
      version: "^0.7.0"
      usage: "OAuth strategies"
    - name: speakeasy
      version: "^2.0.0"
      usage: "TOTP 2FA"
    - name: twilio
      version: "^4.19.3"
      usage: "SMS/WhatsApp"
    - name: nodemailer
      version: "^6.9.7"
      usage: "Email sending"
    - name: zod
      version: "^3.22.4"
      usage: "Validation"
  npm_frontend:
    - name: "@tanstack/react-query"
      version: "^5.0.0"
      usage: "Data fetching"
    - name: zustand
      version: "^4.4.0"
      usage: "State management"
    - name: react-hook-form
      version: "^7.48.0"
      usage: "Forms"

# APIs de terceros
third_party_apis:
  - name: Google OAuth
    docs: https://developers.google.com/identity/protocols/oauth2
    scopes:
      - profile
      - email
  - name: Facebook OAuth
    docs: https://developers.facebook.com/docs/facebook-login
    scopes:
      - email
      - public_profile
  - name: Twitter OAuth 2.0
    docs: https://developer.twitter.com/en/docs/authentication/oauth-2-0
    scopes:
      - tweet.read
      - users.read
  - name: Apple Sign In
    docs: https://developer.apple.com/documentation/sign_in_with_apple
    scopes:
      - name
      - email
  - name: GitHub OAuth
    docs: https://docs.github.com/en/apps/oauth-apps
    scopes:
      - read:user
      - user:email
  - name: Twilio
    docs: https://www.twilio.com/docs
    usage:
      - Programmable SMS
      - WhatsApp Business API

# Endpoints API
api_endpoints:
  base_path: /api/v1/auth
  endpoints:
    - method: POST
      path: /register
      requirement: RF-AUTH-002
      auth: false
    - method: POST
      path: /login
      requirement: RF-AUTH-002
      auth: false
    - method: POST
      path: /logout
      requirement: RF-AUTH-005
      auth: true
    - method: POST
      path: /refresh
      requirement: RF-AUTH-005
      auth: false
    - method: GET
      path: /me
      requirement: RF-AUTH-005
      auth: true
    - method: GET
      path: /oauth/:provider/url
      requirement: RF-AUTH-001
      auth: false
    - method: POST
      path: /oauth/:provider
      requirement: RF-AUTH-001
      auth: false
    - method: DELETE
      path: /oauth/:provider
      requirement: RF-AUTH-001
      auth: true
    - method: POST
      path: /phone/send
      requirement: RF-AUTH-003
      auth: false
    - method: POST
      path: /phone/verify
      requirement: RF-AUTH-003
      auth: false
    - method: POST
      path: /2fa/setup
      requirement: RF-AUTH-004
      auth: true
    - method: POST
      path: /2fa/enable
      requirement: RF-AUTH-004
      auth: true
    - method: POST
      path: /2fa/verify
      requirement: RF-AUTH-004
      auth: false
    - method: POST
      path: /2fa/disable
      requirement: RF-AUTH-004
      auth: true
    - method: POST
      path: /forgot-password
      requirement: RF-AUTH-002
      auth: false
    - method: POST
      path: /reset-password
      requirement: RF-AUTH-002
      auth: false
    - method: POST
      path: /verify-email
      requirement: RF-AUTH-002
      auth: false
    - method: GET
      path: /sessions
      requirement: RF-AUTH-005
      auth: true
    - method: DELETE
      path: /sessions/:id
      requirement: RF-AUTH-005
      auth: true
    - method: DELETE
      path: /sessions
      requirement: RF-AUTH-005
      auth: true

# Notas y decisiones
notes:
  - "OAuth state tokens almacenados en Redis con TTL de 10 minutos"
  - "Refresh token rotation implementada para mayor seguridad"
  - "Backup codes hasheados individualmente con bcrypt"
  - "Rate limiting estricto en endpoints de autenticación"
  - "Todos los tokens de proveedores OAuth encriptados en DB"