Pular para conteúdo

🧠 MEMÓRIA TÉCNICA E HISTÓRICO EVOLUTIVO — Ecossistema portal_mkdocs

Registro cronológico de decisões técnicas, marcos entregues, lições aprendidas e premissas de engenharia. Mantido por Antigravity (Google DeepMind) em conjunto com Ricardo Tec Pro.

📜 Histórico de Fases e Marcos Consolidados

Fase 1: Estabilização Estrutural e Higienização de Repositórios (Concluída ✅)

  • Desafio: Estrutura legada aninhada em portal_mkdocs_repos/ causava caminhos excessivamente longos no Windows (MAX_PATH) e conflitos Git entre projetos.
  • Ação:
  • Migração de todos os repositórios diretamente para a raiz plana portal_mkdocs/.
  • Commit em lote das unidades 17 a 20 pendentes nos 50 cursos.
  • Expurgo completo de pastas residuais _analisar_deletar/ em 46 repositórios.
  • Harmonização da nomenclatura em adm_gestao_dmn (referencia.md), atingindo a Matriz 20/20 Perfeita.
  • Desafio: 1.000 decks de slides apresentavam links quebrados (404) apontando para ../slide-XX.html, e o build do MkDocs demorava excessivamente.
  • Ação:
  • Substituição em lote via regex nos 50 repositórios de ../slide- por slide-XX.html.
  • Desativação de enable_git_follow: false e ativação de processamento paralelo no plugin git-revision-date-localized, reduzindo o tempo de compilação em 60%.
  • Indexação de páginas órfãs no menu de navegação do Hub Central.

Fase 3: Excelência Pedagógica e Interatividade (Concluída ✅)

  • Desafio: Exercícios sem gabarito ou com gabaritos dispersos em páginas separadas; cursos clonados com conteúdos genéricos.
  • Ação:
  • Injeção de 1.000 blocos sanfonados <details><summary><b>Gabarito Explicado</b></summary> diretamente no final de cada página de exercícios.
  • Regeneração didática dos 6 cursos clonados (ads_mod_04, mod_11, mod_12, mod_13, extra_ferramentas, spec_seguranca).
  • Validação de 1.000 quizzes com 10 questões interativas cada, suportados pelo motor quiz.js.

Fase 4: Governança Unificada via CLI Multirepo (Concluída ✅)

  • Desafio: Impossibilidade prática de gerenciar 51 repositórios Git manualmente por linha de comando individual.
  • Ação:
  • Criação da ferramenta CLI multirepo.py na raiz e espelhada no Hub Central (portal_mkdocs_hub/scripts/multirepo.py).
  • Implementação de rotinas multithread de alta performance: list, status (~2s), audit, clean, build, serve, deploy, git, search, sync-hub.

Fase 5: Produtividade, Automação e Sincronização Remota (Concluída ✅)

  • Desafio: Consumo descontrolado de minutos de GitHub Actions e navegação isolada entre os cursos.
  • Ação:
  • Injeção do botão persistente 🌐 Portal: https://ricardotecpro.github.io/ no topo da navegação dos 50 cursos.
  • Implementação de multirepo.py search (busca multithread em < 1s) e multirepo.py clean (liberação de 615 MB em caches).
  • Blindagem de .github/workflows/deploy.yml exclusivamente com on: workflow_dispatch.
  • Sincronização de 100% dos repositórios remotos no GitHub e publicação das páginas em gh-pages.

Fase 6: Experiência do Usuário e Descoberta de Conteúdo (UX/UI) (Concluída ✅)

  • 6.1. Barra de Anúncio Superior (Announcement Bar): Injetado banner responsivo moderno (#0d1b2a -> #0d3b66) em todos os 50 cursos com botão estilizado em formato pill (#64ffda) apontando para o Portal Central.
  • 6.2. Sistema de Tags Didáticas Cruzadas: Ativação do plugin nativo material/tags nos 50 cursos, criação do catálogo docs/tags.md (<!-- material/tags -->), estilização CSS de etiquetas .md-tag e indexação de 3 a 5 tags contextuais nas 1.000 aulas do ecossistema.

Fase 7: Acessibilidade Offline e Formato Livro Digital (Concluída ✅)

  • 7.1. Apostila Consolidada para Impressão / PDF (mkdocs-print-site-plugin):
  • Habilitação da rota /print_page/ ("📖 Versão para Impressão (PDF)") em todos os cursos.
  • Estilização de publicação em papel A4: ocultação de cabeçalhos, banners e botões interativos em @media print, quebra de página automática antes de cada aula e proteção contra fragmentação de tabelas e blocos de código.

Fase 8: Governança Preventiva e Automação Contínua (Concluída ✅)

  • 8.1. Git Pre-Commit Hooks em Lote: Criação e instalação do script .git/hooks/pre-commit nos 51 repositórios via multirepo.py install-hooks.
  • 8.2. Verificador de Saúde Pública Web (multirepo.py health-check): Monitoramento HTTP 200, latência e certificados SSL dos 51 sites no ar com 100% de disponibilidade.
  • 8.3. Linter Automatizado de Sintaxe Markdown (multirepo.py lint-markdown): Motor de análise estática de sintaxe CommonMark validando 8.455 arquivos sem nenhuma falha.

💡 Decisões Técnicas e Lições Aprendidas

  1. Sintaxe Moderna do Plugin Tags (Material for MkDocs 9.6+):
  2. O parâmetro tags_file: tags.md sob plugins: - tags: está obsoleto e gera avisos de compilação.
  3. A sintaxe correta e oficial é declarar - tags na lista de plugins e inserir a diretiva <!-- material/tags --> dentro de docs/tags.md.
  4. Ordem de Carregamento dos Plugins em mkdocs.yml:
  5. O plugin - tags DEVE preceder - print-site: para que o gerador da apostila capture corretamente os metadados e páginas indexadas.
  6. Extração Léxica e Filtro de Código/Diagramas:
  7. Antes de analisar o texto de uma aula para identificar tecnologias, é indispensável remover blocos de código (```) e diagramas Mermaid para evitar falsos positivos (ex: a palavra graph em graph LR gerando a tag Grafos).
  8. Deploy Concorrente Seguro em Multirepo:
  9. Por se tratarem de 51 repositórios Git completamente isolados no disco, operações de compilação e deploy (mkdocs gh-deploy) podem ser executadas com paralelismo de 4 a 6 threads sem concorrência ou disputa de locks no Git, reduzindo o tempo total de publicação de ~25 minutos para ~4 minutos.\n