Governança e Cobertura da Central de Ajuda

Objetivo

Organizar a expansão da Central de Ajuda do sistema de cobrança em homologação, garantindo:

• uma taxonomia consistente
• uma regra clara de sugestão por tela
• um inventário rastreável das telas do sistema
• um backlog explícito das telas ainda sem manual

Este documento deve ser tratado como a referência operacional para evoluir a base de conhecimento tela a tela.

Estado atual da base de conhecimento

Categorias ativas

Atualmente a KB do HML ficou consolidada nas seguintes categorias:

1. Fluxos de Cobrança
2. Relatórios
3. Administração
4. Cadastros e Configurações

Categorias removidas

As categorias abaixo foram removidas por não terem artigo publicado nem uso real:

• Início Rápido
• Segurança

Artigos publicados ativos

Atualmente os artigos publicados e ativos são:

1. Perfis e permissões
2. Relatórios e KPIs
3. Como incluir Históricos no Cliente
4. Reagendar um registro no contato
5. Concluir um registro de contato
6. Como conferir os recebimentos da minha carteira
7. Manual de uso: Fechamento de Gratificações
8. Manual de uso: Metas e Prêmios

Limpeza já executada

Já foi feito no HML:

• exclusão de rascunhos antigos sem uso
• exclusão de categorias vazias
• exclusão de mídias mortas
• vinculação das mídias válidas aos artigos corretos
• endurecimento das sugestões contextuais de telas críticas

Regra de organização da ajuda

Regra 1. Uma tela importante deve ter um manual próprio

Telas operacionais e gerenciais com regra de negócio relevante devem ter artigo dedicado.

Exemplos:

• metas.php
• fechamento_gratificacoes.php
• dashboard_cobrador.php
• painel_distribuicao.php
• acompanhamento_30dias.php
• acompanhamento_renegociacao.php

Regra 2. Sugestão contextual deve priorizar artigo específico da tela

Para telas com manual próprio, a configuração em config/kb_routes.php deve usar:

• slugs
• strict => true

Assim a sugestão da tela não mistura artigo genérico com artigo específico.

Regra 3. Artigo genérico só deve existir quando servir a múltiplas telas

Exemplos aceitáveis:

• Relatórios e KPIs
• Perfis e permissões

Esses artigos não devem competir com manuais específicos onde houver fluxo próprio consolidado.

Regra 4. Rascunho parado não deve permanecer na base

Artigo em draft só deve existir enquanto estiver em produção ativa.

Se o conteúdo não será finalizado no curto prazo, deve ser removido para não poluir:

• banco
• admin
• mídia
• organização geral da KB

Regra 5. Mídia precisa ter vínculo claro

Toda mídia deve obedecer uma destas condições:

• vinculada por article_id
• referenciada de fato em artigo publicado

Mídia órfã ou ligada apenas a artigo morto deve ser removida.

Padrão de manual por tela

Cada novo manual deve seguir esta estrutura mínima:

1. O que esta tela faz
2. Quando usar
3. Como usar
4. Regras importantes
5. Boas práticas
6. Dúvidas comuns
7. Resumo rápido

Taxonomia proposta por domínio funcional

Fluxos de Cobrança

Usar para telas ligadas à operação do cobrador, contato e acompanhamento da carteira.

Exemplos de destino:

• dashboard_cobrador.php
• consulta_historicos.php
• src/contatos/historico_clientes.php
• conferencia_receb_cobrador.php
• acompanhamento_30dias.php
• acompanhamento_renegociacao.php
• painel_distribuicao.php

Relatórios

Usar para telas gerenciais de leitura, fechamento, indicadores e análise consolidada.

Exemplos de destino:

• dashboard_digital.php
• fechamento_gratificacoes.php
• relatorios.php
• mensal.php
• semanal.php
• diario.php
• inadimplencia_completa.php
• indicadores_criticos.php

Administração

Usar para telas de controle de acesso, perfis e gestão administrativa.

Exemplos de destino:

• gerenciar_usuarios.php
• alterar_senha.php
• telas de administração da própria KB

Cadastros e Configurações

Usar para parametrização, metas, configuração operacional e setup de negócio.

Exemplos de destino:

• metas.php
• param_gratificacoes.php
• sugerir_meta.php como apoio técnico, se houver manual específico

Inventário inicial das telas do sistema

Menu superior

Telas identificadas no menu principal do HML:

1. dashboard_digital.php
2. consulta_historicos.php
3. conferencia_receb_cobrador.php
4. param_gratificacoes.php
5. metas.php
6. fechamento_gratificacoes.php
7. carteira_saudavel.php
8. dashboard_gerencia_contatos.php
9. dashboard_gerencia_analise.php
10. painel_distribuicao.php
11. acompanhamento_30dias.php
12. acompanhamento_renegociacao.php
13. gerenciar_usuarios.php
14. kb
15. kb/admin/articles.php
16. kb/admin/categories.php
17. kb/admin/media.php
18. alterar_senha.php

Telas principais fora do menu

Também existem telas relevantes fora do menu principal:

1. dashboard_cobrador.php
2. dashboard_gerencia.php
3. painel_cobrador.php
4. src/contatos/historico_clientes.php
5. index.php
6. bmac_acompanhamento.php

Matriz de cobertura atual

Cobertas

Não cobertas ainda com manual específico da tela

Ordem recomendada de expansão

Para construir a ajuda de todo o sistema com o maior retorno operacional, a ordem recomendada é:

1. dashboard_cobrador.php
2. painel_distribuicao.php
3. acompanhamento_30dias.php
4. acompanhamento_renegociacao.php
5. param_gratificacoes.php
6. dashboard_digital.php
7. consulta_historicos.php
8. conferencia_receb_cobrador.php
9. dashboard_gerencia_contatos.php
10. dashboard_gerencia_analise.php
11. carteira_saudavel.php
12. kb/admin/*

Procedimento padrão para cada nova tela

Para cada nova tela com ajuda dedicada, seguir este checklist:

1. analisar a tela, seus filtros, ações, regras e dependências
2. escrever o manual completo em docs/
3. criar seed específico em scripts/
4. publicar o artigo na KB HML
5. mapear a rota em config/kb_routes.php
6. configurar sugestão contextual com slug específico
7. validar por HTTP:
   • RelatedApi.php
   • ArticleApi.php
   • abertura real via ícone de ajuda
8. commitar e subir no remoto do HML

Critério de sucesso

A Central de Ajuda será considerada organizada para expansão total quando:

• toda tela principal tiver categoria definida
• toda tela principal tiver status de cobertura conhecido
• artigos genéricos e artigos específicos não competirem indevidamente
• não houver rascunhos mortos
• não houver categorias vazias
• não houver mídias órfãs
• cada nova entrega seguir o checklist padrão