🎓 PBL Manager - Gestão de Ciclo de Vida de Projetos Acadêmicos

📖 Introdução

O PBL Manager (Project-Based Learning Manager) é um ecossistema digital focado na estruturação, acompanhamento e avaliação de projetos acadêmicos que adotam metodologias ativas de ensino. Desenvolvido com base em um robusto banco de dados relacional, o sistema visa organizar a complexidade do trabalho colaborativo, oferecendo rastreabilidade de entregas e um histórico institucional.

🎯 Objetivo

Em vez do modelo tradicional, a Aprendizagem Baseada em Projetos (PBL) foca na resolução prática de problemas do mundo real em equipe. O banco de dados do PBL Manager tem o objetivo de resolver desafios complexos de gestão como:

• Relacionamentos complexos entre alunos, grupos, turmas e projetos.
• Versionamento histórico de entregas e submissões (evitando perda de dados através de rastreabilidade de refatoração).
• Mapeamento de tecnologias e avaliações de feedback.
• Feedbacks do professor nas versões do projeto.

🛠️ Stack de Tecnologias

• SGBD: PostgreSQL (Relacional)
• Backend: Python + Flask (API integrada ao banco)
• Frontend: React + TypeScript + Vite (Interface Web simples)
• Infraestrutura: Docker e Docker Compose (Isolamento de ambiente)
• Modelagem: ERDPlus (Modelo Conceitual e Relacional)
• Cliente DB: PgAdmin (Gestão do PostgreSQL e Consultas DML/DDL)
• Testes da Aplicação: Python, pytest e psycopg2 (Validação de restrições de integridade).

---

🗄️ Arquitetura e Modelagem do Banco de Dados

O ecossistema é composto por 20 tabelas relacionais estruturadas de forma coesa e normalizadas até a 3ª Forma Normal (3FN), eliminando redundâncias estruturais e inconsistências de atualização.

🔷 Módulos do Ecossistema

1. Fundação Institucional e Usuários

Modela os atores centrais e a estrutura macro da instituição de ensino, implementando uma estratégia de Especialização Sobreposta/Exclusiva mapeada via chaves estrangeiras (FOREIGN KEY) apontando para a tabela pai.

• usuario: Entidade abstrata contendo as credenciais globais e informações básicas de autenticação (id, nome_completo, email, senha).
• professor: Especialização de usuário contendo atributos exclusivos como titulacao.
• aluno: Especialização de usuário para os discentes.
• departamento: Unidades administrativas institucionais (id, nome, sigla).
• curso: Cursos vinculados a um departamento através de um relacionamento 1:N.

2. Organização Acadêmica e Disciplinas

Mapeia como as matérias e os períodos letivos se dividem.

• disciplina: Catálogo geral de disciplinas com sua respectiva carga_horaria.
• curso_disciplina: Tabela de junção configurando a relação muitos-para-muitos (N:M) entre cursos e disciplinas.
• turma: Instanciação de uma disciplina em um semestre específico.
• aluno_turma: Histórico de matrículas (N:M entre aluno e turma), registrando o status acadêmico atual do discente na sala.

3. Core PBL (Equipes e Projetos)

Gerencia o agrupamento de alunos e a vinculação dos desafios práticos propostos.

• equipe: Agrupamento gerado em uma determinada data_formacao e vinculado a uma única turma.
• membro_equipe: Tabela associativa N:M que aloca alunos em equipes, definindo a funcao exercida (ex: Scrum Master, Product Owner, DevOps).
• projeto: O escopo geral do desafio acadêmico.
• equipe_projeto: Tabela de junção ligando equipes a seus respectivos projetos.
• tecnologia: Dicionário global de tecnologias (ex: PostgreSQL, Docker, Python).
• projeto_tecnologia: Relacionamento N:M mapeando quais ferramentas foram adotadas em cada projeto, especificando a categoria e a versao.

4. Ciclos, Versionamento e Avaliação (Entidades Fracas em 3FN)

Camada de gerenciamento temporal e granularidade de entregas, modelada em níveis hierárquicos de dependência forte.

