erp-construccion/docs/02-definicion-modulos/MAI-001-fundamentos/requerimientos/RF-AUTH-001-roles-construccion.md

RF-AUTH-001: Sistema de Roles de Construcción

📋 Metadata

Campo	Valor
ID	RF-AUTH-001
Módulo	Autenticación y Autorización
Prioridad	P0 - Crítica
Estado	🚧 Planificado
Versión	1.0
Fecha creación	2025-11-17
Última actualización	2025-11-17

🔗 Referencias

Especificación Técnica

📐 ET-AUTH-001: RBAC Implementation

Implementación DDL

🗄️ ENUM Canónico:

• Ubicación: apps/database/ddl/00-prerequisites.sql:30-39
• Tipo: auth_management.construction_role
• Valores: director, engineer, resident, purchases, finance, hr, post_sales

🗄️ Tablas que usan el ENUM:

1. auth_management.profiles → apps/database/ddl/schemas/auth_management/tables/03-profiles.sql:15
2. auth.users → apps/database/ddl/schemas/auth/tables/01-users.sql:15
3. constructoras.user_constructoras → apps/database/ddl/schemas/constructoras/tables/02-user_constructoras.sql:20

Backend

💻 Implementación:

• Enum: apps/backend/src/shared/enums/construction-role.enum.ts
• Guard: apps/backend/src/shared/guards/roles.guard.ts
• Decorator: @Roles('engineer', 'director')

Frontend

🎨 Componentes:

• Types: apps/frontend/src/types/auth.types.ts
• Componentes:
  • apps/frontend/src/components/auth/RoleBasedRoute.tsx
  • apps/frontend/src/components/ui/UserRoleBadge.tsx
  • apps/frontend/src/components/admin/AdminPanel.tsx

Reutilización de Catálogo

♻️ Componente base: shared/catalog/auth/ (Patrón de roles RBAC) Adaptación: 3 roles base → 7 roles específicos de construcción

---

📝 Descripción del Requerimiento

Contexto

El Sistema de Administración de Obra necesita diferenciar entre 7 tipos de usuarios con permisos y funcionalidades específicas para la gestión de proyectos de construcción. Esta diferenciación es crítica para:

• Proteger datos sensibles de obras y presupuestos
• Permitir gestión efectiva de recursos por perfil especializado
• Cumplir con segregación de funciones (SOD - Separation of Duties)
• Garantizar trazabilidad de acciones por responsable

Necesidad del Negocio

Problema: En proyectos de construcción, diferentes actores tienen responsabilidades y necesidades de información distintas:

• Dirección necesita visión global de márgenes y riesgos
• Ingeniería necesita control de presupuestos y programación
• Residentes necesitan capturar avances desde campo
• Compras necesita gestionar proveedores e inventarios
• Finanzas necesita controlar flujo de efectivo
• RRHH necesita gestionar nómina y asistencias
• Postventa necesita atender incidencias y garantías

Sin un sistema de roles bien definido, todos tendrían el mismo nivel de acceso, lo cual:

• Comprometería la confidencialidad de datos financieros
• Dificultaría la asignación de responsabilidades
• Impediría auditorías efectivas
• Generaría confusión en permisos

Solución: Implementar un sistema de roles con 7 niveles especializados de autorización que permita acceso granular basado en función y responsabilidad en la obra.

---

🎯 Requerimiento Funcional

RF-AUTH-001.1: Roles Disponibles

El sistema DEBE soportar exactamente 7 roles de usuario especializados en construcción:

1. Director (director)

Descripción: Director general o de proyectos con visión estratégica

Permisos:

• ✅ Visión global de todos los proyectos de la constructora
• ✅ Acceso a márgenes de utilidad y rentabilidad
• ✅ Ver todos los reportes financieros
• ✅ Aprobar presupuestos y modificaciones mayores
• ✅ Acceso a analytics y dashboards ejecutivos
• ✅ Gestionar equipo de proyecto (asignar responsables)
• ✅ Aprobar estimaciones mayores
• ❌ NO edita datos operativos (lo hace ingeniería)
• ❌ NO captura avances (lo hacen residentes)

