📚 Guia de Desenvolvimento - ECOSIF

Este guia completo explica como configurar e trabalhar com o projeto ECOSIF em ambiente de desenvolvimento local.

📋 Índice

1. Como fazer checkout do projeto (incluindo submódulos)
2. Como criar branches para desenvolvimento
3. Como fazer commits (incluindo melhores práticas)
4. Como atualizar submódulos para o commit das modificações
5. Como configurar variáveis de ambiente para execução local

1. Como fazer checkout do projeto (incluindo submódulos)

1.1. Clonar o repositório principal

# Clonar o repositório principal
git clone git@github.com:disoft-gh/ds-ecosif-ia-services.git
cd ds-ecosif-ia-services

1.2. Inicializar e atualizar submódulos

# Inicializar e clonar todos os submódulos
git submodule update --init --recursive

# OU fazer tudo de uma vez no clone inicial
git clone --recurse-submodules git@github.com:disoft-gh/ds-ecosif-ia-services.git
cd ds-ecosif-ia-services

1.3. Verificar status dos submódulos

# Verificar status de todos os submódulos
git submodule status

# Verificar em qual branch cada submódulo está
git submodule foreach 'echo "$name: $(git branch --show-current 2>/dev/null || echo \"detached\")"'

1.4. Mudar todos os submódulos para um branch específico

# Usar o script fornecido para mudar todos para develop
./scripts/checkout-branch.sh develop

# Ou fazer manualmente
git submodule foreach 'git checkout develop && git pull origin develop'

1.5. Atualizar submódulos para a versão mais recente

# Atualizar todos os submódulos para o commit mais recente do branch atual
git submodule update --remote

# Atualizar um submódulo específico
cd ecosif-auth
git pull origin develop
cd ..

2. Como criar branches para desenvolvimento

2.1. Estrutura de branches

O projeto segue uma estrutura de branches padrão:

