Saltar para o conteúdo principal

Publicação e versionamento da documentação

Estado e arquitetura​

A API REST está em produção em https://api.aedifica.audaces-scale.com/v1 e o MCP em https://api.aedifica.audaces-scale.com/mcp (sondas públicas sem credenciais verificadas em 10-11-2026). Isto não demonstra uma integração autenticada ou OAuth concluída.

O destino previsto da documentação é https://docs.aedifica.audaces-scale.com. O site ainda não está publicado. A configuração do serviço e DNS e o deploy no Coolify ficam a cargo do REA, fora desta frente.

Escolha de design: Docusaurus 3 em website/, TypeScript, saída estática e imagem nginx na porta 80. Sem analytics, pesquisa externa com chaves ou ligações de edição para o repositório privado.

Fontes e geração​

  • Os Markdown em docs/api/ são lidos diretamente pelo Docusaurus (docs.path = '../docs/api', rotas na raiz).
  • docs/api/openapi.yaml é a fonte da referência OpenAPI 3.1. Cada build limpa e regenera docs/api/reference/ com docusaurus-plugin-openapi-docs e copia a especificação para website/static/openapi.yaml.
  • As duas cópias geradas, website/.docusaurus/ e website/build/ estão ignoradas no git. Não editar a referência gerada.
  • A especificação OpenAPI pode ser descarregada sem autenticação no site.

A ordem em website/sidebars.ts é: introdução, visão geral, autenticação, convenções REST; categoria Endpoints (conta, projetos, documentos, catálogo, contactos, horas, planificador, relatórios, ficheiros, pesquisa, webhooks, extras, mensagens e resumo financeiro); portal de horas, assistentes de IA, MCP, publicação e referência OpenAPI gerada. As páginas distinguem operações implementadas de propostas.

Build e validação locais​

pnpm install --frozen-lockfile
pnpm --filter website lint:openapi
pnpm --filter website build
DOCS_BASE_URL=/docs/ pnpm --filter website build

A saída fica em website/build. DOCS_SITE_URL tem por omissão https://docs.aedifica.audaces-scale.com; DOCS_BASE_URL tem por omissão / e é normalizado com barras inicial e final. Ambos são parâmetros de build, não de execução do servidor estático.

website/Dockerfile usa contexto na raiz do repositório, Node 22 e pnpm 10.34.6 para gerar o site; nginx serve os ficheiros na porta 80. Não há publicação automática. O prefixo configurado é preservado no caminho servido pelo nginx.

CI e conteúdo público​

.github/workflows/docs.yml instala dependências com lockfile imutável, executa lint Redocly e build em PRs e pushes para main que afetem esta documentação, website ou workspace/lockfile. Não usa secrets nem faz deploy.

O build falha por links ou destinos Markdown partidos e por conteúdo proibido detetado em docs/api/ ou na saída pública: credenciais, hosts internos e domínios alheios. website/scripts/check-public-content.mjs nunca imprime o valor encontrado. Os placeholders permitidos são apenas aed_live_xxx, aed_test_xxx e aed_live_PREFIXO_SEGREDO; não se permitem endereços locais nos documentos públicos. Ficheiros JavaScript de dependências são também inspecionados: as exceções técnicas são três defaults de parsers de URL e quatro hashes de constantes de alfabetos/base64 e entidades HTML, documentados no script. JSON comprimido do OpenAPI e SVG embutido são descodificados e inspecionados. Não há exclusão genérica de valores opacos nos bundles.

Redocly usa as regras recomendadas. As exceções em website/redocly.yaml justificam apenas metadados editoriais sem alterar o contrato HTTP.

Versionamento​

Cada PR que altera a API deve atualizar a especificação e os Markdown. Quando existir uma versão /v2, pode congelar-se a documentação atual com docusaurus docs:version v1. O workflow atual apenas valida: não publica nem altera infraestrutura.