Restricciones RLS (Row Level Security):

-- Política: Director ve todos los proyectos de su constructora
CREATE POLICY "directors_view_all_projects" ON projects.projects
    FOR SELECT
    TO authenticated
    USING (
        constructora_id = get_current_constructora_id()
        AND get_current_user_role() = 'director'
    );

Casos de Uso:

• Revisar estado financiero de todas las obras
• Analizar desviaciones de costos
• Tomar decisiones estratégicas (cancelar/continuar obras)
• Aprobar órdenes de cambio mayores

---

2. Ingeniero (engineer)

Descripción: Ingeniero de planeación, control de obra, o jefe de proyecto

Permisos:

• ✅ Todos los permisos de residente
• ✅ Crear y editar presupuestos
• ✅ Gestionar catálogo de conceptos de obra
• ✅ Ver y ajustar programación de obra
• ✅ Generar reportes de avance y desviaciones
• ✅ Revisar estimaciones antes de aprobar
• ✅ Asignar cuadrillas a frentes de trabajo
• ✅ Acceso a módulo de planeación
• ❌ NO puede aprobar estimaciones (solo director/finanzas)
• ❌ NO puede ver márgenes de utilidad detallados
• ❌ NO gestiona compras (lo hace departamento de compras)

Restricciones RLS:

-- Política: Ingeniero ve proyectos donde es responsable o de su área
CREATE POLICY "engineers_view_assigned_projects" ON projects.projects
    FOR SELECT
    TO authenticated
    USING (
        get_current_user_role() = 'engineer'
        AND (
            id IN (
                SELECT project_id
                FROM projects.project_team_assignments
                WHERE user_id = get_current_user_id()
                AND role IN ('engineer', 'project_manager')
            )
            OR constructora_id = get_current_constructora_id()
        )
    );

Casos de Uso:

• Elaborar presupuestos por prototipo
• Ajustar precios unitarios
• Revisar avances vs programado
• Generar curva S
• Revisar checklists de calidad

---

3. Residente (resident)

Descripción: Residente de obra o supervisor de campo

Permisos:

• ✅ Capturar avances físicos de obra (desde app móvil)
• ✅ Registrar incidencias y no conformidades
• ✅ Tomar evidencias fotográficas geolocalizadas
• ✅ Completar checklists de actividades
• ✅ Ver programación de su obra
• ✅ Registrar asistencia de empleados (app móvil con biométrico)
• ✅ Solicitar materiales (requisiciones)
• ✅ Ver inventario de su almacén de obra
• ❌ NO puede editar presupuestos
• ❌ NO puede aprobar órdenes de compra
• ❌ NO puede ver datos financieros (costos, márgenes)
• ❌ NO puede ver otras obras (solo las asignadas)

Restricciones RLS:

-- Política: Residente solo ve su(s) obra(s) asignada(s)
CREATE POLICY "residents_view_own_projects" ON projects.projects
    FOR SELECT
    TO authenticated
    USING (
        get_current_user_role() = 'resident'
        AND id IN (
            SELECT project_id
            FROM projects.project_team_assignments
            WHERE user_id = get_current_user_id()
            AND role = 'resident'
            AND active = true
        )
    );

Casos de Uso:

• Capturar avance de cimentación al 80%
• Registrar incidencia de filtración en lote 23
• Tomar foto de avance con GPS
• Completar checklist de instalaciones hidrosanitarias
• Registrar asistencia de cuadrilla de albañiles con huella dactilar

---

4. Compras (purchases)

Descripción: Encargado de compras y almacén

Permisos:

