feat(facebook): integração completa com Graph API, whitelist de obras e release notes automatico

.envExample

@@ -1,9 +1,75 @@
+# =============================================================================
+# DISCORD
+# =============================================================================
+
+# Token de autenticação do bot Discord.
+# Obtido em: https://discord.com/developers/applications → Bot → Token
 API_KEY = token_bot_discord
-CANAL_LANCAMENTOS = channel_id
-CANAL_TESTES = channel_id_tests
-CANAL_TAGS = channel_id_tags
 
-API_ID_PAGINA_FACEBOOK = api_facebook
-API_TOKEN_PAGINA = token_facebook_page
+# ID do canal Discord onde as postagens de lançamentos reais serão enviadas.
+# Para obter o ID: ative o Modo Desenvolvedor no Discord, clique com botão direito
+# no canal → Copiar ID
+CANAL_LANCAMENTOS = channel_id_canal_lancamentos
+
+# ID do canal Discord usado para postagens em modo de teste.
+# As mensagens de teste são enviadas aqui em vez do canal de produção.
+CANAL_TESTES = channel_id_canal_testes
+
+# ID do canal Discord onde as postagens com tags/menções de obras são enviadas.
+CANAL_TAGS = channel_id_canal_tags
+
+# =============================================================================
+# MONGODB ATLAS
+# =============================================================================
+
+# URI de conexão com o cluster do MongoDB Atlas.
+# Obtida em: Atlas Console → Database → Connect → Drivers
+# Formato: mongodb+srv://<usuario>:<senha>@<cluster>.mongodb.net/?retryWrites=true&w=majority
+URI_ATLAS = mongodb+srv://usuario:senha@cluster.mongodb.net/?retryWrites=true&w=majority
+
+# =============================================================================
+# FACEBOOK (Produção)
+# =============================================================================
+
+# ID numérico da página do Facebook onde os anúncios serão publicados.
+# Obtido em: Configurações da Página → Informações da Página → ID da Página
+API_ID_PAGINA_FACEBOOK = id_numerico_da_pagina_facebook
+
+# Token de acesso de longa duração da página do Facebook (produção).
+# Gerado via: https://developers.facebook.com/tools/explorer/
+# Permissões necessárias: pages_manage_posts, pages_read_engagement
+API_TOKEN_PAGINA = token_de_acesso_da_pagina_facebook
+
+# =============================================================================
+# FACEBOOK (Testes)
+# Usadas apenas quando ENABLE_FB_TEST=true. Permitem testar a integração com o
+# Facebook sem publicar na página de produção.
+# =============================================================================
+
+# ID numérico da página do Facebook de testes.
+API_ID_PAGINA_FACEBOOK_TESTE = id_numerico_da_pagina_de_teste
+
+# Token de acesso de longa duração da página do Facebook de testes.
+API_TOKEN_PAGINA_TESTE = token_de_acesso_da_pagina_de_teste
+
+# Ativa o modo de teste do Facebook.
+# Quando "true", as postagens são feitas na página de teste (acima) em vez da produção.
+# Quando "false" ou ausente, usa as credenciais de produção.
+# Padrão: false
+ENABLE_FB_TEST = false
+
+# =============================================================================
+# GOOGLE GEMINI
+# =============================================================================
+
+# Chave de API do Google Gemini, usada para geração de descrições das obras.
+# Obtida em: https://aistudio.google.com/app/apikey
+GEMINI_API = chave_de_api_do_gemini
+
+# =============================================================================
+# WEB SCRAPER
+# =============================================================================
 
-URL_SITE = url_do_site_sem_https//:
+# URL base do site alvo do scraper, sem protocolo (http:// ou https://).
+# Exemplo: tsundoku.com.br
+URL_SITE = url_do_site_sem_protocolo

.github/instructions/python.instructions.md

