Capítulo 12 — Arquitetura de Microsserviços

12.1 Objetivo do Capítulo

Este capítulo apresenta a Arquitetura de Microsserviços da Plataforma de Relacionamento Digital com o Cidadão, detalhando como os domínios funcionais definidos nos capítulos anteriores são decompostos em serviços backend com responsabilidades claras, limites de domínio explícitos e capacidade de evolução independente.

Para cada serviço são descritos: responsabilidade central, responsabilidades funcionais, dados sob sua governança, APIs candidatas e eventos publicados. A decomposição segue os princípios de Domain-Driven Design e as decisões arquiteturais confirmadas: Java, Spring Boot, RabbitMQ, IAM próprio, GOV.BR, multi-tenant, Data Lake por tenant e IA com isolamento por tenant.

Este capítulo não define a quantidade mínima de processos físicos na implantação inicial. A separação física acompanha necessidades reais de autonomia, escala, criticidade e ciclo de mudança — não o número de domínios.

12.2 Princípio Central de Decomposição

Um serviço possui uma responsabilidade de negócio coerente, controla seus próprios dados e expõe contratos explícitos para colaboração com outros componentes.

A separação de serviços não é feita por tabela, entidade JPA, tela ou operação CRUD. A granularidade é definida por domínio de negócio. Dois domínios de baixa complexidade ou baixo volume podem iniciar agrupados em um serviço modular — desde que os limites lógicos estejam preservados no código — e ser separados quando houver justificativa mensurável.

Padrões que caracterizam granularidade inadequada e devem ser evitados:

CitizenCreateService
CitizenUpdateService   ← fragmentação por operação
CitizenAddressService

A decomposição correta:

CitizenService  ← responsável pelo agregado e pelo domínio de cadastro

12.3 Visão Geral dos Serviços

A plataforma é composta por 24 serviços de domínio, organizados em seis grupos:

┌─────────────────────────────────────────────────────────────────┐
│  ACESSO                                                          │
│  API Gateway                                                     │
├─────────────────────────────────────────────────────────────────┤
│  IDENTIDADE E CONTEXTO                                           │
│  Identity Service  │  Tenant Service                            │
├─────────────────────────────────────────────────────────────────┤
│  NÚCLEO DE SERVIÇOS                                              │
│  Citizen  │  Service Catalog  │  Forms  │  Request              │
│  Workflow  │  Task  │  CRM  │  Communication                    │
│  Document  │  Scheduling  │  Ombudsman                          │
├─────────────────────────────────────────────────────────────────┤
│  RELACIONAMENTO E ENGAJAMENTO                                    │
│  Satisfaction  │  Segmentation  │  Campaign                     │
├─────────────────────────────────────────────────────────────────┤
│  DADOS, IA E GOVERNANÇA                                          │
│  Analytics  │  Data Quality  │  Data Lake Ingestion             │
│  AI Gateway  │  AI Specialized Services                         │
├─────────────────────────────────────────────────────────────────┤
│  PLATAFORMA TRANSVERSAL                                          │
│  Integration  │  Configuration  │  Audit                        │
└─────────────────────────────────────────────────────────────────┘

Todo serviço de domínio: publica no RabbitMQ ao produzir eventos relevantes; possui banco operacional próprio; aplica Tenant Context obrigatório; emite logs estruturados, métricas e traces; expõe liveness e readiness separadamente.

12.4 Estratégia de Implantação por Ondas

Primeira Onda — Jornadas Fundamentais

Serviços que habilitam as jornadas centrais da plataforma:

identity-service
tenant-service
citizen-service
service-catalog-service
forms-service
request-service
document-service
communication-service
workflow-service
integration-service
audit-service
ai-gateway
ai-specialized-services (RAG, chat, busca semântica, builder)

Segunda Onda — Expansão de Capacidades

Serviços incorporados conforme maturidade das jornadas iniciais:

