Documentação Operacional — ecosif-structure

Público-alvo: DevOps / SRE
Módulo: ecosif-structure (orquestração)

1. Guia de Primeira Instalação

1.1 Pré-requisitos

Software	Versão mínima
Docker	20.10+
Docker Compose	2.0+ (ou `docker compose` v2)
Python	3.8+ (para `scripts/setup-env.py`)
Git	2.0+

Verificação rápida:

docker --version
docker compose version
python3 --version

1.2 Passo a Passo Resumido

Clonar e entrar no diretório bash cd ds-ecosif-ia-services/ecosif-structure
Configurar variáveis de ambiente - Copiar template: cp env.template .env - Ou usar o script interativo: python3 scripts/setup-env.py - O script setup-env.sh (opcional) ajusta SPRING_AUTOCONFIGURE_EXCLUDE quando OAuth2 não é usado.
Preparar volume e banco (primeira vez) - Iniciar apenas o PostgreSQL: ./scripts/start.sh postgres (ou ./scripts/start.sh --dev postgres) - Aguardar o healthcheck (cerca de 30 s) - Inicializar o banco: ./scripts/init-database.sh - O script cria o banco, utilizador, aplica migrations (Flyway ou SQL manual) e insere dados iniciais (ex.: utilizador admin).
Subir todos os serviços - Desenvolvimento: ./scripts/start.sh --dev - Produção: ./scripts/start.sh - Com rebuild: ./scripts/start.sh --build ou ./scripts/start.sh --dev --build
Verificar - Status: ./scripts/status.sh - Logs: ./scripts/logs.sh --follow ou ./scripts/logs.sh <serviço>

1.3 Variáveis Obrigatórias (Primeira Instalação)

Devem estar definidas no .env (ou env.local / env.test):

Variável	Descrição	Exemplo
POSTGRES_DB	Nome do banco	`ecosif`
POSTGRES_USER	Usuário PostgreSQL	`postgres` ou `ecosif`
POSTGRES_PASSWORD	Senha do PostgreSQL	(senha forte)
AUTH_TOKEN_SECRET	Chave JWT (mín. 32 caracteres)	(gerada ou definida)
TOKEN_EXPIRATION	Validade do token (ms)	`1800000`
ECOSIF_DOMAIN	Domínio base	`localhost` ou `ecosif.cliente.com`
ECOSIF_API_BASE_URL	URL base completa	`http://localhost` ou `https://ecosif.cliente.com`
Portas	ECOSIF_AUTH_PORT, ECOSIF_MASTERDATA_PORT, etc.	Ver `env.template`

As restantes variáveis (CORS, OAuth2, AWS, logging, Angular, Traefik, etc.) têm valores padrão ou opcionais; ver env.template.

1.4 Modelo Atual de Variáveis (fonte de verdade)

O padrão atual do ecossistema é usar variáveis ECOSIF_* por módulo, com fallback para nomes legados apenas quando necessário.

Grupo	Padrão canônico	Observações
Porta por serviço	`ECOSIF_<SERVICO>_PORT`	Ex.: `ECOSIF_AUTH_PORT`, `ECOSIF_COMPLIANCE_PORT`
Context path por serviço	`ECOSIF_<SERVICO>_CONTEXT_PATH`	Ex.: `ECOSIF_AUTH_CONTEXT_PATH`
Angular APIs	`ECOSIF_ANGULAR_API_*`	Pode ficar vazio para derivar de `ECOSIF_*_CONTEXT_PATH`
Auth frontend	`ECOSIF_ANGULAR_AUTH_TOKEN`	Se vazio, compose herda `AUTH_TOKEN_SECRET`
DB padrão	`POSTGRES_*`	Serviços Java usam direto; compliance recebe mapeado para `ECOSIF_DB_*`

Aliases legados ainda existentes em alguns módulos (SERVER_SERVLET_CONTEXT_PATH, API_*_URL) são tratados como compatibilidade e não devem ser usados em novas configurações.

2. Scripts (.sh) e Suas Funções

Todos os scripts devem ser executados a partir do diretório ecosif-structure (ou de um subdiretório onde exista .env / env.local / env.test). Eles detectam o diretório de configuração automaticamente.

