🧠 Padrões Arquiteturais, Diretrizes de Laboratório & Memória do Projeto

Este documento consolida todas as convenções de engenharia, padrões de laboratório, decisões arquiteturais, métricas de conformidade e memória técnica do Portal Educacional e Super-Hub de Projetos (Jekyll SSG).

🏛️ 1. Padrões Canônicos de Estruturação do Portal

A. Padrão Canônico das Páginas Principais dos Módulos (index.md)

Todas as páginas index.md dos 40 módulos, especializações e guias (mod_NN_*, espec_*, extra_*) seguem estritamente a arquitetura canônica (ex.: mod_01_fundamentos_computacao/index.html):

1. Divisão Curricular em 5 Blocos Temáticos:
   • Todos os 40 cursos possuem exatamente 20 capítulos divididos em 5 Blocos de 4 capítulos (### 🧱 Bloco 1 a 5).
   • Páginas de capítulo (topicos, exercicios, exemplos, quizzes) usam layout: single, que gera automaticamente as abas no topo (_includes/chapter-tabs.html) e os cartões anterior/próximo no rodapé (_includes/chapter-pager.html) — nunca escrever navegação à mão.
2. Matriz Tabular Integrada de 6 Colunas:

   | Cap | Tópico Teórico | Exercícios | Exemplos | Slides | Quiz |
   | :---: | :--- | :---: | :---: | :---: | :---: |
   | **01** | [📖 Tópico](topicos/...) | [🧩 Exercícios](exercicios/...) | [💻 Exemplos](exemplos/...) | [📊 Slides](slides/...) | [🧠 Quiz](quizzes/...) |
   

3. Callout de Continuidade Pedagógica:
   > 🚀 **Próxima Etapa da Formação:** ... com link para o próximo curso.
4. Rodapé de Navegação Canônico (exclusivo de páginas index.md):
   [🏠 Voltar ao Início do Portal](../index.html) | [📚 Ver Índice Geral](../indice_geral.html) | [Próximo Módulo ➡️](../...)

🧩 2. Padrão Ouro de Exercícios (4 Níveis Progressivos • 800 Cadernos)

Todos os 800 cadernos de exercícios (3.200 problemas individuais) seguem a estrutura progressiva em 4 níveis, auditada tanto em estrutura quanto em densidade de conteúdo (_scripts/audit_course_depth.py):

• Nível 1 (Fixação Conceitual & Sintaxe): Exercício de código demonstrável com assertions/testes básicos.
• Nível 2 (Prática Guiada & Casos Reais): Cenários práticos com validação de regras de negócio.
• Nível 3 (Integração & Cenários Concorrentes): Resiliência, tratamento de erros e integração entre módulos.
• Nível 4 (Desafio Corporativo & Arquitetura): Solução de nível de produção com testes de integridade e robustez, acompanhada de <details markdown="1"><summary>🔑 Gabarito de Código & Solução Comentada</summary>.

🧠 3. Padrão Ouro de Quizzes Interativos (800 Arquivos)

• Eliminação de Perguntas Superficiais: Substituição de perguntas genéricas por cenários reais de engenharia de software (compiladores, concorrência, memória, segurança, tipagem).
• Estrutura Interativa: Contêineres <div class="quiz-container"> com classes quiz-question, quiz-option, quiz-feedback.
• Feedback Formativo Imediato: 2.400 questões com data-correct="true/false" e data-feedback="..." explicando a fundamentação técnica das respostas certas e distratores (sem tags genéricas <T> ou <stdio.h> desencapadas).
• Sufixo Canônico: Todos nomeados como *_quiz.md.

📊 4. Padrão Ouro de Slides Técnicos (layout: slide)

• Apresentações Técnicas: 800 decks de slides estruturados com layout: slide, comandos de terminal reais, diagramas Mermaid validados e boas práticas corporativas.

🧪 5. Verificação Automática no CI (.github/workflows/jekyll-gh-pages.yml)

• Sintaxe Liquid e Tags raw: _scripts/validate_liquid.py (4.852 arquivos verificados).
• Estrutura e Regras Canônicas: _scripts/check_estrutura_portal.py (40 cursos, projetos/ só com index.md, tabelas com linha em branco antes/depois, quizzes sem <T> solto e proibição de navegação manual).
• Catálogo, Guias e Diagramas de Arquitetura: _scripts/check_projetos_yml.py (185 projetos em _data/projetos.yml), gerar_guia_projeto.py --todos --check e gerar_svg_arquitetura.py --todos --check.
• Integridade Global de Links: _scripts/test_links.py (todas as ~4.930 páginas geradas em _site_local com 0 links quebrados).
• Sintaxe de Diagramas Mermaid: _scripts/check_mermaid.py (todos os 2.305 diagramas Mermaid validados em Chrome headless com Mermaid 10.9.6).

📌 6. Diretrizes do Catálogo de Projetos (catalogo_projetos/)

A. Taxonomia Anti-Colisão de Subpastas

Cada projeto em catalogo_projetos/<id>/ organiza seu código em subpastas no formato <camada>-<tecnologia> (ex.: api-spring, api-fastapi, api-nest, web-angular, web-react, web-vue, web-svelte, desktop-javafx, mobile-android-compose), eliminando pastas genéricas (frontend, backend, src solto na raiz).

B. Padrão cd-first e Execução Local pelo Aluno

## 🚀 Como Executar no Laboratório

### 1. Abra o terminal na subpasta da camada desejada
```bash
cd catalogo_projetos/<id>/<camada>-<tecnologia>

2. Execute a aplicação ou suíte de testes localmente

python -m pytest  # ou ./mvnw spring-boot:run / npm run dev / cargo test / dotnet test

```

C. Diagramas SVG em assets/

• assets/arquitetura_*.svg: gerado automaticamente do código-fonte por python _scripts/gerar_svg_arquitetura.py <id> (nunca editar à mão).
• assets/fluxo_*.svg e diagramas conceituais: SVG puro responsivo (viewBox="0 0 W H"), citando apenas nomes reais do código.

🚀 7. Roadmap de Continuidade

1. Frente 2 (espec_full_stack): Concluir os Blocos 3, 4 e 5 no Padrão Ouro (Grau A), conforme PLANO_FRENTE2_ESPEC_FULL_STACK_2026-10-04.html.
2. Qualidade de Exercícios nos 40 Cursos: Executar as Etapas 2 e 4 de PLANO_DE_MELHORIA_40_CURSOS.html (eliminação de exercícios genéricos nos 4 cursos Nota D e aprofundamento da trilha principal).
3. Evolução Contínua do Catálogo: Expandir o padrão do python_web_tarefas_01_fastapi aos demais projetos python_web e aplicar as correções técnicas mapeadas em PLANO_RETOMADA_2026-10-04.html.