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

Destinatário: Equipe de implantação / DevOps / SRE
Objetivo: Documento técnico preliminar com a informação necessária para implantar o ecossistema eCosif em ambiente de produção (frontend e backends Java/Spring Boot), incluindo criação do banco de dados, variáveis de ambiente, passos de deploy e implantações na AWS com ECS e API Gateway.

Âmbito deste documento (preliminar): - Incluído: ecosif-angular, ecosif-auth, ecosif-masterdata, ecosif-moviments, ecosif-querys, ecosif-reports. - Não incluído (entrega posterior): ecosif-compliance e ecosif-automations — serão entregues em documento complementar na próxima semana.

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, etc.) no lado do cliente — apenas configuração de variáveis de ambiente, execução dos contentores e integração com API Gateway (ou load balancer), 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. Implementação na AWS (ECS e API Gateway)
12. 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). 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) — âmbito preliminar

ecosif-compliance e ecosif-automations serão documentados em entrega posterior.

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"]
    end
    subgraph Backends
        Auth[ecosif-auth]
        MD[ecosif-masterdata]
        Mov[ecosif-moviments]
        Q[ecosif-querys]
        R[ecosif-reports]
    end
    subgraph PostgreSQL
        DB[(ecosif)]
    end
    A --> B
    B --> GW
    GW --> Auth
    GW --> MD
    GW --> Mov
    GW --> Q
    GW --> R
    Auth --> DB
    MD --> DB
    Mov --> DB
    Q --> DB
    R --> DB

2.2 Diagrama de dependências entre módulos (preliminar)

flowchart TD
    Angular[ecosif-angular] --> Auth[ecosif-auth]
    Angular --> MD[ecosif-masterdata]
    Angular --> Mov[ecosif-moviments]
    Angular --> Q[ecosif-querys]
    Angular --> R[ecosif-reports]
    Auth --> DB[(PostgreSQL)]
    MD --> DB
    Mov --> DB
    Q --> DB
    R --> DB

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) — em AWS pode ser resolvido com ACM e API Gateway (ver secção 11).
• 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 (ex.: ECR; URL e credenciais fornecidas com o release).

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.: Amazon RDS).

Passo 2. Criar a base de dados e os utilizadores (executar como superuser, ex.: postgres). Neste documento não se criam utilizadores para ecosif-compliance.

-- 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;

Passo 3. O ecosif-auth é o primeiro serviço a subir com Flyway ativo; ele criará as tabelas do schema. 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 (ex.: AWS Secrets Manager) host, porta, nome da base, cada utilizador e respectiva senha.

4. Variáveis de ambiente

As variáveis são definidas na task definition (ECS), no docker run / docker-compose ou no orquestrador. A tabela abaixo refere apenas os módulos do âmbito preliminar. Segredos (POSTGRES_PASSWORD, AUTH_TOKEN_SECRET) devem ser geridos por repositório seguro (ex.: Secrets Manager) e referenciados na task.

4.1 Tabela de referência — módulos preliminares

O detalhe de como utilizar cada variável está na secção de cada serviço (itens 5 a 10). Para ECS, utilizar Secrets Manager ou Parameter Store para senhas e AUTH_TOKEN_SECRET e referenciá-los na task definition.

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 Variáveis de ambiente

Definir na task/contentor do frontend. O entrypoint usa-as para gerar window.env / config.json. Com domínio único, as bases das APIs são paths relativos (ex.: /ecosif-auth).

Nota: Neste âmbito preliminar não se configura ECOSIF_ANGULAR_API_COMPLIANCE_URL; o frontend pode omitir ou usar valor vazio até à entrega do módulo compliance.

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

1. Obter a imagem Docker do registo (ex.: ECR). Ex.: docker pull <account>.dkr.ecr.<region>.amazonaws.com/ecosif-angular:<tag>.
2. Configurar variáveis de ambiente na task definition (ECS) ou no contentor: URLs em paths relativos.
3. Executar o contentor (porta 80). Health check: /health.
4. Expor o serviço na raiz (path /) no API Gateway ou ALB (ver secção 11).
5. Validar: abrir https://<domínio> e verificar login (requer ecosif-auth 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

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

