Estilo e estrutura da documentação de uso#

Regra de ouro: instrução não inventa#

Toda instrução precisa de âncora em uma destas fontes:

1. Fonte de produto (origem preservada C:/Users/fcocl/develop/Projetos-Novos/3ADigitalPdv, somente leitura): o contrato de navegação, o catálogo de parâmetros, as rotas da API, os rótulos das telas, as mensagens de erro e as tabelas do banco.
2. Documento normativo do próprio produto em docs/ da origem (solução, runbook, projeto), citado por caminho.
3. Regra do projeto Clabor.

Quando a fonte não confirmar um comportamento, não escreva "a confirmar". Separe em dois casos e trate cada um de forma diferente:

1. É fato do produto que dá para provar (código, tela em execução, catálogo de parâmetros): vá provar e afirme, com a âncora. "A confirmar" aqui é preguiça, não rigor.
2. É valor da instalação (parâmetro ajustável, endereço de rede, modelo de equipamento, processo da loja): não é dúvida — é um valor que o produto define por padrão e a loja pode mudar. Escreva em duas partes:

• o padrão de fábrica, com a âncora no catálogo de parâmetros;
• onde a sua loja muda, apontando para Administração › Parâmetros ou para o cadastro correspondente.

Use o bloco ## O que é de fábrica e o que a sua loja pode ter mudado, com uma tabela de três colunas: Ponto · Padrão de fábrica · Como fica diferente.

1. É limite externo ao produto (prazo legal, tabela da SEFAZ, custo comercial de terceiro): diga que o produto não cobre e quem responde por isso. Nunca deixe como pergunta em aberto.

O rótulo A confirmar em ambiente fica reservado ao caso raro: quando nem o produto nem a sua instalação puderem responder sem uma verificação que só o dono faz (ex.: medir a rede da loja). Se você usar o rótulo, diga o que exatamente precisa ser medido e quem faz.

Fonte para o padrão de fábrica: docs/uso/retaguarda/parametros-e-padroes.md, gerada do catálogo real do produto. Não transcreva valor de parâmetro de memória.

Voz e forma#

• Português do Brasil, tratamento direto ao leitor ("você abre", "confirme o valor").
• Frase curta. Uma instrução por passo. Passo começa com verbo no imperativo.
• Nome de tela, campo, botão e tecla exatamente como aparece no produto; em negrito na primeira menção dentro de um procedimento (**Finalizar**, **Sangria**, **F9**).
• Caminho de menu no formato Domínio > Tela, com os títulos reais do contrato de navegação.
• Sem jargão de implementação na parte da tarefa. Detalhe técnico vai para a seção "Como funciona por dentro", e apenas quando muda a decisão do operador.
• Sem promessa de resultado não verificada; sem propaganda.

Estrutura obrigatória de um guia de tarefa#

Duas formas válidas de guia#

O conjunto usa as duas, e as duas são conformes:

Na forma 2, cada tarefa precisa de: pré-requisito (quando houver), passos numerados, o resultado esperado e a tabela de erro — os mesmos elementos da forma 1, distribuídos por tarefa em vez de por página. O rótulo de cada elemento pode variar, e as duas variações abaixo são conformes:

Não misture as duas formas na mesma página. O título do erro pode ser tabela em vez de seção: o que importa é o leitor achar o sintoma dele e a ação segura.

Referência de evidência#

• Formato: ` caminho/relativo.ext:linha ` — relativo à raiz da origem para código do produto, ou à raiz do Clabor para regra do projeto.
• Uma âncora por afirmação não óbvia. Não empilhar 20 âncoras no fim do arquivo sem relação com o texto.
• Se a âncora for um documento de solução da origem, citar o caminho e a seção, não a linha.
• Achado que contraria o que está documentado na origem entra como Divergência conhecida, com os dois lados citados. Não harmonizar em silêncio.

Blocos de aviso#

Usar com parcimônia, no máximo três por página:

• > **Importante** — consequência fiscal, financeira ou de auditoria.
• > **Atenção** — risco de perda de dado ou de retrabalho.
• > **Dica** — atalho de operação.

Nomes de arquivo#

• Minúsculo, com hífens, legível, sem acento (regra de clabor-erpia.md).
• README.md é a porta de entrada de cada pasta.
• Um arquivo por tarefa ou por tela; não criar arquivo gigante que junta assuntos distintos.

Índice e navegação#

• Todo arquivo novo precisa estar ligado a um índice. Documento sem entrada de índice é documento perdido.
• Link relativo entre arquivos do conjunto; link absoluto apenas para a origem de leitura.
• O índice aponta para a fonte única; não replica conteúdo.

Contrato de navegação: a fonte primária da retaguarda#

O menu da retaguarda não é escrito à mão: é gerado de e publicado como dados em (window.CONTRATO_NAVEGACAO). Ao documentar tela, título de menu, caminho de destino ou permissão, leia esse contrato e cite-o — ele é a verdade do produto, não a captura de tela de um dia.

A referência desta candidata é , conferida com o fonte em . Há 9 domínios, 93 entradas e 84 telas.

Conte telas pelos papéis principal e fluxo_filho: 76 + 8 = 84. Os 85 destinos distintos incluem o recorte tela/parametros?filtro=auditoria. Um recorte não cria uma tela. O contrato possui 45 permissões principais e três alternativas, somando 48 permissões distintas. Permissões de ações internas têm validação própria.

Use a referência gerada de telas para títulos, destinos e permissões. Gere os derivados com node site/docs/fonte-comum.mjs após revisar mudanças no contrato. A captura de uma instância local serve como diagnóstico; ela não substitui a revisão versionada.

Conferência automática de cobertura: scripts/verificar-cobertura-menu.ps1.