\nProjeto:<\/strong>\u00a0Plataforma de Cadeia de Suprimentos e Cat\u00e1logo de Pr\u00f3xima Gera\u00e7\u00e3o
\nEstado Inicial:<\/strong>
\nO modelo arquitet\u00f4nico da plataforma evoluiu de forma org\u00e2nica ao longo de tr\u00eas anos. Ele continha mais de 400 classes, dezenas de casos de uso e m\u00faltiplos diagramas interligados espalhados por diferentes reposit\u00f3rios. Os principais pontos de dor inclu\u00edam:<\/p>\n
- \n
- \n
Visibilidade n\u00e3o controlada entre subsistemas, levando \u00e0 exposi\u00e7\u00e3o acidental de APIs<\/p>\n<\/li>\n
- \n
Colis\u00f5es frequentes de nomes ao integrar registros de terceiros com ledger internos<\/p>\n<\/li>\n
- \n
Depend\u00eancias bidirecionais que criaram acoplamento arquitet\u00f4nico e dificultaram a implanta\u00e7\u00e3o independente<\/p>\n<\/li>\n
- \n
Nota\u00e7\u00e3o de diagramas inconsistente que tornava as revis\u00f5es entre equipes propensas a erros e demoradas<\/p>\n<\/li>\n<\/ul>\n
Objetivo:<\/strong>
\nReestruturar o modelo do sistema usando princ\u00edpios de pacotes UML 2.0 para impor fronteiras claras, gerenciar visibilidade de forma expl\u00edcita, resolver conflitos de namespace e estabelecer um fluxo reprodut\u00edvel de documenta\u00e7\u00e3o arquitet\u00f4nica baseado em diagramas como c\u00f3digo.<\/p>\n
\nFase 1: Estabelecimento de Fronteiras Estruturais<\/h2>\n
A equipe de arquitetura come\u00e7ou aplicando oRegra de Propriedade Exclusiva<\/strong>: cada elemento do modelo foi atribu\u00eddo a exatamente um pacote. Isso eliminou refer\u00eancias amb\u00edguas e esclareceu a responsabilidade. Eles reconheceram que ummodelo<\/em>\u00a0por si s\u00f3 \u00e9 simplesmente um pacote de n\u00edvel superior, atuando como o cont\u00eainer raiz para todos os subpacotes secund\u00e1rios.<\/p>\n
Crucialmente, a equipe tratou os pacotes comofronteiras conceituais<\/strong>\u00a0em vez de unidades f\u00edsicas de implanta\u00e7\u00e3o. Embora os pacotes influenciassem os limites dos m\u00f3dulos e as configura\u00e7\u00f5es de compila\u00e7\u00e3o, eles n\u00e3o impuseram mapeamentos r\u00edgidos um para um com artefatos compilados. Essa flexibilidade permitiu que os agrupamentos l\u00f3gicos evolu\u00edssem independentemente da infraestrutura em tempo de execu\u00e7\u00e3o.<\/p>\n
Para gerenciar a complexidade dos diagramas, a equipe padronizou tr\u00eas nota\u00e7\u00f5es visuais UML 2.0:<\/p>\n
- \n
- \n
Membros Ocultos<\/strong>: Usado para revis\u00f5es de arquitetura de alto n\u00edvel. O nome do pacote aparecia centralizado no corpo da pasta, ocultando detalhes internos para reduzir a carga cognitiva.<\/p>\n<\/li>\n
- \n
Membros Exibidos Internamente<\/strong>: Implementado durante sess\u00f5es de design de subsistema. O nome do pacote ficava na aba superior, com os elementos contidos listados dentro da pasta.<\/p>\n<\/li>\n
- \n
Membros Exibidos Externamente<\/strong>: Reservado para an\u00e1lise de depend\u00eancia. Os elementos foram desenhados fora da pasta, conectados por linhas s\u00f3lidas dentro de uma caixa delimitadora para destacar intera\u00e7\u00f5es entre pacotes.<\/p>\n<\/li>\n<\/ol>\n
\nFase 2: Controlando Visibilidade e Gerenciando Depend\u00eancias<\/h2>\n
Com os cont\u00eaineres estruturais em vigor, a equipe imp\u00f4s controles rigorosos de acesso usando marcadores de visibilidade UML:<\/p>\n
- \n
- \n
P\u00fablico (
+<\/code>)<\/strong>: Aplicado a elementos intencionalmente expostos para intera\u00e7\u00e3o entre pacotes.<\/p>\n<\/li>\n- \n
Privado (
-<\/code>)<\/strong>: Restrito ao uso interno do pacote, protegendo detalhes de implementa\u00e7\u00e3o de consumidores externos.<\/p>\n<\/li>\n<\/ul>\nPara gerenciar a comunica\u00e7\u00e3o entre pacotes, a equipe substituiu refer\u00eancias espont\u00e2neas por depend\u00eancias expl\u00edcitas e estereotipadas:<\/p>\n
Importa\u00e7\u00e3o de Elemento vs. Acesso a Elemento<\/h3>\n
Quando o\u00a0
Motor de Aplica\u00e7\u00e3o Web<\/code>\u00a0necessitava de dados do cat\u00e1logo, a equipe usou um\u00a0\u00abimport\u00bb<\/code>\u00a0(Importa\u00e7\u00e3o P\u00fablica)<\/strong>\u00a0rela\u00e7\u00e3o. Isso trouxe elementos p\u00fablicos como\u00a0+Livro<\/code>\u00a0e\u00a0+Autor<\/code>\u00a0para a camada web, expondo-os automaticamente para consumidores downstream. Em contrapartida, utilit\u00e1rios de seguran\u00e7a foram integrados por meio de\u00a0\u00abacesso\u00bb<\/code>\u00a0(Acesso Privado)<\/strong>, permitindo que o motor web use rotinas de valida\u00e7\u00e3o de cofre sem reexport\u00e1-las para a interface p\u00fablica.<\/p>\nImporta\u00e7\u00e3o de Pacote<\/h3>\n
Em vez de importar elementos individuais um por um, a equipe utilizou\u00a0Importa\u00e7\u00e3o de Pacote<\/strong>\u00a0no n\u00edvel de subsistema. Uma \u00fanica\u00a0
\u00abimportar\u00bb<\/code>\u00a0linha de depend\u00eancia entre duas pastas de pacote permitiu que o pacote importador tratasse todos os conte\u00fados p\u00fablicos do pacote-alvo como declarados localmente, reduzindo drasticamente a confus\u00e3o no diagrama.<\/p>\n
\nFase 3: Resolvendo Colis\u00f5es de Namespace e Estendendo Frameworks<\/h2>\n
Durante a integra\u00e7\u00e3o, a equipe encontrou uma colis\u00e3o cl\u00e1ssica de namespace: ambos o\u00a0
Ledger de Invent\u00e1rio<\/code>\u00a0e\u00a0Registro de Editoras<\/code>\u00a0continha uma classe chamada\u00a0Livro<\/code>.<\/p>\nPara manter a integridade do modelo, eles aplicaram inicialmente\u00a0Aliasing<\/strong>, mapeando o externo\u00a0
Registro::Livro<\/code>\u00a0para um pseud\u00f4nimo local (RegistroLivro<\/code>) dentro do pacote do ledger. Embora funcionalmente adequado, a equipe reconheceu que o uso excessivo de aliasing prejudica a legibilidade do diagrama. Seguindo as diretrizes arquitet\u00f4nicas, eles acabaram por\u00a0renomear<\/strong>\u00a0a classe conflitante de forma direta, preservando a clareza de longo prazo em vez da conveni\u00eancia tempor\u00e1ria.<\/p>\nPara extens\u00e3o de framework, a equipe aproveitou\u00a0Mesclagem de Pacote (
\u00abmesclar\u00bb<\/code>)<\/strong>. Isso permitiu que um pacote de infraestrutura base absorvesse e estendesse os conte\u00fados de um pacote-alvo em m\u00faltiplas camadas arquitet\u00f4nicas. Em vez de duplicar recursos estruturais, a diretiva de mesclagem simplificou um comportamento semelhante \u00e0 heran\u00e7a no n\u00edvel do pacote, reduzindo a sobrecarga de manuten\u00e7\u00e3o e garantindo defini\u00e7\u00f5es de base consistentes.<\/p>\n
\nFase 4: Automatizando a Documenta\u00e7\u00e3o com PlantUML<\/h2>\n
Para garantir consist\u00eancia e habilitar diagramas arquitet\u00f4nicos com controle de vers\u00e3o, a equipe adotou o PlantUML como seu padr\u00e3o de diagrama como c\u00f3digo. As seguintes implementa\u00e7\u00f5es foram integradas diretamente na sua pipeline CI\/CD para valida\u00e7\u00e3o autom\u00e1tica do modelo:<\/p>\n
Cen\u00e1rio A: Estrutura\u00e7\u00e3o do Framework (Importa\u00e7\u00e3o de Pacote, Acesso e Visibilidade)<\/h3>\n
![\"\"](\"https:\/\/blog.visual-paradigm.com\/wp-content\/uploads\/2026\/05\/img_6a0eeab5b8ea1.png\")
<\/p>\n\n\nPlantUML<\/span>
\n
\n - \n
- \n
- \n