• develop: Branch principal de desenvolvimento
• qas: Branch de homologação/QA
• production: Branch de produção
• feature/*: Branches de novas funcionalidades
• bugfix/*: Branches de correção de bugs
• hotfix/*: Branches de correção urgente

2.2. Criar branch de feature

# 1. Garantir que está no develop atualizado
git checkout develop
git pull origin develop

# 2. Criar novo branch de feature
git checkout -b feature/nome-da-funcionalidade

# 3. Se trabalhar com submódulos, criar branch também neles
cd ecosif-auth
git checkout -b feature/nome-da-funcionalidade
cd ..

2.3. Usar script para criar branch em todos os repositórios

# Criar branch feature/nova-funcionalidade baseado em develop em todos os repositórios
./scripts/create-branch.sh develop feature/nova-funcionalidade

2.4. Trabalhar com submódulos em branches diferentes

# Criar branch apenas no submódulo específico
cd ecosif-auth
git checkout -b feature/auth-melhorias
# ... fazer alterações ...
cd ..

# No repositório principal, o submódulo apontará para o commit específico
git add ecosif-auth
git commit -m "feat: atualiza ecosif-auth para nova feature"

3. Como fazer commits (incluindo melhores práticas)

3.1. Convenção de mensagens de commit

Seguimos o padrão Conventional Commits:

<tipo>(<escopo>): <descrição curta>

[corpo opcional]

[rodapé opcional]

Tipos de commit:

• feat: Nova funcionalidade
• fix: Correção de bug
• docs: Documentação
• style: Formatação (não afeta código)
• refactor: Refatoração de código
• perf: Melhoria de performance
• test: Adição ou correção de testes
• chore: Tarefas de manutenção (build, dependências, etc.)
• ci: Mudanças em CI/CD

Exemplos:

# Nova funcionalidade
git commit -m "feat(auth): adiciona autenticação OAuth2"

# Correção de bug
git commit -m "fix(moviments): corrige cálculo de saldo"

# Documentação
git commit -m "docs: atualiza guia de instalação"

# Refatoração
git commit -m "refactor(api): simplifica lógica de validação"

# Tarefa de manutenção
git commit -m "chore: atualiza versão para 0.7.01.202601280"

3.2. Boas práticas para commits

✅ FAZER:

1. Commits atômicos: Um commit = uma mudança lógica
2. Mensagens descritivas: Explique o "porquê", não apenas o "o quê"
3. Commits frequentes: Commite pequenas mudanças regularmente
4. Verificar antes de commitar: Use git status e git diff

# Verificar o que será commitado
git status
git diff

# Adicionar arquivos específicos
git add arquivo1.java arquivo2.java

# Commit com mensagem descritiva
git commit -m "feat(auth): implementa refresh token automático

- Adiciona lógica para renovar token antes de expirar
- Implementa retry automático em caso de token expirado
- Adiciona testes unitários para nova funcionalidade"

❌ NÃO FAZER:

1. Commits grandes demais: Evite "feat: implementa sistema completo"
2. Mensagens genéricas: Evite "fix: corrige bug" ou "update"
3. Commits de arquivos não relacionados: Separe mudanças lógicas
4. Commits com código comentado ou debug: Limpe antes de commitar

3.3. Workflow de commit com submódulos

Cenário 1: Alteração apenas em um submódulo

# 1. Entrar no submódulo
cd ecosif-auth

# 2. Fazer alterações e commit
git add .
git commit -m "feat(auth): adiciona validação de senha forte"

# 3. Push do submódulo
git push origin feature/nova-funcionalidade

# 4. Voltar ao repositório principal
cd ..

# 5. Atualizar referência do submódulo
git add ecosif-auth
git commit -m "chore: atualiza ecosif-auth para nova feature de validação"

# 6. Push do repositório principal
git push origin feature/nova-funcionalidade

Cenário 2: Alteração em múltiplos submódulos

# 1. Fazer commits em cada submódulo
cd ecosif-auth
git add .
git commit -m "feat(auth): adiciona endpoint de refresh token"
git push origin develop
cd ..

cd ecosif-masterdata
git add .
git commit -m "feat(masterdata): adiciona endpoint de empresas"
git push origin develop
cd ..

# 2. Atualizar referências no repositório principal
git add ecosif-auth ecosif-masterdata
git commit -m "feat: integra novos endpoints de auth e masterdata"
git push origin develop

3.4. Revisar histórico de commits

# Ver histórico com mensagens
git log --oneline

# Ver histórico detalhado
git log

# Ver histórico de um arquivo específico
git log -- arquivo.java

# Ver diferenças entre branches
git log develop..feature/nova-funcionalidade

4. Como atualizar submódulos para o commit das modificações

4.1. Atualizar referência do submódulo após commit

Quando você faz commit em um submódulo, o repositório principal precisa ser atualizado para apontar para o novo commit:

# 1. Fazer commit no submódulo
cd ecosif-auth
git add .
git commit -m "feat: nova funcionalidade"
git push origin develop
cd ..

# 2. Atualizar referência no repositório principal
git add ecosif-auth
git commit -m "chore: atualiza ecosif-auth para novo commit"
git push origin develop

4.2. Atualizar todos os submódulos para o mesmo branch

# Usar script para atualizar todos os submódulos
./scripts/checkout-branch.sh develop

# Ou manualmente
git submodule foreach 'git checkout develop && git pull origin develop'
git add .
git commit -m "chore: atualiza todos os submódulos para develop"

4.3. Sincronizar submódulos com script

# Sincronizar todos os submódulos com o branch especificado
./scripts/sync-submodules.sh develop

4.4. Verificar status dos submódulos

# Ver quais submódulos têm alterações
git submodule status

# Ver commits à frente/atrás
git submodule foreach 'git fetch origin && git log --oneline HEAD..origin/develop'

4.5. Resolver submódulo em estado "detached HEAD"

Se um submódulo estiver em estado "detached HEAD":

# 1. Entrar no submódulo
cd ecosif-auth

# 2. Verificar em qual commit está
git log --oneline -1

# 3. Criar branch a partir do commit atual ou mudar para branch existente
git checkout -b temp-branch
# OU
git checkout develop

# 4. Voltar ao repositório principal e atualizar
cd ..
git add ecosif-auth
git commit -m "chore: corrige estado do submódulo ecosif-auth"

5. Como configurar variáveis de ambiente para execução local

5.1. Pré-requisitos

Antes de configurar as variáveis de ambiente, certifique-se de ter instalado:

• Java 17+: Download
• Maven 3.6+: Download
• PostgreSQL 13+: Download
• Node.js 18+ (para ecosif-angular): Download
• Python 3.11+ (para ecosif-compliance e ecosif-automations): Download

5.2. Configuração do Banco de Dados

Criar banco de dados PostgreSQL

# Conectar ao PostgreSQL
psql -U postgres

# Criar banco de dados
CREATE DATABASE ecosif;

# Criar usuário (opcional, mas recomendado)
CREATE USER ecosif_user WITH PASSWORD 'sua_senha_segura';
GRANT ALL PRIVILEGES ON DATABASE ecosif TO ecosif_user;

# Sair
\q

5.3. Variáveis de Ambiente Comuns

Crie um arquivo .env na raiz de cada serviço ou configure as variáveis no seu shell.

Variáveis de Banco de Dados (compartilhadas)

# Database
export POSTGRES_HOST=localhost
export POSTGRES_PORT=5432
export POSTGRES_DB=ecosif
export POSTGRES_USER=postgres
export POSTGRES_PASSWORD=sua_senha

Variáveis de Autenticação JWT (DEVEM ser idênticas em TODOS os serviços)

# JWT - IMPORTANTE: Use a mesma chave em todos os serviços
export AUTH_TOKEN_SECRET=sua_chave_secreta_muito_longa_e_segura_minimo_64_caracteres_para_producao
export TOKEN_EXPIRATION=1800000  # 30 minutos em milissegundos

Variáveis de CORS

# CORS - Permitir requisições do frontend Angular
export ECOSIF_CORS=http://localhost:4200

5.4. Configuração por Serviço

5.4.1. ecosif-auth

Porta padrão: 8081

Crie arquivo .env em ecosif-auth/.env:

# Database
POSTGRES_HOST=localhost
POSTGRES_PORT=5432
POSTGRES_DB=ecosif
POSTGRES_USER=postgres
POSTGRES_PASSWORD=sua_senha

# Server
ECOSIF_AUTH_PORT=8081
ECOSIF_AUTH_CONTEXT_PATH=/ecosif-auth

# JWT
AUTH_TOKEN_SECRET=sua_chave_secreta_muito_longa_e_segura_minimo_64_caracteres
TOKEN_EXPIRATION=1800000

# CORS
ECOSIF_CORS=http://localhost:4200

# Logging
ECOSIF_LOGSHOW=true
ECOSIF_LOGMODE_ROOT=INFO
ECOSIF_LOGMODE_SPRING=INFO

Executar:

cd ecosif-auth
mvn clean install -DskipTests
mvn spring-boot:run

5.4.2. ecosif-masterdata

Porta padrão: 8082

Crie arquivo .env em ecosif-masterdata/.env:

# Database
POSTGRES_HOST=localhost
POSTGRES_PORT=5432
POSTGRES_DB=ecosif
POSTGRES_USER=postgres
POSTGRES_PASSWORD=sua_senha

# Server
ECOSIF_MASTERDATA_PORT=8082
ECOSIF_MASTERDATA_CONTEXT_PATH=/ecosif-masterdata

# JWT (DEVE ser a mesma do ecosif-auth)
AUTH_TOKEN_SECRET=sua_chave_secreta_muito_longa_e_segura_minimo_64_caracteres
TOKEN_EXPIRATION=1800000

# CORS
ECOSIF_CORS=http://localhost:4200

# Hibernate
HIBERNATE_DDL_AUTO=update
ECOSIF_FLYWAY_ENABLED=true

Executar:

cd ecosif-masterdata
# Primeiro, instalar ecosif-database localmente
cd ../ecosif-database
mvn clean install -DskipTests
cp target/ecosif-database-*.jar ../ecosif-masterdata/libs/
cd ../ecosif-masterdata
mvn clean install -DskipTests
mvn spring-boot:run

5.4.3. ecosif-moviments

Porta padrão: 8083

Crie arquivo .env em ecosif-moviments/.env:

# Database
POSTGRES_HOST=localhost
POSTGRES_PORT=5432
POSTGRES_DB=ecosif
POSTGRES_USER=postgres
POSTGRES_PASSWORD=sua_senha

# Server
ECOSIF_MOVIMENTS_PORT=8083
ECOSIF_MOVIMENTS_CONTEXT_PATH=/ecosif-moviments

# JWT
AUTH_TOKEN_SECRET=sua_chave_secreta_muito_longa_e_segura_minimo_64_caracteres
TOKEN_EXPIRATION=1800000

# CORS
ECOSIF_CORS=http://localhost:4200

# Hibernate
HIBERNATE_DDL_AUTO=update
ECOSIF_FLYWAY_ENABLED=true

Executar:

cd ecosif-moviments
# Instalar ecosif-database se ainda não tiver
cd ../ecosif-database
mvn clean install -DskipTests
cp target/ecosif-database-*.jar ../ecosif-moviments/libs/
cd ../ecosif-moviments
mvn clean install -DskipTests
mvn spring-boot:run

5.4.4. ecosif-querys

Porta padrão: 8084

Crie arquivo .env em ecosif-querys/.env:

# Database
POSTGRES_HOST=localhost
POSTGRES_PORT=5432
POSTGRES_DB=ecosif
POSTGRES_USER=postgres
POSTGRES_PASSWORD=sua_senha

# Server
ECOSIF_QUERYS_PORT=8084
ECOSIF_QUERYS_CONTEXT_PATH=/ecosif-querys

# JWT
AUTH_TOKEN_SECRET=sua_chave_secreta_muito_longa_e_segura_minimo_64_caracteres
TOKEN_EXPIRATION=1800000

# CORS
ECOSIF_CORS=http://localhost:4200

Executar:

cd ecosif-querys
# Instalar ecosif-database se ainda não tiver
cd ../ecosif-database
mvn clean install -DskipTests
cp target/ecosif-database-*.jar ../ecosif-querys/libs/
cd ../ecosif-querys
mvn clean install -DskipTests
mvn spring-boot:run

5.4.5. ecosif-reports

Porta padrão: 8085

Crie arquivo .env em ecosif-reports/.env:

# Database
POSTGRES_HOST=localhost
POSTGRES_PORT=5432
POSTGRES_DB=ecosif
POSTGRES_USER=postgres
POSTGRES_PASSWORD=sua_senha

# Server
ECOSIF_REPORTS_PORT=8085
ECOSIF_REPORTS_CONTEXT_PATH=/ecosif-reports

# JWT
AUTH_TOKEN_SECRET=sua_chave_secreta_muito_longa_e_segura_minimo_64_caracteres
TOKEN_EXPIRATION=1800000

# CORS
ECOSIF_CORS=http://localhost:4200

Executar:

cd ecosif-reports
# Instalar ecosif-database se ainda não tiver
cd ../ecosif-database
mvn clean install -DskipTests
cp target/ecosif-database-*.jar ../ecosif-reports/libs/
cd ../ecosif-reports
mvn clean install -DskipTests
mvn spring-boot:run

5.4.6. ecosif-compliance (Python)

Porta padrão: 8021

Crie arquivo .env em ecosif-compliance/.env:

# Database
export ECOSIF_DB_SERVER=localhost
export ECOSIF_DB_PORT=5432
export ECOSIF_DB_LOGIN=ecosif
export ECOSIF_DB_USER=postgres
export ECOSIF_DB_PASSWORD=sua_senha

# Server
export ECOSIF_COMPLIANCE_PORT=8021

# Timezone
export TZ=America/Sao_Paulo

Executar:

cd ecosif-compliance

# Criar ambiente virtual (recomendado)
python3 -m venv venv
source venv/bin/activate  # Linux/Mac
# OU
venv\Scripts\activate  # Windows

# Instalar dependências
pip install -r requirements.txt

# Executar
gunicorn starter:app --bind 0.0.0.0:8021 --reload

5.4.7. ecosif-automations (Python)

Porta padrão: 8086

Crie arquivo .env em ecosif-automations/.env:

# Database
export POSTGRES_HOST=localhost
export POSTGRES_PORT=5432
export POSTGRES_DB=ecosif
export POSTGRES_USER=postgres
export POSTGRES_PASSWORD=sua_senha

# Server
export ECOSIF_AUTOMATIONS_PORT=8086

# AWS (opcional, para desenvolvimento pode deixar vazio)
export AWS_ACCESS_KEY_ID=
export AWS_SECRET_ACCESS_KEY=
export AWS_DEFAULT_REGION=us-east-1

Executar:

cd ecosif-automations

# Criar ambiente virtual
python3 -m venv venv
source venv/bin/activate  # Linux/Mac

# Instalar dependências
pip install -r requirements.txt

# Executar
python src/main.py
# OU
flask run --port 8086

5.4.8. ecosif-angular (Frontend)

Porta padrão: 4200

Crie arquivo .env em ecosif-angular/.env:

# API URLs
ECOSIF_ANGULAR_API_AUTH_URL=http://localhost:8081/ecosif-auth
ECOSIF_ANGULAR_API_MASTERDATA_URL=http://localhost:8082/ecosif-masterdata
ECOSIF_ANGULAR_API_MOVIMENTS_URL=http://localhost:8083/ecosif-moviments
ECOSIF_ANGULAR_API_QUERYS_URL=http://localhost:8084/ecosif-querys
ECOSIF_ANGULAR_API_REPORTS_URL=http://localhost:8085/ecosif-reports
ECOSIF_ANGULAR_API_COMPLIANCE_URL=http://localhost:8021/ecosif-compliance

# Configurações
ECOSIF_ANGULAR_PRODUCTION=false
ECOSIF_ANGULAR_DEBUG=true
# Controla visibilidade do menu "Ferramentas Administrativas" (Logs Docker, etc.)
# true = esconde o menu (padrão em produção)
# false = mostra o menu (use em desenvolvimento e QAS)
ECOSIF_ANGULAR_HIDE_ADMIN_MENU=false

Executar:

cd ecosif-angular

# Instalar dependências
npm install

# Executar em modo desenvolvimento
npm start
# OU
ng serve

# Acessar em: http://localhost:4200

Nota sobre ECOSIF_ANGULAR_HIDE_ADMIN_MENU:

Esta variável controla a visibilidade do menu "Ferramentas Administrativas" no frontend Angular, que contém funcionalidades como: - Logs Docker: Visualização de logs dos containers Docker - Criando Lançamentos: Ferramenta administrativa

Comportamento: - ECOSIF_ANGULAR_HIDE_ADMIN_MENU=false (desenvolvimento/QAS): O menu fica visível para facilitar debugging e administração - ECOSIF_ANGULAR_HIDE_ADMIN_MENU=true (produção): O menu fica oculto por segurança

Importante: Esta variável é independente de ECOSIF_ANGULAR_PRODUCTION. Você pode usar ECOSIF_ANGULAR_PRODUCTION=true (para carregar configurações do config.json) e ainda manter ECOSIF_ANGULAR_HIDE_ADMIN_MENU=false para mostrar o menu em ambientes de teste (QAS).

5.5. Script para carregar variáveis de ambiente

Crie um script load-env.sh na raiz do projeto:

#!/bin/bash
# load-env.sh - Carrega variáveis de ambiente para desenvolvimento local

# Variáveis comuns
export POSTGRES_HOST=localhost
export POSTGRES_PORT=5432
export POSTGRES_DB=ecosif
export POSTGRES_USER=postgres
export POSTGRES_PASSWORD=sua_senha

# JWT (DEVE ser a mesma em todos os serviços)
export AUTH_TOKEN_SECRET=sua_chave_secreta_muito_longa_e_segura_minimo_64_caracteres
export TOKEN_EXPIRATION=1800000

# CORS
export ECOSIF_CORS=http://localhost:4200

# Portas dos serviços
export ECOSIF_AUTH_PORT=8081
export ECOSIF_MASTERDATA_PORT=8082
export ECOSIF_MOVIMENTS_PORT=8083
export ECOSIF_QUERYS_PORT=8084
export ECOSIF_REPORTS_PORT=8085
export ECOSIF_COMPLIANCE_PORT=8021
export ECOSIF_AUTOMATIONS_PORT=8086

# Hibernate
export HIBERNATE_DDL_AUTO=update
export ECOSIF_FLYWAY_ENABLED=true

# Logging
export ECOSIF_LOGSHOW=true
export ECOSIF_LOGMODE_ROOT=INFO

echo "✅ Variáveis de ambiente carregadas!"

Usar:

source load-env.sh

5.6. Ordem de inicialização dos serviços

Para desenvolvimento local, inicie os serviços nesta ordem:

1. PostgreSQL (banco de dados)
2. ecosif-database (compilar e instalar localmente)
3. ecosif-auth (serviço de autenticação)
4. ecosif-masterdata (dados mestres)
5. ecosif-moviments (movimentações)
6. ecosif-querys (consultas)
7. ecosif-reports (relatórios)
8. ecosif-compliance (compliance)
9. ecosif-automations (automações)
10. ecosif-angular (frontend)

5.7. Verificar se os serviços estão rodando

# Verificar health check de cada serviço
curl http://localhost:8081/ecosif-auth/actuator/health
curl http://localhost:8082/ecosif-masterdata/actuator/health
curl http://localhost:8083/ecosif-moviments/actuator/health
curl http://localhost:8084/ecosif-querys/actuator/health
curl http://localhost:8085/ecosif-reports/actuator/health
curl http://localhost:8021/ecosif-compliance/health
curl http://localhost:4200  # Frontend Angular

📝 Resumo de Comandos Úteis

Git e Submódulos

# Clonar com submódulos
git clone --recurse-submodules <url>

# Atualizar submódulos
git submodule update --init --recursive

# Mudar branch em todos os repositórios
./scripts/checkout-branch.sh develop

# Criar branch em todos os repositórios
./scripts/create-branch.sh develop feature/nova-funcionalidade

# Fazer merge em todos os repositórios
./scripts/merge-branch.sh develop qas

# Verificar status de push
./scripts/check-submodules-push.sh

Desenvolvimento Local

# Compilar ecosif-database (necessário para outros serviços Java)
cd ecosif-database
mvn clean install -DskipTests

# Executar serviço Java
cd ecosif-auth
mvn spring-boot:run

# Executar serviço Python
cd ecosif-compliance
source venv/bin/activate
gunicorn starter:app --bind 0.0.0.0:8021 --reload

# Executar frontend Angular
cd ecosif-angular
npm start

🔗 Referências

• Guia de Gerenciamento de Branches e Submódulos
• Resumo de Gerenciamento de Submódulos
• Conventional Commits
• Git Submodules Documentation

Última atualização: 2026-01-28