663 lines
32 KiB
Markdown
663 lines
32 KiB
Markdown
# 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)
|