feat: Adiciona cliente MRV e testes unitários com mocks

.github/TEMPLATES/COMMIT_TEMPLATE.md

@@ -0,0 +1,68 @@
+# Modelo de Mensagem de Commit (Conventional Commits)
+
+Este documento serve como um guia rápido para a criação de mensagens de commit padronizadas. O uso deste formato é essencial para manter o histórico do projeto legível, facilitar a automação e gerar changelogs de forma automática.
+
+## Estrutura Principal
+
+Cada mensagem de commit consiste em um cabeçalho, um corpo opcional e um rodapé opcional. A estrutura é a seguinte:
+
+```md
+<tipo>[escopo opcional]: <descrição>
+
+[corpo opcional]
+
+[rodapé(s) opcional(is)]
+```
+
+-   **tipo**: Obrigatório. Define a categoria da mudança (ex: `feat`, `fix`, `docs`).
+-   **escopo**: Opcional. Especifica a parte do código que foi alterada (ex: `api`, `parser`, `database`).
+-   **descrição**: Obrigatório. Um resumo conciso da mudança, em letras minúsculas e sem ponto final.
+-   **corpo**: Opcional. Fornece mais contexto, explicando o "porquê" da mudança. Separado da descrição por uma linha em branco.
+-   **rodapé**: Opcional. Usado para referenciar issues (ex: `Refs: #42`) ou para declarar _breaking changes_ (ex: `BREAKING CHANGE:...`).
+
+## Tipos de Commit Recomendados
+
+| Tipo       | Descrição                                                                      |
+| :--------- | :----------------------------------------------------------------------------- |
+| `feat`     | Introduz uma nova funcionalidade ou capacidade.                                |
+| `fix`      | Corrige um bug ou erro no código.                                              |
+| `docs`     | Alterações relacionadas exclusivamente à documentação.                         |
+| `refactor` | Alterações no código que não corrigem um bug nem adicionam uma funcionalidade. |
+| `perf`     | Uma mudança de código que melhora o desempenho.                                |
+| `test`     | Adição ou correção de testes automatizados.                                    |
+| `build`    | Mudanças que afetam o sistema de build ou dependências externas.               |
+| `ci`       | Mudanças nos arquivos e scripts de configuração de Integração Contínua (CI).   |
+| `chore`    | Outras mudanças que não modificam o código-fonte ou os testes.                 |
+| `style`    | Mudanças de estilo de código que não afetam a lógica (formatação, etc.).       |
+
+### Exemplos Práticos
+
+**1. Commit de correção de bug (fix):**
+
+`fix: corrige cálculo de offset na paginação da API`
+
+**2. Commit de nova funcionalidade (feat) com escopo:**
+
+```md
+feat(parser): adiciona suporte para o formato de dados do TSE
+
+Refs: #45
+```
+
+**3. Commit com corpo para mais detalhes:**
+
+```md
+perf(database): otimiza query para busca de metadados
+
+A query anterior utilizava um JOIN desnecessário que causava lentidão
+em datasets com mais de 10.000 registros. Esta mudança simplifica
+a consulta e adiciona um índice na coluna de metadados.
+```
+
+**4. Commit que fecha uma issue do GitHub:**
+
+```md
+fix(ui): resolve problema de renderização de tabelas no Firefox
+
+Closes: #78
+```

.github/actions/setup-poetry/action.yml

@@ -0,0 +1,38 @@
+name: Setup Poetry
+description: Install Python, cache & install deps (dev)
+runs:
+  using: composite
+  steps:
+    - uses: actions/setup-python@v5
+      with:
+        python-version: ${{ inputs.python_version }}
+
+    - name: Cache Poetry
+      uses: actions/cache@v4
+      with:
+        path: |
+          ${{ inputs.poetry_cache_dir }}
+          .venv
+        key: ${{ runner.os }}-poetry-${{ hashFiles('**/poetry.lock') }}
+        restore-keys: |
+          ${{ runner.os }}-poetry-
+
+    - name: Install Poetry + deps
+      shell: bash
+      run: |
+        pip install poetry==${{ inputs.poetry_version }}
+        poetry config virtualenvs.in-project true
+        poetry install --no-root --with dev --no-interaction
+inputs:
+  python_version:
+    description: Python version
+    required: true
+    default: "3.11"
+  poetry_version:
+    description: Poetry version
+    required: true
+    default: "1.8.5"
+  poetry_cache_dir:
+    description: Poetry cache dir
+    required: true
+    default: "~/.cache/poetry"

.github/workflows/main.yaml

