Files

Frederico Castro ef50aee945 docs: atualizar README com estrutura e endpoints atuais

2025-12-27 01:29:48 -03:00

13 KiB

Raw Blame History

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 V2

Baseado na Minuta Técnica - Ranking AtuaCAPES v2.0

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: Coordenação de Programa PPG (máx 180 pts)

Critério	Pontuação
Base	70 pts
Tempo	5 pts/ano (máx 50)
Programas extras	20 pts/programa (máx 40)
Bônus por nota PPG	até 20 pts

Nota: Bloco B = 0 no V1 (dados incompletos no AtuaCAPES)

Bloco C: Consultoria (máx 230 pts)

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

Regras:

Bônus Continuidade: aplicado se >= 8 anos consecutivos
Bônus Retorno: apenas para CONS_ATIVO com reativação
CONS_FALECIDO não pontua por tempo

Bloco D: Premiações, Avaliações e Participações

Inscrições

Código	Descrição	Base	Teto
INSC_AUTOR	Autoinscrição	10	20
INSC_INST	Inscrição Institucional	30	60

Avaliação de Comissão

Código	Descrição	Base	Teto
AVAL_COMIS_PREMIO	Avaliador Prêmio	30	60
AVAL_COMIS_GP	Avaliador Grande Prêmio	50	80

Coordenação de Comissão

Código	Descrição	Base	Teto
COORD_COMIS_PREMIO	Coord. Comissão Prêmio	50	100
COORD_COMIS_GP	Coord. Comissão GP	60	120

Premiações Recebidas

Código	Descrição	Base	Teto
PREMIACAO	Grande Prêmio CAPES	100	180
PREMIACAO_GP	Prêmio CAPES de Tese	50	60
MENCAO	Menção Honrosa	30	30

Bolsas CNPq

Código	Descrição	Base	Teto
BOL_BPQ_SUPERIOR	Bolsa PQ nível 1A/1B/1C	30	60
BOL_BPQ_INTERMEDIARIO	Bolsa PQ nível 1D/2	50	100

Participações

Código	Descrição	Base	Teto
EVENTO	Participação em Evento	1	5
PROJ	Participação em Projeto	10	40

Orientações

Código	Descrição	Base	Teto
ORIENT_POS_DOC	Orientação Pós-Doc	15	100
ORIENT_TESE	Orientação Tese	10	50
ORIENT_DISS	Orientação Dissertação	5	25
CO_ORIENT_POS_DOC	Co-Orientação Pós-Doc	7	35
CO_ORIENT_TESE	Co-Orientação Tese	5	25
CO_ORIENT_DISS	Co-Orientação Dissertação	3	15

Bancas

Código	Descrição	Base	Teto
MB_BANCA_POS_DOC	Banca Pós-Doc	3	15
MB_BANCA_TESE	Banca Tese	3	15
MB_BANCA_DISS	Banca Dissertação	2	10

Bloco E: Docência e Lattes

Pontuação baseada em atividades de docência e informações do currículo Lattes.

Selos Visuais (sem pontuação)

Indicadores visuais que aparecem no card do consultor:

Selo	Descrição	Ícone
Coord. PPG	Coordenador de Programa	🎓
Presid. Câmara	Presidente de Câmara Temática	🏛️
Bolsista PQ	Bolsista de Produtividade CNPq	🔬
Grande Prêmio	Vencedor do Grande Prêmio	🏆
Prêmio	Vencedor de Prêmio	🥇
Menção Honrosa	Menção Honrosa	🎖️
Orientações	Orient. Pós-Doc/Tese/Diss	📚📖📝
Co-Orientações	Co-Orient. Pós-Doc/Tese/Diss	📚📖📝

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

Entre no diretório do backend:

cd backend

Crie ambiente virtual e instale dependências:

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

Configure as variáveis de ambiente:

cp .env.example .env

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

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

Entre no diretório do frontend:

cd frontend

Instale dependências:

npm install

Execute em modo desenvolvimento:

npm run dev

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

Setup com Docker

Crie a rede compartilhada (apenas uma vez):

docker network create shared_network

Configure as variáveis de ambiente:

cp .env.example .env

Edite .env com suas credenciais
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

Referências

Documentação dos critérios: .claude/rules/ranking-consultores-capes.md
Queries e mapeamentos: .claude/rules/ranking-queries-elasticsearch.md
Queries implementadas: .claude/rules/ranking-queries-implementadas.md

13 KiB Raw Blame History Unescape Escape