Sistema de Ranking de Consultores CAPES

Sistema completo de ranking de consultores CAPES baseado na Minuta Técnica, desenvolvido com arquitetura DDD (Domain-Driven Design).

Arquitetura

Backend (Python + FastAPI + DDD)

• Domain Layer: Entities, Value Objects, Domain Services
• Application Layer: Use Cases, DTOs, Jobs, Mappers, Services
• Infrastructure Layer: Repositories, Elasticsearch Client, Oracle Client, Cache
• Interface Layer: FastAPI Routes, Schemas, Dependencies

Frontend (React + Vite)

• Interface moderna com componentes reutilizáveis
• Comparação lado a lado de consultores
• Sugestão de consultores por tema
• Exportação de fichas em PDF
• Integração com API via Axios
• Design responsivo

Estrutura do Projeto

ranking/
├── backend/
│   ├── src/
│   │   ├── domain/
│   │   │   ├── entities/
│   │   │   │   ├── consultor.py
│   │   │   │   └── consultor_ranking.py
│   │   │   ├── value_objects/
│   │   │   │   ├── criterios_pontuacao.py
│   │   │   │   ├── periodo.py
│   │   │   │   └── pontuacao.py
│   │   │   ├── repositories/
│   │   │   │   └── consultor_repository.py
│   │   │   └── services/
│   │   │       └── calculador_pontuacao.py
│   │   ├── application/
│   │   │   ├── dtos/
│   │   │   │   └── consultor_dto.py
│   │   │   ├── jobs/
│   │   │   │   ├── job_status.py
│   │   │   │   ├── processar_ranking.py
│   │   │   │   ├── popular_componente_b_job.py
│   │   │   │   └── scheduler.py
│   │   │   ├── mappers/
│   │   │   │   └── ranking_mapper.py
│   │   │   ├── services/
│   │   │   │   └── pdf_service.py
│   │   │   └── use_cases/
│   │   │       ├── obter_ranking.py
│   │   │       └── obter_consultor.py
│   │   ├── infrastructure/
│   │   │   ├── cache/
│   │   │   │   └── ranking_cache.py
│   │   │   ├── elasticsearch/
│   │   │   │   └── client.py
│   │   │   ├── oracle/
│   │   │   │   ├── client.py
│   │   │   │   └── ranking_repository.py
│   │   │   ├── repositories/
│   │   │   │   └── consultor_repository_impl.py
│   │   │   └── ranking_store.py
│   │   └── interface/
│   │       ├── api/
│   │       │   ├── app.py
│   │       │   ├── routes.py
│   │       │   ├── config.py
│   │       │   └── dependencies.py
│   │       └── schemas/
│   │           ├── consultor_schema.py
│   │           └── ranking_schema.py
│   ├── scripts/
│   ├── sql/
│   ├── static/
│   ├── tests/
│   ├── requirements.txt
│   ├── Dockerfile
│   └── .env.example
│
├── frontend/
│   ├── src/
│   │   ├── components/
│   │   │   ├── Header.jsx
│   │   │   ├── ConsultorCard.jsx
│   │   │   ├── CompararModal.jsx
│   │   │   ├── FiltroSelos.jsx
│   │   │   ├── BlocoCriteriosModal.jsx
│   │   │   ├── RawDataModal.jsx
│   │   │   └── SugerirConsultores.jsx
│   │   ├── services/
│   │   │   └── api.js
│   │   ├── App.jsx
│   │   ├── App.css
│   │   ├── main.jsx
│   │   └── index.css
│   ├── package.json
│   ├── vite.config.js
│   └── Dockerfile
│
├── scripts/
├── tools/
├── docker-compose.yml
├── .env.example
├── .gitignore
└── README.md

Critérios de Pontuação

Baseado na Minuta Técnica - Ranking AtuaCAPES

Bloco A: Coordenação CAPES

Código	Função	Base	Tempo	Teto Tempo	Bônus Atualidade	Bônus Retorno	Teto
CA	Coordenador de Área	200	10 pts/ano	100	+30	+20	450
CAJ	Coordenador Adjunto	150	8 pts/ano	80	+20	+15	370
CAJ_MP	Coord. Adjunto MP	120	6 pts/ano	60	+15	+10	315
CAM	Câmara Temática	100	5 pts/ano	50	+20	+10	280

Regras:

• Tempo = anos completos × multiplicador (respeitando teto)
• Bônus Atualidade: apenas se mandato vigente
• Bônus Retorno: se houve retorno após período de inatividade

Bloco B: Consultoria (máx 230 pts)

