Manter esta documentação

Estrutura

• Directoryapps/docs

  • astro.config.mjs barra lateral e integrações
  • nixpacks.toml deploy no Coolify
  • Directorypublic/

    • Directoryscreens/ capturas geradas por pnpm capture

      • …
  • Directoryscripts/

    • capture.mjs capturas com Playwright
    • build-pdf.mjs PDF de entrega ao cliente
    • gen-api.mjs regenera a referência da API
  • Directorysrc/

    • Directorycomponents/ Screen, Swatch, Finding

      • …
    • Directorycontent/docs/ páginas em Markdown/MDX

      • …
    • styles/moldape.css tema

Editar uma página

1. Abra o .md ou .mdx em src/content/docs/….
2. Rode pnpm --filter @moldape/docs dev e veja em http://localhost:4321.
3. Diagramas: blocos ```mermaid são renderizados automaticamente.
4. Página nova: crie o arquivo e adicione o slug na sidebar do astro.config.mjs.

Regenerar as capturas de tela

1. Crie apps/docs/.env (já está no .gitignore pela regra **/.env):

   CAPTURE_BASE_URL=https://moldape.com
   CAPTURE_USER_EMAIL=conta-de-teste@exemplo.com
   CAPTURE_USER_PASSWORD=********
   # opcional, para as telas de admin:
   CAPTURE_ADMIN=true

2. Instale o navegador uma vez: pnpm --filter @moldape/docs exec playwright install chromium.

3. Rode pnpm --filter @moldape/docs capture.

O script entra com a conta de teste, percorre as telas em mobile (390 × 844) e desktop (1440 × 900) e salva em public/screens/. Ele desfoca automaticamente células de tabela do admin e campos de dados pessoais. Não confirma pagamento nem altera dados de catálogo.

Cuidado

Use apenas uma conta de teste. Nunca grave a senha no repositório nem em variáveis do Coolify do app de documentação.

Regenerar a referência da API

node apps/docs/scripts/gen-api.mjs

Lê apps/order-lifecycle/src/presentation/routes/*.ts e reescreve src/content/docs/referencia/api.mdx.

Gerar o PDF de entrega ao cliente

pnpm --filter @moldape/docs build
pnpm --filter @moldape/docs pdf

O PDF sai em apps/docs/pdf/Moldape-Documentacao-<data>.pdf, com capa assinada pela Nós Tecnologia, sumário e só as seções voltadas ao cliente (Produto, Tutorial, Experiência do usuário, Roadmap e um resumo da arquitetura). A lista de páginas fica em scripts/build-pdf.mjs.

O mesmo comando publica o PDF para download no site: grava public/downloads/moldape-documentacao.pdf e o manifest.json (data, páginas, tamanho). Faça commit dos dois e rode o build de novo: o botão PDF do cabeçalho e a página Baixar em PDF passam a apontar para a versão nova. O deploy no Coolify não precisa de Chromium, porque o PDF já vai pronto no repositório.

Quando atualizar

Mudança no código	Página a atualizar
Nova rota na API	Rodar gen-api.mjs
Mudança no schema.prisma	Modelo de dados
Nova tela ou passo	Mapa de telas e capturas
Decisão de arquitetura	Novo ADR em decisoes/
Nova variável de ambiente	Variáveis de ambiente
Risco corrigido	Marcar como resolvido em Riscos