• sprint: Divisão cronológica do projeto (numero, data_fim).
• entrega: Artefatos e marcos esperados de uma equipe dentro de uma sprint.
• versao: Versionamento evolutivo das entregas, contendo o link_repositorio (GitHub) e a data_submissao. Evita perdas por sobrescritas.
• feedback: Avaliação nominal realizada por um professor direcionada a uma versao específica, computando uma nota decimal.
• criterio_aceitacao: Destrinchamento granular do feedback, definindo uma descricao para o item avaliado e seu respectivo peso multiplicador na média.

---

💻 A Aplicação Fullstack (Flask + React)

A aplicação consome a inteligência funcional programada no banco de dados, atuando como uma ponte direta entre os cálculos relacionais complexos e uma interface rica focada na experiência do usuário.

🔌 Backend (Flask API)

Desenvolvido em Python, o servidor REST (main.py) expõe endpoints corporativos para controle de turmas, submissão de artefatos e lançamentos de notas.

• init_db.py (Script de Inicialização): Um script utilitário responsável por se conectar programaticamente ao PostgreSQL usando as credenciais do .env, validar a conexão e rodar a criação de tabelas (criar_tabelas.sql), funções, triggers e views, além de rodar os seeders (popular_tabelas.sql).

• Ponto de Entrada: Rodando nativamente no container pbl_backend exposto na porta 5000.

🎨 Frontend (React SPA)

Uma interface modular de alta performance estruturada com TypeScript e compilada através do Vite.

• Componentes Core:

  • AbasSprints.tsx: Chaveamento de ciclos cronológicos e controle visual de prazos limites.

  • ListaEntregas.tsx: Listagem em tempo real contendo o status de cada entrega (automatizado via banco de dados).

  • CardEquipe.tsx: Cartões consolidados exibindo o mapeamento de alunos, suas funções de liderança e médias ponderadas.

• Ponto de Entrada: Rodando no container pbl_frontend exposto na porta 5173.

---

📋 Checklist de Requisitos do Projeto (Critérios de Avaliação)

Mapeamento dos requisitos obrigatórios cumpridos de acordo com as diretrizes da disciplina:

• Divisão de Grupos (no máximo 4 pessoas): Controlado de forma estrita via Triggers no banco de dados.
• Projeto de Banco de Dados Normalizado (40%): Modelos Conceitual e Relacional projetados sem redundâncias estruturais.
• Estrutura de Tabelas (30%): Mais de 20 tabelas e views estruturadas de forma coesa.
• Camada de Inteligência Funcional (30%): Conjunto completo de Views, Triggers e Procedures operacionais.
• Seeders para População (10%): Scripts SQL de inserts realistas automatizados para testes de concorrência e amostragem.
• Testes a Nível de Aplicação (10%): Suíte de testes automatizados escrita em Python com pytest.
• Documentação Completa (10%): Regras de negócio mapeadas e README atualizado.

---

🛠️ Inteligência Programada (Backend SQL)

📈 Views Analíticas

• vw_visao_geral_equipes: Consolida os dados cruciais das equipes, seus respectivos projetos, turmas e disciplinas para acompanhamento macro do professor.
• vw_acompanhamento_sprints: Mapeia de forma cronológica as sprints vigentes, datas limites e o progresso associado.
• vw_feedbacks_e_criterios: Reúne as avaliações feitas pelos professores, as notas aplicadas e as descrições dos critérios de aceitação vinculados.

⚙️ Procedures e Automações

• matricular_aluno_turma: Processa inscrições de alunos garantindo a integridade e limitando o máximo de 40 matrículas por turma.
• criar_proxima_sprint: Facilita o desdobramento ágil ao criar de forma sequencial o próximo ciclo temporal de um projeto.
• reprovar_por_falta_evasao: Atualiza massivamente o status acadêmico de discentes que abandonaram ou não se integraram aos fluxos do PBL.

🔒 Triggers de Integridade e Regras de Negócio Estritas

• trg_restricao_aluno_equipes: Garante em nível de banco que nenhum aluno consiga fazer parte de mais de uma equipe dentro da mesma turma.
• trg_garantia_aluno_matriculado: Bloqueia tentativas de alocar um aluno em uma equipe se ele não possuir vínculo de matrícula ativo na turma correspondente.
• trg_mudanca_status_por_feedback: Analisa a inserção de notas. Atribui automaticamente status de:
• Aprovado: Se $\text{Nota} \ge 8.0$.
• Necessita de ajustes: Se $\text{Nota}$ estiver entre $4.0$ e $7.9$.
• Reprovado: Se $\text{Nota} < 4.0$.