task-service
crm-service
scheduling-service
ombudsman-service
satisfaction-service
segmentation-service
campaign-service
analytics-service
data-quality-service
data-lake-ingestion
configuration-service

A classificação em ondas é arquitetural. O planejamento de execução é definido no âmbito da gestão da parceria.

12.5 Padrões Transversais

Todos os serviços observam os seguintes padrões antes de quaisquer especificidades de domínio.

12.5.1 Tenant Context

O Tenant Context é estabelecido a partir de elementos controlados (identidade autenticada, vínculo com tenant, domínio do canal) e propagado via mecanismo estrutural — interceptor Spring ou ThreadLocal gerenciado — sem depender de disciplina individual do desenvolvedor. O tenantId nunca é aceito diretamente de cabeçalho enviado pelo cliente como único fator de confiança.

12.5.2 Propriedade de Dados

Cada serviço é o único responsável por gravar no seu armazenamento. Outros serviços obtêm informações por API síncrona ou por consumo de eventos — nunca por acesso direto ao banco alheio.

12.5.3 Transactional Outbox

A publicação de eventos críticos utiliza o padrão Transactional Outbox: o evento é gravado na mesma transação que altera o estado de negócio e publicado no RabbitMQ por um publisher em background. Isso elimina a inconsistência entre transação confirmada e evento não publicado.

12.5.4 Idempotência

Consumidores de eventos críticos são idempotentes. O Inbox Pattern — registro do eventId antes de aplicar a mudança de negócio — é a técnica de referência para deduplicação em consumidores que precisam de garantia forte.

12.5.5 Versionamento de Contratos

APIs seguem versionamento por URI (/v1/, /v2/). Eventos incluem a versão no tipo (request.submitted.v1). Versões antigas são mantidas por período de depreciação definido antes da remoção.

12.5.6 Envelope de Evento

{
  "id": "uuid-v4",
  "type": "dominio.evento.v1",
  "version": "1",
  "occurredAt": "2026-07-15T10:30:00Z",
  "tenantId": "tenant-abc",
  "correlationId": "correlation-xyz",
  "causationId": "event-anterior",
  "producer": "nome-do-servico",
  "payload": {}
}

12.5.7 Resiliência

Toda chamada remota tem timeout. Retentativas usam exponential backoff com jitter, limitadas por retry budget, aplicadas apenas a erros transitórios e idempotentes. Circuit breakers isolam dependências degradadas. Bulkheads limitam propagação de saturação entre contextos.

12.5.8 Observabilidade

Logs JSON com tenantId, traceId, correlationId, service, event. Métricas RED por endpoint. Rastreamento distribuído por OpenTelemetry com propagação em HTTP e em mensagens RabbitMQ. Dados pessoais, tokens e secrets são vedados em logs e traces.

12.6 Identity Service

Responsabilidade: gestão de identidades, autenticação, credenciais, sessões, federação GOV.BR e histórico de segurança.

Responsabilidades funcionais: cadastrar usuário; autenticar por credencial local; bloquear e desbloquear; recuperar acesso; iniciar e processar retorno GOV.BR; vincular identidade federada à identidade interna por identificador estável; revogar sessão; emitir tokens de acesso; auditar eventos de autenticação.

Dados:

User / Credential / FederatedIdentity
AuthenticationSession / PasswordRecovery / SecurityEvent

APIs candidatas:

POST /auth/login
POST /auth/logout
POST /auth/refresh
POST /auth/recovery
POST /auth/recovery/confirm
GET  /auth/govbr
GET  /auth/govbr/callback
GET  /me
GET  /users/{id}
POST /users
PATCH /users/{id}
POST /users/{id}/block
POST /users/{id}/unblock

Eventos publicados:

identity.user.created.v1
identity.user.blocked.v1
identity.user.unblocked.v1
identity.federated-linked.v1
identity.authentication-succeeded.v1
identity.authentication-failed.v1

Regra crítica: o GOV.BR confirma identidade. A autorização é sempre responsabilidade da plataforma. Eventos de autenticação minimizam dados pessoais.

