# MAI-001: Fundamentos

## Metadata

| Campo | Valor |
|-------|-------|
| **ID** | MAI-001 |
| **Nombre** | Fundamentos |
| **Vertical** | Construccion |
| **Fase** | 1 - Alcance Inicial |
| **Prioridad** | P0 (Critico) |
| **Story Points** | 50 SP |
| **Presupuesto** | $25,000 MXN |
| **Estado** | Planificado |
| **Sprint** | Sprint 0-2 (Semanas 1-2) |
| **Duracion estimada** | 10 dias |
| **Dependencias** | Ninguna (modulo base) |

---

## Descripcion

**MAI-001 Fundamentos** es el modulo base del Sistema de Administracion de Obra que establece la infraestructura tecnica y funcional para todo el sistema vertical de construccion. Este modulo reutiliza el 95% de los componentes del core ERP (MGN-001, MGN-002, MGN-003) adaptandolos a las necesidades especificas de la industria de la construccion.

### Componentes principales:

- **Autenticacion y Autorizacion:** Sistema de login basado en JWT con OAuth social (Google, Microsoft)
- **Sistema de Roles de Construccion:** 7 roles especializados (Director, Ingeniero, Residente, Compras, Finanzas, RRHH, Postventa)
- **Multi-tenancy:** Aislamiento por constructora con Row-Level Security (RLS)
- **Infraestructura Base:** Backend (NestJS), Frontend (React/Vite), Database (PostgreSQL)
- **Dashboards por Rol:** 7 variantes de dashboard adaptadas a cada perfil de usuario
- **Gestion de Usuarios:** CRUD completo con perfiles extendidos y preferencias

---

## Alcance Funcional

### Incluido en MAI-001

- Sistema de autenticacion JWT (access + refresh tokens)
- Login/logout con email y password
- OAuth con Google y Microsoft
- Recuperacion de password via email
- Registro de usuarios con validacion
- Gestion de perfiles de usuario
- Sistema de roles RBAC con 7 roles de construccion
- Asignacion de permisos granulares
- Multi-tenancy por constructora
- Dashboard principal adaptado por rol
- Sistema de sesiones multiples por usuario
- Proteccion contra brute force
- Auditoria de acciones de usuarios
- API RESTful base con versionado
- Sistema de navegacion y routing
- UI/UX base con componentes reutilizables
- Preferencias de usuario (tema, idioma, notificaciones)

### Excluido de MAI-001

- Modulos funcionales de construccion (proyectos, presupuestos, etc.)
- Gestion de catalogos de construccion
- Reportes especializados de obra
- 2FA/MFA (enhancement futuro)
- Notificaciones push (fase posterior)
- Sistema de archivos/documentos (fase posterior)

---

## Reutilizacion del Core ERP

Este modulo reutiliza el **95%** de los componentes base del ERP Core, especificamente de los modulos:

### MGN-001: Autenticacion (95% de reutilizacion)

**Componentes heredados:**
- Sistema de autenticacion JWT completo
- Manejo de access tokens (15 min) y refresh tokens (7 dias)
- OAuth con Google y Microsoft
- Recuperacion de password via email
- Proteccion contra brute force (rate limiting)
- Bloqueo temporal por intentos fallidos
- Registro de intentos de login
- Manejo de sesiones multiples

**Adaptaciones requeridas:**
- Integracion con 7 roles de construccion (vs 3 roles genericos)
- Validaciones especificas de constructora
- Estados de cuenta extendidos para construccion

**Referencias:**
- [MGN-001 README](/home/isem/workspace/projects/erp-suite/apps/erp-core/docs/01-fase-foundation/MGN-001-auth/README.md)
- [MGN-001 Requerimientos](/home/isem/workspace/projects/erp-suite/apps/erp-core/docs/01-fase-foundation/MGN-001-auth/requerimientos/)

### MGN-002: Usuarios (95% de reutilizacion)

**Componentes heredados:**
- CRUD completo de usuarios
- Gestion de perfiles extendidos
- Sistema de preferencias (tema, idioma, notificaciones)
- Busqueda y filtrado de usuarios
- Soft delete con trazabilidad
- Activacion/desactivacion de cuentas

**Adaptaciones requeridas:**
- Campos adicionales en perfil para construccion
- Vinculacion obligatoria con constructora
- Validaciones de datos especificos de construccion

