workspace-v1/projects/erp-construccion/docs/02-definicion-modulos/MAI-013-administracion-seguridad/RESUMEN-EPICA-MAI-013.md

Resumen Ejecutivo: MAI-013 - Administración & Seguridad

Fecha de generación: 2025-11-20 Estado: 🚧 En Progreso (30% completo) Story Points: 40 SP Prioridad: P0 (Crítica)

---

📊 Estado de Completitud

Tipo de Documento	Completados	Total	%
README Principal	1	1	100% ✅
Requerimientos Funcionales (RF)	2	5	40% 🚧
Especificaciones Técnicas (ET)	0	5	0% ⏳
Historias de Usuario (US)	0	8	0% ⏳
Total Documentos	3	19	16%

Tamaño total generado: ~85 KB (estimado final: ~280 KB)

---

✅ Documentos Completados

1. README.md del Módulo (~30 KB) ✅

Contenido clave:

• Descripción general del módulo transversal
• 7 roles especializados en construcción
• Matriz completa de permisos (7 roles × 14 módulos)
• Estructura jerárquica de centros de costo
• Sistema de auditoría completo (4 categorías de eventos)
• Estrategia de backups 3-2-1 (Full, Incremental, Archivos, Snapshots)
• Seguridad de datos (LFPDPPP + GDPR compliance)
• Políticas de seguridad (contraseñas, sesiones, acceso)
• Métricas de éxito (KPIs operacionales y de seguridad)
• Riesgos y mitigaciones

Audiencia: Product Owner, Stakeholders, Tech Lead, Security Team

---

2. RF-ADM-001: Gestión de Usuarios y Roles (~28 KB) ✅

Contenido principal:

7 Roles Especializados

Rol	Código	Nivel	Permisos Globales
Director General	director	🔴 Alto	CRUD+Approve en todos
Ingeniero	engineer	🟠 Alto	CRUD en Proyectos, Presupuestos, Obra
Residente	resident	🟡 Medio	CRUD en Obra, Compras, Avances
Compras	purchases	🟡 Medio	CRUD+Approve en Compras, Inventarios
Finanzas	finance	🟠 Alto	CRUD+Approve en Estimaciones, Finanzas
RRHH	hr	🟡 Medio	CRUD+Approve en RRHH, Nómina
Postventa	post_sales	🟢 Bajo	CRUD en Postventa, Garantías, CRM

Multi-Tenancy

• Usuario puede pertenecer a múltiples empresas constructoras
• Roles diferentes en cada empresa
• Selector de empresa sin re-login
• Aislamiento total por constructoraId (RLS)

Estados de Cuenta

[*] → active: Invitación aceptada
active → suspended: Suspensión temporal
suspended → active: Reactivación
active → inactive: Baja
inactive → active: Reactivación
active → locked: 5 intentos fallidos
locked → active: Desbloqueo (admin o timeout)

Proceso de Invitación

1. Admin crea invitación (email, rol, empresa)
2. Sistema genera token único (válido 7 días)
3. Email enviado con link de registro
4. Usuario completa perfil y contraseña
5. Primer login automático
6. Estado: active

Row Level Security (RLS)

-- Política automática en PostgreSQL
CREATE POLICY users_isolation_policy ON user_constructoras
  USING (constructora_id = current_setting('app.current_constructora_id')::uuid);

Casos de Uso Documentados:

• Invitar nuevo ingeniero
• Usuario multi-empresa (Director en A, Ingeniero en B)
• Suspensión temporal con reactivación automática

Tests Especificados:

• Invitación exitosa con validación de email enviado
• Multi-tenancy: aislamiento entre empresas
• Cambio de rol con auditoría

---

3. RF-ADM-002: Sistema de Permisos Granulares (~27 KB) ✅

Contenido principal:

RBAC + ABAC Combinados

• RBAC: Permisos basados en roles predefinidos
• ABAC: Permisos adicionales basados en atributos/contexto

Permisos por Acción (CRUD+A)

enum PermissionAction {
  CREATE = 'create',
  READ = 'read',
  UPDATE = 'update',
  DELETE = 'delete',
  APPROVE = 'approve'
}

