Manual e prints

Como este manual é feito, como escrever páginas, e como regerar os prints a partir de uma instância de demonstração com dados fictícios.

Este manual é o repositório auefolia-trio-docs, feito com Fumadocs sobre Next.js, publicado em docs.pagouentrou.com.br pelo Coolify. Cada push na main gera um deploy novo.

Rodar

pnpm install
pnpm dev          # http://localhost:3010
pnpm build && pnpm start

Estrutura

Caminho	O que é
`content/docs/<seção>/`	As páginas. Cada pasta com `"root": true` no `meta.json` vira uma aba na barra superior.
`content/docs/<seção>/meta.json`	Título, ícone (nome do Lucide) e ordem das páginas.
`public/screenshots/`	Os prints, gerados pelo script. Não edite à mão.
`src/app/(home)/page.tsx`	A página inicial (perfis, áreas, fluxo da venda e ajuda).
`src/app/global.css`	O tema: tokens do Fumadocs mapeados para o grafite e o amarelo da marca.
`src/lib/layout.shared.tsx`	Barra superior e tradução da interface para pt-BR.
`scripts/`	Prints e instância de demonstração.

Escrever uma página

Frontmatter com title e description. Não repita o título como # no corpo.
Links internos com caminho relativo ao arquivo: [Parcelas](../financeiro/parcelas.mdx).
Prints com ![descrição](/screenshots/area/nome.webp). Clicar amplia.
Componentes disponíveis sem import: Callout, Cards/Card, Steps/Step, Tabs/Tab, Accordions/Accordion e blocos ```mermaid. Ícones de card vêm de lucide-react, importados no topo do MDX.
Use os rótulos exatamente como aparecem no sistema, em negrito.
Partes do sistema que estão mudando levam um <Callout type="warn" title="Em revisão">. Procure por "revisão" para atualizá-las.

Prints

Os prints saem de uma instância de demonstração do sistema: o mesmo código do auefolia-trio, mas com banco, Redis e fila próprios e só dados fictícios.

Nunca fotografe o banco de trabalho

O banco local auefolia pode ter dados reais importados do sistema antigo. Os prints são publicados no manual: use sempre a instância de demonstração.

Prepare o banco de demonstração

Com o auefolia-trio ao lado deste repositório e o Docker do projeto no ar:

pnpm demo:preparar             # cria auefolia_docs (use --recriar para começar do zero)

Ele roda as migrations, o demo:popular, o cliente de teste, cria a vendedora Raquel Paz com usuário vinculado e deixa três comprovantes de Pix (fictícios, scripts/fixtures) aguardando análise.

Para fotografar um código que ainda não está no seu checkout (ex.: o main recém-mergeado), aponte para outro clone com AUE_TRIO_DIR=/caminho/do/clone nos dois comandos demo:*. O clone precisa de .env, composer install, pnpm install e pnpm build. O admin da demo é admin@auefolia.com.br (aparece como "Marina Costa").

Suba a instância

Em outro terminal:

pnpm demo:servir               # http://127.0.0.1:8010

Ela roda com APP_ENV=testing, que liga o login fake (código 123456) e dispensa o WorkOS. Os assets vêm do public/build (rode pnpm build no auefolia-trio) ou do Vite de desenvolvimento, se ele estiver rodando.

Gere os prints

pnpm screenshots               # todos
pnpm screenshots financeiro    # só os que começam com "financeiro/"

O script entra como cada persona (admin, vendedora, cliente), navega, abre diálogos e salva em public/screenshots/**.webp (1440×900, 2x).

Adicionar um print

Inclua um item em scripts/screenshots.config.mjs:

{
  file: 'financeiro/baixar-parcela',          // public/screenshots/financeiro/baixar-parcela.webp
  as: 'admin',                                 // persona; sem `as`, sem login
  path: '/financeiro/parcelas?periodo=vencidas',
  steps: [{ click: 'Baixar', exact: true }],   // interações antes do print
  clip: 'dialog',                              // viewport | full | dialog | seletor CSS
},

Os passos disponíveis estão documentados no topo do arquivo: clicar por rótulo, abrir menus da barra superior, abrir o ⋮ de uma linha, digitar, rolar até um título e abrir links que vêm da página (voucher, assinatura).

Quando um print falha

"Login … recusado": o sistema limita os pedidos de código (5 por minuto). Acontece ao rodar várias vezes seguidas; o script espera e tenta de novo.
Página "Too Many Requests" no print: mesma causa. Espere um minuto e rode só aquele print.
"Não achei …": o rótulo mudou no sistema. Atualize o passo.
Dado não encontrado (ex.: nenhum pacote em janela de vendas): a demo envelheceu. Rode pnpm demo:preparar --recriar.

Nesta página