**Referencias:**
- [MGN-002 README](/home/isem/workspace/projects/erp-suite/apps/erp-core/docs/01-fase-foundation/MGN-002-users/README.md)
- [MGN-002 Requerimientos](/home/isem/workspace/projects/erp-suite/apps/erp-core/docs/01-fase-foundation/MGN-002-users/requerimientos/)

### MGN-003: Roles y Permisos (95% de reutilizacion)

**Componentes heredados:**
- Sistema RBAC (Role-Based Access Control)
- Modelo de permisos granulares (module:action:resource)
- Guards y decoradores (@Roles, @RequirePermission)
- Asignacion multiple de roles a usuarios
- Verificacion de permisos en tiempo de ejecucion

**Adaptaciones requeridas:**
- Definicion de 7 roles especificos de construccion
- Matriz de permisos adaptada a modulos de obra
- Validacion de permisos por constructora

**Referencias:**
- [MGN-003 README](/home/isem/workspace/projects/erp-suite/apps/erp-core/docs/01-fase-foundation/MGN-003-roles/README.md)
- [MGN-003 Requerimientos](/home/isem/workspace/projects/erp-suite/apps/erp-core/docs/01-fase-foundation/MGN-003-roles/requerimientos/)

---

## Requerimientos Funcionales

| ID | Titulo | Prioridad | Estado | Documentacion |
|----|--------|-----------|--------|---------------|
| RF-AUTH-001 | Sistema de Roles de Construccion | P0 | Planificado | [Ver RF](./requerimientos/RF-AUTH-001-roles-construccion.md) |
| RF-AUTH-002 | Estados de Cuenta de Usuario | P0 | Planificado | [Ver RF](./requerimientos/RF-AUTH-002-estados-cuenta.md) |
| RF-AUTH-003 | Multi-tenancy por Constructora | P0 | Planificado | [Ver RF](./requerimientos/RF-AUTH-003-multi-tenancy.md) |

**Total:** 3 Requerimientos Funcionales

---

## Dependencias con Otros Modulos

### Este modulo NO depende de otros modulos

MAI-001 es el modulo base del sistema de construccion y no tiene dependencias externas. Hereda componentes del Core ERP pero no depende de otros modulos verticales.

### Modulos que dependen de MAI-001

Todos los modulos funcionales del sistema de construccion dependen de MAI-001:

| Modulo | Dependencia | Razon |
|--------|-------------|-------|
| **MAI-002 Proyectos** | MAI-001 | Requiere autenticacion y roles |
| **MAI-003 Presupuestos** | MAI-001 | Valida permisos de ingeniero/director |
| **MAI-004 Programacion** | MAI-001 | Auditoria de cambios en cronograma |
| **MAI-005 Avances** | MAI-001 | Rol de residente para registro |
| **MAI-006 Compras** | MAI-001 | Rol de compras y autorizaciones |
| **MAI-007 Almacen** | MAI-001 | Control de acceso a inventarios |
| **MAI-008 Finanzas** | MAI-001 | Rol de finanzas y auditoria |
| **MAI-009 RRHH** | MAI-001 | Rol de RRHH y permisos |
| **MAI-010 Postventa** | MAI-001 | Rol de postventa y seguimiento |
| **Todos los demas** | MAI-001 | Autenticacion y autorizacion base |

---

## Diagrama de Arquitectura