Código	Situação	Base	Tempo	Teto Tempo	Bônus Atualidade	Continuidade 8a+	Retorno	Teto
CONS_ATIVO	Ativo	150	5 pts/ano	50	+20	+20	+15	230
CONS_HIST	Histórico	100	5 pts/ano	50	-	+20	+20	230
CONS_FALECIDO	Falecido	100	5 pts/ano	50	-	+20	-	230

Regras:

• Bônus Continuidade: aplicado se >= 8 anos consecutivos
• Bônus Retorno: se houve reativação após período de inatividade

Bloco C: Inscrições, Avaliações, Premiações e Orientações

Inscrições

Código	Descrição	Base	Teto	Bônus Recorrência
INSC_AUTOR	Autoinscrição	10	20	+2/participação (máx 10)
INSC_INST_AUTOR	Inscrição Institucional	20	50	+5/participação (máx 10)

Avaliação de Comissão

Código	Descrição	Base	Teto	Bônus Recorrência
AVAL_COMIS_PREMIO	Avaliador Prêmio	30	60	+2/ano (máx 15)
AVAL_COMIS_GP	Avaliador Grande Prêmio	40	80	+3/ano (máx 20)

Coordenação de Comissão

Código	Descrição	Base	Teto	Bônus Recorrência
COORD_COMIS_PREMIO	Coord. Comissão Prêmio	40	100	+4/ano (máx 20)
COORD_COMIS_GP	Coord. Comissão GP	50	120	+6/ano (máx 20)

Premiações Recebidas (Autor)

Código	Descrição	Base	Teto
PREMIACAO_GP_AUTOR	Grande Prêmio CAPES (Autor)	100	300
PREMIACAO_AUTOR	Prêmio CAPES de Tese (Autor)	50	150
MENCAO_AUTOR	Menção Honrosa (Autor)	30	90

Orientações e Bancas (apenas selos, sem pontuação direta)

Código	Descrição	Gera Selo
ORIENT_POS_DOC	Orientação Pós-Doc	Sim
ORIENT_TESE	Orientação Tese	Sim
ORIENT_DISS	Orientação Dissertação	Sim
CO_ORIENT_POS_DOC	Co-Orientação Pós-Doc	Sim
CO_ORIENT_TESE	Co-Orientação Tese	Sim
CO_ORIENT_DISS	Co-Orientação Dissertação	Sim
MB_BANCA_POS_DOC	Banca Pós-Doc	Sim
MB_BANCA_TESE	Banca Tese	Sim
MB_BANCA_DISS	Banca Dissertação	Sim

Nota: Orientações e bancas de trabalhos premiados geram selos especiais (ex: ORIENT_TESE_PREM)

Bloco D: Bolsas e Participações

Bolsas CNPq

Código	Descrição	Base	Teto
BOL_BPQ_NIVEL	Bolsista PQ (qualquer nível)	30	60

Participações

Código	Descrição	Base	Teto	Bônus Recorrência
EVENTO	Participação em Evento	1	5	+1/participação (máx 10)
PROJ	Participação em Projeto	10	30	+2/participação (máx 10)

Bloco E: Coordenação PPG

Código	Descrição	Base	Bônus Atualidade	Bônus Retorno	Continuidade 8a+
PPG_COORD	Coordenador de Programa	0	+15	+10	+15

Nota: PPG_COORD gera selo visual mas não pontua diretamente (dados incompletos no AtuaCAPES)

Selos Visuais

Indicadores visuais que aparecem no card do consultor:

Selo	Descrição
Coord. PPG	Coordenador de Programa
Bolsista PQ	Bolsista de Produtividade CNPq
Grande Prêmio	Autor de Grande Prêmio
Prêmio	Autor de Prêmio
Menção Honrosa	Autor de Menção Honrosa
Orientador Pós-Doc/Tese/Diss	Orientou trabalho
Coorientador Pós-Doc/Tese/Diss	Coorientou trabalho
Banca Pós-Doc/Tese/Diss	Participou de banca
Idioma Bilíngue/Multilíngue	Proficiência em idiomas
Titulação	Mestre/Doutor/Pós-Doutor

Fórmula de Cálculo

Score_Atuação = min(Base + Tempo + Bônus, Teto)
Score_Total = Bloco_A + Bloco_B + Bloco_C + Bloco_D + Bloco_E

Requisitos

• Python 3.11+
• Node.js 18+
• Docker e Docker Compose (opcional)
• Acesso ao Elasticsearch (ATUACAPES)
• Acesso ao Oracle

Setup Local

Backend

1. Entre no diretório do backend:

