Documentação Funcional — ecosif-structure
Público-alvo: Gestores / Clientes / Negócio
Módulo: ecosif-structure (orquestração do ecossistema)
1. Objetivo do Módulo
O ecosif-structure não é uma aplicação de utilizador final; é o “cérebro” da orquestração do ecossistema eCosif. Responsabiliza-se por:
- Subir e ligar todos os serviços (banco de dados, APIs e frontend) com um único conjunto de comandos.
- Garantir que os serviços se encontram na rede e que o acesso externo é feito através de um único domínio (reverse proxy).
- Permitir que o gestor ou a equipa operacional verifiquem se o sistema está saudável (status e health checks).
Em linguagem de negócio:
- O que é: O conjunto de configurações e scripts que permitem instalar e operar o eCosif completo (banco + todos os backends + interface web) em um ou mais servidores.
- Para que serve: Reduzir a complexidade de instalação e manutenção: uma única “estrutura” para desenvolvimento, testes ou produção.
- Quem se beneficia: Equipas de TI, DevOps e gestores que precisam de um ambiente integrado e de uma forma simples de verificar se está tudo a funcionar.
2. Serviços que Compõem o Ecossistema
Quando a orquestração está ativa, os seguintes serviços estão disponíveis (todos na mesma rede Docker):
| Serviço | Função para o negócio |
|---|---|
| postgres | Base de dados onde ficam empresas, filiais, planos de contas, lançamentos, saldos e utilizadores. |
| ecosif-auth | Autenticação e emissão de tokens (login). |
| ecosif-masterdata | Cadastros mestres: empresas, filiais, planos de contas, históricos, configurações. |
| ecosif-moviments | Lançamentos, lotes, importações, consolidação, encerramento. |
| ecosif-querys | Consultas (saldos, razão, listagens). |
| ecif-reports | Geração de relatórios (balancetes, razão, patrimonial, etc.) em PDF/CSV/TXT. |
| ecosif-compliance | Validações e conformidade contábil. |
| ecosif-angular | Interface web (frontend) que o utilizador usa no browser. |
| traefik | Entrada única (HTTP/HTTPS) que encaminha o tráfego para o frontend ou para cada API conforme o caminho (path). |
O utilizador final acede apenas ao domínio configurado (ex.: https://ecosif.cliente.com). O Traefik encaminha:
- Pedidos para
/ecosif-auth,/ecosif-masterdata, etc., para as respetivas APIs. - O resto do tráfego (páginas da aplicação) para o ecosif-angular.
3. Como Verificar se o Sistema Está Saudável
3.1 Status dos Containers
No servidor onde está o ecosif-structure, executar:
./scripts/status.sh
Mostra o estado de cada serviço (running/stopped) e, quando disponível, o estado do health check.
3.2 Health Checks (Saúde dos Serviços)
Cada serviço pode expor um endpoint de saúde. O docker-compose define healthchecks para:
- postgres:
pg_isready(banco aceita conexões). - ecosif-auth, ecosif-masterdata, ecosif-moviments, ecosif-querys, ecosif-reports: chamada HTTP ao
/actuator/health(resposta com"status":"UP"). - ecosif-compliance: endpoint
/health. - ecosif-angular:
curlà raiz (resposta HTTP 200).
Interpretação para o gestor:
- Status “running” e health “healthy” → Serviço considerado saudável.
- Status “running” e health “unhealthy” ou “starting” → Aguardar ou investigar (logs, conectividade, base de dados).
- Status “exited” → Serviço parado; é necessário analisar logs e reiniciar.
3.3 Testes Rápidos de Acesso (Após Arranque)
- Frontend (utilizador): Abrir no browser
http://localhost(dev) ouhttps://seu-dominio(prod). Deve carregar a página de login do eCosif. - APIs:
- Dev:
curl http://localhost/ecosif-auth/actuator/health - Prod:
curl -k https://seu-dominio/ecosif-auth/actuator/health
Resposta esperada: JSON com"status":"UP"(ou equivalente).
Se o frontend carregar e pelo menos o health do ecosif-auth responder UP, o sistema está em condições de uso para login e operação normal. Problemas em outros serviços (ex.: reports, compliance) afetam apenas essas funções.
4. Resumo para o Gestor
- O que é o ecosif-structure: O projeto que orquestra e junta todos os serviços do eCosif (banco, APIs e site) numa única “pilha” Docker.
- Quais serviços compõem o ecossistema: postgres, ecosif-auth, ecosif-masterdata, ecosif-moviments, ecosif-querys, ecosif-reports, ecosif-compliance, ecosif-angular e traefik (entrada única).
- Como verificar se está saudável: Usar
./scripts/status.she, se possível, os health checks; testar o acesso ao site e ao health do ecosif-auth (e outros APIs, se necessário).
Para detalhes de rede e comunicação entre containers, ver architecture/infraestrutura.md. Para primeira instalação e scripts operacionais, ver operacao.md.