@@ -0,0 +1,56 @@
+---
+description: 'Python coding conventions and guidelines'
+applyTo: '**/*.py'
+---
+
+# Python Coding Conventions
+
+## Python Instructions
+
+- Write clear and concise comments for each function.
+- Ensure functions have descriptive names and include type hints.
+- Provide docstrings following PEP 257 conventions.
+- Use the `typing` module for type annotations (e.g., `List[str]`, `Dict[str, int]`).
+- Break down complex functions into smaller, more manageable functions.
+
+## General Instructions
+
+- Always prioritize readability and clarity.
+- For algorithm-related code, include explanations of the approach used.
+- Write code with good maintainability practices, including comments on why certain design decisions were made.
+- Handle edge cases and write clear exception handling.
+- For libraries or external dependencies, mention their usage and purpose in comments.
+- Use consistent naming conventions and follow language-specific best practices.
+- Write concise, efficient, and idiomatic code that is also easily understandable.
+
+## Code Style and Formatting
+
+- Follow the **PEP 8** style guide for Python.
+- Maintain proper indentation (use 4 spaces for each level of indentation).
+- Ensure lines do not exceed 79 characters.
+- Place function and class docstrings immediately after the `def` or `class` keyword.
+- Use blank lines to separate functions, classes, and code blocks where appropriate.
+
+## Edge Cases and Testing
+
+- Always include test cases for critical paths of the application.
+- Account for common edge cases like empty inputs, invalid data types, and large datasets.
+- Include comments for edge cases and the expected behavior in those cases.
+- Write unit tests for functions and document them with docstrings explaining the test cases.
+
+## Example of Proper Documentation
+
+```python
+def calculate_area(radius: float) -> float:
+    """
+    Calculate the area of a circle given the radius.
+
+    Parameters:
+    radius (float): The radius of the circle.
+
+    Returns:
+    float: The area of the circle, calculated as π * radius^2.
+    """
+    import math
+    return math.pi * radius ** 2
+```

.github/workflows/release.yml

@@ -0,0 +1,40 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: write
+
+jobs:
+  release:
+    name: Gerar Release Notes e publicar Release
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout (histórico completo para o git-cliff)
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Gerar CHANGELOG com git-cliff
+        uses: orhun/git-cliff-action@v3
+        id: git_cliff
+        with:
+          config: cliff.toml
+          args: --verbose --latest --strip header
+        env:
+          OUTPUT: CHANGELOG_RELEASE.md
+          GITHUB_REPO: ${{ github.repository }}
+
+      - name: Criar GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          tag_name: ${{ github.ref_name }}
+          name: Release ${{ github.ref_name }}
+          body_path: CHANGELOG_RELEASE.md
+          draft: false
+          prerelease: ${{ contains(github.ref_name, '-rc') || contains(github.ref_name, '-beta') || contains(github.ref_name, '-alpha') }}
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/test-pytest.yaml

@@ -35,13 +35,24 @@ jobs:
 
       - name: Run Pytest with secrets
         env:
-          API_ID_PAGINA_FACEBOOK: ${{ secrets.API_ID_PAGINA_FACEBOOK }}
+          # Discord
           API_KEY: ${{ secrets.API_KEY }}
-          API_TOKEN_PAGINA: ${{ secrets.API_TOKEN_PAGINA }}
           CANAL_LANCAMENTOS: ${{ secrets.CANAL_LANCAMENTOS }}
-          CANAL_TAGS: ${{ secrets.CANAL_TAGS }}
           CANAL_TESTES: ${{ secrets.CANAL_TESTES }}
+          CANAL_TAGS: ${{ secrets.CANAL_TAGS }}
+          # MongoDB Atlas
           URI_ATLAS: ${{ secrets.URI_ATLAS }}
+          # Facebook — produção
+          API_ID_PAGINA_FACEBOOK: ${{ secrets.API_ID_PAGINA_FACEBOOK }}
+          API_TOKEN_PAGINA: ${{ secrets.API_TOKEN_PAGINA }}
+          # Facebook — testes de integração (desabilitado na CI por padrão)
+          API_ID_PAGINA_FACEBOOK_TESTE: ${{ secrets.API_ID_PAGINA_FACEBOOK_TESTE }}
+          API_TOKEN_PAGINA_TESTE: ${{ secrets.API_TOKEN_PAGINA_TESTE }}
+          ENABLE_FB_TEST: "false"
+          # Google Gemini
+          GEMINI_API: ${{ secrets.GEMINI_API }}
+          # Web scraper
+          URL_SITE: ${{ secrets.URL_SITE }}
         run: |
           export PYTHONPATH=$(pwd)
           LC_ALL=pt_BR.UTF-8 LANG=pt_BR.UTF-8 python -m pytest -v

.gitignore

@@ -14,8 +14,10 @@ node_modules/
 
 # Credenciais de Ambiente
 .env
+.env.dev
 
 
 ## cache python
 __pycache__/
 *.py[cod]
+*.pyc