使用说明

agentic-erp-platform-mvp

MVP de referência que demonstra como modernizar um ERP legado usando IA agêntica, sem tocar no núcleo do sistema, aplicando padrões arquiteturais modernos e práticas enterprise.

Visão geral

Este repositório apresenta um MVP (Minimum Viable Product) que demonstra, de forma prática e pragmática, como empresas podem modernizar a forma como utilizam um ERP legado, sem reescrevê-lo ou substituí-lo.

A proposta central é simples:

Manter o ERP estável, protegido e intocado, enquanto uma camada externa de IA agêntica assume decisões, automações e orquestração de processos.

O projeto foi pensado como material de referência para líderes técnicos e de negócio, arquitetos, tech leads e gestores que enfrentam os desafios clássicos de sistemas legados críticos.

O problema que este MVP endereça

Na maioria das organizações, o ERP legado:

É crítico demais para ser alterado;
Carrega regras complexas e pouco documentadas;
Depende de processos manuais, planilhas e decisões humanas;
Bloqueia iniciativas de inovação e automação.

Este MVP demonstra como desacoplar inteligência, decisão e automação do núcleo do ERP, reduzindo risco e criando espaço para evolução contínua.

A proposta arquitetural

O projeto adota uma arquitetura baseada em microserviços, onde cada responsabilidade é claramente isolada:

IA Agêntica: interpreta intenção, planeja ações e orquestra fluxos;
RAG (Retrieval-Augmented Generation): fornece contexto e conhecimento confiável para decisões;
MCP (Model Context Protocol): define e controla as capacidades expostas ao modelo de IA;
ACL (Anti-Corruption Layer): protege o ERP e traduz conceitos de negócio;
ERP Dummy: simula um sistema legado real, sem dependências externas.

Tudo isso é construído sobre Clean Architecture, garantindo baixo acoplamento e alta testabilidade.

Técnicas e conceitos utilizados (e por que)

Agentic AI (IA Agêntica)

Modelo no qual a IA não apenas responde perguntas, mas decide, planeja e executa ações com base em objetivos e contexto. No cenário de ERP, isso permite automatizar decisões operacionais que antes dependiam de intervenção humana.

MCP (Model Context Protocol)

Define explicitamente o que a IA pode ou não fazer. Funciona como uma fronteira de segurança entre o modelo de linguagem e os sistemas corporativos, reduzindo riscos operacionais.

RAG (Retrieval-Augmented Generation)

Permite que a IA tome decisões com base em documentação real, políticas e regras do negócio, evitando respostas inventadas ou inconsistentes.

Strangler Pattern

O ERP não é substituído de uma vez. Funcionalidades e decisões são gradualmente deslocadas para a camada agêntica, reduzindo risco e permitindo evolução incremental.

Clean Architecture

Separa domínio, aplicação e infraestrutura. Garante que regras de negócio não dependam de frameworks, LLMs ou detalhes técnicos.

DDD (Domain-Driven Design)

O domínio é tratado como cidadão de primeira classe. Conceitos do negócio são modelados explicitamente, evitando que o ERP dite a linguagem do sistema.

Microservices

Cada capacidade (agente, MCP, RAG, ACL) é isolada. Isso permite escalar, evoluir ou substituir partes do sistema sem impacto sistêmico.

SDD (Spec Driven Development)

O comportamento do sistema nasce de specs (especificações legíveis por humanos). As specs guiam código, prompts, testes e contratos, alinhando times técnicos e de negócio.

O que este MVP não é

Não é um produto pronto;
Não é um framework fechado;
Não é uma tentativa de “colocar IA dentro do ERP”.

Este repositório é uma demonstração arquitetural, pensada para aprendizado, discussão e adaptação ao contexto real de cada empresa.

Para quem este projeto é indicado

Líderes técnicos avaliando modernização de legados;
Gestores de negócio buscando automação com baixo risco;
Arquitetos definindo estratégias de IA corporativa;
Times explorando Agentic AI além de chatbots.

Como usar este repositório

Como referência arquitetural;
Como base para POCs e MVPs internos;
Como material de discussão entre TI e negócio;
Como exemplo de integração responsável entre IA e sistemas críticos.

Próximos passos sugeridos

Adaptar o ERP Dummy para seu ERP real;
Evoluir specs com regras específicas do negócio;
Integrar mensageria e observabilidade;
Adicionar governança e controles de segurança.

Licença

Uso livre para fins educacionais e experimentais.

Adapte, evolua e questione.

🧑‍💻 Para Usuários

Como Instalar

A forma mais simples é usar as imagens de container publicadas nas Releases:

Baixe os tarballs dos serviços desejados (*-service.tar.gz);
Baixe também o docker-compose.release.yml da mesma Release;
Carregue cada tarball com docker load e retague a imagem para latest;
Suba a stack com docker-compose -f docker-compose.release.yml up -d.

