# 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.