Responsável pelo ciclo de vida completo:

• Planejamento
• Desenvolvimento backend e frontend
• Arquitetura de dados
• Deploy
• Segurança
• Testes funcionais

2. VISÃO GERAL DO SISTEMA

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.

3. ARQUITETURA DE SOFTWARE

3.1 Arquitetura Geral

O sistema utiliza uma Arquitetura Monolítica Modular, composta por:

1. Camada de Apresentação: Jinja2 + Tailwind
2. Camada de Lógica de Negócio: Flask Controllers
3. Camada de Serviços: Analytics, Autenticação, Exportação
4. Camada de Persistência: SQLAlchemy ORM

Vantagens:

• Manutenção centralizada
• Menor latência
• Deploy mais simples
• Menos pontos de falha

3.2 Componentes Internos

• /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)

3.3 Padrões de Projeto Aplicados

• 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.

3.4 Fluxo de Dados (Resumo Formal)

1. Usuário realiza requisição (HTTP).
2. Camada de Roteamento direciona ao Controller.
3. Controller aciona a Camada de Serviços.
4. Serviços acessam o ORM.
5. ORM traduz para SQL e consulta o Banco.
6. Resposta é processada e devolvida ao template Jinja2.
7. HTML final é entregue ao cliente.

4. TECNOLOGIAS UTILIZADAS

4.1 Backend

• Linguagem: Python 3.10+
• Framework: Flask
• Gestão de Sessão: Flask-Session
• ORM: SQLAlchemy
• Analytics: Matplotlib (modo Agg backend)

4.2 Frontend

• Template Engine: Jinja2
• Estilização: Tailwind CSS CDN
• Ícones: Google Material Symbols

4.3 Terceiros e Bibliotecas Conectadas

• Interpretador Base64 para gráficos
• Mecanismo de horário sincronizado (UTC-3)

5. MODELAGEM DE DADOS (DICIONÁRIO DETALHADO)

Abaixo está o modelo de dados, com explicações aprofundadas das entidades principais.

5.1 Entidade: Obra

Unidade central do sistema.

Funções críticas: Define permissões, impacta dashboard, identidade visual e controla o ciclo de vida.

5.2 Entidade: Registro Diário

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.

5.3 Entidade: Etapa

Controla cronogramas.

Campos:

• prioridade (Afeta layout e dashboards)
• data_inicio_prevista
• data_fim_prevista
• status

5.4 Entidades Complementares

• Funcionário
• Solicitação (Leads)
• Usuário Interno

5.5 Esquema ER (Descrito)

• Obra 1 — N Etapas
• Obra 1 — N Registros
• Funcionário M — N Obra
• Solicitações (Independentes)

6. API E ENDPOINTS (ESPECIFICAÇÃO FORMAL)

6.1 Padrões Gerais

• Todas as requisições retornam JSON (exceto renderização de templates).
• Códigos HTTP padronizados.
• Sessão armazenada por cookies seguros.

6.2 Endpoints Principais

• /login → Entrada de credenciais.
• /api/dashboard_analytics → Retorna dados agregados da obra + gráfico Base64.
• /api/enviar_contato → Registra lead externo.

7. LÓGICA FUNCIONAL DETALHADA

7.1 Autenticação

• Sessão criptografada.
• Validação constante de tipo de acesso (Middleware/Decorators).

7.2 Motor de Analytics

• Usa Matplotlib.
• Exporta gráficos como Base64.
• Zero dependência de processamento no browser do cliente.

7.3 Fluxo do Diário

1. Operador cria entrada.
2. Sistema armazena timestamp, autor e imagem.
3. Dashboard atualiza os contadores automaticamente.

8. REGRAS DE NEGÓCIO (FORMALIZAÇÃO)

1. Apenas equipe vinculada pode registrar etapas em uma obra específica.
2. Obra só pode ser marcada como "Finalizada" se 100% das etapas estiverem concluídas.
3. Registros diários não podem ser apagados (garantia de compliance e auditoria).
4. Leads devem ser exibidos estritamente em ordem cronológica.

9. SEGURANÇA E COMPLIANCE

9.1 Hardening

• Sanitização em todos os inputs.

9.2 Proteções a Ameaças

• Proteção contra SQL Injection.
• Proteção contra XSS.
• Proteção contra Sessões Forjadas.

9.3 Sessões

• Cookies com flag HttpOnly.
• Sessões criptografadas no servidor.

9.4 Logs e Auditoria

• Rastreabilidade total das ações críticas.

10. INFRAESTRUTURA E DEVOPS

10.1 Pipeline de Deploy

1. Build local.
2. Configuração de Ambiente virtual (venv).
3. Execução de Migrações de Banco de Dados.
4. Start da aplicação via Gunicorn.
5. Proxy Reverso configurado no NGINX.

10.2 Escalabilidade

• Arquitetura preparada para migração futura para microserviços.
• Possível uso de background workers (ex: Celery) para processamento pesado.

11. REQUISITOS DE SISTEMA E LIMITES

• 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).

12. MANUAL OPERACIONAL (VISÃO POR PERFIL)

12.1 Perfil Gerente (Admin)

• Visualizar todas as obras.
• Ver dashboards analíticos completos.
• Gerir etapas (criar, editar, excluir).
• Visualizar leads captados.
• Exportar dados.

12.2 Perfil Operador

• Registrar diário de obra.
• Adicionar fotos e evidências.
• Visualizar progresso da obra (Read-only).

13. MÓDULOS DE EXPORTAÇÃO E BACKUP

O sistema suporta nativamente a exportação dos dados para:

• CSV (Planilhas)
• JSON (Integração)
• Dump SQL completo (Backup Frio)

14. CONSIDERAÇÕES FINAIS

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.