Pular para conteúdo

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) ou https://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.sh e, 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.