@@ -0,0 +1,202 @@
+name: Python CI/CD
+
+on:
+  pull_request:
+    branches: [main]
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+env:
+  PYTHON_VERSION: "3.11"
+  POETRY_VERSION: "1.8.5"
+  POETRY_VIRTUALENVS_IN_PROJECT: "true"
+  POETRY_CACHE_DIR: "/home/runner/.cache/poetry"
+  DBT_PROJECT_DIR: "${{ github.workspace }}/airflow_lappis/dags/dbt/ipea"
+
+  IMAGE_REGISTRY_OWNER: govhub-br
+  IMAGE_NAME: ghcr.io/govhub-br/airflow-ipea
+  IMAGE_TAG_SHA: ${{ github.sha }}
+
+jobs:
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: ./.github/actions/setup-poetry
+        with:
+          python_version: ${{ env.PYTHON_VERSION }}
+          poetry_version: ${{ env.POETRY_VERSION }}
+          poetry_cache_dir: ${{ env.POETRY_CACHE_DIR }}
+
+      - name: Run lint
+        run: poetry run make lint-ci || true
+
+  test:
+    name: Test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: ./.github/actions/setup-poetry
+        with:
+          python_version: ${{ env.PYTHON_VERSION }}
+          poetry_version: ${{ env.POETRY_VERSION }}
+          poetry_cache_dir: ${{ env.POETRY_CACHE_DIR }}
+
+      - name: Run tests
+        run: >
+          poetry run pytest tests
+          --junitxml=report.xml
+          --cov=. --cov-report=xml:coverage.xml
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: reports
+          path: |
+            report.xml
+            coverage.xml
+
+  docker_build:
+    name: Docker build
+    runs-on: ubuntu-latest
+    needs: [lint, test]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: docker/setup-buildx-action@v3
+
+      - name: Build
+        uses: docker/build-push-action@v5
+        with:
+          push: false
+          context: .
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+          tags: |
+            ${{ env.IMAGE_NAME }}:${{ env.IMAGE_TAG_SHA }}
+
+  docker_push:
+    name: Docker push
+    runs-on: ubuntu-latest
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    needs: docker_build
+    permissions:
+      contents: read
+      packages: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: docker/setup-buildx-action@v3
+
+      - name: Login GHCR
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Build & Push
+        uses: docker/build-push-action@v5
+        with:
+          push: true
+          context: .
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+          tags: |
+            ${{ env.IMAGE_NAME }}:${{ env.IMAGE_TAG_SHA }}
+            ${{ env.IMAGE_NAME }}:latest
+
+  dbt_docs:
+    name: DBT Docs (deploy)
+    runs-on: ubuntu-latest
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    needs: docker_build
+    permissions:
+      contents: read
+      pages: write
+      id-token: write
+    steps:
+      - name: Check VPN secrets
+        env:
+          CLIENT_OVPN: ${{ secrets.CLIENT_OVPN }}
+        run: |
+          if [ -z "$CLIENT_OVPN" ]; then
+            echo "VPN não configurada — pulando."
+            exit 0
+          fi
+
+      - uses: actions/checkout@v4
+
+      - name: Instalar deps (DBT + VPN)
+        run: |
+          sudo apt-get update
+          sudo apt-get -y install openvpn iputils-ping
+          pip install dbt-core dbt-postgres
+
+      - name: Conectar VPN
+        env:
+          CLIENT_OVPN: ${{ secrets.CLIENT_OVPN }}
+          VPN_P12: ${{ secrets.VPN_P12 }}
+          VPN_USER: ${{ secrets.VPN_USER }}
+          VPN_PWD: ${{ secrets.VPN_PWD }}
+        run: |
+          sudo mkdir -p /etc/openvpn
+          echo "$CLIENT_OVPN" | sudo tee /etc/openvpn/client.ovpn >/dev/null
+
+          echo "$VPN_USER" | sudo tee /etc/openvpn/cred.txt >/dev/null
+          echo "$VPN_PWD" | sudo tee -a /etc/openvpn/cred.txt >/dev/null
+
+          echo "$VPN_P12" | base64 --decode | sudo tee /etc/openvpn/auth.p12 >/dev/null
+          sudo chmod 600 /etc/openvpn/*
+
+          sudo rm -f /tmp/ovpn.log || true
+          sudo touch /tmp/ovpn.log
+          sudo chmod 644 /tmp/ovpn.log
+
+          sudo openvpn \
+            --config /etc/openvpn/client.ovpn \
+            --auth-user-pass /etc/openvpn/cred.txt \
+            --pkcs12 /etc/openvpn/auth.p12 \
+            --verb 3 --daemon --log /tmp/ovpn.log
+
+          timeout=60
+          until sudo grep -q 'Initialization Sequence Completed' /tmp/ovpn.log; do
+            sleep 1
+            (( timeout-- ))
+            if (( timeout == 0 )); then
+              echo "❌ VPN não inicializou em 60s" >&2
+              sudo tail -n 200 /tmp/ovpn.log || true
+              exit 1
+            fi
+          done
+
+      - name: Gerar DBT docs
+        env:
+          DB_DW_HOST: ${{ secrets.DB_DW_HOST }}
+          DB_DW_DBNAME: ${{ secrets.DB_DW_DBNAME }}
+          DB_DW_USER: ${{ secrets.DB_DW_USER }}
+          DB_DW_PASSWORD: ${{ secrets.DB_DW_PASSWORD }}
+        run: |
+          cd "${{ env.DBT_PROJECT_DIR }}"
+          dbt deps
+          dbt docs generate
+          mkdir -p public
+          mv target/* public/
+
+      - name: Finalizar VPN
+        if: always()
+        run: sudo pkill openvpn || true
+
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: ${{ env.DBT_PROJECT_DIR }}/public
+
+      - uses: actions/deploy-pages@v4

.gitignore

@@ -9,6 +9,7 @@ dist/
 **/*.lock
 __pycache__/
 .poetry/
+requirements.generated.txt
 
 # Cache directories
 .cache/
@@ -41,8 +42,14 @@ dbt_packages/
 logs/
 
 # Jupyter
-.ipynb_checkpoints/
+**/*.ipynb_checkpoints/
+**/*.ipynb
 
 # System files
 .DS_Store
-Thumbs.db
+Thumbs.db
+
+# VPN 
+/connect.sh
+*.ovpn
+*.p12