Script	Função
setup-env.sh	Ajusta `.env`: se `AUTH2_CLIENT_ID` estiver vazio, define `SPRING_AUTOCONFIGURE_EXCLUDE` para desativar OAuth2. Pode criar `.env` a partir de `env.template` se não existir.
setup-env.py	Configurador interativo: cria/atualiza `.env`, mostra valores, permite gerar senhas.
init-database.sh	Preparação do banco: Carrega `.env`, verifica conexão ao PostgreSQL (container ou host), cria banco e utilizador, garante role `ecosif`, aplica migrations (Flyway ou ficheiros SQL em `../flyway-ecosif/sql`), insere dados iniciais (ex.: admin). Confirmação interativa antes de executar.
start.sh	Inicia serviços: `./start.sh` (produção), `./start.sh --dev` (HTTP), `./start.sh --build` (rebuild), `./start.sh postgres` (só Postgres). Usa `docker compose` ou `docker-compose` e ficheiros `-f docker-compose.yml` e, em dev, `-f docker-compose.dev.yml`.
stop.sh	Para todos os serviços (`docker compose down`).
restart.sh	Para e volta a iniciar serviços.
status.sh	Mostra estado dos containers e, quando possível, health. Uso: `./status.sh` ou `./status.sh --dev`.
logs.sh	Ver logs: `./logs.sh`, `./logs.sh postgres`, `./logs.sh --tail 100`, `./logs.sh --follow`.
backup-database.sh	Backup do PostgreSQL (conteúdo e uso dependem da implementação no repositório).
restore-database.sh	Restauro do backup (idem).
clean.sh	Limpeza de containers/volumes (conforme implementação).
update-submodules.sh	Atualiza submodules Git.
update.sh	Atualização de imagens/serviços (conforme implementação).
version.sh	Exibe versão do ECOSIF (conforme implementação).

2.1 Pastas de Logs

PostgreSQL: Logs padrão do container (volume interno ou stdout, conforme imagem).
ecosif-compliance: Volume montado em ./logs/compliance (path no host); o script logs.sh não cria esta pasta automaticamente; o docker-compose monta ./logs/compliance no container. Para evitar erros de arranque, criar no host antes do primeiro start: mkdir -p logs/compliance.
Demais serviços: Logs em stdout/stderr; consultados com ./scripts/logs.sh <serviço>.

Recomendação: criar a pasta de logs antes da primeira instalação:

mkdir -p logs/compliance

3. Volumes do PostgreSQL e Persistência

O serviço postgres usa o volume nomeado postgres_data mapeado para /var/lib/postgresql/data (e PGDATA=/var/lib/postgresql/data/pgdata).
Os dados persistem entre docker compose down e docker compose up -d.
O init-database.sh não cria o volume; o Docker cria ao subir o serviço postgres. O script apenas cria o banco, utilizador e aplica migrations dentro do container já em execução.
Para ambiente limpo (apagar dados): parar serviços, remover o volume (ex.: docker volume rm ecosif-structure_postgres_data ou o nome que o Compose tiver atribuído) e repetir a primeira instalação.

4. Modos de Operação

Modo	Comando	Ficheiros Compose	Traefik
Produção	`./scripts/start.sh`	docker-compose.yml	HTTPS (websecure), Let's Encrypt
Desenvolvimento	`./scripts/start.sh --dev`	docker-compose.yml + docker-compose.dev.yml	HTTP (web), sem TLS

5. Resumo para SRE

Primeira instalação: Configurar .env → ./scripts/start.sh postgres → aguardar → ./scripts/init-database.sh → ./scripts/start.sh (ou --dev).
Preparação de ambiente: Scripts setup-env.py / setup-env.sh; pasta logs/compliance criada manualmente se necessário.
Volume Postgres: Nomeado no Compose; persistente; init-database.sh preenche schema e dados iniciais.
Comandos do dia a dia: start.sh, stop.sh, restart.sh, status.sh, logs.sh (com ou sem nome do serviço e --follow).

Para topologia e comunicação entre containers, ver architecture/infraestrutura.md. Para visão do gestor (serviços e saúde), ver user/visao_geral.md.

6. Importação via Lambdas (automations)

O modelo atual de importação de IPL em produção é orientado a Lambda/SQS (não apenas container local).

6.1 Variáveis essenciais no `.env`

Grupo	Variáveis
S3	`AWS_S3_BUCKET`, `AWS_S3_ERROR_FOLDER`, `AWS_S3_IMPORTED_FOLDER`, `AWS_S3_REPORTS_FOLDER`, `CT32_MASTER_KEY`
SQS	`AWS_SQS_ENTRIES_QUEUE_URL`, `AWS_SQS_CONSOLIDATION_QUEUE_URL`, `AWS_SQS_CONSOLIDATION_DEFER_QUEUE_URL`
API	`ECOSIF_API_BASE_URL`, `ECOSIF_API_URL_MODE`, `ECOSIF_AUTH_PORT`, `ECOSIF_MASTERDATA_PORT`, `ECOSIF_MOVIMENTS_PORT`
Segurança	`ECOSIF_AUTOMATIONS_SERVICE_SECRET`, `ECOSIF_DB_SECRET`
Consolidação diferida	`CONSOLIDATION_DEFER_ENABLED`, `CONSOLIDATION_DEBOUNCE_SEC`, `CONSOLIDATION_MAX_WAIT_SEC`, `CONSOLIDATION_WINDOW_TABLE`, `CONSOLIDATION_LOCK_TABLE`

6.2 Fluxo operacional

Upload de arquivo .IPL e CT32.LD no bucket de importação.
Lambda de import valida e agenda processamento.
Lambda entries processa lançamentos e aciona fila de consolidação.
Lambda consolidation consolida resultados e grava relatórios.
Monitoramento por logs e status de filas.

6.3 Acompanhamento

Para operar e acompanhar o pipeline, usar os scripts do módulo ecosif-automations (ex.: watch-import-pipeline.sh) em vez de comandos ad-hoc.