erp-construccion/orchestration/directivas/DIRECTIVA-INTEGRACION-INFONAVIT.md

# Directiva: Integración INFONAVIT

## Metadatos

| Campo | Valor |
|-------|-------|
| **ID** | DIR-CONST-001 |
| **Versión** | 1.0.0 |
| **Ámbito** | Vertical Construcción |
| **Módulo** | MAI-011 |
| **Estado** | Activa |

## Propósito

Define las reglas y patrones obligatorios para la integración con programas de INFONAVIT en el ERP de Construcción.

## Alcance

Esta directiva aplica a:
- Registro de proyectos bajo programas INFONAVIT
- Gestión de requisitos normativos
- Checklists de cumplimiento
- Repositorio de evidencias
- Auditorías y verificaciones
- Reportes de cumplimiento

## Programas INFONAVIT Soportados

```yaml
programas:
  - codigo: COFINAVIT
    descripcion: Crédito cofinanciado INFONAVIT + Banco

  - codigo: INFONAVIT_TOTAL
    descripcion: Crédito 100% INFONAVIT

  - codigo: SEGUNDO_CREDITO
    descripcion: Segundo crédito para mejora o ampliación

  - codigo: CONSTRUYO_INFONAVIT
    descripcion: Construcción en terreno propio

  - codigo: LINEA_III
    descripcion: Reparación, ampliación o mejora
```

## Reglas Obligatorias

### 1. Registro de Proyectos

```typescript
// Toda entidad relacionada con INFONAVIT debe incluir:
interface InfonavitProjectEntity {
  // Identificadores obligatorios
  id: string;
  tenantId: string;
  projectId: string;

  // INFONAVIT específico
  infonavitProgramId: string;           // Programa vinculado
  infonavitProjectNumber: string;       // Número de proyecto INFONAVIT
  registrationDate: Date;               // Fecha de registro
  status: InfonavitProjectStatus;       // Estado de cumplimiento

  // Requisitos
  totalRequirements: number;            // Total de requisitos
  completedRequirements: number;        // Requisitos cumplidos
  compliancePercentage: number;         // % de cumplimiento

  // Auditoría
  lastAuditDate: Date | null;
  nextAuditDate: Date | null;
  auditStatus: AuditStatus;
}

type InfonavitProjectStatus =
  | 'REGISTRO_PENDIENTE'
  | 'EN_PROCESO'
  | 'CUMPLIMIENTO_PARCIAL'
  | 'CUMPLIMIENTO_TOTAL'
  | 'OBSERVACIONES'
  | 'SUSPENDIDO';
```

### 2. Checklists de Cumplimiento

```yaml
checklist_structure:
  categorias:
    - codigo: DOC_LEGAL
      nombre: Documentación Legal
      requisitos:
        - Escrituras del terreno
        - Permisos de construcción
        - Licencias municipales
        - Registro RUV

    - codigo: DOC_TECNICA
      nombre: Documentación Técnica
      requisitos:
        - Planos arquitectónicos autorizados
        - Memoria de cálculo estructural
        - Especificaciones técnicas
        - Programa de obra

    - codigo: CALIDAD
      nombre: Control de Calidad
      requisitos:
        - Pruebas de laboratorio
        - Bitácora de obra
        - Reportes fotográficos
        - Actas de verificación

    - codigo: NORMATIVA
      nombre: Cumplimiento Normativo
      requisitos:
        - NOM-020-ENER (eficiencia energética)
        - NOM-001-CONAGUA
        - Normas sísmicas locales
        - Certificación ecológica
```

### 3. Gestión de Evidencias

```typescript
// Toda evidencia debe tener metadatos completos
interface EvidenceDocument {
  id: string;
  tenantId: string;
  projectId: string;
  requirementId: string;

  // Metadatos del documento
  documentType: EvidenceType;
  fileName: string;
  filePath: string;
  mimeType: string;
  fileSize: number;

  // Validación
  uploadedAt: Date;
  uploadedBy: string;
  validatedAt: Date | null;
  validatedBy: string | null;
  validationStatus: ValidationStatus;

  // Versionamiento
  version: number;
  previousVersionId: string | null;

  // Expiración (si aplica)
  expirationDate: Date | null;
  isExpired: boolean;
}

type EvidenceType =
  | 'DOCUMENTO_LEGAL'
  | 'PLANO_TECNICO'
  | 'REPORTE_LABORATORIO'
  | 'FOTOGRAFIA'
  | 'ACTA_VERIFICACION'
  | 'CERTIFICADO'
  | 'OTRO';
```

### 4. Workflow de Auditorías

