Saltar a contenido

Feature: Autenticacion de Usuarios

Proposito

Ejemplo completo de una spec de feature para el modulo de autenticacion del Sistema de Reservas de Turnos Medicos. Sirve como referencia para llenar la plantilla _template.spec.md.

Metadata

Campo Valor
Feature ID FEAT-001
Autor Maria Lopez
Fecha 2025-03-15
Estado Approved
Prioridad Critical
Epic Gestion de Identidad

1. Problema

Contexto

El sistema de turnos medicos necesita identificar a pacientes y medicos para personalizar la experiencia: ver historial de turnos, gestionar agendas, y proteger datos de salud.

Dolor del usuario

  • Los pacientes no pueden acceder a su historial de turnos sin una cuenta.
  • Los medicos no tienen un panel seguro para gestionar su agenda.
  • No existe distincion de permisos entre roles (paciente, medico, admin).

Impacto del negocio

  • Sin autenticacion no se puede lanzar ninguna feature personalizada.
  • Los datos de salud requieren proteccion legal (HIPAA / Ley de proteccion de datos de salud local).
  • Cada dia sin auth es un dia sin poder adquirir usuarios registrados.

2. Solucion Propuesta

Descripcion general

Sistema de autenticacion basado en email + password con soporte para roles (paciente, medico, admin). Incluye registro, login, recuperacion de password, y gestion de sesiones con JWT.

Usuarios objetivo

  • Pacientes: Se registran para reservar turnos y ver su historial.
  • Medicos: Reciben credenciales del admin para gestionar su agenda.
  • Admins: Gestionan usuarios y configuracion del sistema.

Flujo principal (Happy Path)

Registro de paciente: 1. El paciente ingresa email, nombre, apellido, y password. 2. El sistema valida que el email no este registrado. 3. El sistema envia un email de verificacion con un link. 4. El paciente hace click en el link. 5. La cuenta queda activa y el paciente puede hacer login.

Login: 1. El usuario ingresa email y password. 2. El sistema valida credenciales. 3. El sistema retorna un JWT (access token + refresh token). 4. El frontend almacena los tokens y redirige al dashboard correspondiente al rol.

Flujos alternativos

  • Email ya registrado: El sistema muestra "Ya existe una cuenta con este email" y sugiere recuperar password.
  • Login con password incorrecto: El sistema muestra "Credenciales invalidas" (sin revelar si el email existe).
  • Token expirado: El frontend usa el refresh token para obtener uno nuevo. Si el refresh token tambien expiro, redirige al login.

Flujos de error

  • Servicio de email caido: El registro se completa pero la verificacion queda pendiente. El sistema reintenta el envio cada 5 minutos (max 3 reintentos).
  • Demasiados intentos de login fallidos: Bloqueo temporal de 15 minutos despues de 5 intentos fallidos.
  • JWT invalido o manipulado: Retorna 401 y el frontend redirige al login.

3. Reglas de Negocio

ID Regla Ejemplo
RN-01 El password debe tener minimo 8 caracteres, 1 mayuscula, 1 numero "Turno123" es valido, "turno" no
RN-02 El email debe ser unico en el sistema Si "juan@email.com" existe, otro registro con el mismo email falla
RN-03 La cuenta no esta activa hasta verificar el email Un paciente no verificado no puede hacer login
RN-04 Despues de 5 intentos fallidos de login, la cuenta se bloquea 15 min Intento 6 retorna "Cuenta bloqueada temporalmente"
RN-05 El access token expira en 15 minutos A los 16 min, el request retorna 401
RN-06 El refresh token expira en 7 dias Despues de 7 dias sin actividad, el usuario debe re-autenticarse
RN-07 Los medicos NO se auto-registran, son creados por un admin No existe endpoint publico de registro para medicos
RN-08 El password no puede ser igual a los ultimos 3 passwords usados Si cambias de "Turno123" a "Turno123", el sistema rechaza

4. Modelo de Datos

Entidades involucradas

User | Atributo | Tipo | Requerido | Notas | |----------|------|-----------|-------| | id | UUID | Si | PK, autogenerado | | email | string | Si | Unico, indexado | | password_hash | string | Si | bcrypt, nunca plaintext | | first_name | string | Si | | | last_name | string | Si | | | role | enum | Si | PATIENT, DOCTOR, ADMIN | | is_verified | boolean | Si | Default: false | | is_active | boolean | Si | Default: true | | failed_login_attempts | integer | Si | Default: 0 | | locked_until | timestamp | No | Null si no bloqueado | | created_at | timestamp | Si | | | updated_at | timestamp | Si | |