Matriz Completa (7 Roles × 14 Módulos)

Módulo	Director	Engineer	Resident	Purchases	Finance	HR	Post Sales
projects	CRUD+A	CRUD	R	R	R	R	R
budgets	CRUD+A	CRUD	R	R	R	-	-
purchases	CRUD+A	R	CRUD	CRUD+A	R	-	-
construction	CRUD+A	CRUD	CRUD	R	R	-	R
estimations	CRUD+A	CRUD	R	-	CRUD+A	-	-
hr	CRUD+A	R	R	-	R	CRUD+A	-
admin	CRUD+A	-	-	-	R	R	-

Reglas de Negocio (ABAC)

Regla 1: Acceso por Proyecto Asignado

• Usuario solo ve proyectos donde es miembro del equipo
• Excepción: Director ve todos los proyectos

Regla 2: Aprobación por Monto

Monto	Aprobador Nivel 1	Aprobador Nivel 2
< $20K	Compras/Finance	-
$20K - $100K	Finance	Director
> $100K	Finance + Director	Ambos requeridos

Regla 3: Edición Temporal

Entidad	Tiempo límite	Excepción
Estimación autorizada	0 días (bloqueado)	Director puede revertir
Orden de compra	7 días	Director puede modificar
Avance de obra	3 días	Ingeniero puede corregir

Regla 4: Segregación de Funciones

• ❌ Creador de orden de compra NO puede aprobarla
• ❌ Quien captura avances NO puede aprobarlos
• ✅ Director puede (excepción)

Validación en 3 Capas

Capa 1: Frontend (UX)

{hasPermission('projects', 'create') && (
  <Button onClick={createProject}>Crear Proyecto</Button>
)}

Capa 2: Backend (Guards)

@RequirePermissions('projects', 'create')
@RequireRole('director', 'engineer')
async create(@Body() dto: CreateProjectDto) { }

Capa 3: Database (RLS)

CREATE POLICY projects_update_policy ON projects
FOR UPDATE
USING (
  constructora_id = current_setting('app.current_constructora_id')::uuid
  AND (
    current_setting('app.current_user_role') = 'director'
    OR user_id IN (SELECT user_id FROM team WHERE project_id = projects.id)
  )
);

Permisos Personalizados

interface CustomPermission {
  userId: string;
  module: string; // 'budgets'
  actions: PermissionAction[]; // ['read']
  scope?: {
    projectId?: string; // Solo para un proyecto
    validUntil?: Date;  // Permiso temporal
  };
  grantedBy: string;
}

Caso de uso: Auditor externo con acceso temporal (30 días) a presupuestos de un proyecto específico.

Tests Especificados:

• Matriz completa de permisos por rol
• RLS automático en database
• Permisos personalizados temporales con expiración

---

📋 Documentos Pendientes (16/19)

Requerimientos Funcionales (3 pendientes)

RF-ADM-003: Centros de Costo (Estimado: ~22 KB)

Contenido esperado:

• Estructura jerárquica (Empresa → Obra → Etapa → Frente)
• 3 tipos: Directos, Indirectos, Servicios Compartidos
• Imputación automática (Compras, RRHH, Maquinaria)
• Reportes por centro de costo
• Distribución de gastos indirectos

RF-ADM-004: Auditoría y Trazabilidad (Estimado: ~28 KB)

Contenido esperado:

• 4 categorías de eventos: Autenticación, Gestión usuarios, Operaciones críticas, Administración
• Estructura completa de AuditLog (20+ campos)
• Retención: 90 días (operativos), 5 años (críticos)
• Queries de consulta con filtros
• Reportes de auditoría

RF-ADM-005: Backups Automáticos (Estimado: ~25 KB)

Contenido esperado:

• 4 tipos de backup: Full (diario), Incremental (6h), Archivos (1h), Snapshots (30min)
• Estrategia 3-2-1 (3 copias, 2 medios, 1 offsite)
• Proceso de restauración (3 escenarios)
• RTO < 4 horas, RPO < 1 hora
• Pruebas mensuales de restauración

---