```yaml
workflow_auditoria:
  estados:
    - PROGRAMADA
    - EN_PROCESO
    - PENDIENTE_EVIDENCIAS
    - REVISION
    - APROBADA
    - CON_OBSERVACIONES
    - RECHAZADA

  transiciones:
    PROGRAMADA:
      - to: EN_PROCESO
        requiere: fecha_inicio

    EN_PROCESO:
      - to: PENDIENTE_EVIDENCIAS
        requiere: hallazgos_registrados
      - to: REVISION
        requiere: evidencias_completas

    PENDIENTE_EVIDENCIAS:
      - to: EN_PROCESO
        requiere: evidencias_cargadas

    REVISION:
      - to: APROBADA
        requiere: sin_observaciones_criticas
      - to: CON_OBSERVACIONES
        requiere: observaciones_menores
      - to: RECHAZADA
        requiere: incumplimiento_critico
```

## Patrones de Implementación

### Schema de Base de Datos

```sql
-- Schema específico para INFONAVIT
CREATE SCHEMA IF NOT EXISTS infonavit_management;

-- Tabla de programas
CREATE TABLE infonavit_management.programs (
    id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
    tenant_id UUID NOT NULL,
    code VARCHAR(50) NOT NULL,
    name VARCHAR(200) NOT NULL,
    description TEXT,
    requirements_template JSONB,
    is_active BOOLEAN DEFAULT TRUE,
    created_at TIMESTAMPTZ DEFAULT NOW(),
    updated_at TIMESTAMPTZ DEFAULT NOW(),
    UNIQUE(tenant_id, code)
);

-- Tabla de proyectos registrados
CREATE TABLE infonavit_management.registered_projects (
    id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
    tenant_id UUID NOT NULL,
    project_id UUID NOT NULL REFERENCES project_management.projects(id),
    program_id UUID NOT NULL REFERENCES infonavit_management.programs(id),
    infonavit_number VARCHAR(50),
    registration_date DATE NOT NULL,
    status VARCHAR(50) NOT NULL DEFAULT 'REGISTRO_PENDIENTE',
    compliance_percentage DECIMAL(5,2) DEFAULT 0,
    last_audit_date DATE,
    next_audit_date DATE,
    notes TEXT,
    created_at TIMESTAMPTZ DEFAULT NOW(),
    updated_at TIMESTAMPTZ DEFAULT NOW(),
    created_by UUID,
    updated_by UUID
);

-- RLS obligatorio
ALTER TABLE infonavit_management.registered_projects ENABLE ROW LEVEL SECURITY;

CREATE POLICY "tenant_isolation" ON infonavit_management.registered_projects
    USING (tenant_id = current_setting('app.current_tenant_id')::uuid);
```

### Servicio de Cumplimiento

```typescript
@Injectable()
export class InfonavitComplianceService {
  constructor(
    @InjectRepository(RegisteredProjectEntity)
    private projectRepo: Repository<RegisteredProjectEntity>,
    @InjectRepository(RequirementEntity)
    private requirementRepo: Repository<RequirementEntity>,
    private alertService: AlertService,
  ) {}

  // Calcular cumplimiento
  async calculateCompliance(
    projectId: string,
    tenantId: string
  ): Promise<ComplianceResult> {
    const requirements = await this.requirementRepo.find({
      where: { projectId, tenantId }
    });

    const total = requirements.length;
    const completed = requirements.filter(r => r.status === 'CUMPLIDO').length;
    const percentage = total > 0 ? (completed / total) * 100 : 0;

    // Actualizar proyecto
    await this.projectRepo.update(
      { id: projectId, tenantId },
      {
        compliancePercentage: percentage,
        updatedAt: new Date()
      }
    );

    // Alertas automáticas
    if (percentage < 70) {
      await this.alertService.createAlert({
        type: 'INFONAVIT_LOW_COMPLIANCE',
        projectId,
        tenantId,
        message: `Cumplimiento INFONAVIT bajo: ${percentage.toFixed(1)}%`
      });
    }

    return { total, completed, percentage };
  }

  // Verificar documentos próximos a vencer
  async checkExpiringDocuments(tenantId: string): Promise<ExpiringDocument[]> {
    const thirtyDaysFromNow = new Date();
    thirtyDaysFromNow.setDate(thirtyDaysFromNow.getDate() + 30);

    return this.evidenceRepo.find({
      where: {
        tenantId,
        expirationDate: LessThanOrEqual(thirtyDaysFromNow),
        isExpired: false
      }
    });
  }
}
```

## Validaciones Pre-Commit

- [ ] Todas las entidades INFONAVIT incluyen `tenantId` y `projectId`
- [ ] Evidencias tienen metadatos completos
- [ ] Workflow de estados correctamente implementado
- [ ] RLS habilitado en todas las tablas del schema
- [ ] Alertas configuradas para cumplimiento bajo
- [ ] Documentos con fecha de expiración monitoreados

## Referencias

- Documentación: `/docs/01-fase-alcance-inicial/MAI-011-infonavit-cumplimiento/`
- Especificaciones: `/docs/01-fase-alcance-inicial/MAI-011-infonavit-cumplimiento/especificaciones/`
- Core directivas: `../../erp-core/orchestration/directivas/`

---
*Directiva específica de Vertical Construcción*