12.7 Tenant Service

Responsabilidade: ciclo de vida dos tenants e contexto organizacional necessário à segregação da plataforma.

Responsabilidades funcionais: criar, editar, ativar, suspender e desativar tenants; associar domínios, módulos e limites; manter configurações institucionais; validar tenant ativo; fornecer contexto para resolução de tenant.

Dados:

Tenant / TenantDomain / TenantModule
TenantLimit / TenantStatusHistory

APIs candidatas:

GET    /tenants
POST   /tenants
GET    /tenants/{id}
PATCH  /tenants/{id}
POST   /tenants/{id}/activate
POST   /tenants/{id}/suspend
POST   /tenants/{id}/deactivate
GET    /tenants/{id}/modules
PUT    /tenants/{id}/modules

Eventos publicados:

tenant.created.v1
tenant.activated.v1
tenant.suspended.v1
tenant.deactivated.v1
tenant.modules-changed.v1

Regra arquitetural: informações de tenant necessárias à resolução frequente são mantidas em cache com invalidação por evento — o Tenant Service não é consultado sincronamente em toda requisição para evitar se tornar ponto de contenção.

12.8 Citizen Service

Responsabilidade: cadastro unificado do cidadão e visão consolidada das interações autorizadas.

Responsabilidades funcionais: manter dados básicos, documentos identificadores, contatos, endereços, preferências e consentimentos; registrar origem de cada dado; detectar e tratar duplicidades; manter histórico de alterações; compor visão 360° por meio de API de composição — nunca por joins entre bancos de serviços distintos.

Dados:

Citizen / CitizenIdentifier / CitizenContact
CitizenAddress / CitizenPreference / CitizenConsent
CitizenRelationship / CitizenCompanyRepresentation
CitizenDataSource / CitizenChangeHistory

APIs candidatas:

GET   /citizens/{id}
POST  /citizens
PATCH /citizens/{id}
GET   /citizens/{id}/contacts
POST  /citizens/{id}/contacts
GET   /citizens/{id}/addresses
POST  /citizens/{id}/addresses
GET   /citizens/{id}/preferences
PUT   /citizens/{id}/preferences
GET   /citizens/{id}/360

Eventos publicados:

citizen.created.v1
citizen.updated.v1
citizen.contact-changed.v1
citizen.address-changed.v1
citizen.preferences-changed.v1
citizen.consent-changed.v1

12.9 Service Catalog Service

Responsabilidade: ciclo de vida dos serviços públicos digitais disponibilizados pelos tenants.

Responsabilidades funcionais: criar, editar, versionar, revisar, aprovar, publicar, suspender e descontinuar serviços; definir requisitos, documentos exigidos, canais, prazo, nível de autenticação, formulário e processo associados; disponibilizar catálogo público com cache por tenant.

Dados:

PublicService / ServiceVersion / ServiceCategory
ServiceRequirement / ServiceChannel
ServiceDocumentRequirement / ServicePublication

APIs candidatas:

GET  /services
GET  /services/{id}
POST /services
PATCH /services/{id}
POST /services/{id}/versions
POST /services/{id}/publish
POST /services/{id}/suspend
GET  /service-categories

Eventos publicados:

catalog.service.created.v1
catalog.service.updated.v1
catalog.service.published.v1
catalog.service.suspended.v1
catalog.service.discontinued.v1

Regra: publicação de nova versão invalida caches e atualiza índices de busca via evento.

12.10 Forms Service

Responsabilidade: definição, versionamento e validação dos formulários dinâmicos.

Responsabilidades funcionais: criar formulários com seções, campos, validações, condicionais e máscaras; versionar e publicar; validar definição; desativar versões antigas.

Dados:

Form / FormVersion / FormSection
FormField / FormValidation / FormCondition / FormPublication

APIs candidatas:

