# 📚 arSistema ERP Backend — Lógica del Sistema & Arquitectura Contextual (`CONTEXT.md`)

Este documento describe la arquitectura técnica, la lógica de negocio, las reglas de dominio, el modelo de multitenencia y la documentación detallada de los **10 Módulos** del sistema **`arsistema_erp_back`** (Laravel 11 SPA & REST API).

---

## 🏗️ 1. Arquitectura General y Patrón Domain-Driven Design (DDD)

El backend está estructurado siguiendo los principios de **Clean Architecture / Domain-Driven Design (DDD)** adaptados a Laravel. Toda la lógica de negocio reside dentro de `app/Domain/<Modulo>`:

```text
app/
├── Domain/
│   ├── Tenant/          # 1. Multitenencia y 10. Gestión de Claves API
│   ├── Course/          # 2. Cursos, Horarios y Precios USD
│   ├── Teacher/         # 3. Profesores y Carga Académica
│   ├── Student/         # 4. Estudiantes, Solvencia y Progreso
│   ├── User/            # 5. Administración de Usuarios y Roles RBAC
│   ├── ExchangeRate/    # 6. Tasas de Cambio Oficiales BCV (USD/EUR)
│   ├── Installment/     # 7. Mensualidades y Cronogramas de Pago
│   ├── BankAccount/     # 8. Cuentas Bancarias e Instituciones Financieras
│   ├── Payment/         # 9. Pagos, Comprobantes y Conciliación
│   └── DashboardMenu/   # Menú Lateral Dinámico Filtrado por Roles
```

---

## 🏬 2. Detalle Completo de los 10 Módulos del Sistema

### 1. 🏢 Módulo de Multitenencia & Aislamiento (`Tenant`)
- **Descripción**: Permite que múltiples instituciones/escuelas operen en la misma instancia manteniendo aislamiento absoluto de datos.
- **Identificación**: Vía cabecera `X-Tenant-Key` o subdominio URL (`IdentifyTenant` middleware).
- **Seguridad**: El trait `BelongsToTenant` aplica automáticamente el `TenantScope` a todas las consultas de Eloquent (`WHERE tenant_id = <current_tenant_id>`).

---

### 2. 📚 Módulo de Cursos & Oferta Académica (`Course`)
- **Campos**: `name`, `code`, `teacher_id`, `start_date`, `end_date`, `days` (días de la semana), `start_time`, `end_time`, `duration_months`, `price_usd`.
- **Detección de Colisiones**: Valida en tiempo real al inscribir que el alumno no tenga solapamiento simultáneo de fechas, días y rango horario.
- **Permisos**: `view-courses`, `create-courses`, `delete-courses`.

---

### 3. 👨‍🏫 Módulo de Profesores & Carga Docente (`Teacher`)
- **Campos**: `first_name`, `last_name`, `email`, `phone`, `specialty`, `status`.
- **Lógica**: Relacionado con cursos. Permite evaluar la carga de alumnos e instructores activos.
- **Permisos**: `view-teachers`, `create-teachers`, `delete-teachers`.

---

### 4. 👥 Módulo de Estudiantes & Ficha 360° (`Student`)
- **Campos**: `cedula`, `first_name`, `middle_name`, `paternal_last_name`, `maternal_last_name`, `phone`, `age`, `address`, `status` (`active`, `graduated`, `inactive`, `suspended`).
- **Endpoint de Progreso**: `/api/v1/crm/students/{id}/progress` calcula el avance académico y la solvencia financiera (`SOLVENTE`, `EN_MORA`, `PENDIENTE`).
- **Permisos**: `view-students`, `create-students`, `delete-students`.

---

### 5. ⚙️ Módulo de Administración de Usuarios & Roles RBAC (`User` / Spatie)
- **Roles Predefinidos**:
  - `root`: Acceso total del sistema.
  - `gerente`: Gestión administrativa, usuarios, reportes y finanzas.
  - `admin`: Operaciones diarias, cursos, estudiantes y pagos.
  - `asistente`: Registro de datos, lectura de cursos y conciliaciones básicas.
  - `profesor`: Consulta de cursos asignados y alumnos inscritos.
  - `estudiante`: Consulta de materias e historial de mensualidades.
