Instrução Técnica Completa — Implantação do eCosif em Produção

Destinatário: Equipe de implantação / DevOps / SRE (ex.: Banco Itaú)
Objetivo: Documento técnico único com toda a informação necessária para implantar o ecossistema eCosif em ambiente de produção, incluindo criação do banco de dados, variáveis de ambiente, passos de deploy e diagramas.

Modelo de entrega ao cliente

O cliente (banco) não recebe os fontes do projeto. A entrega é feita exclusivamente através de imagens Docker. O cliente obtém essas imagens a partir do registo de imagens e implanta-as no seu ambiente. Não há passos de build de aplicação (sem mvn, npm run build, pip install, etc.) no lado do cliente — apenas configuração de variáveis de ambiente, execução dos contentores e integração com API Gateway, base de dados e rede.

Índice

1. Introdução e versões
2. Arquitetura geral e diagramas
3. Pré-requisitos e criação do banco de dados
4. Variáveis de ambiente
5. ecosif-angular (frontend)
6. ecosif-auth
7. ecosif-masterdata
8. ecosif-moviments
9. ecosif-querys
10. ecosif-reports
11. ecosif-compliance
12. ecosif-automations
13. Checklist pós-implantação

1. Introdução e versões

O eCosif é um ecossistema de aplicações para gestão contábil, composto por um frontend (SPA Angular) e vários serviços backend (Spring Boot e Python). A implantação em produção pressupõe um único domínio (ex.: https://app.ecosif.banco.com.br) com o frontend na raiz e cada backend num path (/ecosif-auth, /ecosif-masterdata, etc.).

1.1 Versões dos módulos (referência)

2. Arquitetura geral e diagramas

2.1 Diagrama de alto nível (fluxo utilizador e APIs)

flowchart LR
    subgraph Browser
        A[Utilizador]
        B[SPA Angular]
    end
    subgraph "API Gateway / Load Balancer"
        GW["/ → Frontend\n/ecosif-auth → Auth\n/ecosif-masterdata → Masterdata\n/ecosif-moviments → Moviments\n/ecosif-querys → Querys\n/ecosif-reports → Reports\n/ecosif-compliance → Compliance"]
    end
    subgraph Backends
        Auth[ecosif-auth]
        MD[ecosif-masterdata]
        Mov[ecosif-moviments]
        Q[ecosif-querys]
        R[ecosif-reports]
        C[ecosif-compliance]
    end
    subgraph PostgreSQL
        DB[(ecosif)]
    end
    A --> B
    B --> GW
    GW --> Auth
    GW --> MD
    GW --> Mov
    GW --> Q
    GW --> R
    GW --> C
    Auth --> DB
    MD --> DB
    Mov --> DB
    Q --> DB
    R --> DB
    C --> DB

2.2 Diagrama de dependências entre módulos

flowchart TD
    Angular[ecosif-angular] --> Auth[ecosif-auth]
    Angular --> MD[ecosif-masterdata]
    Angular --> Mov[ecosif-moviments]
    Angular --> Q[ecosif-querys]
    Angular --> R[ecosif-reports]
    Angular --> C[ecosif-compliance]
    Auth --> DB[(PostgreSQL)]
    MD --> DB
    Mov --> DB
    Q --> DB
    R --> DB
    C --> DB
    Auto[ecosif-automations] --> API[APIs moviments/masterdata]
    API --> Mov
    API --> MD

2.3 Mapeamento de URLs (produção)

3. Pré-requisitos e criação do banco de dados

3.1 Pré-requisitos gerais

• PostgreSQL 12 ou superior (uma instância; uma base de dados ecosif; utilizadores por serviço recomendados).
• Domínio e certificado TLS (ex.: https://app.ecosif.banco.com.br).
• Chave JWT única e segura (AUTH_TOKEN_SECRET), partilhada por auth, masterdata, moviments, querys e reports.
• Docker (ou plataforma que consuma imagens Docker, ex.: ECS, Kubernetes) para executar as imagens entregues.
• Acesso ao registo de imagens de onde o cliente faz pull das imagens Docker (URL do registo e credenciais são fornecidas com o release/tag).

3.2 Passo a passo: criação do banco de dados PostgreSQL

Passo 1. Instalar/configurar o servidor PostgreSQL (ou usar serviço gerido, ex.: RDS).

Passo 2. Criar a base de dados e os utilizadores (executar como superuser, ex.: postgres):

-- Criar a base de dados
CREATE DATABASE ecosif
  WITH ENCODING = 'UTF8'
       LC_COLLATE = 'pt_BR.UTF-8'
       LC_CTYPE = 'pt_BR.UTF-8'
       TEMPLATE = template0;

-- Conectar à base: \c ecosif

-- Utilizador para ecosif-auth (com permissões para criar schema e tabelas via Flyway)
CREATE USER ecosif_auth WITH PASSWORD 'senha_segura_auth';
GRANT ALL PRIVILEGES ON DATABASE ecosif TO ecosif_auth;
GRANT ALL ON SCHEMA public TO ecosif_auth;
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT ALL ON TABLES TO ecosif_auth;

-- Utilizador para ecosif-masterdata
CREATE USER ecosif_masterdata WITH PASSWORD 'senha_segura_masterdata';
GRANT CONNECT ON DATABASE ecosif TO ecosif_masterdata;
GRANT USAGE ON SCHEMA public TO ecosif_masterdata;
GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA public TO ecosif_masterdata;
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT, INSERT, UPDATE, DELETE ON TABLES TO ecosif_masterdata;

-- Utilizador para ecosif-moviments
CREATE USER ecosif_moviments WITH PASSWORD 'senha_segura_moviments';
GRANT CONNECT ON DATABASE ecosif TO ecosif_moviments;
GRANT USAGE ON SCHEMA public TO ecosif_moviments;
GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA public TO ecosif_moviments;
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT, INSERT, UPDATE, DELETE ON TABLES TO ecosif_moviments;

-- Utilizador para ecosif-querys
CREATE USER ecosif_querys WITH PASSWORD 'senha_segura_querys';
GRANT CONNECT ON DATABASE ecosif TO ecosif_querys;
GRANT USAGE ON SCHEMA public TO ecosif_querys;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO ecosif_querys;
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT, INSERT, UPDATE, DELETE ON TABLES TO ecosif_querys;

-- Utilizador para ecosif-reports
CREATE USER ecosif_reports WITH PASSWORD 'senha_segura_reports';
GRANT CONNECT ON DATABASE ecosif TO ecosif_reports;
GRANT USAGE ON SCHEMA public TO ecosif_reports;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO ecosif_reports;
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT, INSERT, UPDATE, DELETE ON TABLES TO ecosif_reports;

-- Utilizador para ecosif-compliance
CREATE USER ecosif_compliance WITH PASSWORD 'senha_segura_compliance';
GRANT CONNECT ON DATABASE ecosif TO ecosif_compliance;
GRANT USAGE ON SCHEMA public TO ecosif_compliance;
GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA public TO ecosif_compliance;
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT, INSERT, UPDATE, DELETE ON TABLES TO ecosif_compliance;

Passo 3. O ecosif-auth é o primeiro serviço a subir com Flyway ativo; ele criará as tabelas do schema (gr_user, roles, etc.). Os restantes serviços utilizam o mesmo schema (lib ecosif-database). Garantir que o utilizador ecosif_auth tem permissão para criar tabelas na primeira execução.

Passo 4. Documentar em local seguro: host, porta, nome da base, cada utilizador e respectiva senha, para configurar as variáveis de ambiente de cada módulo.

4. Variáveis de ambiente

As variáveis de ambiente são definidas na task definition (ECS), no docker run / docker-compose ou no orquestrador (Kubernetes). As imagens Docker leem-nas em tempo de execução. A lista completa está no arquivo ecosif-structure/env.template. Abaixo segue a tabela de referência de todas as variáveis (obrigatórias e opcionais) por módulo, tipo e obrigatoriedade. O detalhe de como utilizar e o que cada uma faz está na secção de cada serviço (itens 5 a 12).

4.1 Tabela de referência — todas as variáveis

Notas: (1) O módulo estrutura refere-se a variáveis usadas pelo ecosif-structure (docker-compose, scripts de setup), não por um contentor de aplicação específico. As variáveis exclusivas da estrutura aparecem no final da tabela e estão centralizadas no final do arquivo env.template. (2) TRAEFIK_ACME_ENABLED foi removida por não ser utilizada pelo docker-compose nem pelo Traefik. (3) Nos serviços Spring Boot, o context path pode ser definido por SERVER_SERVLET_CONTEXT_PATH (direto no contentor) ou, no ecosif-structure, por ECOSIF_*_CONTEXT_PATH (ex.: ECOSIF_AUTH_CONTEXT_PATH). (4) Todas as variáveis são em MAIÚSCULAS (incluindo ecosif-compliance). (5) O detalhe de como utilizar cada variável e o que faz está na secção de cada serviço (itens 5 a 12).

5. ecosif-angular (frontend)

5.1 Função e tecnologia

• Função: Interface web (login, cadastros, lançamentos, consultas, relatórios, administração).
• Stack: Angular 14, TypeScript 4.7, CoreUI, Bootstrap 5, Nginx (servir estáticos).
• Versão: 0.7.01.202601282

5.2 Diagrama (frontend e APIs)

flowchart LR
    subgraph "Navegador"
        UI[SPA Angular]
    end
    subgraph "Mesma origem (ex.: app.ecosif.banco.com.br)"
        UI --> A[/ecosif-auth]
        UI --> M[/ecosif-masterdata]
        UI --> V[/ecosif-moviments]
        UI --> Q[/ecosif-querys]
        UI --> R[/ecosif-reports]
        UI --> C[/ecosif-compliance]
    end

5.3 Variáveis de ambiente

Definir na task/contentor do frontend. O entrypoint usa-as para gerar window.env (ex.: env.js). Se a imagem não suportar variáveis em runtime, os paths das APIs já vêm na imagem para o domínio acordado.

5.4 Passo a passo de implantação (ecosif-angular)

1. Obter a imagem Docker do registo indicado no release. Exemplo: docker pull disoft/ecosif-angular:<tag>.
2. Configurar variáveis de ambiente do contentor (se a imagem suportar): URLs das APIs em paths relativos (ex.: authUrl=/ecosif-auth, apiUrl=/ecosif-masterdata, etc.) ou domínio para o qual a imagem foi preparada.
3. Executar o contentor (ou definir task/serviço em ECS/Kubernetes) com a porta exposta (ex.: 80). O contentor serve arquivos estáticos via Nginx; health check em /health se disponível.
4. Expor o serviço na raiz do domínio (path /) no API Gateway ou load balancer.
5. Validar: abrir https://app.ecosif.banco.com.br e verificar login (requer ecosif-auth já em funcionamento).

6. ecosif-auth

6.1 Função e tecnologia

• Função: Autenticação (login utilizador/senha, OAuth2/Google ou Azure AD), emissão e validação de JWT.
• Stack: Spring Boot 2.7, Java 17, PostgreSQL, Flyway.
• Versão: 0.7.01.202601280

6.2 Variáveis de ambiente

Definir na task/contentor do ecosif-auth. Segredos (POSTGRES_PASSWORD, AUTH_TOKEN_SECRET) em repositório de segredos.

6.3 Passo a passo de implantação (ecosif-auth)

1. Banco criado (ver secção 3) e utilizador ecosif_auth com permissões.
2. Obter a imagem Docker do registo indicado no release (imagem gerada no tag GitHub). Exemplo: docker pull <registro>/ecosif-auth:<tag>.
3. Configurar todas as variáveis de ambiente na task/contentor (POSTGRES_*, AUTH_TOKEN_SECRET, ECOSIF_CORS, SERVER_SERVLET_CONTEXT_PATH=/ecosif-auth, etc.).
4. Subir o contentor (ou serviço ECS/Kubernetes). Na primeira execução, Flyway executará as migrações em db/migration dentro da imagem.
5. Health check: configurar ALB/API Gateway para /ecosif-auth/actuator/health.
6. Mapear no API Gateway o path /ecosif-auth (e /ecosif-auth/{proxy+}) para este serviço.

7. ecosif-masterdata

7.1 Função e tecnologia

• Função: Dados mestres (empresas, filiais, planos de contas, fundos, históricos, utilizadores).
• Stack: Spring Boot 2.7, Java 17, PostgreSQL, lib ecosif-database.
• Versão: 0.7.01.202601280

7.2 Variáveis de ambiente

Definir na task/contentor do ecosif-masterdata. AUTH_TOKEN_SECRET deve ser igual ao do ecosif-auth.

7.3 Passo a passo de implantação (ecosif-masterdata)

1. ecosif-auth já implantado (schema e tabelas existem).
2. Obter a imagem Docker do registo (tag do release). Ex.: docker pull <registro>/ecosif-masterdata:<tag>.
3. Configurar variáveis de ambiente; context path /ecosif-masterdata.
4. Subir o contentor; Health: /ecosif-masterdata/actuator/health.
5. Mapear no API Gateway /ecosif-masterdata (e /ecosif-masterdata/{proxy+}) para este serviço.

8. ecosif-moviments

8.1 Função e tecnologia

• Função: Lançamentos, lotes, consolidação, encerramento, importação (ex.: IPL).
• Stack: Spring Boot 2.7, Java 17, PostgreSQL, Flyway.
• Versão: 0.7.01.202601280

8.2 Variáveis de ambiente

Definir na task/contentor do ecosif-moviments. AUTH_TOKEN_SECRET igual ao do ecosif-auth.

8.3 Passo a passo de implantação (ecosif-moviments)

1. Auth e masterdata já implantados.
2. Obter a imagem Docker do registo (tag do release). Ex.: docker pull <registro>/ecosif-moviments:<tag>.
3. Configurar variáveis de ambiente; context path /ecosif-moviments.
4. Subir o contentor; Health: /ecosif-moviments/actuator/health.
5. Mapear no API Gateway /ecosif-moviments (e /ecosif-moviments/{proxy+}) para este serviço.

9. ecosif-querys

9.1 Função e tecnologia

• Função: Consultas (saldos, razão, listagens) — apenas leitura.
• Stack: Spring Boot 2.7, Java 17, PostgreSQL.
• Versão: 0.7.01.202601280

9.2 Variáveis de ambiente

Definir na task/contentor do ecosif-querys. AUTH_TOKEN_SECRET igual ao do ecosif-auth.

9.3 Passo a passo de implantação (ecosif-querys)

1. Serviços que escrevem no BD (auth, masterdata, moviments) já implantados.
2. Obter a imagem Docker do registo (tag do release). Ex.: docker pull <registro>/ecosif-querys:<tag>.
3. Configurar variáveis de ambiente; context path /ecosif-querys.
4. Subir o contentor; Health: /ecosif-querys/actuator/health.
5. Mapear no API Gateway /ecosif-querys (e /ecosif-querys/{proxy+}) para este serviço.

10. ecosif-reports

10.1 Função e tecnologia

• Função: Geração de relatórios (PDF, CSV, TXT) — JasperReports.
• Stack: Spring Boot 2.7, Java 17, PostgreSQL.
• Versão: 0.7.01.202601282

10.2 Variáveis de ambiente

Definir na task/contentor do ecosif-reports. AUTH_TOKEN_SECRET igual ao do ecosif-auth.

10.3 Passo a passo de implantação (ecosif-reports)

1. Obter a imagem Docker do registo (tag do release). Ex.: docker pull <registro>/ecosif-reports:<tag>.
2. Configurar variáveis de ambiente; context path /ecosif-reports.
3. Subir o contentor (a imagem já inclui java.awt.headless=true para geração de relatórios).
4. Health: /ecosif-reports/actuator/health.
5. Mapear no API Gateway /ecosif-reports (e /ecosif-reports/{proxy+}) para este serviço.

11. ecosif-compliance

11.1 Função e tecnologia

• Função: Validação e conformidade contábil (regras COSIF/CVM); motor de regras em DSL; API REST e Swagger.
• Stack: Python 3.12, Flask, Flask-RESTX, SQLAlchemy, PostgreSQL.
• Versão: 0.1.02.202509121

11.2 Diagrama (compliance)

flowchart LR
    subgraph "ecosif-compliance"
        API[API REST]
        Engine[Motor regras]
    end
    Angular[Frontend] --> API
    API --> Engine
    Engine --> DB[(PostgreSQL)]

11.3 Variáveis de ambiente

O ecosif-compliance (Python/Flask) lê variáveis de ambiente em MAIÚSCULAS e mapeia-as para config.json ou config-{ECOSIF_RUNTIME_ENVIRONMENT}.json. Definir na task/contentor.

11.4 Passo a passo de implantação (ecosif-compliance)

1. Obter a imagem Docker do registo (tag do release). Ex.: docker pull <registro>/ecosif-compliance:<tag>.
2. Configurar variáveis de ambiente do contentor (ECOSIF_DB_SERVER, ECOSIF_DB_PASSWORD, ECOSIF_CORS, ECOSIF_COMPLIANCE_PORT, ECOSIF_RUNTIME_ENVIRONMENT=prod, etc.). A imagem pode usar arquivo config com placeholders resolvidos por variáveis.
3. Configurar prefixo da aplicação /ecosif-compliance (reverse proxy ou configuração na imagem) para que os endpoints respondam em https://app.ecosif.banco.com.br/ecosif-compliance/....
4. Subir o contentor (porta 8021 no interior; gunicorn já configurado na imagem).
5. Health check: endpoint de saúde exposto pela app (ex.: /ecosif-compliance/health).
6. Mapear no API Gateway /ecosif-compliance (e /ecosif-compliance/{proxy+}) para este serviço.

12. ecosif-automations

12.1 Função e tecnologia

• Função: Importação automática de arquivos (.IPL, .CT32.LD), acionada por eventos (S3, SQS); chama as APIs moviments e masterdata.
• Stack: Python 3.11+, AWS (S3, SQS, Lambda) ou execução em ECS.
• Versão: 0.7.01.202601280

12.2 Diagrama (fluxo automatizações)

flowchart LR
    S3[S3 Bucket] --> Lambda[Lambda Import]
    Lambda --> SQS[SQS Fila]
    SQS --> Disp[Lambda Dispatcher]
    Disp --> API[API moviments/masterdata]
    API --> Mov[ecosif-moviments]
    API --> MD[ecosif-masterdata]

12.3 Variáveis de ambiente

Definir na configuração da função Lambda ou na task ECS do ecosif-automations. Em produção (AWS), ECOSIF_LOCAL_MODE=false e ECOSIF_API_BASE_URL aponta para o domínio das APIs.

12.4 Passo a passo de implantação (ecosif-automations)

1. APIs (moviments, masterdata) já implantadas e acessíveis em ECOSIF_API_BASE_URL.
2. Obter as imagens Docker ou pacotes Lambda do registo/release (imagens ou artefactos gerados no tag GitHub para as funções de import e dispatcher).
3. AWS: criar bucket S3, filas SQS; implantar as funções Lambda (ou tarefas ECS) usando as imagens/artefactos fornecidos.
4. Configurar variáveis nas Lambdas ou na task ECS: ECOSIF_API_BASE_URL, AWS_REGION, bucket, filas.
5. Credenciais: IAM roles (Lambdas/ECS) ou variáveis AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY.
6. Testar: upload de arquivo no bucket e verificar processamento e chamadas às APIs.
7. Se existir API HTTP neste módulo: obter a imagem correspondente e mapear /ecosif-automations no API Gateway.

13. Checklist pós-implantação

• [ ] PostgreSQL criado; utilizadores e senhas documentados; ecosif-auth executou Flyway com sucesso.
• [ ] ecosif-auth: health /ecosif-auth/actuator/health retorna 200; login e emissão de JWT funcionam.
• [ ] ecosif-masterdata, ecosif-moviments, ecosif-querys, ecosif-reports: health e endpoints respondem com token válido.
• [ ] ecosif-compliance: health e Swagger acessíveis em /ecosif-compliance.
• [ ] ecosif-angular: carrega em https://app.ecosif.banco.com.br; login e navegação para cadastros e consultas funcionam.
• [ ] CORS configurado em todos os backends com a URL exata do frontend.
• [ ] ecosif-automations (se implantado): integração S3/SQS e chamadas às APIs validadas.
• [ ] Logs e monitorização (ex.: CloudWatch, agregadores) configurados conforme política do banco.
• [ ] Segredos (senhas BD, AUTH_TOKEN_SECRET) geridos por repositório seguro (Secrets Manager, etc.).

Fim do documento. Para detalhes adicionais por módulo, consultar a pasta docs/ de cada repositório (operational.md, aws-ecs-api-gateway.md).

Equipe eCosif · Instrução Técnica de Implantação em Produção