```
┌─────────────────────────────────────────────────────────────────────────┐
│                        CAPA DE PRESENTACION                             │
│                     Frontend (React 18 + Vite)                          │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐                 │
│  │   Login      │  │  Dashboard   │  │   Profile    │                 │
│  │   Register   │  │  (7 roles)   │  │   Settings   │                 │
│  └──────────────┘  └──────────────┘  └──────────────┘                 │
│                                                                         │
│  ┌──────────────────────────────────────────────────────┐              │
│  │         Guards & Routing                             │              │
│  │  - AuthGuard  - RoleGuard  - ConstructoraGuard      │              │
│  └──────────────────────────────────────────────────────┘              │
│                                                                         │
│  ┌──────────────────────────────────────────────────────┐              │
│  │         State Management (Zustand)                   │              │
│  │  - authStore  - userStore  - constructoraStore       │              │
│  └──────────────────────────────────────────────────────┘              │
│                                                                         │
└────────────────────────────┬────────────────────────────────────────────┘
                             │
                             │ HTTPS / REST API
                             │
┌────────────────────────────▼────────────────────────────────────────────┐
│                        CAPA DE NEGOCIO                                  │
│                     Backend (NestJS + TypeScript)                       │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐                 │
│  │ AuthModule   │  │ UsersModule  │  │ RolesModule  │                 │
│  │              │  │              │  │              │                 │
│  │ - AuthSvc    │  │ - UsersSvc   │  │ - RolesSvc   │                 │
│  │ - JwtSvc     │  │ - ProfileSvc │  │ - PermSvc    │                 │
│  │ - OAuthSvc   │  │ - PrefSvc    │  │              │                 │
│  └──────────────┘  └──────────────┘  └──────────────┘                 │
│                                                                         │
│  ┌──────────────────────────────────────────────────────┐              │
│  │         Guards & Middlewares                         │              │
│  │  - JwtAuthGuard  - RolesGuard  - PermissionsGuard   │              │
│  │  - ValidationMiddleware  - ErrorMiddleware           │              │
│  └──────────────────────────────────────────────────────┘              │
│                                                                         │
│  ┌──────────────────────────────────────────────────────┐              │
│  │         Shared Services                              │              │
│  │  - LoggingService  - AuditService  - CacheService   │              │
│  └──────────────────────────────────────────────────────┘              │
│                                                                         │
└────────────────────────────┬────────────────────────────────────────────┘
                             │
                             │ SQL / TypeORM
                             │
┌────────────────────────────▼────────────────────────────────────────────┐
│                        CAPA DE DATOS                                    │
│                     PostgreSQL 15+                                      │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│  ┌──────────────────┐  ┌──────────────────┐  ┌──────────────────┐     │
│  │  Schema: auth    │  │ Schema: public   │  │ Schema: audit    │     │
│  ├──────────────────┤  ├──────────────────┤  ├──────────────────┤     │
│  │ - users_auth     │  │ - users          │  │ - audit_logs     │     │
│  │ - sessions       │  │ - user_profiles  │  │ - login_attempts │     │
│  │ - refresh_tokens │  │ - preferences    │  │                  │     │
│  │ - password_reset │  │ - roles          │  │                  │     │
│  │ - oauth_accounts │  │ - permissions    │  │                  │     │
│  │                  │  │ - user_roles     │  │                  │     │
│  │                  │  │ - constructoras  │  │                  │     │
│  └──────────────────┘  └──────────────────┘  └──────────────────┘     │
│                                                                         │
│  ┌──────────────────────────────────────────────────────┐              │
│  │         Row Level Security (RLS)                     │              │
│  │  - Politicas por constructora                        │              │
│  │  - Validacion de permisos por rol                    │              │
│  └──────────────────────────────────────────────────────┘              │
│                                                                         │
│  ┌──────────────────────────────────────────────────────┐              │
│  │         ENUMS                                        │              │
│  │  - construction_role (7 roles)                       │              │
│  │  - account_status (active, suspended, etc.)          │              │
│  └──────────────────────────────────────────────────────┘              │
│                                                                         │
└─────────────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────────────┐
│                     SERVICIOS EXTERNOS                                  │
├─────────────────────────────────────────────────────────────────────────┤
│  - Google OAuth 2.0                                                     │
│  - Microsoft Azure AD                                                   │
│  - SMTP (Email de recuperacion)                                         │
└─────────────────────────────────────────────────────────────────────────┘
```

### Flujo de Autenticacion

```
Usuario → Login Form → POST /api/v1/auth/login
                              ↓
                        [Validate Credentials]
                              ↓
                        [Check Account Status]
                              ↓
                        [Check Constructora]
                              ↓
                        [Generate JWT Tokens]
                              ↓
                   Access Token (15 min) + Refresh Token (7 dias)
                              ↓
                        [Store in State]
                              ↓
                   Redirect to Dashboard (por rol)
```

---

## Sistema de Roles de Construccion

A diferencia del Core ERP que tiene roles genericos, MAI-001 implementa **7 roles especializados** para la industria de la construccion:

| Rol | Codigo | Descripcion | Permisos Clave | Dashboard |
|-----|--------|-------------|----------------|-----------|
| **Director** | `director` | Director General/Proyectos | - Vision global de proyectos<br>- Margenes y rentabilidad<br>- Riesgos y alertas<br>- Aprobaciones criticas | Tablero ejecutivo con KPIs |
| **Ingeniero** | `engineer` | Ingenieria/Planeacion | - Presupuestos de obra<br>- Programacion de actividades<br>- Control de avances<br>- Explosiones de insumos | Tablero de control tecnico |
| **Residente** | `resident` | Residente/Supervisor | - Registro de avances<br>- Incidencias de obra<br>- Checklists de calidad<br>- Solicitudes de material | Tablero operativo de campo |
| **Compras** | `purchases` | Compras/Almacen | - Ordenes de compra<br>- Cotizaciones<br>- Inventarios<br>- Proveedores | Tablero de abastecimiento |
| **Finanzas** | `finance` | Administracion/Finanzas | - Presupuestos financieros<br>- Flujo de caja<br>- Pagos y cobranza<br>- Conciliaciones | Tablero financiero |
| **RRHH** | `hr` | Recursos Humanos | - Asistencias<br>- Costeo mano de obra<br>- Nominas<br>- Capacitacion | Tablero de personal |
| **Postventa** | `post_sales` | Postventa/Garantias | - Incidencias post-entrega<br>- Seguimiento clientes<br>- Garantias<br>- Satisfaccion | Tablero de servicio |

### Matriz de Permisos Base

| Permiso | Director | Ingeniero | Residente | Compras | Finanzas | RRHH | Postventa |
|---------|----------|-----------|-----------|---------|----------|------|-----------|
| **users:read:all** | ✓ | ✓ | - | - | - | ✓ | - |
| **users:write:all** | ✓ | - | - | - | - | - | - |
| **projects:read:all** | ✓ | ✓ | ✓ | ✓ | ✓ | - | ✓ |
| **projects:write:all** | ✓ | ✓ | - | - | - | - | - |
| **budgets:read:all** | ✓ | ✓ | - | - | ✓ | - | - |
| **budgets:write:all** | ✓ | ✓ | - | - | - | - | - |
| **reports:export:all** | ✓ | ✓ | - | - | ✓ | - | - |

**Nota:** La matriz completa se define en [ET-AUTH-001-rbac.md](./especificaciones/ET-AUTH-001-rbac.md)

---

## Stack Tecnologico

### Frontend

| Tecnologia | Version | Proposito |
|------------|---------|-----------|
| **React** | 18.3.x | Framework UI |
| **TypeScript** | 5.6.x | Lenguaje type-safe |
| **Vite** | 6.x | Build tool & dev server |
| **Zustand** | 5.x | State management |
| **React Router** | 7.x | Routing & navegacion |
| **React Hook Form** | 7.x | Manejo de formularios |
| **Zod** | 3.x | Validacion de schemas |
| **Axios** | 1.x | Cliente HTTP |
| **TailwindCSS** | 4.x | Estilos utility-first |
| **Shadcn/ui** | Latest | Componentes UI |
| **Lucide React** | Latest | Iconografia |

### Backend

| Tecnologia | Version | Proposito |
|------------|---------|-----------|
| **NestJS** | 10.x | Framework backend |
| **TypeScript** | 5.6.x | Lenguaje type-safe |
| **TypeORM** | 0.3.x | ORM para PostgreSQL |
| **PostgreSQL** | 15+ | Base de datos |
| **JWT** | 9.x | Autenticacion |
| **Passport** | 0.7.x | Estrategias de auth |
| **Bcrypt** | 5.x | Hashing de passwords |
| **Class Validator** | 0.14.x | Validacion DTOs |
| **Class Transformer** | 0.5.x | Transformacion datos |
| **Winston** | 3.x | Logging estructurado |

### Base de Datos

| Tecnologia | Version | Proposito |
|------------|---------|-----------|
| **PostgreSQL** | 15+ | Base de datos principal |
| **pgcrypto** | Extension | Funciones de encriptacion |
| **uuid-ossp** | Extension | Generacion de UUIDs |

### DevOps & Testing

| Tecnologia | Version | Proposito |
|------------|---------|-----------|
| **Docker** | Latest | Contenedorizacion |
| **Docker Compose** | Latest | Orquestacion local |
| **Jest** | 29.x | Testing framework |
| **Vitest** | 2.x | Testing para Vite |
| **Supertest** | 6.x | Testing API |
| **ESLint** | 9.x | Linting |
| **Prettier** | 3.x | Code formatting |

---

## Estructura de Directorios