• ✅ Ver requisiciones de todas las obras
• ✅ Crear y gestionar órdenes de compra
• ✅ Comparar cotizaciones de proveedores
• ✅ Gestionar catálogo de proveedores
• ✅ Autorizar entregas parciales/completas
• ✅ Gestionar movimientos de inventario (entradas, salidas, traspasos)
• ✅ Ver kardex de materiales
• ✅ Configurar alertas de stock mínimo
• ❌ NO puede editar presupuestos
• ❌ NO puede ver márgenes de utilidad
• ❌ NO puede aprobar estimaciones

Restricciones RLS:

-- Política: Compras ve requisiciones de todas las obras de la constructora
CREATE POLICY "purchases_view_all_requisitions" ON purchases.purchase_requisitions
    FOR SELECT
    TO authenticated
    USING (
        get_current_user_role() = 'purchases'
        AND constructora_id = get_current_constructora_id()
    );

Casos de Uso:

• Comparar 3 cotizaciones de cemento
• Generar orden de compra por $50,000
• Autorizar entrega parcial de acero
• Traspasar materiales entre obras
• Alertar por stock bajo de alambrón

---

5. Finanzas (finance)

Descripción: Administración, contabilidad o finanzas

Permisos:

• ✅ Ver presupuestos y costos reales de todas las obras
• ✅ Aprobar estimaciones hacia clientes
• ✅ Aprobar estimaciones hacia subcontratistas
• ✅ Ver flujo de efectivo de obra
• ✅ Gestionar pagos y cobranzas
• ✅ Ver reportes financieros detallados
• ✅ Exportar datos contables
• ✅ Configurar centros de costo
• ❌ NO puede editar avances físicos
• ❌ NO puede crear órdenes de compra (solo autorizar pagos)

Restricciones RLS:

-- Política: Finanzas ve datos financieros de toda la constructora
CREATE POLICY "finance_view_all_financials" ON budgets.budgets
    FOR SELECT
    TO authenticated
    USING (
        get_current_user_role() = 'finance'
        AND constructora_id = get_current_constructora_id()
    );

Casos de Uso:

• Revisar desviaciones de presupuesto por obra
• Aprobar estimación 3 de obra A por $2M
• Ver flujo de efectivo proyectado
• Generar reporte de cartera vencida
• Exportar pólizas contables

---

6. RRHH (hr)

Descripción: Recursos Humanos y nómina

Permisos:

• ✅ Gestionar empleados y cuadrillas
• ✅ Ver asistencias de todas las obras
• ✅ Generar reportes de nómina
• ✅ Exportar datos para IMSS/INFONAVIT
• ✅ Ver costeo de mano de obra por obra
• ✅ Gestionar oficios y categorías
• ✅ Configurar parámetros de nómina
• ❌ NO puede ver presupuestos completos
• ❌ NO puede aprobar estimaciones
• ❌ NO puede ver márgenes de utilidad

Restricciones RLS:

-- Política: RRHH ve datos de empleados de toda la constructora
CREATE POLICY "hr_view_all_employees" ON hr.employees
    FOR SELECT
    TO authenticated
    USING (
        get_current_user_role() = 'hr'
        AND constructora_id = get_current_constructora_id()
    );

Casos de Uso:

• Dar de alta nuevo empleado en IMSS
• Generar archivo SUA mensual
• Revisar asistencias de obra B
• Calcular costeo de mano de obra por partida
• Exportar nómina semanal

---

7. Postventa (post_sales)

Descripción: Coordinador de postventa y garantías

Permisos:

• ✅ Ver viviendas entregadas
• ✅ Gestionar tickets de postventa
• ✅ Registrar incidencias de clientes
• ✅ Dar seguimiento a garantías
• ✅ Programar visitas de reparación
• ✅ Gestionar cuadrillas de postventa
• ✅ Ver historial completo de vivienda
• ❌ NO puede ver presupuestos
• ❌ NO puede ver datos de obras en ejecución
• ❌ NO puede gestionar compras

Restricciones RLS:

-- Política: Postventa solo ve viviendas entregadas
CREATE POLICY "post_sales_view_delivered_units" ON projects.housing_units
    FOR SELECT
    TO authenticated
    USING (
        get_current_user_role() = 'post_sales'
        AND status = 'delivered'
        AND constructora_id = get_current_constructora_id()
    );

Casos de Uso:

• Registrar incidencia de filtración en vivienda entregada
• Programar reparación de grieta en muro
• Ver historial de tickets de lote 45
• Generar reporte de garantías vencidas
• Asignar cuadrilla de plomería para reparación

---

RF-AUTH-001.2: Asignación de Roles

Reglas de Asignación:

1. Al registrarse (self-service):

   • Usuarios nuevos reciben rol resident por defecto
   • No es posible auto-asignarse otros roles
   • Registro requiere invitación de constructora

2. Promoción a otros roles:

   • Solo director puede asignar/cambiar roles
   • Requiere justificación documentada en audit_logs
   • Cambio de rol envía notificación por email

3. Relación con Constructoras:

   • Un usuario puede pertenecer a múltiples constructoras (diferentes roles)
   • Ejemplo: Juan es engineer en Constructora A y resident en Constructora B
   • Usuario selecciona constructora activa al login

4. Degradación de rol:

   • director puede degradar cualquier rol
   • Usuario puede solicitar cambio de rol
   • Cambio de rol no elimina acceso histórico (solo auditoría)

---

RF-AUTH-001.3: Validación de Roles

El sistema DEBE validar roles en 3 capas:

1. Backend (Guards):

// apps/backend/src/modules/budgets/budgets.controller.ts
@Roles('director', 'engineer', 'finance')
@Get('budgets/:id')
getBudget(@Param('id') id: string) {
  // Solo director, engineer y finance pueden ver presupuestos
}

2. Database (RLS Policies):

-- Cada tabla sensible debe tener políticas RLS por rol
-- Ejemplo: presupuestos solo visibles por director, engineer, finance
CREATE POLICY "budgets_select_by_role" ON budgets.budgets
    FOR SELECT
    TO authenticated
    USING (
        get_current_user_role() IN ('director', 'engineer', 'finance')
        AND constructora_id = get_current_constructora_id()
    );

3. Frontend (Routing y UI):

// apps/frontend/src/routes/ProtectedRoute.tsx
<RoleBasedRoute allowedRoles={['engineer', 'director']}>
  <BudgetManagement />
</RoleBasedRoute>

---

📊 Matriz de Permisos por Módulo

Módulo	director	engineer	resident	purchases	finance	hr	post_sales
Proyectos
Ver todos los proyectos	✅	✅	❌	❌	✅	❌	❌
Ver proyectos asignados	✅	✅	✅	❌	✅	❌	❌
Crear proyecto	✅	✅	❌	❌	❌	❌	❌
Editar proyecto	✅	✅	❌	❌	❌	❌	❌
Presupuestos
Ver presupuestos	✅	✅	❌	❌	✅	❌	❌
Crear presupuesto	✅	✅	❌	❌	❌	❌	❌
Editar presupuesto	✅	✅	❌	❌	❌	❌	❌
Ver márgenes	✅	❌	❌	❌	✅	❌	❌
Compras
Ver requisiciones	✅	✅	✅	✅	✅	❌	❌
Crear requisición	✅	✅	✅	✅	❌	❌	❌
Crear orden de compra	✅	❌	❌	✅	❌	❌	❌
Aprobar orden	✅	❌	❌	❌	✅	❌	❌
Inventarios
Ver inventario	✅	✅	✅	✅	✅	❌	❌
Movimientos	✅	✅	✅	✅	❌	❌	❌
Control de Obra
Capturar avances	✅	✅	✅	❌	❌	❌	❌
Ver avances	✅	✅	✅	❌	✅	❌	❌
Editar avances	✅	✅	❌	❌	❌	❌	❌
RRHH
Ver empleados	✅	✅	✅	❌	✅	✅	❌
Gestionar empleados	✅	❌	❌	❌	❌	✅	❌
Ver asistencias	✅	✅	✅	❌	✅	✅	❌
Registrar asistencia	✅	✅	✅	❌	❌	✅	❌
Exportar IMSS/INFONAVIT	✅	❌	❌	❌	✅	✅	❌
Postventa
Ver tickets	✅	✅	❌	❌	❌	❌	✅
Crear ticket	✅	✅	❌	❌	❌	❌	✅
Asignar cuadrilla	✅	❌	❌	❌	❌	❌	✅
Reportes
Dashboard ejecutivo	✅	❌	❌	❌	✅	❌	❌
Reportes de obra	✅	✅	✅	❌	✅	❌	❌
Reportes financieros	✅	❌	❌	❌	✅	❌	❌