1. Banco criado (secção 3) e utilizador ecosif_auth com permissões.
2. Obter imagem Docker do registo.
3. Configurar variáveis na task ECS (ou contentor); segredos via Secrets Manager.
4. Subir o serviço ECS. Na primeira execução, Flyway cria as tabelas.
5. Health check (ALB): /ecosif-auth/actuator/health.
6. Mapear no API Gateway /ecosif-auth e /ecosif-auth/{proxy+} para o ALB deste serviço (secção 11).

7. ecosif-masterdata

7.1 Função e tecnologia

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

7.2 Variáveis de ambiente

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

1. ecosif-auth já implantado.
2. Obter imagem; configurar variáveis; context path /ecosif-masterdata.
3. Subir serviço ECS. Health: /ecosif-masterdata/actuator/health.
4. Mapear no API Gateway /ecosif-masterdata e /ecosif-masterdata/{proxy+} (secção 11).

8. ecosif-moviments

8.1 Função e tecnologia

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

8.2 Variáveis de ambiente

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

1. Auth e masterdata já implantados.
2. Obter imagem; configurar variáveis; context path /ecosif-moviments.
3. Subir ECS. Health: /ecosif-moviments/actuator/health.
4. Mapear no API Gateway /ecosif-moviments e /ecosif-moviments/{proxy+} (secção 11).

9. ecosif-querys

9.1 Função e tecnologia

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

9.2 Variáveis de ambiente

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

1. Auth, masterdata, moviments já implantados.
2. Obter imagem; configurar variáveis; context path /ecosif-querys.
3. Subir ECS. Health: /ecosif-querys/actuator/health.
4. Mapear no API Gateway /ecosif-querys e /ecosif-querys/{proxy+} (secção 11).

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

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

1. Obter imagem; configurar variáveis; context path /ecosif-reports.
2. Subir ECS. Health: /ecosif-reports/actuator/health.
3. Mapear no API Gateway /ecosif-reports e /ecosif-reports/{proxy+} (secção 11).

11. Implementação na AWS (ECS e API Gateway)

Esta secção descreve como implantar os serviços do eCosif (âmbito preliminar) na Amazon Web Services, utilizando Amazon ECS para execução dos contentores e API Gateway como ponto de entrada único com certificado digital no domínio designado.

11.1 Arquitetura na AWS

• Domínio final: ex.: https://app.ecosif.banco.com.br (ou o domínio acordado com o cliente).
• API Gateway: um único API (HTTP API ou REST API) com domínio customizado e certificado SSL/TLS (ACM). Todo o tráfego HTTPS termina no API Gateway.
• Roteamento por path: o API Gateway encaminha cada path para o ALB do respetivo serviço ECS.
• ECS: um cluster ECS; um serviço ECS por aplicação (ecosif-angular, ecosif-auth, ecosif-masterdata, ecosif-moviments, ecosif-querys, ecosif-reports), cada um com o seu Application Load Balancer (ALB) e target group.
• PostgreSQL: pode ser Amazon RDS na mesma VPC; os contentores ECS acedem ao RDS pelo endpoint e porta configurados (POSTGRES_HOST, POSTGRES_PORT).

Fluxo resumido:

Cliente (HTTPS) → API Gateway (domínio + certificado) → rotas por path → ALB → ECS (tasks)

11.2 Mapeamento de paths no API Gateway

Configurar as rotas de forma a que os paths mais específicos tenham prioridade; a rota default (ex.: / ou catch-all) encaminha para o frontend.

Cada integração HTTP do API Gateway deve apontar para o ALB do serviço (DNS do ALB ou ARN, conforme o tipo de API). O API Gateway encaminha o path completo para o ALB (o backend recebe, por ex., /ecosif-auth/api/auth/signin); por isso os serviços Spring Boot devem ter SERVER_SERVLET_CONTEXT_PATH igual ao prefixo do path.

11.3 Certificado digital no domínio do API Gateway

O endereço correto que o utilizador usa é o domínio customizado (ex.: app.ecosif.banco.com.br). O certificado SSL/TLS é associado a esse domínio no API Gateway, não nos contentores.

Passos:

1. Certificado no ACM (AWS Certificate Manager)
   - Pedir um certificado para o domínio (ex.: app.ecosif.banco.com.br ou *.ecosif.banco.com.br).
   - Validação por DNS (recomendado): criar os registos CNAME indicados na zona DNS (Route 53 ou externo) até o certificado ficar Issued.
   - O certificado deve estar na mesma região do API Gateway (ou em us-east-1 se for API Gateway edge-optimized).