```
MAI-001-fundamentos/
├── README.md                    # Este archivo
├── _MAP.md                      # Mapa del modulo
│
├── requerimientos/              # Requerimientos Funcionales
│   ├── RF-AUTH-001-roles-construccion.md
│   ├── RF-AUTH-002-estados-cuenta.md
│   └── RF-AUTH-003-multi-tenancy.md
│
├── especificaciones/            # Especificaciones Tecnicas
│   ├── ET-AUTH-001-rbac.md
│   ├── ET-AUTH-002-estados-cuenta.md
│   └── ET-AUTH-003-multi-tenancy.md
│
├── historias-usuario/           # User Stories
│   ├── US-FUND-001-autenticacion-basica-jwt.md
│   ├── US-FUND-002-perfiles-usuario-construccion.md
│   ├── US-FUND-003-dashboard-por-rol.md
│   ├── US-FUND-004-infraestructura-base.md
│   ├── US-FUND-005-sistema-sesiones.md
│   ├── US-FUND-006-api-restful-base.md
│   ├── US-FUND-007-navegacion-routing.md
│   └── US-FUND-008-ui-ux-base.md
│
├── implementacion/              # Inventarios de implementacion
│   ├── TRACEABILITY.yml         # Matriz de trazabilidad
│   ├── DATABASE.yml             # Objetos de base de datos
│   ├── BACKEND.yml              # Modulos backend
│   └── FRONTEND.yml             # Componentes frontend
│
└── pruebas/                     # Documentacion de testing
    ├── TEST-PLAN.md             # Plan de pruebas
    └── TEST-CASES.md            # Casos de prueba
```

---

## Enlaces a Documentacion

### Documentacion del Modulo

| Tipo | Documento | Descripcion |
|------|-----------|-------------|
| **Mapa** | [_MAP.md](./_MAP.md) | Indice completo del modulo con metricas |
| **Trazabilidad** | [TRACEABILITY.yml](./implementacion/TRACEABILITY.yml) | Matriz completa de trazabilidad RF→ET→US→DB→BE→FE |
| **Base de Datos** | [DATABASE.yml](./implementacion/DATABASE.yml) | Inventario de schemas, tablas, funciones |
| **Backend** | [BACKEND.yml](./implementacion/BACKEND.yml) | Inventario de modulos, servicios, guards |
| **Frontend** | [FRONTEND.yml](./implementacion/FRONTEND.yml) | Inventario de componentes, hooks, stores |

### Requerimientos Funcionales

| ID | Documento | Titulo |
|----|-----------|--------|
| RF-AUTH-001 | [RF-AUTH-001-roles-construccion.md](./requerimientos/RF-AUTH-001-roles-construccion.md) | Sistema de Roles de Construccion |
| RF-AUTH-002 | [RF-AUTH-002-estados-cuenta.md](./requerimientos/RF-AUTH-002-estados-cuenta.md) | Estados de Cuenta de Usuario |
| RF-AUTH-003 | [RF-AUTH-003-multi-tenancy.md](./requerimientos/RF-AUTH-003-multi-tenancy.md) | Multi-tenancy por Constructora |

### Especificaciones Tecnicas

| ID | Documento | Titulo |
|----|-----------|--------|
| ET-AUTH-001 | [ET-AUTH-001-rbac.md](./especificaciones/ET-AUTH-001-rbac.md) | Implementacion RBAC |
| ET-AUTH-002 | [ET-AUTH-002-estados-cuenta.md](./especificaciones/ET-AUTH-002-estados-cuenta.md) | Estados de Cuenta |
| ET-AUTH-003 | [ET-AUTH-003-multi-tenancy.md](./especificaciones/ET-AUTH-003-multi-tenancy.md) | Multi-tenancy Implementation |

### Historias de Usuario