- **Permisos**: `manage-users`, `manage-tenant`.

---

### 6. 💱 Módulo de Tasas de Cambio Oficiales BCV (`ExchangeRate`)
- **Lógica**: Registra la tasa de cambio oficial diaria fijada por el Banco Central de Venezuela (`rate_bcv_usd`, `rate_bcv_eur`).
- **Conversión Dinámica**: Utilizada por el motor financiero para calcular en tiempo real el monto a pagar en Bolívares (VES) al momento de registrar una transferencia o pago móvil.
- **Permisos**: `view-exchange-rates`, `create-exchange-rates`, `edit-exchange-rates`, `delete-exchange-rates`.

---

### 7. 💳 Módulo de Mensualidades & Cuotas (`Installment`)
- **Lógica**: Cronograma de cuotas asociadas a la inscripción de un estudiante en un curso.
- **Campos**: `student_id`, `course_id`, `amount`, `due_date`, `status` (`pending`, `paid`, `late`).
- **Permisos**: `view-installments`, `manage-installments`.

---

### 8. 🏦 Módulo de Cuentas Bancarias & Bancos (`BankAccount` / `Bank`)
- **Lógica**: Cuentas bancarias de la institución para recibir transferencias nacionales, pago móvil o divisas.
- **Campos**: `bank_id`, `account_number`, `account_type`, `holder_name`, `holder_id`, `phone_number`.
- **Permisos**: `view-bank-accounts`, `create-bank-accounts`, `edit-bank-accounts`, `delete-bank-accounts`.

---

### 9. 📄 Módulo de Pagos & Conciliación (`Payment`)
- **Lógica**: Registro de pagos efectuados por alumnos con adjunto de comprobante, número de referencia y método de pago (Pago Móvil, Transferencia, Zelle, Efectivo).
- **Estados**: `pending_validation`, `approved`, `declined`, `under_review`.
- **Conciliación**: Al aprobar un pago, el sistema liquida las mensualidades (`installments`) pendientes.
- **Permisos**: `view-payments`, `manage-payments`.

---

### 10. 📊 Módulo de Central de Reportes & Radar Alumnos en Riesgo (`ReportController`)
- **Hub de Reportes**: KPIs de recaudación, total recaudado en USD y Bs, resumen de morosidad y conversión de captación.
- **Radar Alumnos en Riesgo (Algoritmo 0-100 pts)**:
  - **Fórmula**:
    $$\text{Risk Score} = \min(100, \text{Riesgo Financiero} + \text{Riesgo Académico} + \text{Riesgo Inactividad})$$
  - Categorías: `CRITICAL` ($\ge 60$), `HIGH` ($\ge 40$), `MEDIUM` ($\ge 20$), `LOW` ($< 20$).
  - Genera recomendaciones automatizadas por IA para retención.
- **Permisos**: `view-payments`.

---

### 🔑 Bonus: Módulo de Tenant API Keys & Integraciones M2M CRM (`ApiKey`)
- **Seguridad**: Autenticación M2M vía `X-API-Key`. Cifrado SHA-256, expiración configurablemente e IP Whitelisting.
- **Scopes Granulares**:
  - `reports:read`, `students:read`, `students:write`, `teachers:read`, `courses:read`, `enrollments:write`, `payments:read`.
- **Middleware**: [`AuthenticateApiKey.php`](file:///mnt/98F8B311F8B2EC9E/other_projects/arsistema_erp_back/app/Http/Middleware/AuthenticateApiKey.php).

---

## 🛠️ 3. Resumen de Rutas REST API M2M (CRM)

```http
GET  /api/v1/crm/reports/hub             (Scope: reports:read)
GET  /api/v1/crm/reports/at-risk         (Scope: reports:read)
GET  /api/v1/crm/students                (Scope: students:read)
GET  /api/v1/crm/students/{id}/progress  (Scope: students:read)
POST /api/v1/crm/students                (Scope: students:write)
GET  /api/v1/crm/teachers                (Scope: teachers:read)
GET  /api/v1/crm/courses                 (Scope: courses:read)
POST /api/v1/crm/enrollments             (Scope: enrollments:write)
```