Versão: 1.0.0
Data: 10 de Dezembro de 2025
Classificação: Documentação Técnica Oficial
- Dados de Autoria e Desenvolvimento
- Visão Geral do Sistema
- Arquitetura de Software
- Tecnologias Utilizadas
- Modelagem de Dados (Dicionário Detalhado)
- APIs e Endpoints (Especificação Formal)
- Lógica Funcional Detalhada
- Regras de Negócio (Modelo Formal)
- Segurança e Compliance
- Infraestrutura e DevOps
- Requisitos de Sistema e Limites
- Manual Operacional (Visão por Perfil)
- Módulos de Exportação e Backup
- Considerações Finais
- Responsável Técnico: Rodrigo Gandarela Soares de Farias Duca
- Formação: Desenvolvedor Full Stack / Engenheiro da Computação
- Versão da Build: 1.0.0
- Contato:
rodrigosfduca@gmail.com - LinkedIn: linkedin.com/in/rodrigo-gandarela-02473434b
- Github: github.com/RodrigoDuca
Responsável pelo ciclo de vida completo:
- Planejamento
- Desenvolvimento backend e frontend
- Arquitetura de dados
- Deploy
- Segurança
- Testes funcionais
O Sky ALP é uma plataforma inteligente para gestão de obras, integrando:
- ✔ Diário de Obra
- ✔ Gestão de Etapas
- ✔ Dashboard Analítico
- ✔ Módulos administrativos
- ✔ Exportação de dados
- ✔ Coleta de leads e comunicação
Nota: O sistema segue uma filosofia de confiabilidade, rastreabilidade, segurança e mobilidade, garantindo operação a campo, mesmo com operadores de baixa familiaridade tecnológica.
O sistema utiliza uma Arquitetura Monolítica Modular, composta por:
- Camada de Apresentação: Jinja2 + Tailwind
- Camada de Lógica de Negócio: Flask Controllers
- Camada de Serviços: Analytics, Autenticação, Exportação
- Camada de Persistência: SQLAlchemy ORM
Vantagens:
- Manutenção centralizada
- Menor latência
- Deploy mais simples
- Menos pontos de falha
/controllers/→ Endpoints e rotas/services/→ Módulos independentes (analytics, exportação, segurança)/models/→ Classes ORM/static/→ Tailwind, ícones/templates/→ Interfaces Jinja2/utils/→ Funções auxiliares (data/hora, validações)
- Factory Pattern: Criação da instância da aplicação Flask.
- MVC Parcial: Usado de forma pragmática.
- Repository Pattern: Implementado via SQLAlchemy.
- Adapter Pattern: Abstração para exportações.
- Service Layer: Lógica encapsulada fora dos controladores.
- Usuário realiza requisição (HTTP).
- Camada de Roteamento direciona ao Controller.
- Controller aciona a Camada de Serviços.
- Serviços acessam o ORM.
- ORM traduz para SQL e consulta o Banco.
- Resposta é processada e devolvida ao template Jinja2.
- HTML final é entregue ao cliente.
- Linguagem: Python 3.10+
- Framework: Flask
- Gestão de Sessão: Flask-Session
- ORM: SQLAlchemy
- Analytics: Matplotlib (modo Agg backend)
- Template Engine: Jinja2
- Estilização: Tailwind CSS CDN
- Ícones: Google Material Symbols
- Interpretador Base64 para gráficos
- Mecanismo de horário sincronizado (UTC-3)
Abaixo está o modelo de dados, com explicações aprofundadas das entidades principais.
Unidade central do sistema.
| Campo | Tipo | Descrição |
|---|---|---|
id |
PK | Identificador único |
nome |
Texto | Nome da obra |
status |
Texto | “Em andamento”, “Pendente”, “Concluída” |
cor_primaria |
Hex | Cor identificadora |
equipe |
Rel. M:N | Funcionários associados |
Funções críticas: Define permissões, impacta dashboard, identidade visual e controla o ciclo de vida.
Contém fatos operacionais.
Campos importantes:
data_hora: Usado para exibição visual.data_iso: Usado para ordenação lógica.autor_nome: Nome do responsável.foto: Arquivo ou string Base64.status_novo: Flag de estado.
Inclui rastreabilidade histórica completa.
Controla cronogramas.
Campos:
prioridade(Afeta layout e dashboards)data_inicio_previstadata_fim_previstastatus
- Funcionário
- Solicitação (Leads)
- Usuário Interno
- Obra 1 — N Etapas
- Obra 1 — N Registros
- Funcionário M — N Obra
- Solicitações (Independentes)
- Todas as requisições retornam JSON (exceto renderização de templates).
- Códigos HTTP padronizados.
- Sessão armazenada por cookies seguros.
/login→ Entrada de credenciais./api/dashboard_analytics→ Retorna dados agregados da obra + gráfico Base64./api/enviar_contato→ Registra lead externo.
- Sessão criptografada.
- Validação constante de tipo de acesso (Middleware/Decorators).
- Usa Matplotlib.
- Exporta gráficos como Base64.
- Zero dependência de processamento no browser do cliente.
- Operador cria entrada.
- Sistema armazena timestamp, autor e imagem.
- Dashboard atualiza os contadores automaticamente.
- Apenas equipe vinculada pode registrar etapas em uma obra específica.
- Obra só pode ser marcada como "Finalizada" se 100% das etapas estiverem concluídas.
- Registros diários não podem ser apagados (garantia de compliance e auditoria).
- Leads devem ser exibidos estritamente em ordem cronológica.
- Sanitização em todos os inputs.
- Proteção contra SQL Injection.
- Proteção contra XSS.
- Proteção contra Sessões Forjadas.
- Cookies com flag
HttpOnly. - Sessões criptografadas no servidor.
- Rastreabilidade total das ações críticas.
- Build local.
- Configuração de Ambiente virtual (venv).
- Execução de Migrações de Banco de Dados.
- Start da aplicação via Gunicorn.
- Proxy Reverso configurado no NGINX.
- Arquitetura preparada para migração futura para microserviços.
- Possível uso de background workers (ex: Celery) para processamento pesado.
- Upload máximo: 32 MB por requisição.
- Timezone: Horário forçado a UTC-3 (Brasília).
- Conexão DB: Via variável de ambiente (Environment Variable).
- Visualizar todas as obras.
- Ver dashboards analíticos completos.
- Gerir etapas (criar, editar, excluir).
- Visualizar leads captados.
- Exportar dados.
- Registrar diário de obra.
- Adicionar fotos e evidências.
- Visualizar progresso da obra (Read-only).
O sistema suporta nativamente a exportação dos dados para:
- CSV (Planilhas)
- JSON (Integração)
- Dump SQL completo (Backup Frio)
Este documento consolida toda a engenharia interna, regras de negócio e detalhes da plataforma Sky ALP, apresentando uma visão completa para manutenção, auditoria, evolução e conformidade técnica do software.