Pular para o conteúdo principal

Ajuda contextual - contrato de integração

As aplicações Via Fluvial podem exibir ajuda (painel lateral, link ou tooltip) usando a documentação como fonte única.

Contrato​

  • Manifesto: GET /help/manifest.json → { schema: "viafluvial.help-manifest/1", items: [...] }.
  • Item: GET /help/<HELP-ID>.json → título, resumo, blocos de conteúdo (p, steps, list, tip, warning), aplicações, rotas, versões e URL canônica.
  • Identificadores estáveis: HELP-PAS-PAGAMENTO-001, HELP-CARGAS-COTACAO-001 etc.
  • Classificação: a base pública só devolve itens public. Itens internos só existem na base interna.
  • Esquema JSON em /contracts/help-manifest.schema.json.

Uso em React​

import { HelpButton } from '@viafluvial/help'; // copiar src/components/contextual-help e src/services/helpClient.ts

<HelpButton helpId="HELP-PAS-PAGAMENTO-001" baseUrl="https://docs.viafluvial.com.br" />

Sem React, use o cliente:

import { createHelpClient } from './helpClient';

const help = createHelpClient({ baseUrl: 'https://docs.viafluvial.com.br' });
const item = await help.item('HELP-CARGAS-COTACAO-001');
const doRoute = await help.forRoute('via-fluvial-app-cargas', '/');

Como integrar às aplicações (fase posterior)​

  1. Copiar HelpButton, HelpBlocks e helpClient para a aplicação (ou publicá-los como pacote).
  2. Mapear telas → helpId (campo routes do manifesto indica as rotas/telas sugeridas).
  3. Tratar HELP_NOT_AVAILABLE (404) escondendo o botão ou exibindo mensagem neutra.
  4. Configurar CORS no hospedeiro da documentação para as origens das aplicações.
info

Esta etapa não altera via-fluvial-app nem via-fluvial-app-cargas. O exemplo funcional está na Central de ajuda.