Frequencia_zap 📝🚀

Modular application for school attendance automation, integrated with the SIAP portal and WhatsApp (via Evolution API).

---

🇺🇸 English Version

🌟 Key Features

• SIAP Miner: Fully automated web scraper for the SIAP portal (Goiás State). Handles login, CAPTCHA bypass, and data extraction from all teacher-filled classes of the day.
• Smart Data Hub: Integrates students' attendance from multiple sources (API, XML, XLSX, and SIAP) into a local SQLite database.
• WhatsApp Integration: Sends automated missing student notifications to parents using Evolution API with reliable message delivery.
• Local Privacy: Database, contact info, and logs are kept locally to ensure student data privacy and security.
• Automated Cleanup: The system maintains 15 days of historical data, automatically cleaning older records to keep the database lightweight.
• Security First: Audited with Bandit and protected against SQL Injection and XXE. No hardcoded secrets.
• Secret Management Ready: Designed to evolve from .env to Vault or Cloud Secrets Managers.

📂 Structure

• app.py: Streamlit-based Web Interface for data visualization, review, and manual triggers.
• backend_processor/:
  • siap_scraper.py: The heart of the SIAP automation.
  • db_importer.py: Smart importer for physical school files.
• database/: db_handler.py manages local SQLite persistence.
• core/: Business logic, message formatting, and data cross-referencing.
• services/: API connectors for WhatsApp (Evolution) and School services.
• launcher.py: Orchestrator that starts Docker (API) and the Streamlit app together.
• debug_html/: Folder containing logs of the scraped SIAP pages for transparency.

⚙️ Quick Start (Windows)

1. Initial Setup: Run CONFIGURAR_SISTEMA.bat to create the virtual environment and install dependencies.
2. Environment: Create a .env file with your credentials (SIAP, Evolution API, Admin Password).
3. Launch: Run INICIAR_FREQUENCIA_ZAP.bat to start all services (Docker + Web UI).

---

🇧🇷 Versão em Português

🌟 Funcionalidades Principais

• Minerador SIAP: Scraper totalmente automatizado para o portal SIAP (Goiás). Realiza login, bypass de CAPTCHA e extração de faltas de todas as turmas do dia.
• Hub de Dados Inteligente: Cruza faltas de diversas fontes (API, XML, XLSX e SIAP) com o banco de dados físico de contatos.
• Integração WhatsApp: Disparo automático de notificações para os responsáveis via Evolution API.
• Privacidade Local: Banco de dados, contatos e logs são mantidos localmente, garantindo a segurança dos dados dos alunos.
• Limpeza Automática: Mantém 15 dias de histórico, removendo registros antigos para manter o sistema sempre rápido.
• Segurança: Auditado com Bandit e protegido contra SQL Injection e XXE. Sem senhas expostas no código.
• Gestão de Segredos: Pronto para evoluir do .env para Vault ou Cloud Secrets Managers. |

📂 Estrutura do Projeto

• app.py: Interface Web (Streamlit) para visualização, revisão e disparo manual.
• backend_processor/:
  • siap_scraper.py: O coração da automação com o portal SIAP.
  • db_importer.py: Importação inteligente de planilhas e XMLs escolares.
• database/: db_handler.py gerencia a persistência SQLite local.
• core/: Lógica de negócios, formatação de mensagens e cruzamento de dados.
• launcher.py: Orquestrador que liga o Docker (API) e o Streamlit simultaneamente.
• debug_html/: Pasta com os registros das páginas mineradas do SIAP para conferência.

⚙️ Como Iniciar (Windows)

1. Configuração Inicial: Execute CONFIGURAR_SISTEMA.bat para criar o ambiente virtual e instalar as bibliotecas.
2. Ambiente: Crie um arquivo .env com suas credenciais (SIAP, Evolution API, Senha Adm).
3. Execução: Use o INICIAR_FREQUENCIA_ZAP.bat para abrir todo o sistema com um clique (Docker + Interface Web).

---

🔒 Security

Operation is strictly local. All external calls (WhatsApp/SIAP) are made over secure sessions with timeouts. For a production-ready security audit, use python -m bandit -r . -x .venv.

🛣️ Advanced Secrets Management (Evolution Roadmap)

This project currently uses .env files for local simplicity. For enterprise or cloud deployments, the following architectures are recommended:

1. HashiCorp Vault (The Gold Standard): Best for cloud-agnostic infrastructures. Credentials are delivered directly to memory with short TTLs and automatic expiration.
2. Cloud Secrets Manager (AWS, Azure, GCP): Ideal for native cloud workloads using IAM Roles. No persistent secret files on disk; keys are fetched via API.
3. Orchestration-level Secrets (Docker/K8s): Inject secrets via memory volumes (tmpfs), preventing them from ever touching physical storage.

---

🔒 Segurança (Roadmap de Evolução)

A operação atual é estritamente local. Para auditorias de segurança em produção, use python -m bandit -r . -x .venv.

🛡️ Gestão Avançada de Segredos (Futuro)

Atualmente o sistema utiliza arquivos .env para simplicidade local. Para implementações em larga escala, as seguintes arquiteturas são ideais:

1. HashiCorp Vault (O Padrão Ouro): O sistema não possui a senha fixa; ele se autentica dinamicamente. O Vault entrega a credencial diretamente na memória do processo com tempo de vida (TTL) curto.
2. Cloud Secrets Manager (AWS, Azure, GCP): Escolha eficiente para implementações em nuvem. As chaves são entregues via API através de IAM Roles, sem necessidade de arquivos no diretório.
3. Segredos em Nível de Orquestração (Docker/K8s): Os segredos são montados em volumes de memória (tmpfs), o que significa que eles nunca tocam o armazenamento físico (SSD/HD).

📜 Logs

Operational logs are available at logs/app.log.