michangarrito/backups/docs-backup-2026-01-10/docs/01-epicas/MCH-002-autenticacion.md

MCH-002: Autenticacion

Metadata

• Codigo: MCH-002
• Fase: 1 - MVP Core
• Prioridad: P0
• Estado: Completado
• Fecha inicio: 2026-01-05
• Fecha fin: 2026-01-06

Descripcion

Sistema de autenticacion adaptado a micro-negocios mexicanos: login via telefono con OTP (SMS/WhatsApp), PIN de 4 digitos para acceso rapido, soporte biometrico opcional, y JWT para sesiones.

Objetivos

1. Login via telefono + OTP
2. PIN de 4 digitos para acceso rapido
3. Soporte biometrico (Face ID/huella)
4. Gestion de sesiones JWT
5. Roles: owner, employee, viewer

Alcance

Incluido

• Registro con telefono
• OTP via SMS/WhatsApp
• PIN de 4 digitos
• JWT con refresh tokens
• Roles basicos (owner/employee/viewer)
• Logout y revocacion de sesiones

Excluido

• OAuth (Google, Facebook) - fase posterior
• 2FA via TOTP - fase posterior
• SSO empresarial

Flujos de Usuario

Registro Inicial

1. Usuario ingresa telefono
2. Se envia OTP via SMS/WhatsApp
3. Usuario verifica OTP
4. Usuario configura PIN de 4 digitos
5. Se crea tenant automaticamente (para owners)
6. Usuario accede al dashboard

Login Subsecuente

1. Usuario ingresa telefono
2. Usuario ingresa PIN de 4 digitos
   - O usa biometrico si esta configurado
3. JWT generado
4. Acceso al sistema

Login por OTP (sin PIN)

1. Usuario selecciona "Olvide mi PIN"
2. Se envia OTP
3. Usuario verifica OTP
4. Puede reconfigurrar PIN

Modelo de Datos

Tablas (schema: auth)

• users: id, tenant_id, phone, email, password_hash, name, role, pin_hash, status
• sessions: id, user_id, token, device_info, expires_at, revoked_at
• roles: id, tenant_id, name, permissions (JSONB)

Endpoints API

Metodo	Endpoint	Descripcion
POST	/auth/register	Registro nuevo usuario
POST	/auth/send-otp	Enviar OTP a telefono
POST	/auth/verify-otp	Verificar OTP
POST	/auth/set-pin	Configurar PIN
POST	/auth/login	Login con telefono + PIN
POST	/auth/login-otp	Login solo con OTP
GET	/auth/me	Usuario actual
POST	/auth/refresh	Renovar JWT
POST	/auth/logout	Cerrar sesion
DELETE	/auth/sessions	Revocar todas las sesiones

Entregables

Entregable	Estado	Archivo
DDL auth schema	Completado	04-auth.sql
auth.module.ts	Completado	modules/auth/
JwtStrategy	Completado	strategies/jwt.strategy.ts
Guards	Completado	guards/

Dependencias

Depende de

• MCH-001 (Infraestructura)

Bloquea a

• MCH-003 (Productos)
• MCH-004 (POS)
• Todos los modulos que requieren auth

Criterios de Aceptacion

• Registro con telefono funcional
• OTP se envia correctamente
• PIN de 4 digitos funciona
• JWT se genera y valida
• Roles owner/employee/viewer funcionan
• Sesiones se pueden revocar

Configuracion

// JWT Config
{
  secret: process.env.JWT_SECRET,
  expiresIn: '7d',
  refreshExpiresIn: '30d'
}

// OTP Config
{
  length: 6,
  expiresIn: '5m',
  maxAttempts: 3
}

---

Ultima actualizacion: 2026-01-07