Governança documental

Responsável: time Gateway.

Escopo permanente

A documentação arquitetural do TOTVS Gateway abrange exclusivamente os componentes backend, seus contratos, modelos de dados, fluxos E2E e infraestrutura associada. Sistemas consumidores, incluindo interfaces frontend, são representados apenas como atores externos, sem detalhamento de implementação ou deployment.

Esta regra se aplica também à futura modelagem de dados, aos fluxos E2E, aos templates e às revisões de documentação.

Regras permanentes de evidência e ambiente

1. O código-fonte dos microserviços é a principal evidência do comportamento implementado.
2. Os manifests locais comprovam apenas a configuração declarada no ambiente local.
3. A documentação oficial da infraestrutura e dos deployments corporativos pertence ao TOTVS Apps. Este portal mantém uma referência à documentação oficial, sem duplicar seu conteúdo ou manter um inventário de informações pendentes.
4. Tecnologias experimentais não devem aparecer como oficialmente adotadas.
5. Decisões propostas devem ser diferenciadas de decisões aprovadas.
6. Toda documentação de infraestrutura deve indicar o ambiente ao qual se refere.
7. Não classifique automaticamente a implementação corporativa como incorreta por diferir do ambiente local.

Aplicar essas regras na revisão de diagramas, fichas, modelos de dados e fluxos E2E. Registrar fontes e ambiente no nível da página, sem repetir metadados em cada seção. Os detalhes dos ambientes corporativos permanecem na documentação do TOTVS Apps. Estudos experimentais permanecem na seção própria até aprovação e comprovação de adoção.

Regra mínima de atualização

Quem altera contrato, comportamento ou deployment atualiza a página canônica correspondente, ou explica no PR por que não há impacto documental. Em mudanças entre repositórios, vincule PR de código e PR documental. Não é exigida uma ADR para cada alteração.

Use os templates. Identificar responsabilidade e fontes por commit quando necessário, aproveitando o inventário central. Não completar informações ausentes com suposições.

Apresentação dos estados

Usar Implementado para componentes e funcionalidades comprovados no código, sem acrescentar ressalvas sobre execução. Preservar Parcialmente implementado, Planejado, Experimental e Legado conforme as definições. Em implementações parciais, explicar a limitação concreta.

Mencionar execução efetiva somente quando tecnicamente relevante e sustentada por evidências concretas. Incertezas da análise devem constar no relatório final da tarefa, sem repetição nas páginas oficiais. Preservar avisos sobre riscos reais, limitações funcionais e diferenças entre ambientes. Não usar estados de auditoria operacional como estados de implementação.

Organização e responsabilidade

• Uma página canônica por assunto. Fichas e fluxos referenciam contratos/modelos em vez de copiá-los integralmente.
• Nomes novos em kebab-case, sem acentos; títulos em português. Identificadores HTTP/JSON/BSON mantêm a grafia do código.
• Preserve paths antigos ou forneça compatibilidade explícita e testada. As páginas históricas mantêm nomes originais.
• C4 contexto, containers e componentes em Mermaid; sequências para interações. Cada figura declara nível, fronteira e fonte.
• Propostas e achados ficam em Épicos/Análises. Não misturar recomendação futura ao comportamento implementado.
• ADR registra contexto, alternativas e consequências de decisão relevante. Alteração de decisão referencia a anterior.
• JSON deve vir de DTO/contrato/teste real, com origem e sanitização anotadas. Não publicar tokens, credenciais ou dados de cliente.
• Links de código devem identificar repositório, commit e path. Eventuais limitações de acesso às fontes devem constar no relatório final da tarefa.

Revisão de um PR documental

1. Verificar o escopo backend e manter consumidores externos fora das fronteiras do sistema e do cluster. Confirmar que a evidência sustenta a afirmação e corresponde ao ref indicado.
2. Conferir headers, tenancy, erros e fronteiras de responsabilidade quando aplicáveis.
3. Aplicar estados de implementação simples e preservar riscos e diferenças entre ambientes.
4. Executar build estrito, validação de links/acervo/fontes e renderização no navegador conforme procedimento.
5. Anexar resultado e captura visual quando houver alteração de navegação/layout.

Esta entrega não cria agenda de manutenção nem altera os pipelines dos serviços. A modelagem detalhada está na seção de dados; os fluxos E2E continuam como etapa posterior.