| ID | Documento | Titulo | SP |
|----|-----------|--------|----|
| US-FUND-001 | [US-FUND-001-autenticacion-basica-jwt.md](./historias-usuario/US-FUND-001-autenticacion-basica-jwt.md) | Autenticacion Basica JWT | 8 |
| US-FUND-002 | [US-FUND-002-perfiles-usuario-construccion.md](./historias-usuario/US-FUND-002-perfiles-usuario-construccion.md) | Perfiles de Usuario de Construccion | 5 |
| US-FUND-003 | [US-FUND-003-dashboard-por-rol.md](./historias-usuario/US-FUND-003-dashboard-por-rol.md) | Dashboard Principal por Rol | 8 |
| US-FUND-004 | [US-FUND-004-infraestructura-base.md](./historias-usuario/US-FUND-004-infraestructura-base.md) | Infraestructura Tecnica Base | 12 |
| US-FUND-005 | [US-FUND-005-sistema-sesiones.md](./historias-usuario/US-FUND-005-sistema-sesiones.md) | Sistema de Sesiones y Estado | 6 |
| US-FUND-006 | [US-FUND-006-api-restful-base.md](./historias-usuario/US-FUND-006-api-restful-base.md) | API RESTful Basica | 8 |
| US-FUND-007 | [US-FUND-007-navegacion-routing.md](./historias-usuario/US-FUND-007-navegacion-routing.md) | Navegacion y Routing | 5 |
| US-FUND-008 | [US-FUND-008-ui-ux-base.md](./historias-usuario/US-FUND-008-ui-ux-base.md) | UI/UX Base (migrada de GAMILIT) | 3 |

### Pruebas

| Documento | Descripcion |
|-----------|-------------|
| [TEST-PLAN.md](./pruebas/TEST-PLAN.md) | Plan de pruebas del modulo |
| [TEST-CASES.md](./pruebas/TEST-CASES.md) | Casos de prueba detallados |

### Referencias al Core ERP

| Modulo | Documento | Descripcion |
|--------|-----------|-------------|
| MGN-001 | [README.md](/home/isem/workspace/projects/erp-suite/apps/erp-core/docs/01-fase-foundation/MGN-001-auth/README.md) | Autenticacion Core |
| MGN-002 | [README.md](/home/isem/workspace/projects/erp-suite/apps/erp-core/docs/01-fase-foundation/MGN-002-users/README.md) | Usuarios Core |
| MGN-003 | [README.md](/home/isem/workspace/projects/erp-suite/apps/erp-core/docs/01-fase-foundation/MGN-003-roles/README.md) | Roles Core |

---

## Metricas del Modulo

### Metricas de Planificacion

| Metrica | Valor | Notas |
|---------|-------|-------|
| **Presupuesto estimado** | $25,000 MXN | Incluye desarrollo + pruebas |
| **Presupuesto target** | $25,000 MXN ±5% | Rango: $23,750 - $26,250 |
| **Story Points estimados** | 50 SP | Reducidos vs 60 SP de GAMILIT |
| **Duracion estimada** | 10 dias | vs 11 dias GAMILIT (90% reutilizacion) |
| **Reutilizacion Core** | 95% | De MGN-001, MGN-002, MGN-003 |
| **Ahorro estimado** | ~2.5 semanas | vs desarrollo desde cero |

### Metricas de Alcance

| Metrica | Cantidad |
|---------|----------|
| **Requerimientos Funcionales** | 3 |
| **Especificaciones Tecnicas** | 3 |
| **User Stories** | 8 |
| **Schemas de BD** | 4 (auth, auth_management, audit, public) |
| **Tablas estimadas** | ~18 |
| **Endpoints API** | ~25 |
| **Componentes Frontend** | ~30 |
| **Roles de sistema** | 7 |

### Metricas de Calidad (Targets)

| Metrica | Target | Estrategia |
|---------|--------|------------|
| **Code Coverage** | >80% | Jest + Vitest |
| **API Response Time** | <200ms | P95 |
| **Frontend Lighthouse** | >90 | Performance score |
| **Security Audit** | 0 vulnerabilities | npm audit |
| **TypeScript Strict** | 100% | strict mode enabled |
| **ESLint Issues** | 0 | Pre-commit hooks |

---

## Seguridad y Cumplimiento

### Medidas de Seguridad

| Area | Implementacion |
|------|----------------|
| **Passwords** | Bcrypt con cost factor 12 |
| **Tokens JWT** | Access (15 min) + Refresh (7 dias) |
| **Rate Limiting** | 5 intentos/minuto por IP |
| **Bloqueo Temporal** | 15 minutos tras 5 intentos fallidos |
| **Reset Password** | Tokens expiran en 1 hora |
| **HTTPS** | Obligatorio en produccion |
| **CORS** | Whitelist de dominios |
| **Helmet.js** | Headers de seguridad |
| **SQL Injection** | TypeORM parametrizado |
| **XSS** | Sanitizacion de inputs |
| **CSRF** | Tokens CSRF en forms |