GET  /forms
POST /forms
GET  /forms/{id}
POST /forms/{id}/versions
GET  /forms/{id}/versions/{version}
POST /forms/{id}/versions/{version}/publish
POST /forms/validate-definition

Eventos publicados:

form.version-published.v1
form.version-deprecated.v1

Regra crítica: a solicitação registra formId e formVersion no momento da submissão. A publicação de uma versão posterior não altera retroativamente o significado dos dados submetidos em versões anteriores. A validação do backend usa a versão exata registrada.

12.11 Request Service

Responsabilidade: ciclo de vida das solicitações de serviços públicos e seus protocolos. É um dos serviços centrais da plataforma.

Responsabilidades funcionais: criar rascunho; associar cidadão, serviço e versão; registrar versão do formulário; receber dados; associar documentos; submeter; gerar protocolo único; controlar estados e transições; solicitar e receber complementação; cancelar quando permitido; manter histórico auditável.

Dados:

Request / RequestData / RequestProtocol
RequestStatus / RequestStatusHistory
RequestComplement / RequestDocumentReference
RequestExternalReference

APIs candidatas:

POST /requests
GET  /requests/{id}
PATCH /requests/{id}
POST /requests/{id}/submit
POST /requests/{id}/cancel
GET  /requests/{id}/history
POST /requests/{id}/complements
POST /requests/{id}/complements/{id}/submit
GET  /protocols/{protocolNumber}

Eventos publicados:

request.created.v1
request.submitted.v1
request.status-changed.v1
request.complement-requested.v1
request.complement-submitted.v1
request.cancelled.v1
request.completed.v1

Separação com Workflow: o Request Service é responsável pela solicitação; o Workflow Service é responsável pela execução do processo. A submissão publica request.submitted.v1; o Workflow consome e inicia a instância; o resultado retorna ao Request via evento de atualização de status. O Request não implementa motor de workflow internamente.

12.12 Workflow Service

Responsabilidade: definições executáveis de processo e instâncias em execução.

Responsabilidades funcionais: modelar e versionar processos; publicar definições; iniciar instâncias; avançar fluxo; executar transições e decisões; controlar timers; acionar integrações externas; criar tarefas humanas; suspender, retomar, cancelar e concluir instâncias; registrar trilha de execução.

Dados:

ProcessDefinition / ProcessVersion / ProcessInstance
ProcessVariable / ProcessTransition / ProcessExecutionHistory / Timer

APIs candidatas:

GET  /process-definitions
POST /process-definitions
POST /process-definitions/{id}/versions
POST /process-definitions/{id}/versions/{v}/publish
POST /process-instances
GET  /process-instances/{id}
POST /process-instances/{id}/suspend
POST /process-instances/{id}/resume
POST /process-instances/{id}/cancel

Eventos publicados:

workflow.instance-started.v1
workflow.step-entered.v1
workflow.step-completed.v1
workflow.instance-completed.v1
workflow.instance-failed.v1
workflow.instance-suspended.v1
workflow.instance-resumed.v1

Eventos consumidos: request.submitted.v1, task.completed.v1, eventos de integração externa.

12.13 Task Service

Responsabilidade: tarefas humanas e filas de trabalho. Separado do Workflow Service porque tarefas humanas têm ciclo de vida, consultas, distribuição e volumetria próprios.

Responsabilidades funcionais: criar, atribuir, distribuir e redistribuir tarefas; assumir, transferir e delegar; priorizar; registrar comentário; controlar prazo e SLA; escalar; concluir e devolver resultado ao processo.

Dados:

Task / TaskAssignment / TaskQueue
TaskComment / TaskPriority / TaskSla / TaskHistory

APIs candidatas:

GET  /tasks
GET  /tasks/{id}
POST /tasks/{id}/claim
POST /tasks/{id}/assign
POST /tasks/{id}/transfer
POST /tasks/{id}/complete
GET  /task-queues
GET  /task-queues/{id}/tasks

Eventos publicados:

