workspace/projects/erp-suite/apps/verticales/construccion/docs/02-definicion-modulos/MAI-013-administracion-seguridad

MAI-013: Administración & Seguridad

Épica: MAI-013 Nombre: Administración & Seguridad Fase: 1 - Alcance Inicial Presupuesto: $25,000 MXN Story Points: 40 SP Estado: 📝 En documentación Sprint: Sprint 3-4 (Semanas 5-8) Prioridad: P0 (Crítica) Fecha de creación: 2025-11-20

---

📋 Descripción General

El módulo de Administración & Seguridad constituye la base transversal del sistema ERP de construcción, proporcionando los mecanismos fundamentales para:

• Gestión completa de usuarios, roles y permisos específicos de construcción
• Sistema de permisos granulares (RBAC + ABAC) multi-tenancy
• Estructura organizacional con centros de costo por obra y empresa
• Auditoría completa y trazabilidad de todas las operaciones críticas
• Backups automáticos, restauración y disaster recovery
• Seguridad de datos y cumplimiento normativo (LFPDPPP/GDPR)

Diferenciador clave: Reutiliza el 90% de la infraestructura probada de GAMILIT, adaptando los 7 roles específicos del sector construcción.

---

🎯 Objetivos

Objetivos de Negocio

1. Control total de acceso: Cada usuario solo ve y opera lo que le corresponde según su rol
2. Trazabilidad completa: Auditoría de todas las operaciones críticas (aprobaciones, cambios, eliminaciones)
3. Seguridad empresarial: Aislamiento total entre empresas (multi-tenancy estricto)
4. Continuidad del negocio: Backups automáticos y recuperación rápida ante desastres
5. Cumplimiento normativo: LFPDPPP (México), GDPR (si aplica), ISO 27001 compatible

Objetivos Técnicos

1. RBAC multi-nivel: Permisos por rol + permisos granulares por módulo + RLS en base de datos
2. Defense in Depth: Validación en 3 capas (Frontend, Backend, Database)
3. Audit logging: Registro automático de eventos críticos con contexto completo
4. RTO < 4 horas: Recuperación de sistema en menos de 4 horas
5. RPO < 1 hora: Pérdida máxima de datos de 1 hora

---

👥 Roles del Sistema

7 Roles Especializados en Construcción

Rol	Código	Descripción	Acceso Principal
Director General	director	Máxima autoridad, visión estratégica	Todos los módulos (CRUD+Approve)
Ingeniero/Planeación	engineer	Planeación técnica, presupuestos, control	Proyectos, Presupuestos, Control Obra
Residente de Obra	resident	Ejecución en campo, supervisión diaria	Control Obra, Compras, Avances
Compras/Almacén	purchases	Gestión de compras, inventarios, proveedores	Compras, Inventarios, Proveedores
Administración/Finanzas	finance	Control financiero, estimaciones, pagos	Estimaciones, Finanzas, Reportes
RRHH/Nómina	hr	Recursos humanos, asistencias, nómina	RRHH, Asistencias, Nómina
Postventa	post_sales	Atención cliente, garantías, calidad	Postventa, Garantías, CRM

Diferencia vs GAMILIT: GAMILIT tiene 3 roles académicos (student, admin_teacher, super_admin); aquí se expanden a 7 roles especializados en construcción.

---

🔒 Matriz de Permisos por Módulo

Módulo	Director	Engineer	Resident	Purchases	Finance	HR	Post Sales
Fundamentos	CRUD+A	R	R	R	R	R	R
Proyectos	CRUD+A	CRUD	R	R	R	R	R
Presupuestos	CRUD+A	CRUD	R	R	R	-	-
Compras	CRUD+A	R	CRUD	CRUD+A	R	-	-
Inventarios	CRUD+A	R	CRUD	CRUD	R	-	-
Contratos	CRUD+A	CRUD	R	R	R	-	-
Control Obra	CRUD+A	CRUD	CRUD	R	R	-	R
Estimaciones	CRUD+A	CRUD	R	-	CRUD+A	-	-
RRHH	CRUD+A	R	R	-	R	CRUD+A	-
Calidad	CRUD+A	CRUD	CRUD	-	-	-	CRUD
CRM	CRUD+A	R	-	-	R	-	CRUD+A
INFONAVIT	CRUD+A	R	-	-	CRUD	CRUD	R
Reportes	CRUD+A	R	R	R	CRUD	R	R
Administración	CRUD+A	-	-	-	R	R	-

Leyenda:

• Create (Crear), Read (Leer), Update (Actualizar), Delete (Eliminar), Approve (Aprobar)
• - Sin acceso

---

🏢 Centros de Costo

Estructura Jerárquica

Los centros de costo permiten la imputación precisa de gastos y el análisis de rentabilidad por:

Empresa Constructora ABC
├── 000 - Dirección General
│   ├── 001 - Finanzas
│   ├── 002 - RRHH
│   ├── 003 - Sistemas
│   └── 004 - Legal
├── 100 - Obra: Fraccionamiento Los Pinos
│   ├── 101 - Etapa 1
│   │   ├── 101.1 - Urbanización
│   │   ├── 101.2 - Edificación
│   │   └── 101.3 - Acabados
│   └── 102 - Etapa 2
│       ├── 102.1 - Urbanización
│       └── 102.2 - Edificación
└── 200 - Obra: Torre Residencial Aura
    ├── 201 - Cimentación
    ├── 202 - Estructura
    ├── 203 - Instalaciones
    └── 204 - Acabados

Tipos de Centros de Costo

1. Directos (Producción): Vinculados a obras específicas
2. Indirectos (Administración): Gastos corporativos
3. Servicios Compartidos: TI, RRHH, Finanzas

Imputación Automática

• Compras: Se imputan al centro de costo de la obra/etapa
• RRHH: Horas-hombre se distribuyen por frente de obra
• Maquinaria: Uso de activos se imputa por proyecto
• Gastos indirectos: Distribución proporcional por proyecto

---

🔍 Sistema de Auditoría

Eventos Auditables

1. Autenticación y Autorización

• Login exitoso/fallido (incluye IP, user agent, geolocalización)
• Logout (manual o por timeout)
• Cambio de contraseña
• Bloqueo/desbloqueo de cuenta
• Cambio de constructora (multi-tenancy)

2. Gestión de Usuarios

• Creación de usuario (con rol asignado)
• Modificación de permisos/roles
• Activación/desactivación de usuarios
• Cambio de datos personales
• Invitaciones enviadas

3. Operaciones Críticas

• ✅ Aprobación de estimaciones (>$50K)
• ✅ Aprobación de órdenes de compra (>$20K)
• ✅ Modificación de presupuestos maestros (cualquier cambio)
• ✅ Cierre de etapas de obra (irreversible)
• ✅ Eliminación de registros importantes (soft delete con log)
• ✅ Cambio de estado de proyecto (cualquier transición)
• ✅ Pago de estimaciones (>$10K)

4. Administración del Sistema

• Cambios en configuración global
• Creación/restauración de backups
• Modificación de centros de costo
• Cambios en políticas de seguridad
• Activación/desactivación de módulos

Estructura de Log de Auditoría

interface AuditLog {
  id: string; // UUID
  timestamp: Date; // ISO 8601

  // Usuario
  userId: string;
  userName: string;
  userEmail: string;
  userRole: ConstructionRole;

  // Contexto empresarial
  constructoraId: string;
  constructoraName: string;

  // Acción
  action: AuditAction; // create, update, delete, approve, login, etc.
  module: string; // projects, budgets, estimations, etc.
  entityType: string; // project, budget, estimation, etc.
  entityId: string; // UUID del registro afectado

  // Cambios
  changes?: {
    field: string;
    oldValue: any;
    newValue: any;
  }[];

  // Contexto técnico
  ipAddress: string;
  userAgent: string;
  sessionId: string;
  geolocation?: {
    latitude: number;
    longitude: number;
  };

  // Metadata
  severity: 'low' | 'medium' | 'high' | 'critical';
  success: boolean;
  errorMessage?: string;
}

Retención de Logs

• Logs operativos: 90 días en base de datos principal
• Logs críticos: 5 años en base de datos de auditoría (comprimidos)
• Logs de autenticación: 1 año (para análisis de seguridad)

---

💾 Estrategia de Backups

Tipos de Backup

Tipo	Frecuencia	Retención	Contenido
Full Backup	Diario (3:00 AM)	7 días	Base de datos completa + archivos + configuraciones
Incremental	Cada 6 horas	48 horas	Solo cambios desde último backup
Archivos críticos	Cada hora	24 horas	Documentos, evidencias fotográficas, planos
Snapshots DB	Cada 30 min	6 horas	Snapshot de PostgreSQL (PITR)

Ubicaciones de Almacenamiento

Estrategia 3-2-1:

• 3 copias de los datos
• 2 medios diferentes (local + cloud)
• 1 copia offsite (geográficamente separada)

