rckrdmrd
8a540b4e94
- MCH-002: 4 HU (MCH-US-010 a MCH-US-013), 13 SP - MCH-003: 5 HU (MCH-US-020 a MCH-US-024), 8 SP - MCH-004: 6 HU (MCH-US-030 a MCH-US-035), 21 SP - MCH-005: 4 HU (MCH-US-040 a MCH-US-043), 13 SP Formato: Como/Quiero/Para + Criterios [CA-XXX-N] + Tareas [MCH-TT-XXX-NN] Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
281 lines
8.1 KiB
Markdown
281 lines
8.1 KiB
Markdown
---
|
|
id: EPIC-MCH-002
|
|
type: Epic
|
|
title: "MCH-002: Autenticacion"
|
|
code: MCH-002
|
|
status: Completado
|
|
phase: 1
|
|
priority: P0
|
|
story_points: 13
|
|
created_at: 2026-01-05
|
|
updated_at: 2026-01-17
|
|
simco_version: "4.0.1"
|
|
dependencies:
|
|
blocks: ["MCH-003", "MCH-004"]
|
|
depends_on: ["MCH-001"]
|
|
---
|
|
|
|
# MCH-002: Autenticacion
|
|
|
|
## Metadata
|
|
- **Codigo:** MCH-002
|
|
- **Fase:** 1 - MVP Core
|
|
- **Prioridad:** P0 (Critica)
|
|
- **Estado:** Completado
|
|
- **Story Points:** 13
|
|
- **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 de Epica
|
|
|
|
- [x] Registro con telefono funcional
|
|
- [x] OTP se envia correctamente
|
|
- [x] PIN de 4 digitos funciona
|
|
- [x] JWT se genera y valida
|
|
- [x] Roles owner/employee/viewer funcionan
|
|
- [x] Sesiones se pueden revocar
|
|
|
|
---
|
|
|
|
## Historias de Usuario
|
|
|
|
### MCH-US-010: Registro con Telefono y OTP
|
|
|
|
**Como** propietario de un micro-negocio
|
|
**Quiero** registrarme usando mi numero de telefono y verificar con OTP
|
|
**Para** crear mi cuenta de forma sencilla sin necesidad de email
|
|
|
|
**Story Points:** 3
|
|
|
|
**Criterios de Aceptacion:**
|
|
- [CA-010-1] El usuario puede ingresar su numero de telefono mexicano (10 digitos)
|
|
- [CA-010-2] Se envia OTP de 6 digitos via SMS o WhatsApp
|
|
- [CA-010-3] OTP expira en 5 minutos
|
|
- [CA-010-4] Maximo 3 intentos de verificacion antes de bloqueo temporal
|
|
- [CA-010-5] Al verificar exitosamente, se crea el tenant automaticamente
|
|
|
|
**Tareas:**
|
|
| ID | Tarea | Tipo | Estado |
|
|
|----|-------|------|--------|
|
|
| MCH-TT-010-01 | DDL tabla auth.users con campos phone, pin_hash | DDL | Completado |
|
|
| MCH-TT-010-02 | Endpoint POST /auth/register | Backend | Completado |
|
|
| MCH-TT-010-03 | Endpoint POST /auth/send-otp | Backend | Completado |
|
|
| MCH-TT-010-04 | Endpoint POST /auth/verify-otp | Backend | Completado |
|
|
| MCH-TT-010-05 | Servicio OTPService con integracion SMS | Backend | Completado |
|
|
| MCH-TT-010-06 | Tests unitarios de registro | Test | Completado |
|
|
|
|
---
|
|
|
|
### MCH-US-011: Login con PIN de 4 Digitos
|
|
|
|
**Como** usuario registrado
|
|
**Quiero** acceder a mi cuenta usando un PIN de 4 digitos
|
|
**Para** entrar rapidamente sin tener que esperar un OTP cada vez
|
|
|
|
**Story Points:** 3
|
|
|
|
**Criterios de Aceptacion:**
|
|
- [CA-011-1] Usuario puede configurar PIN de 4 digitos despues del registro
|
|
- [CA-011-2] PIN se almacena hasheado (bcrypt)
|
|
- [CA-011-3] Login exitoso con telefono + PIN genera JWT
|
|
- [CA-011-4] 5 intentos fallidos bloquean la cuenta temporalmente (15 min)
|
|
- [CA-011-5] Opcion "Olvide mi PIN" envia OTP para recuperacion
|
|
|
|
**Tareas:**
|
|
| ID | Tarea | Tipo | Estado |
|
|
|----|-------|------|--------|
|
|
| MCH-TT-011-01 | Endpoint POST /auth/set-pin | Backend | Completado |
|
|
| MCH-TT-011-02 | Endpoint POST /auth/login (telefono + PIN) | Backend | Completado |
|
|
| MCH-TT-011-03 | Endpoint POST /auth/login-otp (recuperacion) | Backend | Completado |
|
|
| MCH-TT-011-04 | Logica de bloqueo por intentos fallidos | Backend | Completado |
|
|
| MCH-TT-011-05 | Tests unitarios de login | Test | Completado |
|
|
|
|
---
|
|
|
|
### MCH-US-012: Gestion de Sesiones JWT
|
|
|
|
**Como** sistema de autenticacion
|
|
**Quiero** manejar sesiones con JWT y refresh tokens
|
|
**Para** mantener sesiones seguras y permitir logout remoto
|
|
|
|
**Story Points:** 5
|
|
|
|
**Criterios de Aceptacion:**
|
|
- [CA-012-1] JWT access token con expiracion de 7 dias
|
|
- [CA-012-2] Refresh token con expiracion de 30 dias
|
|
- [CA-012-3] Endpoint GET /auth/me retorna usuario actual
|
|
- [CA-012-4] Endpoint POST /auth/refresh renueva el JWT
|
|
- [CA-012-5] Endpoint POST /auth/logout revoca sesion actual
|
|
- [CA-012-6] Endpoint DELETE /auth/sessions revoca todas las sesiones
|
|
- [CA-012-7] Sessions incluyen device_info para identificacion
|
|
|
|
**Tareas:**
|
|
| ID | Tarea | Tipo | Estado |
|
|
|----|-------|------|--------|
|
|
| MCH-TT-012-01 | DDL tabla auth.sessions | DDL | Completado |
|
|
| MCH-TT-012-02 | JwtStrategy con Passport | Backend | Completado |
|
|
| MCH-TT-012-03 | Endpoint GET /auth/me | Backend | Completado |
|
|
| MCH-TT-012-04 | Endpoint POST /auth/refresh | Backend | Completado |
|
|
| MCH-TT-012-05 | Endpoint POST /auth/logout | Backend | Completado |
|
|
| MCH-TT-012-06 | Endpoint DELETE /auth/sessions | Backend | Completado |
|
|
| MCH-TT-012-07 | Tests de sesiones | Test | Completado |
|
|
|
|
---
|
|
|
|
### MCH-US-013: Sistema de Roles Basicos
|
|
|
|
**Como** propietario del negocio
|
|
**Quiero** asignar roles a mis empleados (owner, employee, viewer)
|
|
**Para** controlar que acciones puede realizar cada persona
|
|
|
|
**Story Points:** 2
|
|
|
|
**Criterios de Aceptacion:**
|
|
- [CA-013-1] Rol owner tiene acceso completo al tenant
|
|
- [CA-013-2] Rol employee puede operar POS y ver reportes basicos
|
|
- [CA-013-3] Rol viewer solo puede consultar sin modificar
|
|
- [CA-013-4] Roles se almacenan en tabla auth.roles con permisos JSONB
|
|
- [CA-013-5] Guards validan permisos en cada endpoint protegido
|
|
|
|
**Tareas:**
|
|
| ID | Tarea | Tipo | Estado |
|
|
|----|-------|------|--------|
|
|
| MCH-TT-013-01 | DDL tabla auth.roles | DDL | Completado |
|
|
| MCH-TT-013-02 | RolesGuard para proteger endpoints | Backend | Completado |
|
|
| MCH-TT-013-03 | Decorador @Roles() para controllers | Backend | Completado |
|
|
| MCH-TT-013-04 | Seed de roles por defecto | Backend | Completado |
|
|
| MCH-TT-013-05 | Tests de autorizacion | Test | Completado |
|
|
|
|
---
|
|
|
|
## Resumen de Story Points
|
|
|
|
| Historia | SP | Estado |
|
|
|----------|-----|--------|
|
|
| MCH-US-010: Registro con Telefono y OTP | 3 | Completado |
|
|
| MCH-US-011: Login con PIN de 4 Digitos | 3 | Completado |
|
|
| MCH-US-012: Gestion de Sesiones JWT | 5 | Completado |
|
|
| MCH-US-013: Sistema de Roles Basicos | 2 | Completado |
|
|
| **TOTAL** | **13** | **Completado** |
|
|
|
|
---
|
|
|
|
## Configuracion
|
|
|
|
```typescript
|
|
// JWT Config
|
|
{
|
|
secret: process.env.JWT_SECRET,
|
|
expiresIn: '7d',
|
|
refreshExpiresIn: '30d'
|
|
}
|
|
|
|
// OTP Config
|
|
{
|
|
length: 6,
|
|
expiresIn: '5m',
|
|
maxAttempts: 3
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
**Ultima actualizacion:** 2026-01-17
|