erp-construccion/docs/02-definicion-modulos/MAI-013-administracion-seguridad/README.md

479 lines
18 KiB
Markdown

# 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:**
- **C**reate (Crear), **R**ead (Leer), **U**pdate (Actualizar), **D**elete (Eliminar), **A**pprove (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
```typescript
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:**
- **A**cceso: Consultar datos personales
- **R**ectificación: Corregir datos incorrectos
- **C**ancelación: Eliminar datos (soft delete)
- **O**posició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](./requerimientos/RF-ADM-001-usuarios-roles.md) | Gestión de usuarios y roles | CRUD usuarios, asignación de roles, multi-tenancy | Media |
| [RF-ADM-002](./requerimientos/RF-ADM-002-permisos-granulares.md) | Sistema de permisos granulares | RBAC + ABAC, matriz de permisos, RLS | Alta |
| [RF-ADM-003](./requerimientos/RF-ADM-003-centros-costo.md) | Centros de costo | Estructura jerárquica, imputación automática | Media |
| [RF-ADM-004](./requerimientos/RF-ADM-004-auditoria.md) | Auditoría y trazabilidad | Logging automático, consultas, reportes | Alta |
| [RF-ADM-005](./requerimientos/RF-ADM-005-backups.md) | Backups automáticos | Estrategia 3-2-1, restauración, DR | Alta |
### Especificaciones Técnicas (5)
| ID | Título | RF relacionado | Complejidad |
|----|--------|----------------|-------------|
| [ET-ADM-001](./especificaciones/ET-ADM-001-rbac-multi-tenancy.md) | Modelo de RBAC multi-tenancy | RF-ADM-001, RF-ADM-002 | Alta |
| [ET-ADM-002](./especificaciones/ET-ADM-002-centros-costo-jerarquicos.md) | Centros de costo jerárquicos | RF-ADM-003 | Media |
| [ET-ADM-003](./especificaciones/ET-ADM-003-audit-logging.md) | Audit logging y change tracking | RF-ADM-004 | Alta |
| [ET-ADM-004](./especificaciones/ET-ADM-004-backups-dr.md) | Backups y Disaster Recovery | RF-ADM-005 | Alta |
| [ET-ADM-005](./especificaciones/ET-ADM-005-seguridad-datos.md) | Seguridad de datos | RF-ADM-002 | Alta |
### Historias de Usuario (8) - 40 SP
| ID | Título | SP | Prioridad |
|----|--------|----|-----------|
| [US-ADM-001](./historias-usuario/US-ADM-001-crear-usuarios.md) | Crear y gestionar usuarios | 5 | P0 |
| [US-ADM-002](./historias-usuario/US-ADM-002-asignar-roles-permisos.md) | Asignar roles y permisos | 5 | P0 |
| [US-ADM-003](./historias-usuario/US-ADM-003-centros-costo.md) | Configurar centros de costo | 5 | P1 |
| [US-ADM-004](./historias-usuario/US-ADM-004-consultar-auditoria.md) | Consultar bitácora de auditoría | 5 | P0 |
| [US-ADM-005](./historias-usuario/US-ADM-005-backups-automaticos.md) | Configurar backups automáticos | 3 | P1 |
| [US-ADM-006](./historias-usuario/US-ADM-006-restaurar-backup.md) | Restaurar desde backup | 5 | P0 |
| [US-ADM-007](./historias-usuario/US-ADM-007-dashboard-admin.md) | Dashboard de administración | 7 | P1 |
| [US-ADM-008](./historias-usuario/US-ADM-008-politicas-seguridad.md) | 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](./_MAP.md)
- **Fase 1 completa:** [../README.md](../README.md)
- **Definición del MVP:** [../../00-overview/MVP-APP.md](../../00-overview/MVP-APP.md)
- **Análisis de reutilización GAMILIT:** [../ANALISIS-REUTILIZACION-GAMILIT.md](../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)