# SecInterp - Development Guide

Welcome to the SecInterp development guide. This document outlines the standards, best practices, and workflows for contributing to the project.

## 🏗️ Technical Stack

- Language: Python 3.10+ (QGIS 3.x compatible)

- GUI Framework: PyQt5 (Native QGIS integration)

- Geospatial Engine: PyQGIS API (`qgis.core`, `qgis.gui`)

- Package Manager: `uv` (recommended) or `pip`

- Linter & Formatter: `Ruff`

- Testing: `pytest`

## 🎨 Coding Standards

### 🧬 Design Principles

- SOLID: Follow SRP, OCP, and DIP strictly.

- Separation of Concerns: GUI code (Managers/UI) MUST NOT contain business logic. Delegating to `Core/Services` is mandatory.

- DRY (Don’t Repeat Yourself): If a calculation or check is used twice, move it to a `core/utils` module.

### 📝 Naming Conventions

- Classes: `CapWords` (e.g., `ProfileService`).

- Variables/Functions: `snake_case` (e.g., `calculate_apparent_dip`).

- Qt Overrides: `camelCase` (MUST match the original C++ signature, e.g., `showEvent`).

- Signals: `camelCase` (PyQt style, e.g., `dataChanged`).

### 🐍 Imports Ordering

1. Standard Library: `os`, `sys`, `math`, etc.

2. Third-Party: `numpy`, `pandas`, etc.

3. QGIS Core: `from qgis.core import ...`

4. QGIS GUI: `from qgis.gui import ...`

5. PyQt: `from qgis.PyQt.QtWidgets import ...` (Always use `qgis.PyQt` shim).

6. Local Modules: `from sec_interp.core import ...`

## ⚡ Git Workflow

### Conventional Commits

All commits MUST follow the Conventional Commits specification:

Format: `<type>(<scope>): <description>`

- `feat`: A new feature (e.g., `feat(drill): add 3d projection`)

- `fix`: A bug fix (e.g., `fix(gui): resolve range attribute error`)

- `refactor`: Code change that neither fixes a bug nor adds a feature.

- `docs`: Documentation changes.

- `test`: Adding or correcting tests.

- `chore`: Build process or auxiliary tool changes.

Language: All commit messages must be in English.

## 🛠️ Tooling (Ruff)

We use Ruff for linting and formatting. It replaces Black, isort, and Flake8.

### Basic Commands

    # Lint and auto-fix
    ruff check . --fix

    # Format code
    ruff format .

    # Check everything (QA)
    ruff check . && ruff format . --check

### IDE Integration

It is highly recommended to install the Ruff extension in VS Code and enable “Format on Save”.

## 🧪 Testing

### Running Tests

    # Run all tests
    pytest

    # Run tests with coverage report
    pytest --cov=sec_interp

### Mocking QGIS

When testing core services, use `unittest.mock` to avoid requiring a running QGIS instance. For integration tests, use the `qgis_app` fixture if available.

## 📝 Documentation Standards

### Docstrings

All public functions and methods MUST have docstrings in Google Style:

    def process_data(self, layer: QgsVectorLayer, factor: float) -> Optional[list]:
        """
        Processes the layer using the specified scaling factor.

        Args:
            layer: The input QGIS vector layer.
            factor: The vertical exaggeration factor.

        Returns:
            A list of processed coordinates or None if invalid.
        """

### Image Assets

Save all documentation images in `docs/images/` using the following convention:

- `workflow_DESC.png`: Step-by-step guides.

- `ui_DESC.png`: General interface screenshots.

- `feature_DESC.png`: Specific highlighted features.

## 📦 Deployment & Makefile

Use the `Makefile` for common development tasks:

- `make deploy`: Installs the plugin into your local QGIS plugins folder.

- `make zip`: Creates a release-ready ZIP file.

- `make docus`: Builds the Sphinx documentation.

- `make clean`: Removes temporary and compiled files.