Entrada de Leitura de Documentação de Requisitos na Página (Visualizador)
Objetivo
Integrar a documentação de requisitos já existente no projeto à interface do produto, permitindo que os usuários consultem as instruções correspondentes diretamente na página atual; ao mesmo tempo, garantir que a entrada não atrase a renderização inicial, não vaze conteúdo histórico e não exponha documentos internos acidentalmente em produção.
Limite com a Redação de Documentos
- Esta skill é responsável apenas pela implementação da camada de leitura: posição da entrada, mapeamento de documentos, cópia em tempo de build, renderização, pesquisa, carregamento preguiçoso, estado de erro, superfície de exposição em produção, testes e revisão.
- O conteúdo dos documentos é fornecido por
prd-rule-authoringou qualquer outra fonte; esta skill não define como os documentos devem ser escritos, nem exige que o projeto utilize prd-rule-authoring. - Ambos são independentes: projetos sem um visualizador também devem produzir documentação de requisitos; ter um visualizador não altera as regras de redação.
- O único ponto de acoplamento é o sumário do documento + convenção Markdown: caminhos, títulos e sintaxe renderizável. A convenção é definida na configuração do projeto, não codificada na skill.
Quando Usar
- Quando produto/desenvolvimento/testes desejam "ver as regras diretamente na página atual", evitando a necessidade de consultar arquivos MD em outra tela;
- Quando já existe um conjunto estabelecido de documentos de requisitos em Markdown, que precisam ser exibidos apenas para leitura;
- Quando é necessário integrar documentos internos em demonstrações de entrega, mas deve-se controlar a visibilidade em produção.
Não se aplica a: edição online/colaboração/comentários, fluxo de aprovação de documentos, serviço de busca em texto completo, leitura com níveis de permissão (podem ser estendidos futuramente, não fazem parte da implementação mínima).
Ordem de Leitura
| Arquivo | Quando ler |
|---|---|
references/integration-design.md | Ao projetar entrada/build/mapeamento/carregamento preguiçoso |
references/rendering-and-search.md | Ao lidar com renderização limitada de MD, filtragem de seções de histórico, pesquisa |
references/acceptance-checklist.md | Ao testar, revisar e aceitar |
references/ops-and-governance.md | Ao tratar exposição em produção, atualização de documentos e processo de deploy |
Lista de Implementação Mínima
- Entrada: Exibir apenas em páginas que possuem mapeamento de documentos; sem mapeamento, não renderizar (não deixar botão inativo); a entrada em si não carrega documento algum.
- Fonte: A fonte dos documentos é Markdown dentro do repositório (ou arquivo estático equivalente); copiar para o diretório de saída em tempo de build; realizar validação bidirecional saída↔mapeamento durante o build (falha se houver documento órfão ou mapeamento sem documento).
- Mapeamento: O registro rota/página → caminho do documento é a única fonte de mapeamento; a árvore de documentos é agrupada por módulo; documentos no nível de módulo são identificados separadamente.
- Carregamento: Solicitar o documento apenas após a abertura da gaveta/painel; ao abrir, carregar o documento atual; construir o índice de pesquisa em segundo plano após a abertura; não pré-carregar documentos na inicialização.
- Renderização: Renderização limitada de Markdown (títulos/parágrafos/listas/tabelas/código/citações/linhas horizontais/links); escape total de HTML, gerar apenas tags da lista de permissões; codificação de URL para nomes de arquivo com caracteres chineses/parenteses; adaptação para subcaminhos de deploy; slugs de âncora de título com escape de caracteres perigosos em HTML/URL (
<>&"'), com ponto único de geração de âncora (compartilhado por sumário/corpo/pesquisa/atalho). - Regras do Visualizador: Exibir apenas a versão mais recente — não renderizar seções 'registro de atualizações/registro de alterações' (incluindo seu conteúdo), sumário e pesquisa devem excluir sincronizadamente; se o documento de origem contiver anotações de histórico, filtrar conforme a convenção do projeto ou o autor do documento não as escrever.
- Interação: Clique no sumário para navegar, página de ação pode sugerir navegação padrão por seção, pesquisa global por palavra-chave (agrupada por documento, hits da página atual no topo, fragmento sem ruído de Markdown) e salto, estado de erro e repetição, fechamento. Contexto de navegação dos resultados da pesquisa: clicar em um hit apenas alterna o corpo do texto, sem limpar termos de pesquisa/lista de resultados; manter a posição de rolagem da área de resultados; destacar itens (chave estável, contendo pelo menos documento + âncora + título, adicionar fragmento se necessário para diferenciar múltiplos hits na mesma seção); fornecer entrada clara de 'limpar pesquisa' para restaurar a árvore de documentos; ao abrir um documento pela árvore, limpar a pesquisa; não reconstruir o índice. Linha vermelha: se o sumário estiver fixo no topo ou a lista expandida estiver permanentemente acima do corpo, o clique para navegar deve compensar o deslocamento de cobertura para evitar obstrução; usar asserções de obstrução em automação (
toBeVisiblenão verifica obstrução). Detalhes sobre sumário recolhível no topo, compensação de rolagem, etc., vejareferences/integration-design.md§7. - Superfície de Exposição em Produção: O interruptor de entrada controla apenas o botão, não protege os documentos estáticos; em produção, uma das duas opções é obrigatória: excluir o diretório de documentos do build OU adicionar autenticação ao caminho dos documentos (escrever na porta de acesso de produção).
- Testes: Integridade do mapeamento, consistência dos artefatos do build, não exibição de seções de histórico, carregamento preguiçoso sem pré-carregamento, pesquisa e navegação, manutenção do contexto dos resultados da pesquisa (palavras-chave/resultados/posição de rolagem preservados, hits consecutivos, limpeza restaura a árvore, destaque único, sem reconstrução de índice), estado de erro; asserções de obstrução para sumário/navegação (
toBeVisiblenão verifica obstrução); asserções de restauração de rolagem tolerantes a clamp, sem exigir igualdade absoluta de pixels; revisão visual em navegador e arquivamento de evidências (captura de tela consistente com comportamento final).
Limites
- Não alterar o comportamento das páginas de negócio, valores de rota/menu de negócio, dados Mock; apenas adicionar a entrada de leitura e o pipeline de ativos de documentação.
- Não introduzir dependências pesadas de renderização MD de terceiros; o renderizador é limitado, testável e capaz de escapar HTML.
- Não codificar 'regras de redação de documentos' nesta skill; não codificar 'detalhes de implementação da entrada' na skill de redação.
- A autenticação real, deploy em produção e mecanismo de permissão seguem a porta de acesso do projeto; Mock/demonstração aprovados não equivalem à proteção em produção.
Entregáveis
Posição da entrada e condição de visibilidade, fonte e mapeamento dos documentos, cópia e validação em build, renderização e filtragem de histórico, carregamento preguiçoso e pesquisa, estado de erro, tratamento da superfície de exposição em produção, evidências de teste e revisão, itens não cobertos.