---

📁 Estrutura do Projeto

PBLManager/
├── .env.example                       # Variáveis de ambiente de exemplo
├── docker-compose.yml                 # Orquestração do PostgreSQL via Docker
├── Dockerfile                         # Arquivo de build Docker do backend
├── diagramas/
│   ├── Modelo Conceitual.pdf          # Diagrama Entidade-Relacionamento (DER)
│   └── Modelo Relacional.pdf          # Diagrama Relacional/Lógico
├── docs/
│   ├── Captura de tela 2026-06-04 205608.png  # Diretrizes de avaliação
│   └── PBL Manager.pdf                # Regras de negócio e escopo detalhado
├── frontend/                          # Interface React + Vite + Typescript (com Bun)
├── scripts/
│   ├── criacao/
│   │   └── criar_tabelas.sql          # Script DDL das 20 tabelas principais
│   ├── consulta/
│   │   ├── consulta01.sql             # Consultas pontuais de testes
│   │   ├── scripts_principais_consultas.sql # Queries avançadas do ecossistema
│   │   ├── vw_acompanhamento_sprints.sql    # View de controle de prazos por ciclo
│   │   ├── vw_feedbacks_e_criterios.sql     # View de notas e critérios de aceitação
│   │   └── vw_visao_geral_equipes.sql       # View analítica consolidada de equipes
│   ├── functions/
│   │   ├── func_Alunos_Em_Turma.sql   # Contador de densidade por sala
│   │   ├── func_busca_link_GitHub.sql # Localizador de artefatos por versão
│   │   ├── func_obter_Média_Equipe.sql# Cálculo de média ponderada de notas
│   │   ├── func_Professor_Por_Id.sql  # Captura nominal de orientadores
│   │   └── func_Sprints_Projeto.sql   # Mapeador de ciclos por escopo
│   ├── seeds/
│   │   ├── procedures/
│   │   │   ├── criar_proxima_sprint.sql     # Gerador automatizado de cronograma
│   │   │   ├── matricular_aluno_turma.sql   # Validador de limite de vagas (máx 40)
│   │   │   └── reprovar_por_falta_evasao.sql# Rotina de atualização de status
│   │   └── popular_tabelas.sql        # Ingestão de dados realistas (DML)
│   └── triggers/
│       ├── trg_garantia_aluno_matriculado.sql # Restringe alocações ilegítimas
│       ├── trg_mudanca_status_por_feedback.sql# Automação de status da entrega por nota
│       └── trg_restricao_aluno_equipes.sql    # Impede duplicidade de aluno em equipes
├── main.py                            # Ponto de entrada da API Flask
├── init_db.py                         # Inicializador automatizado do banco de dados
├── entrypoint.sh                      # Inicializador do backend no Dockerfile
├── setup.sh                           # Script shell de automação geral do deploy
└── README.md                          # Este arquivo

---

🚀 Como Inicializar o Projeto (Instruções de Uso)

1. Pré-requisitos

• Ter o Docker e o Docker Compose instalados na sua máquina.
• Python 3.10+ (opcional, apenas se desejar rodar a suíte de testes de aplicação localmente).

2. Subindo o Banco de Dados com Docker

O projeto já conta com um docker-compose.yml para facilitar a inicialização do PostgreSQL. No terminal, na raiz do projeto, execute:

# 1. Copie o arquivo de variáveis de ambiente:
cp .env.example .env

Preencha as variáveis de ambiente do arquivo .env após copiar.

⚠️ Nota: O valor da variável PGADMIN_DEFAULT_EMAIL deve ser preenchido no padrão 'xxx@xxx.com'. O valor das variáveis de ambiente restantes é arbitrário, preencha como quiser.

# 2. Inicie o container do banco:
docker compose up -d --build

Nota: Após executar, rode o comando uv run init_db.py com a variável POSTGRES_HOST vazia.

*O PostgreSQL estará