task.created.v1
task.assigned.v1
task.claimed.v1
task.transferred.v1
task.sla-warning.v1
task.sla-breached.v1
task.completed.v1

12.14 CRM Service

Responsabilidade: contexto de atendimento e histórico operacional de interações com o cidadão.

Responsabilidades funcionais: abrir interação; registrar conversa; classificar por assunto; distribuir para fila e atendente; transferir; vincular cidadão, solicitação e protocolo; registrar notas; concluir; manter histórico de atendimento.

Dados:

Interaction / Conversation / ServiceSession
InteractionQueue / InteractionAssignment
InteractionNote / InteractionTag

APIs candidatas:

GET  /interactions
POST /interactions
GET  /conversations/{id}
POST /conversations/{id}/messages
POST /interactions/{id}/assign
POST /interactions/{id}/transfer
POST /interactions/{id}/close

Eventos publicados:

crm.interaction-created.v1
crm.interaction-assigned.v1
crm.interaction-transferred.v1
crm.interaction-closed.v1
crm.human-assistance-requested.v1

Separação com Communication Service: o CRM controla o contexto e o ciclo de vida do atendimento. O Communication Service controla a entrega técnica de mensagens pelos canais. Uma mensagem recebida via WhatsApp chega ao Communication Service, que publica evento; o CRM consome e associa ao atendimento ativo.

12.15 Communication Service

Responsabilidade: orquestração de comunicações e abstração dos canais de entrega.

Responsabilidades funcionais: receber solicitação de comunicação; resolver template com variáveis; carregar preferências e consentimentos; selecionar canal; enviar; registrar tentativa e status; processar callbacks de provedores; aplicar retry; encaminhar falha; manter caixa de mensagens interna do portal.

Dados:

Communication / CommunicationAttempt / CommunicationChannel
Template / TemplateVersion / DeliveryStatus
ProviderCallback / PortalMessage

Canais: portal, push, e-mail, SMS, WhatsApp ou equivalente.

APIs candidatas:

GET  /messages
GET  /messages/{id}
POST /messages/{id}/read
GET  /templates
POST /templates
POST /templates/{id}/versions
POST /communications
GET  /communications/{id}

Eventos publicados:

communication.requested.v1
communication.sent.v1
communication.delivered.v1
communication.read.v1
communication.failed.v1
communication.received.v1

12.16 Document Service

Responsabilidade: domínio documental da plataforma.

Responsabilidades funcionais: iniciar e coordenar upload; registrar metadados e hash de integridade; versionar sem sobrescrever; associar a solicitações e processos; classificar; controlar acesso por perfil e finalidade; solicitar processamento assíncrono (OCR, extração); gerar referência de acesso; integrar com GED externo quando aplicável.

Dados:

Document / DocumentVersion / DocumentMetadata
DocumentClassification / DocumentAssociation
DocumentAccessPolicy / DocumentProcessingStatus

O binário é armazenado em storage segregado (object storage ou GED), referenciado pelos metadados. O banco operacional do serviço armazena apenas metadados.

APIs candidatas:

POST /documents
GET  /documents/{id}
GET  /documents/{id}/download
POST /documents/{id}/versions
POST /documents/{id}/classify
DELETE /documents/{id}

Eventos publicados:

document.uploaded.v1
document.processed.v1
document.processing-failed.v1
document.classified.v1
document.associated.v1

12.17 Scheduling Service

Responsabilidade: agendamentos de atendimentos e serviços que exigem reserva de horário.

Responsabilidades funcionais: cadastrar agendas, unidades e recursos; definir calendário, capacidade e bloqueios; disponibilizar horários; reservar vaga com controle de concorrência; confirmar, remarcar e cancelar; acionar notificações.

Dados:

Agenda / AgendaUnit / AgendaResource
AgendaSlot / Appointment / AppointmentHistory

APIs candidatas:

GET  /agendas
POST /agendas
GET  /agendas/{id}/availability
POST /appointments
GET  /appointments/{id}
POST /appointments/{id}/reschedule
POST /appointments/{id}/cancel