Ubicaciones

1. Primaria: Servidor local (NAS/SAN)
2. Secundaria: Cloud storage (AWS S3 / Azure Blob Storage)
3. Terciaria: Backup offsite opcional (para clientes enterprise)

Proceso de Restauración

Escenarios de recuperación:

1. Recuperación de archivo individual

• RTO: 15 minutos
• Procedimiento: Buscar en backup incremental más reciente → Restaurar archivo

2. Recuperación de base de datos completa

• RTO: 2-4 horas
• Procedimiento:
  1. Detener servicios backend
  2. Restaurar último full backup
  3. Aplicar incrementales
  4. Verificar integridad con checksums
  5. Reiniciar servicios
  6. Validar con usuarios clave

3. Disaster Recovery (servidor completo)

• RTO: 4-8 horas
• RPO: 1 hora
• Procedimiento:
  1. Provisionar nueva infraestructura
  2. Restaurar desde cloud backup
  3. Reconfigurar DNS/networking
  4. Validar funcionalidad
  5. Comunicar a usuarios

Pruebas de Restauración

• Frecuencia: Mensual (primer domingo de cada mes)
• Alcance: Restauración completa en ambiente de QA
• Validación: Checklist de 20 puntos críticos
• Documentación: Reporte de prueba con tiempos y hallazgos

---

🔐 Seguridad de Datos

Encriptación

En Reposo (At Rest)

• Base de datos: PostgreSQL con pgcrypto extension
• Archivos: AES-256 para documentos sensibles
• Backups: Cifrado completo con GPG
• Datos biométricos: Hash SHA-256 irreversible

En Tránsito (In Transit)

• HTTPS/TLS 1.3: Todo el tráfico web
• WSS (WebSocket Secure): Notificaciones en tiempo real
• VPN: Conexiones entre servidores
• SSH: Acceso administrativo

Cumplimiento Normativo

LFPDPPP (Ley Federal de Protección de Datos Personales en Posesión de Particulares - México)

Datos sensibles protegidos:

• Datos biométricos (huellas dactilares, reconocimiento facial)
• Datos financieros (salarios, cuentas bancarias)
• Datos de salud (incapacidades, accidentes laborales)

Derechos ARCO implementados:

• Acceso: Consultar datos personales
• Rectificación: Corregir datos incorrectos
• Cancelación: Eliminar datos (soft delete)
• Oposición: Oponerse al tratamiento

Consentimiento explícito:

• Registro de consentimiento para captura de biométricos
• Aviso de privacidad aceptado al crear cuenta
• Log de aceptación con timestamp e IP

GDPR (si aplica - clientes europeos)

• Right to be forgotten (eliminación completa)
• Data portability (exportación de datos en JSON/CSV)
• Privacy by design (desde arquitectura)

Políticas de Seguridad

1. Contraseñas:

   • Mínimo 8 caracteres (1 mayúscula, 1 número, 1 símbolo)
   • Expiración cada 90 días (configurable)
   • No reutilizar últimas 5 contraseñas
   • Bloqueo tras 5 intentos fallidos

2. Sesiones:

   • Timeout de inactividad: 30 minutos
   • Máximo 3 sesiones concurrentes por usuario
   • Logout forzado al cambiar contraseña

3. Acceso a datos:

   • Row Level Security (RLS) en PostgreSQL
   • Queries automáticamente filtradas por constructoraId
   • Logs de acceso a datos sensibles

---

📊 Componentes del Módulo

Requerimientos Funcionales (5)

ID	Título	Descripción	Complejidad
RF-ADM-001	Gestión de usuarios y roles	CRUD usuarios, asignación de roles, multi-tenancy	Media
RF-ADM-002	Sistema de permisos granulares	RBAC + ABAC, matriz de permisos, RLS	Alta
RF-ADM-003	Centros de costo	Estructura jerárquica, imputación automática	Media
RF-ADM-004	Auditoría y trazabilidad	Logging automático, consultas, reportes	Alta
RF-ADM-005	Backups automáticos	Estrategia 3-2-1, restauración, DR	Alta

Especificaciones Técnicas (5)

ID	Título	RF relacionado	Complejidad
ET-ADM-001	Modelo de RBAC multi-tenancy	RF-ADM-001, RF-ADM-002	Alta
ET-ADM-002	Centros de costo jerárquicos	RF-ADM-003	Media
ET-ADM-003	Audit logging y change tracking	RF-ADM-004	Alta
ET-ADM-004	Backups y Disaster Recovery	RF-ADM-005	Alta
ET-ADM-005	Seguridad de datos	RF-ADM-002	Alta