PasswordHistory | Atributo | Tipo | Requerido | Notas | |----------|------|-----------|-------| | id | UUID | Si | PK | | user_id | UUID | Si | FK -> User | | password_hash | string | Si | | | created_at | timestamp | Si | |

RefreshToken | Atributo | Tipo | Requerido | Notas | |----------|------|-----------|-------| | id | UUID | Si | PK | | user_id | UUID | Si | FK -> User | | token | string | Si | Unico, indexado | | expires_at | timestamp | Si | | | revoked | boolean | Si | Default: false |

Relaciones

  • Un User tiene muchos PasswordHistory (1:N).
  • Un User tiene muchos RefreshToken (1:N).

Cambios al modelo existente

  • Tabla users es nueva.
  • Tabla password_history es nueva.
  • Tabla refresh_tokens es nueva.

5. Criterios de Aceptacion

  • DADO un paciente nuevo CUANDO se registra con datos validos ENTONCES recibe un email de verificacion y su cuenta queda pendiente.
  • DADO un paciente verificado CUANDO hace login con credenciales correctas ENTONCES recibe un access token y un refresh token.
  • DADO un usuario CUANDO ingresa un password incorrecto 5 veces ENTONCES su cuenta se bloquea 15 minutos.
  • DADO un access token expirado CUANDO el frontend envia el refresh token ENTONCES recibe un nuevo access token.
  • DADO un refresh token expirado o revocado CUANDO se intenta renovar ENTONCES retorna 401 y el usuario debe re-autenticarse.
  • DADO un admin CUANDO crea un medico ENTONCES el medico recibe un email con credenciales temporales.
  • DADO un usuario CUANDO cambia su password ENTONCES no puede usar los ultimos 3 passwords.

6. Out of Scope

  • OAuth / Login social (Google, Facebook): Se implementara en una fase posterior.
  • Autenticacion multi-factor (MFA): Fuera de alcance para v1, planeado para v2.
  • Gestion de permisos granulares (RBAC avanzado): v1 solo maneja 3 roles fijos.
  • SSO empresarial (SAML/OIDC): No aplica para el MVP.

7. Dependencias

Dependencia Tipo Estado Contacto
Servicio de email (SendGrid) Servicio externo Ready DevOps team
Base de datos PostgreSQL Infraestructura Ready Platform team
Frontend - pantallas de auth Equipo In Progress Ana (frontend lead)

8. Consideraciones Tecnicas

Performance

  • Login debe responder en < 500ms (p95).
  • bcrypt con cost factor 12 (balance seguridad/velocidad).
  • Indice en users.email para busquedas rapidas.

Seguridad

  • Passwords hasheados con bcrypt, nunca almacenados en plaintext.
  • JWT firmado con RS256 (par de claves asimetricas).
  • Rate limiting en endpoints de login y registro: 10 req/min por IP.
  • Headers de seguridad: HSTS, X-Content-Type-Options, X-Frame-Options.
  • Mensajes de error genericos para no revelar informacion (ej: "Credenciales invalidas" en vez de "Password incorrecto").

Escalabilidad

  • Los JWT son stateless, no requieren consulta a BD en cada request.
  • La tabla de refresh tokens puede crecer: implementar job de limpieza de tokens expirados.
  • Para 10,000+ usuarios concurrentes, considerar Redis para rate limiting.

9. Mockups / Wireframes

  • Pantalla de registro: Formulario con campos email, nombre, apellido, password, confirmar password. Boton "Crear cuenta".
  • Pantalla de login: Formulario con email y password. Link "Olvide mi password". Boton "Iniciar sesion".
  • Pantalla de verificacion: Mensaje "Revisa tu email para verificar tu cuenta" con opcion de reenviar.
  • Pantalla de reset password: Formulario con nuevo password y confirmacion.

(Links a Figma se agregarian aqui cuando esten disponibles.)

10. Metricas de Exito

Metrica Baseline Target Como se mide
Tasa de registro exitoso N/A (feature nueva) > 80% de intentos Eventos de analytics
Tiempo de login (p95) N/A < 500ms APM (Datadog/NewRelic)
Tasa de verificacion de email N/A > 60% en primeras 24h Query a BD
Intentos de login bloqueados por brute force N/A < 1% de logins totales Logs + alertas

Checklist de Completitud

  • Problema claramente definido
  • Solucion descrita sin ambiguedad
  • Reglas de negocio listadas y con ejemplos
  • Criterios de aceptacion escritos y testeables
  • Out of scope definido
  • Dependencias identificadas
  • Consideraciones de seguridad documentadas
  • Revisada por otro ingeniero
  • Derivados generados (API contract / test plan / threat model)

Archivos relacionados