Especificaciones Técnicas (5 pendientes)

ID	Título	Complejidad	Tamaño Estimado
ET-ADM-001	Modelo de RBAC multi-tenancy	Alta	~45 KB
ET-ADM-002	Centros de costo jerárquicos	Media	~35 KB
ET-ADM-003	Audit logging y change tracking	Alta	~40 KB
ET-ADM-004	Backups y Disaster Recovery	Alta	~38 KB
ET-ADM-005	Seguridad de datos (encriptación)	Alta	~35 KB

Total estimado: ~193 KB

Contenido esperado:

• Entities TypeORM completas
• ENUMs y tipos
• Services con lógica de negocio
• Controllers RESTful
• Frontend components (React)
• Validaciones Zod
• Tests unitarios
• Cron jobs (backups, cleanup)

---

Historias de Usuario (8 pendientes)

ID	Título	SP	Tamaño Estimado
US-ADM-001	Crear y gestionar usuarios	5	~15 KB
US-ADM-002	Asignar roles y permisos	5	~15 KB
US-ADM-003	Configurar centros de costo	5	~12 KB
US-ADM-004	Consultar bitácora de auditoría	5	~13 KB
US-ADM-005	Configurar backups automáticos	3	~10 KB
US-ADM-006	Restaurar desde backup	5	~14 KB
US-ADM-007	Dashboard de administración	7	~16 KB
US-ADM-008	Configurar políticas de seguridad	5	~13 KB

Total: 40 SP | ~108 KB estimado

---

🏗️ Arquitectura Técnica (Preliminar)

Base de Datos (PostgreSQL)

-- Schemas principales
CREATE SCHEMA IF NOT EXISTS auth_management;
CREATE SCHEMA IF NOT EXISTS admin;
CREATE SCHEMA IF NOT EXISTS audit_logging;

-- Tablas clave (estimadas)
auth_management.users (12 columnas)
auth_management.user_constructoras (6 columnas)
auth_management.invitations (8 columnas)
admin.roles (5 columnas)
admin.role_permissions (5 columnas)
admin.custom_permissions (10 columnas)
admin.cost_centers (12 columnas)
admin.system_settings (8 columnas)
audit_logging.audit_logs (20+ columnas)
admin.backups (15 columnas)

-- Total estimado: 10-12 tablas principales

Backend (NestJS)

apps/backend/src/modules/
├── auth-management/
│   ├── users.service.ts
│   ├── invitations.service.ts
│   └── users.controller.ts
├── admin/
│   ├── roles.service.ts
│   ├── permissions.service.ts
│   ├── cost-centers.service.ts
│   └── system-settings.service.ts
├── audit/
│   ├── audit-logs.service.ts
│   ├── audit.middleware.ts
│   └── audit-logs.controller.ts
└── backups/
    ├── backup.service.ts
    ├── backup.cron.ts
    └── restore.service.ts

Frontend (React)

apps/frontend/src/features/admin/
├── pages/
│   ├── UsersManagementPage.tsx
│   ├── RolesPermissionsPage.tsx
│   ├── CostCentersPage.tsx
│   ├── AuditLogsPage.tsx
│   ├── BackupsPage.tsx
│   └── SystemSettingsPage.tsx
├── components/
│   ├── UserForm.tsx
│   ├── PermissionMatrix.tsx
│   ├── CostCenterTree.tsx
│   ├── AuditLogViewer.tsx
│   ├── BackupManager.tsx
│   └── SystemDashboard.tsx
└── stores/
    └── adminStore.ts

---

📈 Características Clave Implementadas (Documentadas)

1. Multi-Tenancy Seguro ✅

• Múltiples empresas en el mismo sistema
• Aislamiento total por constructoraId
• RLS en PostgreSQL (defensa en profundidad)
• Selector de empresa sin re-login

2. RBAC + ABAC Combinados ✅

• 7 roles especializados en construcción
• Matriz de permisos (7 × 14 módulos)
• Reglas de negocio contextuales
• Permisos personalizados temporales

3. Validación en 3 Capas ✅