Historias de Usuario (8) - 40 SP

ID	Título	SP	Prioridad
US-ADM-001	Crear y gestionar usuarios	5	P0
US-ADM-002	Asignar roles y permisos	5	P0
US-ADM-003	Configurar centros de costo	5	P1
US-ADM-004	Consultar bitácora de auditoría	5	P0
US-ADM-005	Configurar backups automáticos	3	P1
US-ADM-006	Restaurar desde backup	5	P0
US-ADM-007	Dashboard de administración	7	P1
US-ADM-008	Configurar políticas de seguridad	5	P0

Total: 40 SP

---

🔗 Integraciones con Otros Módulos

Este módulo es transversal y se integra con todos los demás:

Módulo	Integración	Funcionalidad
MAI-001 (Fundamentos)	Core	Reutiliza autenticación, extiende roles
MAI-002 (Proyectos)	RLS + Permisos	Filtrado por constructoraId, permisos CRUD
MAI-003 (Presupuestos)	Auditoría	Log de cambios en presupuestos maestros
MAI-004 (Compras)	Centros de Costo	Imputación automática de compras
MAI-005 (Control Obra)	Permisos	Residentes solo ven sus proyectos
MAI-007 (RRHH)	Centros de Costo	Distribución de horas-hombre
MAI-008 (Estimaciones)	Auditoría	Log de aprobaciones de estimaciones
MAE-014 (Finanzas)	Centros de Costo	Reporting financiero por centro

---

📈 Métricas de Éxito

KPIs Operacionales

KPI	Target	Medición
Tiempo de creación de usuario	< 2 minutos	Desde invitación hasta primer login
Disponibilidad del sistema	99.5%	Uptime mensual
RTO (Recovery Time Objective)	< 4 horas	Tiempo de recuperación total
RPO (Recovery Point Objective)	< 1 hora	Pérdida máxima de datos
Accesos no autorizados	0	Intentos bloqueados por RLS
Auditoría completa	100%	% de operaciones críticas logueadas

KPIs de Seguridad

KPI	Target	Medición
Intentos de login fallidos	< 0.5%	% del total de logins
Cuentas bloqueadas	< 1%	% de usuarios activos
Tiempo de detección de anomalías	< 5 minutos	Alertas de seguridad
Backups exitosos	100%	% de backups completados sin errores
Tiempo de restauración (prueba)	< 2 horas	Pruebas mensuales

---

🚨 Riesgos y Mitigaciones

Riesgo	Probabilidad	Impacto	Mitigación
Filtración de datos por RLS mal configurado	Media	Crítico	Tests automáticos de RLS en CI/CD, auditoría trimestral
Pérdida de backups	Baja	Crítico	Estrategia 3-2-1, pruebas mensuales de restauración
Ataque de fuerza bruta	Media	Alto	Rate limiting, bloqueo tras 5 intentos, CAPTCHA
Insider threat (empleado malicioso)	Baja	Alto	Auditoría completa, separación de funciones, alertas
Downtime prolongado	Baja	Crítico	Alta disponibilidad, DR plan, monitoreo 24/7

---

🎯 Próximos Pasos

Fase de Documentación

1. ✅ README.md completado
2. ⏳ Crear 5 Requerimientos Funcionales
3. ⏳ Crear 5 Especificaciones Técnicas
4. ⏳ Crear 8 Historias de Usuario
5. ⏳ Crear TRACEABILITY.yml

Fase de Implementación (Sprint 3-4)

1. Sprint 3 - Semana 5-6:

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

2. Sprint 4 - Semana 7-8:

   • US-ADM-003: Centros de costo (5 SP)
   • US-ADM-006: Restauración (5 SP)
   • US-ADM-007: Dashboard admin (7 SP)
   • US-ADM-008: Políticas seguridad (5 SP)
   • US-ADM-005: Backups (3 SP)
   • Total: 25 SP

---

📚 Referencias

• Índice del módulo: _MAP.md
• Fase 1 completa: ../README.md
• Definición del MVP: ../../00-overview/MVP-APP.md
• Análisis de reutilización GAMILIT: ../ANALISIS-REUTILIZACION-GAMILIT.md

---

Generado: 2025-11-20 Versión: 1.0 Autor: Sistema de Documentación Técnica Estado: ✅ Completo Reutilización GAMILIT: 90% (infraestructura base)