📐 Plano de Padronização e Nomenclatura do Catálogo de Projetos

Elevação dos 185 Projetos ao Padrão Ouro Educacional

RepositĂłrio: portal_jekyll | DiretĂłrio: catalogo_projetos/ | Data: 04 de Outubro de 2026
Status: ✅ 100% EXECUTADO E HOMOLOGADO EM TODAS AS 5 FASES (185/185 PROJETOS NO PADRÃO OURO) | ReferĂȘncia CanĂŽnica: SĂ©rie Lista de Tarefas (fullstack_tarefas_*)

📋 1. Contexto e Motivação

Com a conclusão do PR #38, o hub de projetos pråticos foi promovido a diretório de primeiro nível do portal: catalogo_projetos/, reunindo 185 projetos em 18 grupos temåticos e 23 séries curriculares.

Na etapa anterior, a série Lista de Tarefas (fullstack_tarefas_*, 10 partes) foi completamente auditada e padronizada, estabelecendo o Padrão Ouro de Projetos:

  1. Subpastas Anti-Colisão: Nomenclatura no formato rigoroso <camada>-<tecnologia> (ex.: api-spring, web-svelte, mobile-android-xml, desktop-javafx, mobile-android-compose), eliminando pastas genéricas (frontend, backend, mobile, src).
  2. Engenharia de Software Formal: 5 HistĂłrias de UsuĂĄrio (US), 5 Requisitos Funcionais (RF), 5 Requisitos NĂŁo-Funcionais (RNF), 5 Casos de Uso (UC) com diagrama Mermaid e Matriz de Rastreabilidade (RTM).
  3. Roteiro de Homologação com Checkpoints PASS: Tabela canînica de testes de aceitação com CP-01..05 e status PASS ✅.
  4. Riqueza Gråfica em assets/: No mínimo 2 a 4 ilustraçÔes vetoriais autorais em SVG inline/responsivo por projeto.

Este plano define o roteiro executivo para estender esse mesmo padrão a todos os outros 175 projetos do catålogo, eliminando colisÔes de pastas, arquivos soltos na raiz e disparidades instrucionais.

🔍 2. Diagnóstico Completo do Catálogo (Censo de 185 Projetos)

A auditoria automatizada em todo o diretĂłrio catalogo_projetos/ revelou o seguinte diagnĂłstico quantitativo:

Métrica Auditada Situação no Catålogo Impacto / Problema
Total de Projetos Registrados 185 projetos 18 grupos temåticos, 23 séries
Projetos no PadrĂŁo Ouro Completo 10 projetos (5,4%) Apenas a SĂ©rie Lista de Tarefas (fullstack_tarefas_01..10)
Projetos com Subpastas Genéricas 89 projetos (48,1%) ColisÔes com frontend, backend, app, src, mobile, client
Projetos com CĂłdigo/Build na Raiz 68 projetos (36,7%) pom.xml, package.json, Cargo.toml ou src/ soltos na raiz
Projetos sem Engenharia de Software 176 projetos (95,1%) Falta de US, RF, RNF, Casos de Uso ou RTM no index.md
Projetos sem Matriz PASS 159 projetos (85,9%) Testes ausentes ou descritos apenas em texto narrativo
Projetos sem IlustraçÔes SVG 176 projetos (95,1%) AusĂȘncia de diagramas visuais na pasta assets/
Projetos com Status em-construcao 23 projetos (12,4%) Projetos com esqueletos que precisam de conclusĂŁo prĂĄtica

Censo por Grupo TemĂĄtico:

Grupo Projetos Status YAML Situação de Subpastas Engenharia de Software SVGs em assets/
fullstack 24 21 compl. / 3 guia 10 OK (Tarefas) / 14 com frontend e backend 10 com US/RF / 14 sem 26 SVGs (Tarefas)
front 10 6 compl. / 4 constr. Pastas src na raiz ou genéricas 0 com US/RF 0 SVGs
java_web 17 16 compl. / 1 guia Pastas mistas (bibliotecajogos, loginusuarios) 0 com US/RF 0 SVGs
java_desktop 7 7 completo CĂłdigos em subpastas ou soltos 0 com US/RF 0 SVGs
java_testes 3 1 compl. / 2 constr. Pastas com src na raiz 0 com US/RF 0 SVGs
android 25 24 compl. / 1 guia MĂłdulos Android com app/ na raiz ou aninhados 0 com US/RF 0 SVGs
flutter 4 4 completo Projetos com lib/ e pubspec.yaml na raiz 0 com US/RF 0 SVGs
python 29 24 compl. / 5 constr. SĂ©ries intro com degrau_*; outros com src/ 0 com US/RF 0 SVGs
python_web 3 3 completo Subpastas genéricas app/ e tests/ 0 com US/RF 0 SVGs
c_cpp 22 22 completo Miniprojetos C migrados; src/ solto 0 com US/RF 0 SVGs
csharp 4 1 compl. / 3 constr. Arquivos .sln e src/ na raiz 0 com US/RF 0 SVGs
go 5 3 compl. / 2 constr. go.mod e main.go soltos na raiz 0 com US/RF 0 SVGs
rust 4 1 compl. / 3 constr. Cargo.toml e src/ soltos na raiz 0 com US/RF 0 SVGs
php 4 1 compl. / 3 constr. Subpastas genéricas app/, routes/ 0 com US/RF 0 SVGs
infra 9 5 compl. / 4 constr. docker-compose.yml, Terraform soltos 0 com US/RF 0 SVGs
dados 10 10 completo Scripts SQL e Python soltos na raiz 0 com US/RF 0 SVGs
multilang 2 2 completo Pastas por linguagem (angular, cpp, etc.) 0 com US/RF 0 SVGs
docs 3 3 completo DocumentaçÔes técnicas 0 com US/RF 0 SVGs