# Download: pegue os tarballs (*-service.tar.gz) e o docker-compose.release.yml da Release
for img in agent-service mcp-service erp-acl-service rag-service; do
  gunzip -c "$img.tar.gz" | docker load
  docker tag "$img:<versão>" "$img:latest"
done
docker-compose -f docker-compose.release.yml up -d

Também é possível construir tudo do código-fonte:

git clone https://github.com/amaurycarvalho/agentic-erp-platform-mvp.git
cd agentic-erp-platform-mvp
make install
make build-images
docker-compose up -d --build

Como Usar

Após subir a stack, a API de cada serviço fica disponível:

agent-service: http://localhost:8080
mcp-service: http://localhost:8082
rag-service: http://localhost:8083
erp-acl-service: http://localhost:8084

Exemplo de chamada de busca de contexto no RAG:

curl -X POST http://localhost:8083/rag/search \
  -H "Content-Type: application/json" \
  -d '{"operation_context":"order.create","correlation_id":"USR-001"}'

Para encerrar os serviços:

docker-compose down

👨‍🔧 Para Desenvolvedores

Como Instalar

Baixando o codigo fonte

git clone https://github.com/amaurycarvalho/agentic-erp-platform-mvp.git

Como Compilar

make install
make build

Requisitos:

.NET SDK 8.0
Docker (para make build-images e docker-compose)

Testes unitários

make test

Executa os testes unitários e coleta cobertura por serviço (exclui a integração MCP que exige stack ativa). Para validar a cadeia agent -> mcp -> acl ponta a ponta, suba a stack e rode a integração:

docker-compose up -d --build
MCP_BASE_URL=http://localhost:8082 make test-integration

Quality Gate

O quality gate executa lint + testes (com cobertura) + verificação de cobertura + métricas + segurança:

make quality-gate

Verificações individuais:

make lint               # formato/análise (dotnet format --verify-no-changes)
make test               # testes + cobertura
make coverage-check     # cobertura contra COVERAGE_THRESHOLD (default 80)
make metrics            # linhas de código (LOC) por serviço
make security           # pacotes vulnerables/deprecated/outdated + Semgrep SAST

Análise estática, complexidade, code smells, dívida técnica e rating de manutenibilidade são coordenados pelo SonarCloud no CI, com um projeto por serviço (análise per-service), Leak Period sobre código novo e decoração de Pull Requests. A cobertura é encaminhada via TestResults/**/coverage.cobertura.xml.

Jobs no CI: o job sonarcloud (SonarCloud) e o job integration-test (integração MCP ponta a ponta) rodam apenas em pull requests. O job quality-gate (lint + test + coverage + metrics + security) roda em push para main e em pull requests.

Análise SonarCloud no pipeline CI

O SonarCloud requer a configuração dos secrets abaixo no Github:

SONAR_PROJECT_KEY_PREFIX
SONAR_ORG
SONAR_TOKEN

A chave do projeto no SonarCloud deverá seguir o padrão:

SONAR_PROJECT_KEY_PREFIX-service_name

Exemplo:

agentic-erp-agent-service
agentic-erp-mcp-service
agentic-erp-acl-service
agentic-erp-rag-service

Análise SonarQube local (self-hosted)

