erp-construccion/docs/02-definicion-modulos/MAI-001-fundamentos/README.md

32 KiB

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-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-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:


Requerimientos Funcionales

ID Titulo Prioridad Estado Documentacion
RF-AUTH-001 Sistema de Roles de Construccion P0 Planificado Ver RF
RF-AUTH-002 Estados de Cuenta de Usuario P0 Planificado Ver RF
RF-AUTH-003 Multi-tenancy por Constructora P0 Planificado Ver RF

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
- Margenes y rentabilidad
- Riesgos y alertas
- Aprobaciones criticas
Tablero ejecutivo con KPIs
Ingeniero engineer Ingenieria/Planeacion - Presupuestos de obra
- Programacion de actividades
- Control de avances
- Explosiones de insumos
Tablero de control tecnico
Residente resident Residente/Supervisor - Registro de avances
- Incidencias de obra
- Checklists de calidad
- Solicitudes de material
Tablero operativo de campo
Compras purchases Compras/Almacen - Ordenes de compra
- Cotizaciones
- Inventarios
- Proveedores
Tablero de abastecimiento
Finanzas finance Administracion/Finanzas - Presupuestos financieros
- Flujo de caja
- Pagos y cobranza
- Conciliaciones
Tablero financiero
RRHH hr Recursos Humanos - Asistencias
- Costeo mano de obra
- Nominas
- Capacitacion
Tablero de personal
Postventa post_sales Postventa/Garantias - Incidencias post-entrega
- Seguimiento clientes
- Garantias
- 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


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 Indice completo del modulo con metricas
Trazabilidad TRACEABILITY.yml Matriz completa de trazabilidad RF→ET→US→DB→BE→FE
Base de Datos DATABASE.yml Inventario de schemas, tablas, funciones
Backend BACKEND.yml Inventario de modulos, servicios, guards
Frontend FRONTEND.yml Inventario de componentes, hooks, stores

Requerimientos Funcionales

ID Documento Titulo
RF-AUTH-001 RF-AUTH-001-roles-construccion.md Sistema de Roles de Construccion
RF-AUTH-002 RF-AUTH-002-estados-cuenta.md Estados de Cuenta de Usuario
RF-AUTH-003 RF-AUTH-003-multi-tenancy.md Multi-tenancy por Constructora

Especificaciones Tecnicas

ID Documento Titulo
ET-AUTH-001 ET-AUTH-001-rbac.md Implementacion RBAC
ET-AUTH-002 ET-AUTH-002-estados-cuenta.md Estados de Cuenta
ET-AUTH-003 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 Autenticacion Basica JWT 8
US-FUND-002 US-FUND-002-perfiles-usuario-construccion.md Perfiles de Usuario de Construccion 5
US-FUND-003 US-FUND-003-dashboard-por-rol.md Dashboard Principal por Rol 8
US-FUND-004 US-FUND-004-infraestructura-base.md Infraestructura Tecnica Base 12
US-FUND-005 US-FUND-005-sistema-sesiones.md Sistema de Sesiones y Estado 6
US-FUND-006 US-FUND-006-api-restful-base.md API RESTful Basica 8
US-FUND-007 US-FUND-007-navegacion-routing.md Navegacion y Routing 5
US-FUND-008 US-FUND-008-ui-ux-base.md UI/UX Base (migrada de GAMILIT) 3

Pruebas

Documento Descripcion
TEST-PLAN.md Plan de pruebas del modulo
TEST-CASES.md Casos de prueba detallados

Referencias al Core ERP

Modulo Documento Descripcion
MGN-001 README.md Autenticacion Core
MGN-002 README.md Usuarios Core
MGN-003 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:

-- 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)

  • Migrar componentes de GAMILIT
  • Adaptar estructura de carpetas
  • Configurar base de datos
  • 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)