Manter e publicar a documentação

O projeto da documentação vive em application/docs/ e gera um site estático. Ele tem dependências e build próprios, independentes da API e dos três aplicativos.

Executar localmente

Requisitos: Node.js 22 ou superior, preferencialmente 24 LTS, e pnpm 11.5.1.

cd application/docs
pnpm install --frozen-lockfile
pnpm dev

Abra http://localhost:3200. A busca usa um índice produzido no build de produção; para testar os resultados reais, use:

pnpm check
pnpm serve

Organização do projeto

Caminho	Responsabilidade
content/	Guias Markdown/MDX publicados
src/pages/index.tsx	Página inicial da documentação
src/css/custom.css	Adaptação do design system COBRES ao Docusaurus
static/	Fontes locais, marca, robots.txt e indicação do domínio
sidebars.ts	Ordem das dez trilhas e índices das categorias
docusaurus.config.ts	URL oficial, idioma, plugins, navegação, SEO e busca
Dockerfile e nginx.conf.template	Build e serviço HTTP estático com porta configurável

A documentação usa o design system COBRES: Space Grotesk nos títulos, na navegação e nas ações, DM Sans no corpo e Space Mono em código, dados e identificadores. As fontes locais, suas licenças OFL e a marca são os mesmos ativos utilizados pelo site. Os valores de cor acompanham site/theme/brand.ts, na raiz do repositório. Ao alterar o design system, revise a documentação nos temas claro e escuro.

Criar um guia

Adicione um .md na trilha adequada com título e descrição:

---
title: Título que descreve a tarefa
description: O resultado que a pessoa consegue alcançar com este guia.
sidebar_position: 10
---

O nome do arquivo define a URL. content/operacao/minha-tarefa.md será publicado em /operacao/minha-tarefa/. A navegação da categoria é gerada a partir dos arquivos. Use sidebar_position para ordenar os guias dentro dela.

Prefira links relativos para outros arquivos Markdown. O build verifica referências quebradas, imagens ausentes e rotas duplicadas. Ao renomear uma página, atualize seus links e avalie um redirecionamento para a URL anterior.

Critérios editoriais

Cada guia deve indicar a finalidade, os pré-requisitos, o procedimento, a conferência do resultado e as limitações relevantes. Use exemplos fictícios. Valide regras de negócio nas rotas, schemas, SQL e testes correspondentes.

Evite transformar uma proposta de PRD em instrução de uso. Recursos sujeitos a ativação ou configuração devem deixar essa condição clara. Não publique runbooks internos, dados de clientes ou configurações reais do ambiente.

Os contratos ficam na raiz de application/, com índice em application/CONTRATOS.md. Esses arquivos não são copiados para o site.

Validação e integração contínua

pnpm typecheck
pnpm build

O workflow .github/workflows/docs.yml executa a instalação com lockfile, a verificação TypeScript e o build, e armazena build/ como artefato. A busca local é gerada nesse mesmo processo e não exige cadastro em um serviço externo.

Na revisão visual, confira a página inicial, um guia extenso, tabelas, blocos de código, diagramas, busca, navegação mobile e ambos os temas.

Publicar em docs.cobres.com.br

A URL canônica já está configurada como https://docs.cobres.com.br, com baseUrl: '/'. O sitemap, o robots.txt e os links da documentação usam esse domínio.

Para uma hospedagem estática:

1. Configure a raiz do projeto como application/docs.
2. Execute pnpm install --frozen-lockfile e pnpm build.
3. Publique o diretório build/.
4. Cadastre docs.cobres.com.br no provedor escolhido.
5. Crie o registro DNS solicitado pelo provedor no domínio cobres.com.br e habilite HTTPS.
6. Valide a home, uma URL interna aberta diretamente, a busca, /sitemap.xml e uma URL inexistente, que deve responder com status 404.

O arquivo static/CNAME registra o domínio para hospedagens que o utilizam. A existência dele não cria registros DNS nem emite certificados.

Railway

A produção publica a documentação como um serviço Railway de nome docs, construído pela branch main com raiz application/docs e o Dockerfile deste diretório. O domínio personalizado docs.cobres.com.br aponta para esse serviço por CNAME. Não existe ambiente de staging da documentação: a main é a fonte única.

Serviço em contêiner

Na raiz do repositório:

docker build -t cobres-docs ./application/docs
docker run --rm -p 3200:8080 cobres-docs

O Nginx serve os arquivos gerados e aceita PORT, cujo valor padrão é 8080. Rotas de guias são diretórios com index.html; URLs inexistentes recebem a página 404 do Docusaurus com status 404. Não configure um fallback de SPA para a página inicial.

O site público não acessa o banco de dados nem precisa das variáveis da API. Uma alteração de conteúdo exige novo build e nova publicação do diretório estático.