{"v":{"area":"admin","slug":"guia-colaborador","path":"/home/tiixcom/public_html/sistema/docs/readme/admin/guia-colaborador.md","relative_path":"docs/readme/admin/guia-colaborador.md","title":"Guia do Colaborador","html":"<h1>Guia do Colaborador</h1><h2>Rota</h2><ul><li><code>/adm/guia-colaborador</code></li></ul><h2>O que e</h2><p>Central premium de conhecimento operacional e contextual do sistema TIIX.</p><p>A tela consolida artigos editoriais do banco, READMEs contextuais versionados de pages, checklists, destaques e atalhos em uma experiencia inspirada no padrao visual das centrais tecnicas, como Tracy Logs e API Logs. A ideia e cobrir o sistema inteiro, nao apenas a ajuda de uma pagina isolada.</p><p>O proximo passo conceitual e transformar esse acervo em experiencia contextual por perfil, permissao, grupo e tipo de usuario logado.</p><h2>Para que serve</h2><ul><li>resolver duvidas rapidamente por busca;</li><li>explorar a base por dominio, tipo, origem e intencao;</li><li>navegar por guias por perfil, permissao, grupo e contexto logado;</li><li>abrir READMEs contextuais das paginas sem sair do guia;</li><li>consultar checklists e atalhos operacionais;</li><li>apoiar onboarding, rotina diaria, suporte, desenvolvimento e governanca;</li><li>reduzir dispersao entre documentacao versionada e conteudo editorial cadastrado no banco.</li><li>servir como base de conhecimento ampla do sistema, nao so como ajuda contextual de tela;</li></ul><h2>Fontes de conteudo</h2><ul><li>migration SQL <code>sql/2026-04-21-00-create-guide-knowledge-schema.sql</code> para garantir a estrutura <code>wpjy_guide_*</code> antes dos seeds;</li><li>tabelas <code>wpjy_guide_categories</code>, <code>wpjy_guide_articles</code>, <code>wpjy_guide_checklists</code>, <code>wpjy_guide_highlights</code> e <code>wpjy_guide_quick_links</code>;</li><li>seed SQL <code>sql/2026-04-23-seed-guia-sistema-operacional.sql</code> para guias amplos sobre funcionamento, uso e rotinas do sistema;</li><li>seed SQL <code>sql/2026-04-21-seed-guia-dev-design.sql</code> para conteudo editorial de desenvolvimento e design;</li><li>seed SQL <code>sql/2026-04-23-seed-guia-dev-design-expansao-pratica.sql</code> para enriquecer os guias de Dev &amp; Design com instrucoes de onde inserir, como inserir e como testar;</li><li>seed SQL <code>sql/2026-04-24-seed-guia-dev-design-trilhas-e-decisoes.sql</code> para criar trilhas de leitura e atalhos de decisao de Dev &amp; Design no proprio Guia;</li><li>seed SQL <code>sql/2026-04-24-seed-guia-trilhas-papeis-glossario.sql</code> para criar trilhas por papel, glossario essencial do sistema e decisoes rapidas de curadoria;</li><li>seed SQL <code>sql/2026-04-23-seed-guia-ajudas-paginas.sql</code> para governanca de ajudas contextuais e estrategia README versus banco;</li><li>roadmap versionado em <code>docs/roadmaps/sistema-tiix-evolucao.md</code> para registrar a leitura macro das frentes do sistema, com exibicao no produto restrita a super admin;</li><li>arquivos Markdown em <code>docs/readme/{area}/*.md</code> para READMEs contextuais de pages e areas operacionais;</li><li>endpoint <code>/adm/api/Guide/summary</code>.</li></ul><h2>Layout atual</h2><p>O guia usa o conceito de <code>Knowledge Workspace</code>.</p><ul><li>hero escuro no padrao das centrais tecnicas do admin;</li><li>roadmap visivel do sistema com resumo no topo e detalhamento em <code>offcanvas</code>, apenas para super admin;</li><li>percentual do roadmap recalibrado conforme a evolucao real das frentes, evitando inflar maturidade sem entrega correspondente;</li><li>painel de governanca editorial, tambem restrito a super admin, com sinais iniciais de cobertura, READMEs sem rota, titulos repetidos e facetas frageis;</li><li>fila editorial persistida refletida no mesmo painel para mostrar o que ja esta em tratamento, em revisao ou parado;</li><li>sinais de telemetria inicial no painel de governanca para mostrar buscas sem resultado e termos mais recorrentes;</li><li>bloco de recomendacoes contextualizadas por perfil, permissao e grupo ativo, para acelerar a leitura inicial;</li><li>busca principal no hero com atalho <code>Ctrl K</code>;</li><li>KPIs sinteticos de conteudos, artigos, READMEs e acoes rapidas;</li><li>painel de recorte ativo com badges de filtros;</li><li>abas de modo: <code>Resolver</code>, <code>Explorar</code>, <code>Aprender</code>, <code>Atalhos</code> e <code>Dev &amp; Design</code>;</li><li>launchpad <code>Comece por aqui</code> com tres pontos de entrada recomendados para o recorte atual;</li><li>lista premium de resultados, sem grade de cards;</li><li>split principal entre lista e leitura, com metade da largura para cada lado nas larguras maiores;</li><li>filtros em offcanvas com busca por palavra, tipo, dominio, categoria/area e intencao para manter o miolo limpo;</li><li>leitura rapida em painel lateral sticky;</li><li>bloco <code>Por que apareceu</code> na leitura para explicar o motivo do item estar no recorte atual;</li><li>acoes contextuais na leitura para abrir rota, ver relacionados e filtrar por mesmo objetivo;</li><li>command palette em modal para abrir qualquer conteudo sem navegar;</li><li>trilhas sugeridas para onboarding, rotina e perfis de uso;</li><li>estados vazios com acoes de recuperacao rapida para limpar recorte ou entrar por trilha.</li></ul><h2>Modos de uso</h2><ul><li><code>Resolver</code>: ranqueia conteudos por relevancia e busca livre;</li><li><code>Explorar</code>: favorece navegacao por dominio, tipo e origem;</li><li><code>Aprender</code>: prioriza READMEs, checklists e artigos com intencao de aprendizado;</li><li><code>Atalhos</code>: foca em links diretos para telas operacionais.</li><li><code>Dev &amp; Design</code>: prioriza guias de criacao de pages, CSS, JavaScript, bibliotecas e contexto do template.</li></ul><h2>Filtros</h2><p>O offcanvas de filtros permite combinar:</p><ul><li>palavra ou termo livre;</li><li>tipo de conteudo;</li><li>dominio;</li><li>categoria ou area;</li><li>intencao.</li></ul><p>A busca por palavra do offcanvas sincroniza com a busca principal do hero, permitindo refinar o recorte sem voltar ao topo da pagina.</p><h2>Governanca editorial</h2><p>Para super admin, a tela mostra uma camada adicional de governanca editorial logo abaixo dos KPIs principais.</p><p>Essa leitura inicial usa o proprio payload de <code>/adm/api/Guide/summary</code> para destacar:</p><ul><li>cobertura editorial atual sem depender de atalhos;</li><li>paginas do inventario contextual ainda sem base do Guia;</li><li>paginas com ajuda legada, README e page map conectadas ou faltando conexao;</li><li>grupos potenciais de titulos repetidos;</li><li>facetas ou areas com apenas um item;</li><li>distribuicao atual por dominio.</li></ul><p>Nesta evolucao, o frontend tambem passou a pedir <code>include_governance = 1</code> no resumo do Guia quando o usuario e super admin. Com isso, o backend entrega um recorte real do inventario contextual com:</p><ul><li>total de paginas vistas no inventario de ajuda;</li><li>paginas sem Guia;</li><li>paginas com ajuda legada sem Guia;</li><li>paginas com README sem Guia;</li><li>paginas com Guia sem README;</li><li>amostras das primeiras paginas de cada fila;</li><li>resumo da fila editorial persistida, com itens abertos, em revisao e alta prioridade;</li><li>telemetria inicial de buscas nos ultimos 14 dias, incluindo buscas sem resultado, termos mais usados e itens mais abertos.</li></ul><p>Os sinais principais dessa camada agora tambem oferecem saida direta para <code>/adm/ajudas-paginas</code>, abrindo filas acionaveis por query string para:</p><ul><li><code>legacy_without_guide</code>;</li><li><code>readme_without_guide</code>;</li><li><code>guide_without_readme</code>.</li></ul><p>A fila <code>readme_without_guide</code> tambem ja conta com uma acao de criacao assistida em <code>Ajudas de Paginas</code>, reaproveitando o README contextual para gerar artigo e page map do Guia com menos trabalho manual.</p><p>A fila <code>legacy_without_guide</code> passa a ter um caminho complementar de revisao assistida, abrindo o editor com a ajuda legada preenchida antes da publicacao no Guia.</p><p>O proprio inventario de <code>Ajudas de Paginas</code> agora tambem consegue persistir status, prioridade, responsavel e observacoes por fila editorial, usando <code>wpjy_guide_editorial_queue</code> como memoria operacional da curadoria.</p><p>A experiencia principal agora tambem organiza um bloco de <code>Recomendado para voce</code>, usando o contexto de permissao, grupo e perfil logado para sugerir leituras iniciais mais provaveis.</p><p>Nesta rodada, o Guia tambem passou a registrar eventos leves de uso em <code>wpjy_guide_usage_events</code>, começando por buscas e abertura de itens.</p><p>O proximo passo recomendado passa a ser usar essa telemetria para ranqueamento, lacunas por dominio e fila editorial do ciclo README -&gt; seed -&gt; page map.</p><h2>Classificacao editorial</h2><p>O frontend calcula metadados para melhorar a navegacao sem exigir nova tabela imediatamente.</p><ul><li><code>domain</code>: operacao, suporte, governanca, desenvolvimento, documentacao, comunicacao ou sistema;</li><li><code>intent</code>: resolver, executar, aprender ou referencia;</li><li><code>facet</code>: categoria do artigo, area do README ou grupo operacional;</li><li><code>score</code>: pontuacao de relevancia considerando busca, modo ativo e destaque.</li></ul><h2>Area Desenvolvimento</h2><p>O conteudo de <code>Dev &amp; Design</code> deve entrar no Guia pelo banco, via seed ou cadastro editorial.</p><p>O seed principal desta area e <code>sql/2026-04-21-seed-guia-dev-design.sql</code>, que cria artigos, checklists, destaques, atalhos e mapeamentos contextuais para:</p><ul><li>criacao de pages admin;</li><li>quando usar CSS local ou global;</li><li>quando usar JS embutido, compartilhado ou de modulo;</li><li>bibliotecas ja carregadas pelo template;</li><li>variaveis PHP e globais JavaScript disponiveis apos <code>head.php</code>, <code>body-start.php</code> e <code>footer.php</code>;</li><li>padrao de UX/UI premium para bases grandes;</li><li>instrucoes praticas de onde inserir CSS e JS, como incluir arquivos compartilhados e como testar a entrega;</li><li>documentacao tecnica que precisa virar conhecimento consultavel no produto.</li></ul><p>Os arquivos em <code>docs/readme/desenvolvimento</code> permanecem como documentacao versionada de apoio para devs e como fonte de manutencao do seed, mas nao sao indexados dinamicamente pelo Guia. A base viva consultada pelo usuario final deve estar nas tabelas <code>wpjy_guide_*</code>.</p><p>Com a trilha adicional de 2026-04-24, o modo <code>Dev &amp; Design</code> tambem passa a ficar menos dependente de busca livre ao oferecer:</p><ul><li>artigo de entrada para onboarding tecnico;</li><li>atalhos de decisao sobre composicao visual;</li><li>melhor conexao com <code>guia-colaborador</code>, <code>changelogs</code> e <code>ajudas-paginas</code>.</li></ul><p>Com a camada adicional de trilhas por papel e glossario, o Guia tambem passa a:</p><ul><li>sugerir caminhos mais curtos para onboarding, suporte, devs, gestores, financeiro e saude;</li><li>concentrar termos essenciais do sistema em um glossario editorial consultavel;</li><li>reforcar decisoes rapidas sobre quando um conteudo vira README, Guia, ajuda contextual, changelog ou glossario;</li><li>conectar melhor <code>glossarios</code>, <code>onboarding-admin</code>, <code>devs</code> e <code>central-performance</code> ao conhecimento editorial certo.</li></ul><h2>Estrutura e migrations</h2><p>Antes de qualquer seed editorial, o deploy precisa ter aplicado <code>sql/2026-04-21-00-create-guide-knowledge-schema.sql</code>.</p><p>Essa migration cria as tabelas do Guia quando elas ainda nao existem e adiciona campos essenciais em bancos que tenham uma versao parcial da estrutura. Sem ela, seeds como <code>sql/2026-04-21-seed-guia-dev-design.sql</code> ou <code>sql/2026-04-23-seed-guia-sistema-operacional.sql</code> podem falhar por tabela/campo ausente, mesmo com <code>run_migrations</code> ativo no deploy.</p><h2>Comportamento dos READMEs</h2><ul><li>o backend varre <code>docs/readme</code> dinamicamente para areas operacionais e pages contextuais;</li><li>arquivos <code>README.md</code> de indice sao ignorados;</li><li>cada arquivo individual vira um resultado pesquisavel;</li><li>o conteudo Markdown abre no painel lateral ou no offcanvas;</li><li>a rota exibida e derivada da area e do nome do arquivo.</li></ul><h2>Ajudas de paginas</h2><p>A auditoria e edicao das ajudas contextuais fica em <code>/adm/ajudas-paginas</code>.</p><p>Essa tela mostra, em um unico inventario, paginas com:</p><ul><li>artigo ou relacionamento no Guia;</li><li>ajuda legada em <code>wpjy_telas.ajuda</code>;</li><li>README contextual em <code>docs/readme</code>.</li></ul><p>Use essa tela para importar legado, editar ajuda sem abrir a pagina original e decidir o que deve virar conteudo vivo do Guia.</p><h2>Guias amplos do sistema</h2><p>O seed <code>sql/2026-04-23-seed-guia-sistema-operacional.sql</code> alimenta o Guia com conteudos que nao dependem de uma pagina especifica.</p><p>Ele adiciona artigos, checklists, destaques, atalhos e alguns page maps sobre:</p><ul><li>o que e o sistema TIIX e como ele organiza a operacao;</li><li>areas, contratos, papeis e contexto;</li><li>ciclo de trabalho, tickets, tarefas, notas e conversas;</li><li>agenda, atendimento, paciente e prontuario;</li><li>financeiro, assinaturas, cobrancas e faturamento manual;</li><li>comunicacao com ativos vinculados;</li><li>catalogos, medicamentos, receitas e protocolos;</li><li>governanca de acesso, auditoria e dados sensiveis;</li><li>onboarding, parceiros e validacao de entregas.</li></ul><p>Esses conteudos devem funcionar como base de conhecimento geral, mesmo quando o usuario ainda nao sabe qual tela procurar.</p><h2>Escala</h2><p>A experiencia visual foi preparada para bases grandes ao evitar grids de cards e priorizar busca, filtros em offcanvas, lista densa e leitura lateral.</p><p>Para muitos milhares de artigos, a evolucao recomendada continua sendo mover busca, filtros, ranqueamento e paginacao para o endpoint <code>/adm/api/Guide/summary</code>.</p><h2>Novidades, Health e feedback</h2><p>O Guia passou a ter um bloco de Novidades com os conteudos adicionados ou atualizados recentemente. A ordenacao usa <code>updated_at</code> e <code>created_at</code> dos artigos, destaques, checklists e READMEs carregados.</p><p>Para abrir diretamente o recorte tecnico da frente Health, use:</p><p><code>/adm/guia-colaborador?facet=tiix-health-dev&amp;mode=learn</code></p><p>Esse filtro mostra a categoria <code>TIIX Health Dev</code>, alimentada pelo seed <code>sql/2026-05-07-seed-guia-health-dev-completo.sql</code>.</p><p>O leitor rapido tambem ganhou feedback de conteudo:</p><ul><li>utilidade: se o item ajudou ou nao;</li><li>nota de 1 a 5;</li><li>comentario livre para sugerir ajuste.</li></ul><p>Os registros ficam em <code>wpjy_guide_feedback</code>, criada por <code>sql/2026-05-07-guide-feedback-e-novidades.sql</code>. A proxima evolucao natural e uma tela de curadoria para super admin acompanhar artigos mal avaliados, comentarios pendentes e temas que precisam virar conteudo novo.</p><p>O Guia nao usa lido/nao lido por usuario. Em vez disso, cada abertura de conteudo registra um evento <code>item_open</code> em <code>wpjy_guide_usage_events</code>, e a tela exibe um contador agregado de visualizacoes por item. Isso da sinal de popularidade e utilidade sem transformar a base em caixa de entrada individual.</p><h2>Observacoes</h2><ul><li>a tela deve continuar funcionando mesmo sem registros no banco, desde que existam READMEs em <code>docs/readme</code>;</li><li>novos READMEs devem ser cadastrados no indice da area correspondente quando forem documentacao versionada;</li><li>conteudos que precisam aparecer como base viva do Guia devem entrar por seed ou cadastro nas tabelas <code>wpjy_guide_*</code>;</li><li>o roadmap macro do sistema continua versionado em <code>docs/roadmaps</code>, mas sua leitura visual dentro do Guia deve aparecer somente para super admin;</li><li>o painel de governanca editorial segue a mesma regra e deve aparecer somente para super admin;</li><li>a fila editorial persistida do Guia fica armazenada em <code>wpjy_guide_editorial_queue</code> e aparece no painel de governanca apenas para super admin;</li><li>a telemetria inicial do Guia fica armazenada em <code>wpjy_guide_usage_events</code> e deve ser usada apenas como leitura operacional e editorial, sem expor a camada de governanca para perfis comuns;</li><li>o contador de visualizacoes vem da telemetria agregada de <code>item_open</code> e nao representa confirmacao individual de leitura;</li><li>o feedback do Guia fica em <code>wpjy_guide_feedback</code> e deve orientar curadoria editorial, nao punicao de usuarios;</li><li>a camada de governanca e busca contextual deve degradar com seguranca mesmo em ambientes sem a extensao PHP <code>iconv</code>, usando normalizacao conservadora em vez de erro 500;</li><li>mudancas relevantes no guia devem sempre vir acompanhadas de changelog e README operacional atualizado.</li></ul>"},"exp":1780849752}