2. Domínio customizado no API Gateway
   - API Gateway → Custom domain names → Create domain name.
   - Domain name: ex. app.ecosif.banco.com.br.
   - Certificate: selecionar o certificado do ACM criado acima.
   - Endpoint type: Regional (recomendado para HTTP API).

3. Mapear o domínio à API
   - No domínio customizado, Configure API mappings: associar à sua HTTP API (ou REST API) e ao stage (ex.: $default ou prod).
   - Garantir que as rotas (paths) estão definidas e apontam para os ALBs corretos (ver 11.2).

4. DNS
   - Na zona DNS (Route 53 ou provedor externo), criar um registo (ex.: CNAME ou A Alias) que aponte o nome do domínio (ex.: app.ecosif.banco.com.br) para o Target domain name do domínio customizado do API Gateway (valor mostrado na consola).
   - Após propagação, https://app.ecosif.banco.com.br passa a usar o certificado do API Gateway e o roteamento para os serviços ECS.

Assim, o certificado digital fica no endereço correto — no domínio do API Gateway. Os contentores continuam a servir HTTP (porta 80 ou 8080); o HTTPS é terminado no API Gateway.

11.4 ECS — pontos principais

• Cluster ECS: criar um cluster (ex.: Fargate ou EC2) na VPC desejada.
• Task definitions: uma por serviço (ecosif-angular, ecosif-auth, etc.):
• Imagem: ECR (ex.: <account>.dkr.ecr.<region>.amazonaws.com/ecosif-auth:<tag>).
• Porta do contentor: 80 para ecosif-angular (Nginx), 8080 para os backends Spring Boot.
• Variáveis de ambiente: conforme secções 5 a 10; segredos (POSTGRES_PASSWORD, AUTH_TOKEN_SECRET) via Secrets Manager ou Parameter Store (referência na task definition).
• Logs: configurar logConfiguration para CloudWatch Logs (driver awslogs).
• Serviços ECS: um serviço por aplicação; cada serviço está atrás de um ALB com target group (porta 80 ou 8080 conforme o tipo de app). O target group deve ter health check no path correto:
• Frontend: /health
• Backends: /ecosif-auth/actuator/health, /ecosif-masterdata/actuator/health, etc.
• Rede: as tasks devem estar em subnets privadas (recomendado) com acesso ao RDS e à internet (NAT) se necessário; os ALBs podem estar em subnets públicas. O API Gateway integra com os ALBs (via VPC Link para REST API ou integração HTTP para o endpoint do ALB).

11.5 Ordem sugerida de implantação na AWS

1. Criar VPC, subnets, RDS (PostgreSQL) e utilizadores da base (secção 3).
2. Criar cluster ECS e repositórios ECR (ou usar registo fornecido).
3. ecosif-auth: task definition, ALB, target group (health /ecosif-auth/actuator/health), serviço ECS.
4. ecosif-masterdata, ecosif-moviments, ecosif-querys, ecosif-reports: task definition, ALB, target group, serviço ECS para cada um.
5. ecosif-angular: task definition, ALB, target group (health /health), serviço ECS.
6. API Gateway: criar API (HTTP API ou REST API); criar rotas por path (11.2) com integração HTTP para cada ALB; criar domínio customizado e anexar certificado ACM (11.3); configurar DNS.
7. Validar: aceder a https://<domínio> e testar login e fluxos principais.

Para detalhes por módulo (variáveis, health checks), consultar a pasta docs/ de cada repositório (operational.md, aws-ecs-api-gateway.md).

12. Checklist pós-implantação (preliminar)

• [ ] PostgreSQL criado; utilizadores (auth, masterdata, moviments, querys, reports) e senhas documentados/em Secrets Manager; 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-angular: carrega em https://<domínio>; login e navegação para cadastros e consultas funcionam.
• [ ] CORS configurado em todos os backends com a URL exata do frontend.
• [ ] Na AWS: certificado ACM no domínio customizado do API Gateway; DNS apontando para o API Gateway; rotas por path a encaminhar para os ALBs dos serviços ECS.
• [ ] Logs e monitorização (ex.: CloudWatch) configurados conforme política do cliente.
• [ ] Segredos (senhas BD, AUTH_TOKEN_SECRET) geridos por Secrets Manager (ou equivalente) e referenciados nas task definitions.

ecosif-compliance e ecosif-automations serão validados no documento de entrega posterior.

Fim do documento preliminar.

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 Preliminar de Implantação em Produção