# Guía de Distinción de Componentes "Core"

Este documento tiene como objetivo aclarar la distinción entre los diferentes componentes denominados "Core" dentro del proyecto **SecInterp**, para evitar confusiones tanto por parte de desarrolladores humanos como de agentes de IA.

## ⚠️ La Distinción Fundamental

Existen dos entidades "Core" que coexisten en este entorno de desarrollo:

1.  **SecInterp Core** (El Núcleo del Proyecto):
    *   **Ubicación**: Directorio `/core` dentro de la raíz del proyecto.
    *   **Propósito**: Contiene la lógica de negocio pura, algoritmos geológicos, servicios de procesamiento y modelos de datos (DTOs) específicos de SecInterp.
    *   **Estado Actual**: **Desacoplado**. A partir de la versión 2.8.0, este módulo ha sido saneado para no tener dependencias directas de las clases vivas de QGIS durante el procesamiento pesado (Thread-Safe).

2.  **QGIS Core** (La API de QGIS):
    *   **Referencia**: Paquete de Python `qgis.core`.
    *   **Propósito**: Proporciona la infraestructura geoespacial subyacente (geometrías, capas, proyectos, CRS).
    *   **Interacción**: SecInterp utiliza `qgis.core` para extraer datos en el hilo principal, pero el **SecInterp Core** procesa estos datos usando tipos agnósticos (WKT, diccionarios, primitivos).

---

## 🧭 Reglas para Desarrolladores e IA

Para mantener la integridad arquitectónica, siga estas directrices:

### 1. No asuma que "Core" siempre es QGIS
Si se le pide "revisar el core", se refiere casi exclusivamente al directorio `/core` de este plugin. No intente buscar o modificar archivos internos del motor de QGIS.

### 2. Límites de Datos (Decoupling)
*   **En `/core`**: Se deben usar tipos de dominio agnósticos. Evite instanciar `QgsVectorLayer` o acceder a `QgsProject.instance()` dentro de los servicios del núcleo. Use `DomainGeometry` (WKT) y diccionarios de atributos.
*   **En `/gui`**: Es el lugar donde se realiza la traducción entre la API real de QGIS (`qgis.core`) y el **SecInterp Core**. Aquí es donde se extraen las geometrías y se preparan los DTOs.

### 3. Nomenclatura de Archivos e Importaciones
*   **Archivos Locales**: Los archivos en `core/` (ej. `core/services/geology_service.py`) son el **Cerebro de SecInterp**.
*   **API Externa**: Las importaciones que empiezan con `qgis.core`, `qgis.gui` o `qgis.utils` son **Dependencias Externas**.
*   **Regla de Nomenclatura**: En discusiones o comentarios de código, use "Internal Core" para referirse a `/core` y "PyQGIS API" para la del software.

### 4. El Patrón "Extract-then-Compute" (Extraer y Calcular)
Para evitar complicaciones futuras, el flujo de datos **DEBE** seguir este patrón:
1.  **Capa GUI/Task Interface**: Recibe objetos de QGIS (`QgsVectorLayer`, `QgsFeature`). Extrae lo necesario (geometría en WKT, diccionarios de atributos).
2.  **Capa Core**: Recibe únicamente los datos extraídos (strings, dicts, floats). Realiza los cálculos geométricos pesados.
3.  **Resultado**: El Core devuelve DTOs (Data Transfer Objects) definidos en `core/types.py`. La capa GUI se encarga de convertir esto de nuevo a capas de QGIS si es necesario.

### 5. Reglas de Oro de Hilo-Seguridad (Thread-Safety)
*   **Prohibido**: Importar `qgis.gui` dentro de `core/`. Los hilos de fondo morirán si intentan tocar cualquier widget o ventana.
*   **Restricción**: Minimizar el uso de `qgis.core` dentro de `core/`. Aunque algunas clases como `QgsGeometry` son seguras, es preferible operar sobre WKT para garantizar total independencia.
*   **Contexto de Aplicación**: Nunca use `iface` o `QgsProject.instance()` dentro de `core/`. Si necesita datos del proyecto, páselos como argumentos pre-extraídos.

---

## 🧪 Estrategia de Testing Diferenciada

*   **Tests del Core (`tests/core/`)**: Deben poder ejecutarse sin instalar QGIS completo. Usan mocks ligeros. Son el termómetro de la lógica geológica.
*   **Tests de Integración (`tests/integration/`)**: Requieren QGIS real. Prueban que nuestro "Core" se entiende correctamente con la "API de QGIS".

---

## 🛠️ Resumen de Desacoplamiento (Enero 2026)

Se ha completado un esfuerzo mayor para asegurar que:
*   `GeologyService` no use capas vivas de QGIS en su método de procesamiento.
*   `DrillholeService` use diccionarios en lugar de objetos `QgsFeature` durante el cálculo de trazas.
*   La lógica de proyección 3D acepta tuplas y tipos primitivos.

**En resumen: Mantenga nuestro Core "puro". Trate a QGIS como un proveedor de servicios externo. No permita que las raíces de uno entren en la lógica del otro.**