Para analisar os serviços localmente contra um servidor SonarQube self-hosted em execução (ex.: http://localhost:9000), instale o scanner e rode a análise per-service:

make sonar-install
SONAR_TOKEN=<seu-token> make sonar-check

O sonar-check executa begin → build + test (com cobertura) → end para cada um dos quatro serviços, um projeto SonarQube por serviço (chave = SONAR_PROJECT_KEY_PREFIX + nome do serviço, ex.: agentic-erp-agent-service).

Subindo um servidor SonarQube local (Docker Compose)

O repositório inclui uma stack local reproduzível (SonarQube Community + PostgreSQL, com volumes persistentes) em sonarqube/docker-compose.yml, baseada na referência oficial da SonarSource e com o mesmo hardening (read_only, tmpfs, volumes nomeados). Fluxo completo:

make sonar-up        # sobe a stack e aguarda o SonarQube ficar pronto
# 1) Acesse http://localhost:9000 e faça login com admin / admin
# 2) Troque a senha no primeiro login (obrigatório)
# 3) My Account -> Security -> Tokens -> Generate (token de um usuário admin)
SONAR_TOKEN=<seu-token> make sonar-check   # analisa os 4 serviços
make sonar-down      # para a stack preservando os volumes

Com um token de um usuário admin, os quatro projetos per-service (as chaves exibidas pelo make sonar-up, uma por serviço) são criados automaticamente na primeira análise.

Requisitos de host:

Linux: o Elasticsearch embutido exige vm.max_map_count maior; aplique sudo sysctl -w vm.max_map_count=262144 (persista em /etc/sysctl.conf).
Docker Desktop (Windows/Mac): reserve pelo menos 2–4 GB de memória para o engine (o compose define SONAR_ES_BOOTSTRAP_CHECKS_DISABLE=true para evitar a falha do max_map_count, que não é diretamente configurável nesses hosts).
Reset completo (apaga dados da stack): docker compose -f sonarqube/docker-compose.yml down -v.
As credenciais admin/admin são padrão de desenvolvimento local — não use em produção.

Variáveis de ambiente:

SONAR_HOST_URL — URL do servidor SonarQube (default http://localhost:9000);
SONAR_TOKEN — token de autenticação (obrigatório);
SONAR_PROJECT_KEY_PREFIX — prefixo das chaves de projeto (default agentic-erp-).

O estado local do scanner (/.sonarqube) é ignorado pelo git. A análise local usa os mesmos relatórios de cobertura cobertura (TestResults/**/coverage.cobertura.xml) do make test, com exclusão de fontes de teste.

Mutation testing (opcional)

O teste de mutação com Stryker.NET é manual e não entra no gate do CI:

make install-quality-tools
make mutation

Os reportes de mutação são gerados com threshold high/low/break (80/70/60).

Leve os reports disponíveis em services/**/tests/**/StrykerOutput/**/reports/mutation-report.json e services/**/tests/**/StrykerOutput/**/reports/mutation-report.html para análise do seu agente de codificação e solicite a criação de testes para matar os mutantes sobreviventes. Depois, rode o mutation testing novamente.

Testes de integração

Ative os serviços com Docker Compose, configure a variável de ambiente com a url base e depois rode o teste.

sudo docker-compose up -d --build --timeout 120
MCP_BASE_URL=http://localhost:8082 make test-integration
sudo docker-compose down

Como Usar

Docker Compose

Suba os serviços (constrói as imagens a partir dos Dockerfile):

sudo docker-compose up -d --build

Acesse via:

agent-service: http://localhost:8080
mcp-service: http://localhost:8082
rag-service: http://localhost:8083
erp-acl-service: http://localhost:8084 (gRPC em 8081)

Derrube os serviços:

sudo docker-compose down

Usando Imagens Pré-compiladas

Para usar uma imagem publicada em uma Release, baixe o tarball do serviço, carregue no Docker e suba com o docker-compose (ou outro orquestrador):

# Download: pegue agent-service.tar.gz da Release
gunzip -c agent-service.tar.gz | docker load
docker tag agent-service:<versão> agent-service:latest
# Volte a referenciar a imagem no docker-compose.yml (ex.: image: agent-service:<versão>)
docker-compose up -d

O mesmo procedimento se aplica a mcp-service.tar.gz, erp-acl-service.tar.gz e rag-service.tar.gz.

智能体ERP平台

使用说明

agentic-erp-platform-mvp

Visão geral

O problema que este MVP endereça

A proposta arquitetural

Técnicas e conceitos utilizados (e por que)

Agentic AI (IA Agêntica)

MCP (Model Context Protocol)

RAG (Retrieval-Augmented Generation)

Strangler Pattern

Clean Architecture

DDD (Domain-Driven Design)

Microservices

SDD (Spec Driven Development)

O que este MVP não é

Para quem este projeto é indicado

Como usar este repositório

Próximos passos sugeridos

Licença

🧑‍💻 Para Usuários

Como Instalar

Como Usar

👨‍🔧 Para Desenvolvedores

Como Instalar

Baixando o codigo fonte

Como Compilar

Testes unitários

Quality Gate

Análise SonarCloud no pipeline CI

Análise SonarQube local (self-hosted)

Subindo um servidor SonarQube local (Docker Compose)

Mutation testing (opcional)

Testes de integração

Como Usar

Docker Compose

Usando Imagens Pré-compiladas

Saiba Mais

使用说明

agentic-erp-platform-mvp

Visão geral

O problema que este MVP endereça

A proposta arquitetural

Técnicas e conceitos utilizados (e por que)

Agentic AI (IA Agêntica)

MCP (Model Context Protocol)

RAG (Retrieval-Augmented Generation)

Strangler Pattern

Clean Architecture

DDD (Domain-Driven Design)

Microservices

SDD (Spec Driven Development)

O que este MVP não é

Para quem este projeto é indicado

Como usar este repositório

Próximos passos sugeridos

Licença

🧑‍💻 Para Usuários

Como Instalar

Como Usar

👨‍🔧 Para Desenvolvedores

Como Instalar

Baixando o codigo fonte

Como Compilar

Testes unitários

Quality Gate

Análise SonarCloud no pipeline CI

Análise SonarQube local (self-hosted)

Subindo um servidor SonarQube local (Docker Compose)

Mutation testing (opcional)

Testes de integração

Como Usar

Docker Compose

Usando Imagens Pré-compiladas

Saiba Mais

相关 MCP

Unity MCP AI游戏开发工具

网页数据提取 MCP 服务

AI智能体运行平台

数据库MCP工具箱

Git MCP 服务器

Excalidraw 绘图画布服务