đŸ›ïž 3. PadrĂŁo TaxonĂŽmico Universal de Subpastas Anti-ColisĂŁo

Para eliminar 100% das colisÔes e permitir que qualquer projeto seja aberto em editores e terminais com clareza imediata, fica instituída a seguinte convenção:

\[\text{Nome da Subpasta} = \mathbf{<camada>} \boldsymbol{-} \mathbf{<tecnologia>}\]

Tabela CanĂŽnica de Mapeamento:

Camada / Papel Tecnologia / Framework Nome CanÎnico da Subpasta Exemplo de Aplicação
Backend / API REST Spring Boot api-spring fullstack_tecloja_01_spring_angular/api-spring
  FastAPI (Python) api-fastapi fullstack_tecloja_02_fastapi_vue/api-fastapi
  NestJS (Node) api-nest fullstack_tecloja_03_nest_react/api-nest
  Laravel (PHP) api-laravel backend_php_01_laravel_rest/api-laravel
  Gin / Fiber (Go) api-gin / api-fiber backend_golang_01_api_gin_gorm/api-gin
  Axum (Rust) api-axum sistemas_rust_02_axum_async_api/api-axum
  ASP.NET Core (C#) api-aspnet sistemas_csharp_01_aspnet_clean/api-aspnet
Frontend / Web SPA Angular Standalone web-angular fullstack_tecloja_01_spring_angular/web-angular
  React / Vite web-react fullstack_tecloja_03_nest_react/web-react
  Vue.js 3 / Pinia web-vue fullstack_tecloja_02_fastapi_vue/web-vue
  Next.js (SSR/RSC) web-nextjs fullstack_tecloja_04_nest_nextjs/web-nextjs
  Svelte 5 (Runes) web-svelte fullstack_tarefas_02_spring_svelte/web-svelte
  JavaScript Vanilla web-vanilla front_vanilla_01_todolist_dom/web-vanilla
Mobile Android XML (Java) mobile-android-xml fullstack_tarefas_04_spring_android/mobile-android-xml
  Android Compose (Kotlin) mobile-android-compose fullstack_tarefas_10_spring_compose/mobile-android-compose
  Ionic Framework mobile-ionic fullstack_tarefas_08_spring_angular/mobile-ionic
  Quasar Framework mobile-quasar fullstack_tarefas_06_spring_vue/mobile-quasar
  React Native (Expo) mobile-reactnative fullstack_tarefas_07_spring_react/mobile-reactnative
  Flutter (Dart) mobile-flutter mobile_flutter_01_catalog/mobile-flutter
Desktop Nativo Java Swing desktop-swing fullstack_tarefas_03_spring_swing/desktop-swing
  JavaFX Moderno desktop-javafx fullstack_tarefas_09_spring_javafx/desktop-javafx
  .NET MAUI / WPF desktop-maui / desktop-wpf sistemas_csharp_03_maui_offline_sync/desktop-maui
  Python Tkinter desktop-tkinter sistemas_python_intro_01/degrau_4_interface_tkinter
CLI / Sistemas C POSIX / C17 cli-c / app-c sistemas_c_01_shell_posix/cli-c
  C++ Moderno cli-cpp / app-cpp sistemas_cpp_01_raytracer/app-cpp
  Rust cli-rust sistemas_rust_01_cli_concorrente/cli-rust
  Go cli-go backend_golang_02_cli_crawler/cli-go
  Python cli-python sistemas_python_01_desktop_poo/cli-python
Infraestrutura / IaC Docker Compose infra-docker fullstack_tarefas_05_arquitetura/infra-docker
  Kubernetes infra-k8s infra_kubernetes_01_k8s_cluster/infra-k8s
  Terraform infra-terraform infra_terraform_05_iac_aws/infra-terraform

📐 4. O Padrão Ouro Instrucional de cada index.md

Todo projeto do catålogo deve possuir um index.md completo, autoguiado e estruturado nas seguintes seçÔes mandatórias:

index.md (Estrutura ObrigatĂłria):
├── Frontmatter YAML (layout: default, title: "...")
├── 🎯 Visão Geral & Objetivos de Aprendizagem
├── 📐 1. Engenharia de Software Formal
│    ├── 1.1 Histórias de Usuário (US-01 a US-05)
│    ├── 1.2 Requisitos Funcionais (RF-01 a RF-05) com UX e Regras de Negócio
│    ├── 1.3 Requisitos NĂŁo-Funcionais (RNF-01 a RNF-05) com Justificativas TĂ©cnicas
│    ├── 1.4 Diagrama Mermaid de Casos de Uso (UC01 a UC05)
│    └── 1.5 Matriz de Rastreabilidade (RTM)
├── đŸ—ș 2. Arquitetura da Solução & IlustraçÔes Vetoriais (SVGs em assets/)
├── 🌳 3. Estrutura de Pastas Visual (Árvore comentada)
├── đŸ’» 4. CĂłdigo-Fonte Completo & Esqueletos Explicados Passo a Passo
├── 🚀 5. Como Executar no Laboratório (Comandos reproduzíveis)
├── đŸ§Ș 6. Matriz de Homologação & Checkpoints de Validação (CP-01..05 com PASS ✅)
├── 🧯 7. Tabela de Troubleshooting (Sintoma, Causa Provável, Solução)
└── 🏁 8. Conclusão & Próximo Passo na Trilha (Links relativos Markdown)

đŸ—ș 5. Roadmap de Execução em 5 Fases PrioritĂĄrias

Dada a envergadura de 175 projetos, a execução serå dividida em 5 Fases modulares, viabilizando entregas graduais e homologadas via Pull Requests independentes:

🚀 Fase 1: O Grupo Full Stack Remanescente (14 Projetos) — [STATUS: 100% CONCLUÍDO ✅]

Foco: Eliminar as pastas frontend e backend duplicadas e alinhar à série Lista de Tarefas com subpastas anti-colisão, SVGs autorais, Engenharia de Software formal e validação de CI.

🌐 Fase 2: Grupos Web Especializados & APIs (34 Projetos) [CONCLUÍDO ✅]

Foco: Organizar as pastas soltas em Vanilla, React, Vue, Angular, Java Web, Python Web e PHP com subpastas anti-colisĂŁo, galeria SVG e PadrĂŁo Ouro.

đŸ“± Fase 3: Grupos Mobile & Multiplataforma (29 Projetos) [STATUS: 100% CONCLUÍDO ✅]

Foco: Estruturar os mĂłdulos Android nativos e Flutter em subpastas anti-colisĂŁo (mobile-flutter/, mobile-android-xml/, mobile-android-kotlin/), galeria de diagramas SVG autorais e mockups responsivos em assets/, Engenharia de Software formal (US, RF, RNF, Mermaid, RTM e CP-01..05 PASS).

⚙ Fase 4: Sistemas, Compiladores & Linguagens Compiladas (35 Projetos) — [100% CONCLUÍDA ✅]

Foco: Isolamento de fontes soltos na raiz para subpastas anti-colisĂŁo (cli-c/, app-cpp/, cli-rust/, api-axum/, web-wasm/, app-rust/, api-gin/, cli-go/, api-grpc/, app-go/, cli-csharp/, api-aspnet/), galeria de diagramas SVG autorais, Engenharia de Software formal (US, RF, RNF, Mermaid, RTM) e matriz de checkpoints CP-01..05 PASS.

🧠 Fase 5: Python, Dados, IA, Infraestrutura, Java Desktop e Multilinguagem (63 Projetos) — [100% CONCLUÍDA ✅]

Foco: Padronização integral de séries introdutórias, algoritmos, IA, pipelines de dados, DevOps, Java desktop, testes automatizados e comparativos multilíngues.

đŸ›Ąïž 6. PortĂ”es de Aceite e Homologação ContĂ­nua

Cada lote de projetos migrado passarĂĄ pelos 4 validadores obrigatĂłrios antes de qualquer commit/PR:

  1. python _scripts/check_projetos_yml.py: Garante paridade entre as pastas no disco e o _data/projetos.yml.
  2. python _scripts/check_estrutura_portal.py: Assegura conformidade com as regras do portal (tabelas, nomes de pasta e ausĂȘncia de navegação escrita Ă  mĂŁo).
  3. python _scripts/validate_liquid.py: verifica se todo bloco de cĂłdigo com chaves duplas ou tags Liquid estĂĄ protegido por raw/endraw.
  4. python _scripts/test_links.py: Valida que nenhum link relativo Markdown foi quebrado com as renomeaçÔes.
âŹ…ïž Voltar Ă  Central de Documentação 🏠 PĂĄgina Inicial