cd backend

2. Crie ambiente virtual e instale dependências:

python -m venv venv
source venv/bin/activate
pip install -r requirements.txt

3. Configure as variáveis de ambiente:

cp .env.example .env

4. Edite .env com suas credenciais:

ES_URL=http://seu-elasticsearch:9200
ES_INDEX=atuacapes
ES_USER=seu_usuario_elastic
ES_PASSWORD=sua_senha_elastic
ORACLE_LOCAL_USER=seu_usuario
ORACLE_LOCAL_PASSWORD=sua_senha
ORACLE_LOCAL_DSN=host:1521/service_name

5. Execute o backend:

python -m uvicorn src.interface.api.app:app --host 0.0.0.0 --port 8000 --reload

A API estará disponível em http://localhost:8000

Frontend

1. Entre no diretório do frontend:

cd frontend

2. Instale dependências:

npm install

3. Execute em modo desenvolvimento:

npm run dev

O frontend estará disponível em http://localhost:5173

Setup com Docker

1. Crie a rede compartilhada (apenas uma vez):

docker network create shared_network

2. Configure as variáveis de ambiente:

cp .env.example .env

3. Edite .env com suas credenciais

4. Execute com Docker Compose:

docker-compose up -d

• Backend: http://localhost:8010
• Frontend: http://localhost:5173
• Oracle local: localhost:1521

Endpoints da API

Ranking

Método	Endpoint	Descrição
GET	/api/v1/ranking	Ranking resumido
GET	/api/v1/ranking/paginado	Ranking paginado com detalhes
GET	/api/v1/ranking/detalhado	Ranking completo
GET	/api/v1/ranking/busca?nome=X	Busca por nome
GET	/api/v1/ranking/estatisticas	Estatísticas do ranking
GET	/api/v1/ranking/status	Status do job de processamento
GET	/api/v1/ranking/selos	Lista de selos disponíveis
GET	/api/v1/ranking/posicao/{id}	Posição de um consultor
POST	/api/v1/ranking/processar	Dispara reprocessamento

Consultor

Método	Endpoint	Descrição
GET	/api/v1/consultor/{id}	Detalhes do consultor
GET	/api/v1/consultor/{id}/raw	Documento ES completo
GET	/api/v1/consultor/{id}/lattes	Dados do Lattes
GET	/api/v1/consultor/{id}/pdf	Exportar ficha em PDF

Sugestões

Método	Endpoint	Descrição
GET	/api/v1/consultores/sugerir?tema=X	Sugerir consultores por tema
GET	/api/v1/consultores/areas-avaliacao	Listar áreas de avaliação
POST	/api/v1/equipe/pdf	Gerar PDF de equipe

Utilitários

Método	Endpoint	Descrição
GET	/api/v1/health	Health check
GET	/	Info da API

Fontes de Dados

Elasticsearch (ATUACAPES)

• Índice: atuacapes
• Campos: id, dadosPessoais, atuacoes, idiomas, formacoes, titulacoes, identificadorLattes
• Tipos de atuação:
  • Coordenação de Área de Avaliação
  • Histórico de Coordenação de Área de Avaliação
  • Consultor
  • Histórico de Consultoria
  • Premiação Prêmio
  • Avaliação Prêmio
  • Inscrição Prêmio
  • Docência
  • Orientação
  • Bolsista CNPq

Oracle Local (Ranking)

• Tabela: TB_RANKING_CONSULTOR
• Armazena ranking pré-calculado para performance
• ~350.000 consultores

Oracle CAPES (SUCUPIRA_PAINEL)

• Tabela: VM_COORDENADOR
• JOIN com: VM_PROGRAMA_SUCUPIRA, VM_AREA_CONHECIMENTO, VM_AREA_AVALIACAO

Documentação da API

Após iniciar o backend, acesse:

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

Desenvolvimento

Testes

cd backend
pytest

Linting

black src/
ruff check src/

Build para Produção

Backend:

docker build -t ranking-capes-backend ./backend

Frontend:

cd frontend
npm run build

Funcionalidades do Frontend

• Ranking Paginado: Navegação por páginas com 10-500 registros por página
• Busca por Nome: Localiza consultor e navega para sua posição
• Comparação: Selecione 2 consultores para comparar lado a lado
• Sugestão por Tema: Busca consultores por área de conhecimento/pesquisa
• Filtro por Selos: Filtra por tipos de atuação
• Exportação PDF: Gera ficha individual ou de equipe
• Detalhes Expandidos: Card expansível com todas as atuações
• Integração Lattes: Exibe dados do currículo Lattes