• Frontend: UX (oculta botones)
• Backend: Guards (seguridad real)
• Database: RLS (defensa en profundidad)

4. Auditoría Completa 🚧 (Pendiente documentar)

• 4 categorías de eventos
• Registro automático de operaciones críticas
• Retención diferenciada (90 días / 5 años)
• Queries con filtros avanzados

5. Backups Automáticos 🚧 (Pendiente documentar)

• Estrategia 3-2-1
• 4 tipos de backup (Full, Incremental, Archivos, Snapshots)
• RTO < 4 horas, RPO < 1 hora
• Pruebas mensuales

---

🔗 Integraciones con Otros Módulos

Módulo	Tipo	Funcionalidad
Todos los módulos	Transversal	RBAC, RLS, Auditoría
MAI-001 (Fundamentos)	Core	Reutiliza auth, extiende roles
MAI-002 (Proyectos)	RLS	Filtrado por constructora y equipo
MAI-003 (Presupuestos)	Auditoría	Log de cambios en presupuestos
MAI-004 (Compras)	Centros Costo	Imputación automática
MAI-008 (Estimaciones)	Auditoría	Log de aprobaciones >$50K
MAE-014 (Finanzas)	Centros Costo	Reporting financiero

---

📊 Métricas de Progreso

Métrica	Planificado	Actual	%
README	1	1	100% ✅
RFs	5	2	40% 🚧
ETs	5	0	0% ⏳
USs	8	0	0% ⏳
Story Points	40 SP	-	-
Tamaño Documentación	~280 KB	~85 KB	30%
Tiempo invertido	-	~1 hora	-

---

🎯 Próximos Pasos Inmediatos

Opción 1: Completar Requerimientos Funcionales ⭐ RECOMENDADO

Razón: Terminar la capa de RFs antes de pasar a ETs

Pendientes:

1. RF-ADM-003: Centros de Costo (~1 hora)
2. RF-ADM-004: Auditoría (~1.5 horas)
3. RF-ADM-005: Backups (~1 hora)

Estimación: 3.5 horas para completar RFs (100%)

Opción 2: Comenzar Especificaciones Técnicas

Razón: Tener especificación técnica completa de lo documentado

Prioridad:

1. ET-ADM-001: RBAC multi-tenancy (45 KB, ~2 horas)
2. ET-ADM-003: Audit logging (40 KB, ~2 horas)

Opción 3: Crear Historias de Usuario

Razón: Tener user stories listas para sprint planning

Prioridad P0 (críticas):

• US-ADM-001: Gestión de usuarios (5 SP)
• US-ADM-002: Roles y permisos (5 SP)
• US-ADM-004: Auditoría (5 SP)
• US-ADM-006: Restauración (5 SP)

---

📝 Lecciones Aprendidas

Reutilización de GAMILIT

Componente	Reutilización	Adaptación Necesaria
Auth base	95%	Extender de 3 a 7 roles
Multi-tenancy	90%	Adaptar de schools a constructoras
RLS policies	85%	Adaptar contexto (school_id → constructora_id)
Audit logging	70%	Agregar eventos específicos de construcción
RBAC guards	90%	Agregar permisos APPROVE

Ahorro estimado: 90% del trabajo base ya hecho en GAMILIT.

Complejidad Manejada

✅ Multi-tenancy con múltiples roles por empresa ✅ Matriz de permisos 7 × 14 ✅ Validación en 3 capas (Frontend, Backend, Database) ✅ Reglas de negocio complejas (ABAC) ✅ Permisos personalizados temporales

---

🚨 Riesgos Identificados

Riesgo	Probabilidad	Impacto	Mitigación
RLS mal configurado	Media	Crítico	Tests automáticos en CI/CD
Permisos demasiado complejos	Media	Alto	Documentación clara, UI intuitiva
Performance de audit logs	Media	Medio	Particionamiento de tabla, retención
Backups fallan silenciosamente	Baja	Crítico	Monitoreo activo, alertas

---

Generado: 2025-11-20 Versión: 1.0 Autor: Sistema de Documentación Técnica Próxima revisión: Al completar RFs pendientes Reutilización GAMILIT: 90%