Gerar e validar o portal¶

Escopo: documentação, sem inicializar microserviços, consultar bancos ou aplicar Helm. Execute na pasta infra/totvs-gateway-infra-local/mkdocs.

Ambiente isolado¶

O Dockerfile usa Python 3.12; a validação local desta edição usa Python 3.14. Dependências diretas e transitivas estão fixadas em requirements.txt. Material 9.6.22, MkDocs 1.6.1 e PyMdown Extensions 10.16.1 foram selecionados como conjunto e devem ser atualizados em PR conjunto.

python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements.txt
.\.venv\Scripts\python.exe -m mkdocs build --strict
.\.venv\Scripts\python.exe scripts/validate_site.py
.\.venv\Scripts\python.exe -m mkdocs serve

No Linux, os executáveis ficam em .venv/bin/python. mkdocs serve é um servidor de desenvolvimento; pare com Ctrl+C. Diretórios de ambiente, saída e screenshots estão ignorados pelo Git.

O que a validação estática verifica¶

Diagramas de dados — geração compartilhada¶

O modelo mestre é gerado pelo mesmo comando a partir das fontes individuais. Para validá-lo no navegador após o build, execute python scripts/validate_master_diagram.py --channel msedge.

Os domínios usam o mesmo renderer do Core: Graphviz 16.1.0, distribuído em WebAssembly por @viz-js/viz 3.31.0, com dependência e lockfile fixados em tools/data-diagrams. O build MkDocs usa os SVGs versionados, sem exigir Node ou Graphviz instalado. Para regenerar, use Node 22 ou superior (validado com Node 24.13.0):

cd tools/data-diagrams
npm ci --ignore-scripts --no-audit --no-fund
npm run generate
npm run check -- --workspace C:/TOTVS/workspace/gateway

npm ci baixa a dependência na instalação; a geração e a navegação não consultam serviços externos. Na pipeline documental, execute npm ci, npm run check e o build MkDocs. --workspace é opcional e exige o checkout dos serviços; verifica hashes das fontes contra o modelo revisado.

Para atualizar: revise entidades, codecs e repositories; ajuste o JSON do domínio registrado em models.json; atualize os hashes após a revisão; gere novamente e versione JSON, DOT e SVG juntos. npm run check falha se os artefatos diferirem da geração. As relações são curadas a partir do código: nomes semelhantes não geram vínculos automaticamente. --domain templates limita generate/check ao domínio selecionado.

Os DOT ficam em tools/data-diagrams/generated/<domínio> (Core mantém seu diretório original); os SVGs em docs/assets/diagrams/<domínio>. O viewer comum oferece zoom, deslocamento e tela cheia. Os títulos abrem os dicionários existentes. Valide com python scripts/validate_data_diagrams.py --channel msedge, além do build e dos links. O teste percorre todos os modelos, temas e larguras, confere geometria/contraste, zoom e links dos SVGs; também aceita --domain templates. Consulte o atlas para a cobertura por domínio.

Graphviz foi escolhido por conectar linhas a campos específicos e compor cabeçalhos/campos em SVG. Mermaid continua adequado às visões simplificadas existentes, mas não oferece o mesmo controle de portas por campo. DBML introduziria convenções relacionais desnecessárias; D2 exigiria outra ferramenta de geração sem benefício para este piloto. Fontes: tabelas e portas Graphviz, API local Viz.js.

Links, assets e evidências¶

mkdocs build --strict: navegação completa, Markdown, arquivos e âncoras referenciadas.
validate_site.py: destinos e âncoras HTML locais, imagens/scripts/estilos, integridade SHA-256 do acervo e do runtime Mermaid.
Com --workspace <raiz-do-workspace>: existência de cada path de evidência no commit Git registrado, sem acesso de rede.

URLs externas não são autenticadas ou percorridas automaticamente. Em particular, links Azure podem exigir login e commits ainda locais podem não estar disponíveis remotamente. O validador reporta esse limite.

Renderização, pesquisa e navegação¶

.\.venv\Scripts\python.exe -m pip install -r requirements-validation.txt
.\.venv\Scripts\python.exe -m playwright install chromium
.\.venv\Scripts\python.exe scripts/validate_browser.py

Alternativa no Windows com Edge instalado: scripts/validate_browser.py --channel msedge, usando o mesmo Python. O script inicia e encerra um servidor HTTP restrito a loopback, abre todas as páginas, verifica SVGs Mermaid, pesquisa, navegação, âncoras antigas e layout móvel. Bloqueia requests externos para comprovar que os assets de renderização são locais. Salva screenshots e JSON em validation-output/.

O Mermaid 11.12.0 está em docs/assets/vendor/, com licença e hash em validation/vendor-files.json. O override carrega esse runtime antes do Material para evitar seu fallback de CDN sem versão exata. Não adicionar outro inicializador Mermaid concorrente. As fontes do tema são locais/sistema (font: false).

Build documental no Docker¶

docker build --target build -t gateway-docs-build .

O estágio build instala o lock Python, executa build estrito e o validador estático. O build completo mantém os estágios Sonar/NGINX existentes; dependências corporativas e publicação remota precisam do ambiente correspondente. Não há deploy automático neste procedimento.

Para a imagem runtime, a porta interna é 8080 (docker run --rm -p 8080:8080 <imagem>). O endereço/base path de publicação deve ser confirmado antes de configurar site_url; os links locais são relativos e a validação desta entrega usa a raiz do site.

Atualizar evidências ou acervo¶

Os manifests em validation/ são registros auditáveis, não devem ser regenerados para esconder falhas. Ao acrescentar fonte, registrar repositório/path/commit/URL e validar o objeto Git. Alterar conteúdo histórico ou versão vendorizada exige decisão explícita e revisão do hash correspondente. Consulte a governança.

Validar a apresentação dos diagramas¶

Depois do build, execute com as dependências de validação instaladas:

python scripts/validate_diagrams.py --channel msedge

O comando abre as páginas com diagramas em 1280 e 1440 px, alterna o seletor de tema e verifica largura, tamanho de texto, contraste renderizado, cortes e sobreposição de nós. Salva métricas e capturas em validation-output/diagrams/. Inspecione também as imagens: asserções geométricas não substituem a avaliação de clareza das relações.

A sintaxe e as relações ficam no Markdown. O hook hooks/diagrams.py acrescenta a configuração de Mermaid e as classes comuns durante o build; os estilos estão em docs/assets/stylesheets/mermaid.css e a paleta em documentation.css. Use as classes entry, domain, security, store, async e external. Ajuste espaçamento em hooks/mermaid.json; divida diagramas antes de reduzir fontes. Nenhuma dependência adicional é necessária para o hook.