---

✅ Criterios de Aceptación

AC-001: Roles Implementados

• ENUM construction_role existe en DDL con 7 valores
• Backend tiene enum TypeScript espejo
• Frontend tiene types TypeScript
• Documentación de cada rol completa

AC-002: RLS Policies Activas

• Tabla projects.projects tiene policies por rol
• Tabla budgets.budgets tiene policies por rol
• Tabla hr.employees tiene policies por rol
• 10+ tablas críticas con RLS implementado

AC-003: Guards Funcionales

• @Roles() decorator implementado en backend
• Endpoints sensibles protegidos con guards
• Tests E2E validan autorización por rol

AC-004: UI Adapta por Rol

• Dashboard muestra diferentes opciones según rol (7 variantes)
• Menú de navegación adapta según rol
• Componentes restringidos no se muestran a roles no autorizados

AC-005: Auditoría

• Cambios de rol se auditan en audit_logs
• Timestamp, admin que realizó cambio, y justificación registrados

---

🧪 Testing

Test Case 1: Residente NO puede ver presupuestos

test('Resident cannot view budgets', async () => {
  const resident = await createUser({ role: 'resident' });
  const project = await createProject();

  await loginAs(resident);
  const response = await api.get(`/budgets/project/${project.id}`);

  expect(response.status).toBe(403); // Forbidden
});

Test Case 2: Ingeniero puede crear presupuesto

test('Engineer can create budget', async () => {
  const engineer = await createUser({ role: 'engineer' });
  const project = await createProject();

  await loginAs(engineer);
  const response = await api.post('/budgets', {
    project_id: project.id,
    name: 'Presupuesto base',
    total: 1000000
  });

  expect(response.status).toBe(201);
  expect(response.data.budget.id).toBeDefined();
});

Test Case 3: Director tiene acceso completo

test('Director can access all projects', async () => {
  const director = await createUser({ role: 'director' });
  await createMultipleProjects(5);

  await loginAs(director);
  const response = await api.get('/projects');

  expect(response.status).toBe(200);
  expect(response.data.projects.length).toBe(5);
});

---

📚 Referencias Adicionales

Documentos Relacionados

• 📄 RF-AUTH-002: Estados de Cuenta de Usuario
• 📄 RF-AUTH-003: Multi-tenancy por Constructora
• 📐 ET-AUTH-001: RBAC Implementation

Estándares de Industria

• NIST RBAC Model
• OWASP: Authorization Cheat Sheet

---

📅 Historial de Cambios

Versión	Fecha	Autor	Cambios
1.0	2025-11-17	Tech Lead	Creación inicial basada en EAI-001/RF-AUTH-001 de GAMILIT

---

Documento: docs/01-fase-alcance-inicial/MAI-001-fundamentos/requerimientos/RF-AUTH-001-roles-construccion.md Ruta relativa: MAI-001-fundamentos/requerimientos/RF-AUTH-001-roles-construccion.md Épica: MAI-001 Sprint: Sprint 1 (Semanas 2-3)