Eventos publicados:

appointment.scheduled.v1
appointment.confirmed.v1
appointment.rescheduled.v1
appointment.cancelled.v1

Regra crítica: a confirmação garante exclusividade da vaga. Reservas temporárias expiram por timeout configurável. Dois pedidos simultâneos para o mesmo slot retornam conflito ao segundo solicitante.

12.18 Ombudsman Service

Responsabilidade: registro e tratamento de manifestações de ouvidoria.

Responsabilidades funcionais: registrar manifestação (reclamação, denúncia, sugestão, elogio, solicitação, pedido de informação); triar e classificar; encaminhar ao setor responsável; solicitar complementação; registrar resposta; controlar prazos com alerta; concluir; preservar anonimato quando aplicável.

Dados:

Manifestation / ManifestationClassification
ManifestationForwarding / ManifestationResponse
ManifestationHistory / ManifestationDeadline

APIs candidatas:

POST /manifestations
GET  /manifestations/{id}
GET  /manifestations/{id}/history
POST /manifestations/{id}/forward
POST /manifestations/{id}/respond
POST /manifestations/{id}/close

Eventos publicados:

ombudsman.manifestation-created.v1
ombudsman.manifestation-forwarded.v1
ombudsman.deadline-warning.v1
ombudsman.manifestation-responded.v1
ombudsman.manifestation-closed.v1

12.19 Satisfaction Service

Responsabilidade: coleta e consolidação de avaliações de cidadãos sobre serviços e atendimentos.

Responsabilidades funcionais: solicitar avaliação após pontos-chave da jornada; receber nota e comentário; associar ao contexto (serviço, protocolo, canal, data, tenant); consolidar indicadores; disponibilizar para analytics.

Dados:

Feedback / FeedbackContext / FeedbackSummary

APIs candidatas:

POST /feedback
GET  /feedback
GET  /feedback/summary

Eventos publicados:

satisfaction.feedback-received.v1

12.20 Segmentation Service

Responsabilidade: definição e cálculo de segmentos de cidadãos para uso em campanhas e personalização.

Responsabilidades funcionais: criar e versionar segmentos com critérios configuráveis; calcular e atualizar público do segmento; isolar segmentos por tenant; auditar critérios.

Dados:

Segment / SegmentVersion / SegmentCriteria
SegmentMembership / SegmentCalculationRun

APIs candidatas:

GET  /segments
POST /segments
GET  /segments/{id}
POST /segments/{id}/calculate
GET  /segments/{id}/members

Eventos publicados:

segment.created.v1
segment.updated.v1
segment.calculated.v1

12.21 Campaign Service

Responsabilidade: criação, aprovação, execução e acompanhamento de campanhas de comunicação segmentadas.

Responsabilidades funcionais: criar campanha com objetivo, segmento, conteúdo, canal e período; submeter para aprovação; executar; pausar, retomar e cancelar; consolidar métricas de entrega e engajamento.

Dados:

Campaign / CampaignVersion / CampaignApproval
CampaignExecution / CampaignMetrics

APIs candidatas:

GET  /campaigns
POST /campaigns
GET  /campaigns/{id}
POST /campaigns/{id}/submit
POST /campaigns/{id}/approve
POST /campaigns/{id}/start
POST /campaigns/{id}/pause
POST /campaigns/{id}/cancel
GET  /campaigns/{id}/metrics

Eventos publicados:

campaign.created.v1
campaign.approved.v1
campaign.started.v1
campaign.paused.v1
campaign.completed.v1
campaign.cancelled.v1

12.22 Analytics Service

Responsabilidade: dashboards operacionais, relatórios e exploração de dados por tenant.

Responsabilidades funcionais: disponibilizar indicadores consolidados por domínio; servir dashboards configuráveis por perfil; processar consultas de exploração; exportar relatórios; agendar envios recorrentes.