### Row-Level Security (RLS)

Todas las tablas implementan RLS para aislamiento por constructora:

```sql
-- Ejemplo de politica RLS
CREATE POLICY "users_select_policy"
  ON public.users
  FOR SELECT
  USING (
    constructora_id = current_setting('app.current_constructora_id')::uuid
    OR
    EXISTS (
      SELECT 1 FROM public.user_roles ur
      JOIN public.roles r ON ur.role_id = r.id
      WHERE ur.user_id = auth.uid()
      AND r.name = 'super_admin'
    )
  );
```

### Auditoria

Todas las operaciones criticas se auditan:

- Login/Logout
- Cambios de password
- Asignacion de roles
- Modificacion de permisos
- Acceso a datos sensibles
- Operaciones CRUD de usuarios

---

## Roadmap de Implementacion

### Sprint 0: Migracion (2 dias)

- [x] Migrar componentes de GAMILIT
- [x] Adaptar estructura de carpetas
- [x] Configurar base de datos
- [x] Adaptar variables de entorno

### Sprint 1: Autenticacion (4 dias)

- [ ] Implementar login/logout JWT
- [ ] OAuth con Google/Microsoft
- [ ] Recuperacion de password
- [ ] Sistema de sesiones
- [ ] Rate limiting y bloqueo

### Sprint 2: Usuarios y Roles (4 dias)

- [ ] CRUD de usuarios
- [ ] Perfiles extendidos
- [ ] Sistema RBAC con 7 roles
- [ ] Asignacion de permisos
- [ ] Multi-tenancy por constructora

### Sprint 3: Dashboard y UI (3 dias)

- [ ] Dashboard por rol (7 variantes)
- [ ] Navegacion y routing
- [ ] Componentes UI base
- [ ] Sistema de preferencias
- [ ] Responsive design

### Sprint 4: Testing y QA (2 dias)

- [ ] Tests unitarios (>80% coverage)
- [ ] Tests de integracion API
- [ ] Tests E2E criticos
- [ ] Security audit
- [ ] Performance testing

**Total: 15 dias (10 dias de desarrollo + 5 dias buffer)**

---

## Lecciones Aprendidas (de GAMILIT)

### Best Practices

1. **RLS desde dia 1:** Implementar Row Level Security desde el inicio evita refactoring posterior
2. **Tests rigurosos:** Coverage >80% = deployment mas seguro y tranquilo
3. **Modularizacion temprana:** Facilita desarrollo paralelo de equipos
4. **Documentacion previa:** Especificar antes de implementar reduce cambios y retrabajo
5. **Type Safety:** TypeScript strict mode evita bugs en produccion
6. **API Versionado:** `/api/v1` desde el inicio facilita evolucionar sin breaking changes

### Errores a Evitar

1. **NO** implementar autenticacion custom sin JWT
2. **NO** guardar passwords en texto plano (obvio pero critico)
3. **NO** usar ORMs sin prepared statements
4. **NO** olvidar rate limiting en endpoints publicos
5. **NO** exponer stack traces en produccion
6. **NO** hacer commits sin tests pasando

---

## Contacto y Soporte

### Equipo

| Rol | Responsable | Contacto |
|-----|-------------|----------|
| **Tech Lead** | @tech-lead | tech-lead@example.com |
| **Backend Team** | @backend-team | backend@example.com |
| **Frontend Team** | @frontend-team | frontend@example.com |
| **Database Team** | @database-team | database@example.com |
| **QA Team** | @qa-team | qa@example.com |

### Recursos

- **Wiki del Proyecto:** [Confluence/Wiki URL]
- **Board de Tareas:** [Jira/Linear URL]
- **Repositorio:** [GitHub/GitLab URL]
- **CI/CD:** [Jenkins/GitHub Actions URL]
- **Monitoring:** [Datadog/Grafana URL]

---

## Historial de Cambios

| Fecha | Version | Cambio | Autor |
|-------|---------|--------|-------|
| 2025-12-06 | 1.0 | Creacion del README del modulo MAI-001 | Requirements-Analyst |
| 2025-11-17 | 0.1 | Creacion inicial del modulo con _MAP.md | Requirements-Analyst |

---

**Generado por:** Requirements-Analyst
**Fecha:** 2025-12-06
**Estado:** Planificado
**Proxima revision:** Sprint 1 (inicio de implementacion)