Dados: read models e projeções derivadas de eventos do Data Lake ou de fontes analíticas. O Analytics Service não acessa diretamente os bancos operacionais dos serviços de domínio.

APIs candidatas:

GET /dashboards
GET /dashboards/{id}/data
GET /reports
POST /reports/export
GET  /metrics/{domain}

12.23 Data Quality Service

Responsabilidade: definição e execução de regras de qualidade sobre os dados da plataforma.

Responsabilidades funcionais: definir regras de qualidade por domínio e dimensão; executar avaliações; identificar, classificar e atribuir falhas; acompanhar correção; medir tendências.

Dados:

QualityRule / QualityRuleVersion
QualityRun / QualityIssue / QualityMetric

Eventos publicados:

data-quality.issue-detected.v1
data-quality.issue-resolved.v1

12.24 Data Lake Ingestion

Responsabilidade: consumo de eventos de negócio do RabbitMQ e ingestão no Data Lake segregado por tenant.

Responsabilidades funcionais: consumir eventos com idempotência; validar contrato; identificar tenant e origem; transformar para formato analítico; persistir na partição correta do Data Lake; registrar linhagem; encaminhar falhas para DLQ.

Este componente é orientado a eventos — sem API REST para ingestão de negócio. Consome do RabbitMQ e escreve no Data Lake. A indisponibilidade do Data Lake não bloqueia o processamento transacional da plataforma.

Eventos consumidos: todos os eventos de domínio publicados pelos serviços da plataforma.

12.25 AI Gateway

Responsabilidade: ponto de entrada governado para todas as capacidades de inteligência artificial da plataforma.

Responsabilidades funcionais: receber requisição com Tenant Context obrigatório; aplicar políticas de acesso, quotas e rate limits por tenant; rotear para o serviço de IA adequado (chat, busca, classificação, sumarização); registrar métricas de consumo; aplicar guardrails de entrada e saída; desacoplar serviços de negócio dos provedores de modelo.

Dados:

AIRequest / AIUsageLog / AIPolicy / AIQuota

APIs candidatas:

POST /ai/chat
POST /ai/search
POST /ai/classify
POST /ai/summarize
POST /ai/extract
GET  /ai/knowledge-bases
POST /ai/knowledge-bases/{id}/search

Eventos publicados:

ai.chat-completed.v1
ai.feedback-received.v1
ai.knowledge-indexed.v1

Princípio: os serviços de domínio nunca dependem diretamente de um provedor de modelo. A troca de provedor ou modelo é transparente para os consumidores do AI Gateway.

12.26 AI Specialized Services

Responsabilidade: capacidades especializadas de inteligência artificial — RAG, busca semântica, chat com base de conhecimento, FAQ e construção de bases de conhecimento.

Esses serviços podem coexistir com os serviços Java sem obrigatoriedade de reescrita na mesma linguagem, desde que se comuniquem por contratos explícitos e passem pelo AI Gateway. Cada serviço possui contexto de tenant isolado: base de conhecimento, embeddings, coleções vetoriais, configurações de modelo e quotas.

Serviços identificados:

search-rag-api      → busca semântica com RAG
chat-rag-api        → chat com base de conhecimento por tenant
faq-rag-api         → respostas a perguntas frequentes
search-rag-builder  → construção e indexação de bases de conhecimento

12.27 Integration Service

Responsabilidade: adaptadores para sistemas externos e mediação de integrações governamentais.

Responsabilidades funcionais: gerenciar configurações de integração por tenant; executar chamadas a sistemas externos com resiliência (timeout, retry, circuit breaker); publicar e consumir eventos de integração; monitorar saúde; registrar falhas e reprocessar com autorização.

Sistemas integrados: GOV.BR, MG API, SEI!MG, Data Lake MG, SEG.ID, MG-Ouv, PRO SMTP, Agenda Minas, Portal de Municípios, sistemas de trânsito e sistemas corporativos dos órgãos.

Dados:

IntegrationConfig / IntegrationExecution
IntegrationError / IntegrationHealthRecord

Eventos publicados:

integration.sei.registered.v1
integration.external-response-received.v1
integration.failed.v1

12.28 Configuration Service

Responsabilidade: configurações funcionais dos tenants, identidade visual e parâmetros da plataforma.

Responsabilidades funcionais: manter configurações por tenant e por módulo; versionar parâmetros; disponibilizar configurações com cache; notificar mudanças por evento.

Dados:

TenantConfiguration / ConfigurationVersion
PlatformParameter / BrandingConfiguration

Eventos publicados:

configuration.changed.v1
branding.updated.v1

12.29 Audit Service

Responsabilidade: trilha imutável de ações sensíveis realizadas na plataforma.

Responsabilidades funcionais: receber registros de auditoria dos serviços por API síncrona ou por evento RabbitMQ; garantir imutabilidade; disponibilizar consultas restritas por perfil; auditar as próprias consultas à trilha.

Dados:

AuditEvent / AuditContext / AuditQuery

Eventos consumidos: eventos de auditoria publicados por todos os serviços de domínio.

Regra: a gravação da trilha não bloqueia o fluxo principal quando a criticidade da ação permite processamento assíncrono.

12.30 Matriz de Colaboração entre Serviços

12.31 Matriz de Serviços

12.32 Catálogo de Eventos por Domínio

12.33 Riscos e Mitigações

12.34 Benefícios da Arquitetura

• responsabilidades de negócio claras por serviço;
• autonomia de evolução e deploy por domínio;
• escalabilidade seletiva por pressão real;
• isolamento de falhas por circuit breaker e bulkhead;
• propriedade de dados com fonte de verdade definida;
• integração por contratos explícitos e versionados;
• isolamento de tenant em todos os serviços;
• processamento assíncrono por RabbitMQ;
• IA desacoplada de serviços de negócio por AI Gateway;
• base para observabilidade distribuída com rastreamento ponta a ponta.

12.35 Decisões Arquiteturais

12.36 Considerações Finais

A Arquitetura de Microsserviços decompõe o backend da plataforma em 24 serviços orientados a domínio, com responsabilidades claras, dados próprios e contratos explícitos. Os padrões transversais — Tenant Context, Transactional Outbox, idempotência, versionamento de contratos, resiliência e observabilidade — são aplicados uniformemente por todos os serviços.

O Capítulo 13 detalha a Arquitetura de Mensageria e RabbitMQ, descrevendo a topologia de exchanges e filas, os padrões de consumidor e as políticas de DLQ que sustentam a comunicação assíncrona entre os serviços descritos neste capítulo.

12.37 Controle de Versão

12.38 Rastreabilidade PRODEMGE

• [ANX-III] Bloco 1 — Relacionamento e Atendimento: Citizen, CRM, Communication, Segmentation, Campaign, Satisfaction, AI Gateway.
• [ANX-III] Bloco 2 — BPM: Request, Workflow, Task, Integration, RabbitMQ.
• [ANX-III] Bloco 3 — Gestão Documental: Document, workers documentais, AI Specialized Services (builder e RAG).
• [ANX-III] Bloco 4 — Dados e Inteligência: Analytics, Data Quality, Data Lake Ingestion, AI Gateway, AI Specialized Services.
• [ANX-III] Bloco 5 — Integração e Interoperabilidade: Integration Service, API Gateway, RabbitMQ, contratos versionados.
• [ANX-III] Bloco 6 — Infraestrutura, Segurança e Governança: Identity, Tenant, Audit, Configuration, Tenant Context, observabilidade.
• [ANX-IV] — A decomposição demonstra capacidade de escalabilidade seletiva, isolamento multi-tenant, IA governada e observabilidade distribuída.
• [ANX-V] — Sustentabilidade por propriedade de dados, versionamento de contratos, padrões corporativos e evolução incremental por domínio.